shrub/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 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
--