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
|
|
|
::
|
2018-05-25 01:39:56 +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,
|
2018-05-25 01:39:56 +03:00
|
|
|
:: {:>} 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*
|
2018-05-25 01:39:56 +03:00
|
|
|
:: preceded by {:: } - ie, not indented. a long body starts with
|
|
|
|
:: a *single line* indented by two extra spaces, {:: }, then a
|
2017-04-05 03:33:20 +03:00
|
|
|
:: 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
|
2018-05-25 01:39:56 +03:00
|
|
|
:: a *single line* of the form {:: name: value}.
|
2017-04-05 03:33:20 +03:00
|
|
|
::
|
|
|
|
:: 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,
|
2018-05-25 01:39:56 +03:00
|
|
|
:: indented by four extra spaces, {:: }, for code.
|
2017-04-05 03:33:20 +03:00
|
|
|
::
|
|
|
|
:: a backward decoration {:<} is only one line, always parsed
|
|
|
|
:: as a short body.
|
|
|
|
::
|
|
|
|
:- %say
|
|
|
|
|= *
|
|
|
|
=< [%noun (say-hello %world)]
|
2018-05-25 01:39:56 +03:00
|
|
|
=> :: # %arch
|
|
|
|
::
|
|
|
|
:: 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-04-05 03:33:20 +03:00
|
|
|
|%
|
2018-05-25 01:39:56 +03:00
|
|
|
:: # %model
|
|
|
|
::
|
|
|
|
:: models (molds) are functions that normalize nouns.
|
|
|
|
::
|
2018-06-02 00:31:10 +03:00
|
|
|
:: arms producing molds are introduced with {+$}. the
|
2018-05-25 01:39:56 +03:00
|
|
|
:: compiler will copy the arm decoration onto its product
|
2017-04-05 03:33:20 +03:00
|
|
|
+|
|
2018-06-02 00:31:10 +03:00
|
|
|
+$ spot [p=@ q=@] :: a coordinate
|
|
|
|
+$ tops :: also a coordinate
|
2017-11-15 00:16:06 +03:00
|
|
|
[p=@ q=@]
|
2018-06-02 00:31:10 +03:00
|
|
|
+$ goof :: a simple tuple
|
2018-05-25 01:39:56 +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
|
|
|
==
|
2018-06-02 00:31:10 +03:00
|
|
|
+$ juice :: fruity beverage
|
2018-05-25 01:39:56 +03:00
|
|
|
$% [%plum p=@] :: fresh prune
|
|
|
|
[%pear p=@ q=@] :: good for cider
|
|
|
|
[%acai p=@] :: aztec superfood
|
2017-04-05 03:33:20 +03:00
|
|
|
==
|
2018-05-25 01:39:56 +03:00
|
|
|
:: #
|
|
|
|
:: # %pattern
|
|
|
|
:: #
|
|
|
|
::
|
|
|
|
:: patterns are functions that build models.
|
|
|
|
::
|
|
|
|
:: other languages might call these "type constructors"
|
|
|
|
:: or "higher-kinded types".
|
2017-04-05 03:33:20 +03:00
|
|
|
+|
|
2018-05-25 01:39:56 +03:00
|
|
|
++ 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)])
|
2018-05-25 01:39:56 +03:00
|
|
|
:: #
|
|
|
|
:: # %constant
|
|
|
|
:: #
|
|
|
|
:: if you have constants, put them in their own chapter.
|
2017-04-05 03:33:20 +03:00
|
|
|
+|
|
2018-05-25 01:39:56 +03:00
|
|
|
++ answer :: answer to everything
|
2017-04-05 03:33:20 +03:00
|
|
|
42
|
|
|
|
--
|
2018-05-25 01:39:56 +03:00
|
|
|
:: #
|
|
|
|
:: # %work
|
|
|
|
:: #
|
|
|
|
:: engines for our imaginary hello, world app.
|
|
|
|
::
|
2017-04-05 03:33:20 +03:00
|
|
|
|%
|
2018-05-25 01:39:56 +03:00
|
|
|
++ 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)}"
|
2018-05-25 01:39:56 +03:00
|
|
|
:: ++say-goodbye: say a really proper goodbye
|
|
|
|
::
|
|
|
|
:: some paragraphs about the goodbye algorithm, possibly
|
|
|
|
:: including code indented by four extra spaces:
|
|
|
|
::
|
|
|
|
:: ?: =(%hello %world)
|
|
|
|
:: %hello
|
|
|
|
:: %world
|
2017-11-16 02:22:42 +03:00
|
|
|
::
|
2018-05-27 22:15:15 +03:00
|
|
|
++ say-goodbye ::
|
2018-05-25 01:39:56 +03:00
|
|
|
:: 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
|
2018-05-25 01:39:56 +03:00
|
|
|
:: foo: four
|
|
|
|
:: bar: forty-two
|
2017-04-05 03:33:20 +03:00
|
|
|
=/ foo (add 2 2)
|
|
|
|
=/ bar (add (mul num foo) 2)
|
2018-05-25 01:39:56 +03:00
|
|
|
=/ moo (mul num bar) :: for all the cows
|
2017-04-05 03:33:20 +03:00
|
|
|
"goodbye and {(scot %ud moo)}, {(rip 3 txt)}"
|
2017-11-16 02:22:42 +03:00
|
|
|
::
|
2018-05-25 01:39:56 +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)}"
|
|
|
|
--
|