From 37343b6d87f667771064a8e717f7ca9e69744059 Mon Sep 17 00:00:00 2001
From: drbeefsupreme <jon@tlon.io>
Date: Wed, 6 Jul 2022 17:20:21 -0400
Subject: [PATCH] doccords: add sample library lib/deco.hoon

---
 pkg/arvo/lib/deco.hoon | 178 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 178 insertions(+)
 create mode 100644 pkg/arvo/lib/deco.hoon

diff --git a/pkg/arvo/lib/deco.hoon b/pkg/arvo/lib/deco.hoon
new file mode 100644
index 0000000000..91f3cbefc5
--- /dev/null
+++ b/pkg/arvo/lib/deco.hoon
@@ -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)}"
+--