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)}" +--