mirror of
https://github.com/urbit/shrub.git
synced 2024-12-19 00:13:12 +03:00
doccords: add sample library lib/deco.hoon
This commit is contained in:
drbeefsupreme
parent
938dc8cfe4
commit
37343b6d87
178
pkg/arvo/lib/deco.hoon
Normal file
178
pkg/arvo/lib/deco.hoon
Normal file
@ -0,0 +1,178 @@
|
||||
:: 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.
|
||||
::
|
||||
:: informal comments (lines with {::}) should be used only for
|
||||
:: meta-discussion *about* the code.
|
||||
::
|
||||
:: whenever possible, use formal decorations. {:>} decorates
|
||||
:: the next expression; {:<} decorates the previous one.
|
||||
::
|
||||
:: 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 is for single-line comments at a given lexical location
|
||||
:: (see below), which may be written above any arm in a core and
|
||||
:: the parser will move the comment to the specified arm.
|
||||
::
|
||||
:: style 2 is much like style 1, but may be followed by a series
|
||||
:: of paragraphs:
|
||||
:: {::}
|
||||
:: {:: more text}
|
||||
:: {:: even more text}
|
||||
:: {::}
|
||||
:: {:: |=(code=hoon !!)}
|
||||
::
|
||||
:: a paragraph is a series of lines, not indented for text,
|
||||
:: but indented by four extra spaces, {:: }, for code.
|
||||
::
|
||||
:: style 3 is used to annotate the hoon or spec that immediately follows
|
||||
:: the comment. this may be either a single line comment as in style 1,
|
||||
:: or multi-line comment as in 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. you may still write doccords for these locations, and they
|
||||
:: will be parsed, but are 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
|
||||
::
|
||||
:: |% and |@ cores can be given @tas names with e.g. `|% %foo`. for
|
||||
:: now, the only purpose of this is to make cores not built by arms
|
||||
:: legible to doccords. in order to name any other core type, you will
|
||||
:: need to desugar it for now.
|
||||
::
|
||||
:: to inspect doccords in this file from dojo, try the following:
|
||||
::
|
||||
:: > =deco -build-file %/lib/deco/hoon
|
||||
:: > # deco
|
||||
:: > # deco/arch
|
||||
:: > # deco/arch/model
|
||||
:: > # deco/arch/model/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: 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 {+|}).
|
||||
|% %arch
|
||||
:> models (molds) are functions that normalize nouns.
|
||||
:>
|
||||
:> arms producing molds are introduced with {+$}. the
|
||||
:> compiler will copy the arm decoration onto its product
|
||||
+| %model
|
||||
+$ 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
|
||||
==
|
||||
:> patterns are functions that build models.
|
||||
:>
|
||||
:> other languages might call these "type constructors"
|
||||
:> or "higher-kinded types".
|
||||
+| %pattern
|
||||
++ binary-tree :< tree pattern mold
|
||||
|* 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.
|
||||
:>
|
||||
|% %work
|
||||
++ 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 :< say bye to someone
|
||||
:> 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)}"
|
||||
--
|
||||
Loading…
Reference in New Issue
Block a user