mirror of
https://github.com/urbit/shrub.git
synced 2024-11-28 13:54:20 +03:00
190 lines
6.7 KiB
Plaintext
190 lines
6.7 KiB
Plaintext
:: Hoon doccords sample
|
|
::
|
|
:: this is a sample file designed to explain syntax and conventions
|
|
:: for doccords
|
|
::
|
|
:: 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.
|
|
::
|
|
:: whenever possible, use formal decorations. {::} decorates
|
|
:: the next expression when put on its own line, and the previous
|
|
:: expression if written on the same line
|
|
::
|
|
:: there are two places to put decorations: in line with the
|
|
:: code, and on the right margin.
|
|
::
|
|
:: the file below is a well-commented library, built around
|
|
:: a typical two-core structure. the cores are labeled {%arch}
|
|
:: (structures) and {%work} (productions).
|
|
::
|
|
:: 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.
|
|
::
|
|
:: there are three ways to mark the beginning of a formal comment:
|
|
:: 1- {:: $foo:}
|
|
:: 2- {:: +bar:}
|
|
:: 3- {:: }
|
|
::
|
|
:: style 1 may optionally be followed by a series of paragraphs, where each
|
|
:: paragraph is preceded by a line containing only {::} and whitespace, and
|
|
:: each line of a given paragraph is preceded by four aces.
|
|
:: {::}
|
|
:: {:: more text}
|
|
:: {:: even more text}
|
|
:: {::}
|
|
:: {:: |=(code=hoon !!)}
|
|
::
|
|
:: style 2 is much like style 1, but paragraphs are indented by two spaces
|
|
:: instead of four.
|
|
:: {::}
|
|
:: {:: more text}
|
|
:: {:: even more text}
|
|
:: {::}
|
|
:: {:: |=(code=hoon !!)}
|
|
::
|
|
:: code is indented a total of six aces, for either style.
|
|
::
|
|
:: style 3 is used to annotate the hoon or spec that immediately follows
|
|
:: the comment. paragraphs are written with style 2.
|
|
::
|
|
:: the $foo and +bar above are examples of *lexical locations* for
|
|
:: style and batch-commenting purposes. this tells the parser to attempt
|
|
:: to attach the comment to the specified location. these locations
|
|
:: may be written as follows:
|
|
:: - `|foo` means a chapter
|
|
:: - `%foo` means a constant
|
|
:: - `.foo` means a face
|
|
:: - `+foo` means an arm
|
|
:: - `$foo` means a spec
|
|
:: - `^foo` means a core
|
|
:: - `_foo` means a door
|
|
:: - `=foo` means a gate
|
|
:: - `/foo` means a file path segment
|
|
::
|
|
:: thus /lib/foo^widget|initial=open means the =open gate in the |initial
|
|
:: chapter of the ^widget core in the /foo library
|
|
::
|
|
:: at present, doccords does not support lexical locations in full.
|
|
:: only single-element locations of the form `$foo` and `+foo` are supported,
|
|
:: and must be written above an arm in the core to which they are to be
|
|
:: attached, and after the chapter they are in (if the core has chapters).
|
|
:: you may still write doccords for other locations in anticipation of the
|
|
:: fully supported lexical location, but they will be thrown away before they
|
|
:: make it to the compiler.
|
|
::
|
|
:: a postfix formal comment will either attach to hoon or spec on the
|
|
:: current line, or the arm name if there is no hoon or spec on the
|
|
:: line. the convention for +$ arms is that the comment attached to the
|
|
:: arm is about the mold itself, while the comment attached to the spec
|
|
:: is about the output type of the mold.
|
|
::
|
|
:: to inspect doccords in this file from dojo, try the following:
|
|
::
|
|
:: > =deco -build-file %/lib/deco/hoon
|
|
:: > # deco
|
|
:: > # deco/arch
|
|
:: > # deco/arch/molds
|
|
:: > # deco/arch/molds/goof
|
|
::
|
|
:: > ?? *goof:deco
|
|
::
|
|
=> ::
|
|
:: structures for our imaginary hello, world generator.
|
|
::
|
|
:: nothing forces us to put structures in a separate core.
|
|
:: but compile-time evaluation doesnt work in the current
|
|
:: core; we often want to statically evaluate structures.
|
|
::
|
|
:: there are three kinds of structures: moldss (normalizing
|
|
:: functions), mold builders (functions that build molds), and
|
|
:: constants (static data).
|
|
::
|
|
:: most code will not need its own mold builders. but put them
|
|
:: in a separate chapter (separated by {+|}).
|
|
|%
|
|
:: molds are functions that normalize nouns.
|
|
::
|
|
:: arms producing molds are introduced with {+$}. the
|
|
:: compiler will copy the arm decoration onto its product
|
|
+| %molds
|
|
:: $jam: some delicious jam
|
|
:: $jelly: different from jam?
|
|
+$ spot [p=@ q=@] :: a coordinate
|
|
+$ tops :: mold for coordinate
|
|
[p=@ q=@] :: another coordinate
|
|
+$ goof :: a simple tuple mold
|
|
$: foo=@ :: something mysterious
|
|
bar=@ :: go here for drink
|
|
moo=(binary-tree juice) :: cows do this
|
|
==
|
|
+$ juice :: fruity beverage mold
|
|
$% [%plum p=@] :: fresh prune
|
|
[%pear p=@ q=@] :: good for cider
|
|
[%acai p=@] :: aztec superfood
|
|
==
|
|
+$ jam @tas
|
|
+$ jelly @tas
|
|
:: mold builders are functions that build molds from other molds
|
|
::
|
|
:: other languages might call these "type constructors"
|
|
:: or "higher-kinded types".
|
|
+| %mold-builders
|
|
++ binary-tree :: tree mold builder
|
|
|* a=$-(* *)
|
|
$@(~ [n=a l=(binary-tree a) r=(binary-tree a)])
|
|
::
|
|
:: if you have constants, put them in their own chapter.
|
|
+| %constant
|
|
++ answer :: answer to everything
|
|
42
|
|
--
|
|
:: engines for our imaginary hello, world app.
|
|
::
|
|
|%
|
|
:: +default-jam: bunts $jam
|
|
:: +default-juice: bunts $juice
|
|
++ say-hello :: say hi to someone
|
|
:: friendly welcome message
|
|
::
|
|
|=
|
|
:: .txt: friend to say hi to
|
|
::
|
|
txt=term
|
|
^- 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:
|
|
::
|
|
:: ?: =(%hello %world)
|
|
:: %hello
|
|
:: %world
|
|
::
|
|
++ say-goodbye
|
|
:: describe product of function
|
|
::
|
|
|=
|
|
:: .txt: departing friend
|
|
:: .num: number of friends
|
|
$: txt=term
|
|
num=@
|
|
==
|
|
^- 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 {(scow %ud moo)}, {(rip 3 txt)}"
|
|
::
|
|
++ say-minimum :: minimal decoration
|
|
|= txt=term
|
|
"nothing to say to {(rip 3 txt)}"
|
|
::
|
|
++ default-jam *jam
|
|
++ default-juice *juice
|
|
--
|