2017-04-05 03:33:20 +03:00
|
|
|
::
|
|
|
|
:: this is a sample file designed to set conventions for
|
|
|
|
:: high-quality conventional hoon.
|
|
|
|
::
|
|
|
|
:: all lines must be under 80 characters. no blank lines.
|
|
|
|
:: any line longer than 60 characters is probably too long.
|
|
|
|
:: uppercase or non-ascii letters are strongly discouraged.
|
2017-05-08 01:45:26 +03:00
|
|
|
::
|
2017-04-05 03:33:20 +03:00
|
|
|
:: informal comments (lines with {::}) should be used only for
|
2017-05-08 01:45:26 +03:00
|
|
|
:: meta-discussion *about* the code.
|
2017-04-05 03:33:20 +03:00
|
|
|
::
|
|
|
|
:: whenever possible, use formal decorations. {:>} decorates
|
|
|
|
:: the next expression; {:<} decorates the previous one.
|
|
|
|
::
|
2017-05-08 01:45:26 +03:00
|
|
|
:: there are two places to put decorations: in line with the
|
2017-04-05 03:33:20 +03:00
|
|
|
:: code, and on the right margin.
|
|
|
|
::
|
|
|
|
:: in comments and decorations, use *phrase* for emphasis
|
2017-05-08 01:45:26 +03:00
|
|
|
:: and {braces} to surround code literals. (documentation will
|
2017-04-05 03:33:20 +03:00
|
|
|
:: eventually be automatically generated from formal comments.)
|
2017-05-08 01:45:26 +03:00
|
|
|
:: %literal, ++literal, ~ship need no braces. for a valid
|
2017-04-05 03:33:20 +03:00
|
|
|
:: hoon expression, `exp.
|
|
|
|
::
|
|
|
|
:: there are three conventions for naming: *ultralapidary*,
|
|
|
|
:: *lapidary*, and *natural*. this file is mostly natural.
|
|
|
|
::
|
2017-05-08 01:45:26 +03:00
|
|
|
:: when in doubt, use the *natural* naming convention. for
|
2017-04-05 03:33:20 +03:00
|
|
|
:: both arms and faces, natural naming means long, legible,
|
|
|
|
:: english-language phrases, in hyphen-separated {kebab-case}.
|
|
|
|
::
|
|
|
|
:: lapidary conventions should be used only for small, simple,
|
|
|
|
:: self-contained systems. lapidary mode means three-letter
|
|
|
|
:: faces ("variable names") and four-letter arms ("methods").
|
|
|
|
::
|
|
|
|
:: ultralapidary conventions use single-letter names starting
|
|
|
|
:: with {a}. use this convention only for one-liners, etc.
|
2017-05-08 01:45:26 +03:00
|
|
|
::
|
2017-04-05 03:33:20 +03:00
|
|
|
:: the file below is a medium-sized generator, built around
|
|
|
|
:: a typical two-core structure. the cores are labeled {%arch}
|
|
|
|
:: (structures) and {%work} (productions). this is canonical.
|
|
|
|
::
|
|
|
|
:: this code is written to display the variety of formatting
|
|
|
|
:: options the parser allows. a specific convention should pick
|
|
|
|
:: one of these styles and stick to it.
|
|
|
|
::
|
|
|
|
:: a forward decoration block {:>} is either a *document block* or
|
|
|
|
:: a *definition block*.
|
|
|
|
|
2017-05-08 01:45:26 +03:00
|
|
|
:: a document block has two parts, each of which is optional:
|
|
|
|
:: the *title* and the *body*,
|
2017-04-05 03:33:20 +03:00
|
|
|
::
|
2017-05-08 01:45:26 +03:00
|
|
|
:: the title is a ++term preceded by {:> # %}. only cores
|
2017-04-05 03:33:20 +03:00
|
|
|
:: and core chapters (preceded by {+|}) can use titles. titles
|
2017-05-08 01:45:26 +03:00
|
|
|
:: are optionally surrounded by blank or semi-blank decorations,
|
|
|
|
:: {:>} or {:> #}.
|
2017-04-05 03:33:20 +03:00
|
|
|
::
|
2017-05-08 01:45:26 +03:00
|
|
|
:: the body is either short or long. a short body is a *single line*
|
2017-04-05 03:33:20 +03:00
|
|
|
:: preceded by {:> } - ie, not indented. a long body starts with
|
|
|
|
:: a *single line* indented by two extra spaces, {:> }, then a
|
|
|
|
:: blank line, then a series of paragraphs.
|
|
|
|
::
|
|
|
|
:: a definition block is a list of name definitions. the twig below
|
|
|
|
:: the block is traversed for bindings on these names.
|
|
|
|
::
|
|
|
|
:: a name definition can be short or long. a short definition is
|
|
|
|
:: a *single line* of the form {:> name: value}.
|
|
|
|
::
|
|
|
|
:: a long definition is a short definition, followed by a blank
|
|
|
|
:: decoration {:>}, followed by a series of paragraphs each
|
|
|
|
:: indented by an extra two spaces.
|
|
|
|
::
|
|
|
|
:: a paragraph is a series of lines, not indented for text,
|
|
|
|
:: indented by four extra spaces, {:> }, for code.
|
|
|
|
::
|
|
|
|
:: a backward decoration {:<} is only one line, always parsed
|
|
|
|
:: as a short body.
|
|
|
|
::
|
|
|
|
:- %say
|
|
|
|
|= *
|
|
|
|
=< [%noun (say-hello %world)]
|
2017-11-15 00:16:06 +03:00
|
|
|
=> :> # %arch
|
|
|
|
:>
|
2017-04-05 03:33:20 +03:00
|
|
|
:> structures for our imaginary hello, world generator.
|
|
|
|
:>
|
|
|
|
:> nothing forces us to put structures in a separate core.
|
|
|
|
:> but compile-time evaluation doesn't work in the current
|
|
|
|
:> core; we often want to statically evaluate structures.
|
|
|
|
:>
|
|
|
|
:> there are three kinds of structures: models (normalizing
|
|
|
|
:> functions), patterns (functions that build models), and
|
|
|
|
:> constants (static data).
|
|
|
|
:>
|
|
|
|
:> most code will not need its own patterns. but put them
|
|
|
|
:> in a separate chapter (separated by {+|}).
|
|
|
|
|%
|
2017-05-08 01:45:26 +03:00
|
|
|
:> # %model
|
2017-11-15 00:16:06 +03:00
|
|
|
:>
|
2017-04-05 03:33:20 +03:00
|
|
|
:> models (molds) are functions that normalize nouns.
|
2017-05-08 01:45:26 +03:00
|
|
|
:>
|
2017-11-16 02:22:42 +03:00
|
|
|
:> arms producing molds are introduced with {+=}. the
|
|
|
|
:> compiler will copy the arm decoration onto its product
|
2017-04-05 03:33:20 +03:00
|
|
|
+|
|
2017-11-09 22:04:27 +03:00
|
|
|
+= spot [p=@ q=@] :< a coordinate
|
2017-11-16 02:22:42 +03:00
|
|
|
+= tops :< also a coordinate
|
2017-11-15 00:16:06 +03:00
|
|
|
[p=@ q=@]
|
2017-11-16 02:22:42 +03:00
|
|
|
+= goof :< a simple tuple
|
2017-11-15 00:16:06 +03:00
|
|
|
$: foo=@ :< something mysterious
|
|
|
|
bar=@ :< go here for drink
|
|
|
|
moo=(binary-tree juice) :< cows do this
|
2017-04-05 03:33:20 +03:00
|
|
|
==
|
2017-11-16 02:22:42 +03:00
|
|
|
+= juice :< fruity beverage
|
2017-11-15 00:16:06 +03:00
|
|
|
$% [%plum p=@] :< fresh prune
|
|
|
|
[%pear p=@ q=@] :< good for cider
|
|
|
|
[%acai p=@] :< aztec superfood
|
2017-04-05 03:33:20 +03:00
|
|
|
==
|
2017-05-08 01:45:26 +03:00
|
|
|
:> #
|
|
|
|
:> # %pattern
|
|
|
|
:> #
|
|
|
|
:>
|
2017-04-05 03:33:20 +03:00
|
|
|
:> patterns are functions that build models.
|
|
|
|
:>
|
|
|
|
:> other languages might call these "type constructors"
|
|
|
|
:> or "higher-kinded types".
|
|
|
|
+|
|
|
|
|
++ binary-tree :< tree pattern
|
2017-11-15 00:16:06 +03:00
|
|
|
|* a=$-(* *)
|
2018-03-19 07:18:20 +03:00
|
|
|
$@(~ [n=a l=(binary-tree a) r=(binary-tree a)])
|
2017-05-08 01:45:26 +03:00
|
|
|
:> #
|
|
|
|
:> # %constant
|
|
|
|
:> #
|
2017-04-05 03:33:20 +03:00
|
|
|
:> if you have constants, put them in their own chapter.
|
|
|
|
+|
|
|
|
|
++ answer :< answer to everything
|
|
|
|
42
|
|
|
|
--
|
2017-11-15 00:16:06 +03:00
|
|
|
:> #
|
2017-05-08 01:45:26 +03:00
|
|
|
:> # %work
|
2017-11-15 00:16:06 +03:00
|
|
|
:> #
|
2017-05-08 01:45:26 +03:00
|
|
|
:> engines for our imaginary hello, world app.
|
2017-04-05 03:33:20 +03:00
|
|
|
:>
|
|
|
|
:> note that ++say-goodbye is the correct notation, even though
|
|
|
|
:> it's a {+-} arm.
|
|
|
|
|%
|
|
|
|
++ say-hello :< say hi to someone
|
|
|
|
:> friendly welcome message
|
|
|
|
:>
|
|
|
|
|= :> txt: friend to say hi to
|
|
|
|
:>
|
2017-11-15 00:16:06 +03:00
|
|
|
txt=term
|
2017-04-05 03:33:20 +03:00
|
|
|
^- tape
|
|
|
|
"hello, {(rip 3 txt)}"
|
|
|
|
:> ++say-goodbye: say a really proper goodbye
|
|
|
|
:>
|
|
|
|
:> some paragraphs about the goodbye algorithm, possibly
|
|
|
|
:> including code indented by four extra spaces:
|
2017-05-08 01:45:26 +03:00
|
|
|
:>
|
2017-04-05 03:33:20 +03:00
|
|
|
:> ?: =(%hello %world)
|
|
|
|
:> %hello
|
|
|
|
:> %world
|
2017-11-16 02:22:42 +03:00
|
|
|
::
|
2017-04-05 03:33:20 +03:00
|
|
|
+- say-goodbye ::
|
|
|
|
:> describe product of function
|
|
|
|
:>
|
|
|
|
|= :> txt: departing friend
|
|
|
|
:> num: number of friends
|
2017-11-15 00:16:06 +03:00
|
|
|
$: txt=term
|
|
|
|
num=@
|
2017-04-05 03:33:20 +03:00
|
|
|
==
|
|
|
|
^- tape
|
|
|
|
:> foo: four
|
|
|
|
:> bar: forty-two
|
|
|
|
=/ foo (add 2 2)
|
|
|
|
=/ bar (add (mul num foo) 2)
|
|
|
|
=/ moo (mul num bar) :< for all the cows
|
|
|
|
"goodbye and {(scot %ud moo)}, {(rip 3 txt)}"
|
2017-11-16 02:22:42 +03:00
|
|
|
::
|
|
|
|
++ say-minimum :< minimal decoration
|
2017-11-15 00:16:06 +03:00
|
|
|
|= txt=term
|
2017-04-05 03:33:20 +03:00
|
|
|
"nothing to say to {(rip 3 txt)}"
|
|
|
|
--
|