urbit/pkg/arvo/lib/deco.hoon

:>    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; {:<} 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 other 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. 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.
:>
:>  |% 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
:>  more legible to doccords users. in order to name any other core type,
:>  you will need to desugar it by hand for the time being.
:>
:>  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 {+|}).
    |%  %arch
    :>    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.
:>
|%  %work
:>  +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                                         :<  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)}"
::
++  default-jam  *jam
++  default-juice  *juice
--