@@ -0,0 +1,532 @@
8+`::` all code following '::' on a line is a comment.
10+By convention, comments should begin on either column 39 or
13+####Runes (Expressions)
15+- Most runes have a predetermined amount of children, and thus do not need to be closed.
17+- Runes that accept an arbitrary number of children are typically closed with
18+ `==`, with the exception being the `|` runes, some of which are closed with
21+- In some cases, the second glyph denotes how many 'children' a rune accepts:
27+- Backstep pattern: in order to avoid excess parentheses as well as code that
28+ flows off the page, the last child of a rune should fall directly below it.
29+ The first child should be the furthest to the right, with every subsequent
30+ rune 'backstepping' two spaces towards the last child.
34+The first glyph in a rune defines a rough semantic category of expressions:
36+##### ? : Conditional statements
53+`?.` - Inverted if-then-else
55+`?@` - If atom-then-else
57+`?^` - If cell-then-else
60+`?-` - Switch (on type)
62+`?+` - Swith (on type) with default
65+`?>` - Assert `p` is false.
67+`?<` - Assert `p` is true.
70+`?~` - if null-then-else Note: don't forget, changes type
71+`?=` - is `q` of type `p`Note: don't forget, changes the type
73+##### % : Code execution
75+`%-` Call `p` with 1 arg
77+ - Irregular: `(p q)` Note: irregular form can accept n children.
79+`%.` Inverted `%-`: call `q` with arg `p`
81+`%+` Call `p` with 2 args
83+`%^` Call `p` with 3 args
86+`%~` Call one arm `p` within object/core `q` with arg `r`
88+ - Irregular: `~(p q r)`
90+`%*` Same as `%~` except `s` is a list of changes that can be made anywhere in
91+the context, not just to input data.
94+`%=` Evaluate `p` with changes specified in `q`
96+ - Irregular: `a(p q.p, q p.a)`, where `a` is the code to be executed with changes
97+ specified in the `()`
99+`%_` Same as `%=`, except that product is cast back to type of `p`.
101+##### : : Tuple construction
105+ - Irregular `[p q ..]` Note: the irregular form can make tuples of arbitrary size
107+`:_` Inverted tuple of two
114+`:*` Tuple of arbitrary number of elements, closed with `==`
116+`:~` Null terminated tuple of arbitrary number of elements, closed with `==`.
121+##### | : Object aka "core" construction
123+`|%` Generic core, closed with `--`
125+`|_` Core with input data (aka 'sample), closed with `--`
128+`|=` Function with type-checking at compile time (aka 'dry gate'); called automatically
130+`|*` Function with type-checking at run time (aka 'wet gate'); called automatically
132+`|.` Function (like `|=`) with no argument; called automatically
134+`|-` Function with no arguments (like `|.`); not called automatically
137+`|/` Same as `|_`, but with well typed output, closed with `--`
139+`|^` Same as `|-`, but can contain internal arms, closed with `--`
141+`|+` Function with unreadable argument(s) (aka 'sample'), so as to avoid type conflicts
143+`|?` Same as `|_` but both the input and 'context' are hidden to avoid type conflicts
145+##### $ : Type definitions
147+`$|` Union between atom and cell
149+`$_` 'Unbunt'; create type from example
151+ - Irregular: `_p`, but only when in mold syntax
153+`$:` Tuple of types (aka 'molds')
155+ - Irregular: `{i.p i.t.p i.t.t.p}`
159+`$+` Type of function (type signature)
161+`$&` Union of two cells: one w/cellular head and other w/atomic head
163+`$*` 'Bunt'; produce default value of a type
165+ - Irregular: `*([mold])`
167+`$=` Add variable name; technically changes the type as well
169+ - Irregular: `p=q`, but only when in mold syntax
171+`$?` Union of types; non-empty list of types ('molds'). Default value ('bunt') is the value of the first element
173+ - Irregular: `?([list of molds])`, but only when in mold syntax
175+##### = : Subject ("context") modification XX
177+`=>` Resolve code; use the product of `p` as the subject of `q`
181+`=<` Inverted `=>`, used for code readability
184+`=|` Push default value of type ('mold') onto subject
186+`=+` Push variable/value onto subject
188+`=-` Inverted `=+`; push product of `q` onto subject `p`
191+`=.` One change to subject; produce `r` with `p` in the context (in hoon the
192+'subject') set to `q`
194+`=:` Multiple changes to subject; Make a list of changes to the context (in hoon the 'subject')
196+ XX how do we talk about subject and context.
199+`=^` Used to push a new variable `q` with face `p` onto the subject `s`, as
200+well as to change the value of another. `r` is a function that accepts `q` and
201+produces a cell of a new value of `q`, and a new subject. XX
203+`=~` Compose a list of twigs, applying `=>` to the list, using each result as the subject to the subsequent expressions.
205+`=*` Make `p` an alias of `q`
209+`^|` Make core context unreadable so as to avoid type conflicts
211+`^.` Cast `q` to the product type of `p`. Useful when you don't actually want to run a funciton at run time
213+`^-` Traditional Cast `q` to the type of the default value ('bunt') of `p`
217+`^+` Cast `q` to the type of `p`. Used to cast to types that have previously been made into validator functions with `$,`.
219+`^&` Convert object/core from invariant to covariant
221+`^~` Try to execute `p` statically at compile time. If this fails, `p` remains dynamic
223+`^=` Put on variable name ('face')
227+`^?` Convert core with unreadable context to a core whose input ('sample') and context are unreadable. Used to avoid type conflicts
229+##### . : Nock operations
231+`.^` Nock 11; loads a file from `%clay`
233+`.+` Nock 4; increments an atom
237+`.*` Compute nock; formula `q` on subject `p`
239+`.=` Nock 5; test `p` and `q` for equality
241+ - Irregular: `=(p q)`
243+`.?` Test if noun is cell or an atom
245+##### # : Pretty printing
247+`#<` Pretty print tape; only used in its irregular form
249+ - Irregular: `<i.p i.t.p i.t.t.p>`
251+`#>` Pretty print `++tank`; used only in it's irregular form
253+ - Irregular: `>i.p i.t.p i.t.t.p<`
255+##### / : Library access
257+`//` Load a file between twigs
259+`/~` Cached computation, similar to a `=+` at the top of the file
261+`/$` Pull in dynamic request data, slam it through a gate
263+`/=` Horn form of `^=`. Puts a face on a cached computation
265+`/^` Horn form of `^-`
267+`/;` Apply gate to result of horn
269+`/,` Appen path to current working beam before computing horn
273+`/%` Reifiy the 'heel' virtual path, letting any requested resource interpret it further
275+`/.` Construct list of specified horns
277+`/*` similar to `/.`, but produces a map instead
279+`/_` descend into each available subdirectory, construct a map from all successfully building versions
281+`/&` Parse directory name as `@da`
283+`/|` Parse directory name as `@dr`
285+##### ~ : Compiler hints
287+`~$` Label computation `q` as `p` for profiling
289+`~|` `p` in stacktrace if `q` crashes
291+`~_` Preformatted stackframe `p` (a trap producing a `++tank`) into stacktrace
293+`~%` i.p i.t.p i.t.t.pRegister jet in core `s`
297+`~<` Hint to product; applies arbitrary hint `p` to the product of `q`, which is computed beforehand
299+`~>` Arbitrary hint `p` to `q`
301+`~+` Memoize computation of `p`
305+`~=` Hint to avoid duplication
307+`~?` PrintF if `q` is true
309+`~!` Print type on compilation fail
311+##### ! : Special runes
313+`!_` Path and range in stack trace
315+`!>` Produces a cell of both the type and value of `p` (called a `++vase`).
316+Useful for debugging.
318+`!=` Show nock of `p`
320+`!?` Enforce a Hon version restriction
329+`++tape` - List of chars. Used when you want to manipulate and interpolate text - `"[text]"`
330+ See [list]() section for operations.
332+`@t` - UTF-8 text; aka `++cord` - `'[text]'`
333+ `++trip`: cord to string XX
334+ `++taco`: cord to octet stream (for http requests) XX
335+ `++slav`: parse cord to an atom of input odor XX
337+`@ta` - Valid Hoon ASCII symbols - `~.[text]` + {`a-z`, `0-9`, `~`, `-`, `.`, `_`.}
338+`@tas` - Hoon identifier ASCII subset - `%` + `a-z`, `-` (not first), `1-9` (not first)
340+XX Would love to add half a liine about the difference between cords and tapes.
344+`@` - Generic atom (defaults to unsigned integer) - `42`
345+`@u` - Unsigned integer - `42`
346+`@sd` - Signed decimal - `-42`(-), `--42` see `++si` for operations
347+`@rd` - Single precision floating point - `.-42.75` (-), `.42.75` (+), see `++rd` for operations
349+#####Other Important Atoms
350+`@da` - absolute date - `~~[year].[month].[date]..[hour].[minute].[second]..[fractionals]`
351+ `++year`: `++date` to `@d` XX
352+ `++yore`: `@d` to `++date` XX
353+ note: year month day is mandatory, others are optional
354+`@dr` - relative date (timespan) - `~d[day].h[hour]m[minute].s[second]..[fractionals]`
355+ note: every measurement optional.
356+ `++add`: can add `@dr`s together XX
357+ `++yell`: `@d` to `++tarp` XX
358+`@p` - phonemic base - `~[valid @p]`
359+ `(scot %p [number])` prints a number as a `@p`
363+######Tuples are made with the `:` runes and their irregular `[]` wide forms
365+ To construct, use [`[]`]() (irregular form of [`:` runes]()).
371+`~[1 2 3]` > `[1 2 3 ~]`
373+`[1 2 3]~` > `[[1 2 3] ~]`
375+`~[1 2 3]~` > `[[1 2 3 ~] ~]`
379+To eliminate need for excess `[]`, tuples automatically group to
382+`[1 [2 [3 ~]]]` == `[1 2 3 ~]`
384+######pair, trel, quad put faces on tuples
386+``=+ a=`(pair term cord)`[%h 'j']`` > `[p=%h q='j']`
388+Faces allow you to access specific axes within your context:
390+`p.a` > `%h` and `p:[p=%h q='j']` > `%h`
392+######Lists are null-terminated and have faces of `i` and `t`
396+`++ list |* a=_,* :: null-term list
397+ $|(~ [i=a t=(list a)]) ::
400+- Constructor: `++limo` makes a list out of a null terminated tuple.
402+`(limo [67 55 201 ~])` > `[i=67 t=[i=55 t=[i=201 t=~]]]`
404+``(list ,@t)`(list ,@)\`~[67 55] > <|C 7|>``
408+`++weld`: concatenate
409+`++scag`: slice up to (and including) index number args: (index, list)
410+`++slag`: slice list after index, args: (index, list)
411+`++turn`: map over list, args: (list, function)
412+`++reel`: right fold args: (list, function)
413+`++roll`: left fold args: (list, function)
414+`++sort`: quicksort, args: (list, comparator-function)
420+` ++ map |* [a=_,* b=_,*] :: associative tree
421+ $|(~ [n=[p=a q=b] l=(map a b) r=(map a b)]) ::
424+- Constructor: `++mo` produces a map of key-val pairs from left-right cell pairs of a list
427+ ~zod/try=> (mo \`(list ,[@t *])\`[[a 1] [b 2] ~])
428+ {[p=a q=1] [p=b q=2]}
431+- Operations: contained within the `++by` core
433+`++by` accepts a map, then we use `%~` to pull the desired arm, which we then
434+pass the remainder of the arguments
437+> =m (mo \`(list ,[@t *])\`[['a' 1] ['b' 2] ~])
442+`+-all:by`: logical 'AND'
443+`+-any:by`: logical 'OR'
444+`+-del:by`: delete at key
445+`+-dig:by`: axis of key
446+`+-gas:by`: concatenate: insert a list of key-value pairs into map
447+`+-get:by`: pull out value at key as a unit
448+`+-got:by`: assert: pull value at key, crash if key doesn't exist
449+`+-has:by`: check if key exists
450+`+-int:by`: intersection: if keys match, use value from `b`
451+`+-put:by`: add key value pair
452+`+-rep:by`: fold over map
453+`+-run:by`: 'map' over map
454+`+-tap:by`: convert map to list
455+`+-uni:by`: produce union between keys; if both share keys, use value from `a`
456+`+-urn:by`: 'map', with key included with value as input to mapping function
457+`+-wyt:by`: produce depth of tree of map
464+ ++ set |* a=_,* :: set
465+ $|(~ [n=a l=(set a) r=(set a)]) ::
468+- Constructor: `++sa`
471+ ~zod/try=> (sa \`(list ,@)\`[1 2 3 4 5 ~])
475+- Operations: contained within the `++in` core
477+The `++in` core accepts a set, then we use `%~` to pull desired operation out
478+of it, which we then pass the remainder of the arguments.
480+ > =a (~(gas in `(set ,@t)`~) `(list ,@t)`[`a` `b` `c` ~])
485+`+-all:in`: logical 'AND'
486+`+-any:in`: logical 'OR'
487+`+-del:in`: delete val at key
488+`+-dif:in`: difference between sets
489+`+-dig:in`: produce axis `b` in set
490+`+-gas:in`: concatenate: insert elements of list `b` into set
491+`+-has:in`: check if element exists in set
492+`+-int:in`: intersection
493+`+-put:in`: add an element to set
494+`+-rep:in`: fold over set
495+`+-tap:in`: convert set to list
496+`+-uni:in`: produces the union between two sets
497+`+-wyt:in`: Produces the number of elements in set
499+#####Addressing within nouns
501+There are several ways you can address an axes of a noun:
503+1. `[face].[variable-name]`
505+2. `-.+.+.a`: 'the head, within the tail of the tail of `a`.'
507+Can also intersperse faces: `+.a.b` reads 'the tail of `a` within `b`.
509+3. `->+.a`: 'tail within the head of the head of `a`.'
511+Must start with either `-` (head) or `+` (tail), and then follow with either `<` (head) or `>` (tail), so
512+as to not repeat two symbols.
514+4. `|[number].[var]` returns the elements that follow the nth element in a list
516+5. `&[number]` returns the nth element in a list. Cannot return the last element.
520+ i. hoon-how to generate the list of errors (Henry)