@@ -0,0 +1,532 @@
1+
2+##Quick references
3+
4+###Lexical syntax
5+
6+####Comments
7+
8+`::` all code following '::' on a line is a comment.
9+
10+By convention, comments should begin on either column 39 or
11+column 57.
12+
13+####Runes (Expressions)
14+
15+- Most runes have a predetermined amount of children, and thus do not need to be closed.
16+
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
19+ `--`.
20+
21+- In some cases, the second glyph denotes how many 'children' a rune accepts:
22+
23+ `-` two
24+ `+` three
25+ `^` four
26+
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.
31+
32+ XX
33+
34+The first glyph in a rune defines a rough semantic category of expressions:
35+
36+##### ? : Conditional statements
37+
38+`?&` Logical "and"
39+
40+ - Irregular: `&`
41+
42+`?|` Logical "or"
43+
44+ - Irregular: `|.`
45+
46+`?!` Logical "not"
47+
48+ - Irregular: `!`
49+
50+
51+`?:` - If-then-else
52+
53+`?.` - Inverted if-then-else
54+
55+`?@` - If atom-then-else
56+
57+`?^` - If cell-then-else
58+
59+
60+`?-` - Switch (on type)
61+
62+`?+` - Swith (on type) with default
63+
64+
65+`?>` - Assert `p` is false.
66+
67+`?<` - Assert `p` is true.
68+
69+
70+`?~` - if null-then-else Note: don't forget, changes type
71+`?=` - is `q` of type `p`Note: don't forget, changes the type
72+
73+##### % : Code execution
74+
75+`%-` Call `p` with 1 arg
76+
77+ - Irregular: `(p q)` Note: irregular form can accept n children.
78+
79+`%.` Inverted `%-`: call `q` with arg `p`
80+
81+`%+` Call `p` with 2 args
82+
83+`%^` Call `p` with 3 args
84+
85+
86+`%~` Call one arm `p` within object/core `q` with arg `r`
87+
88+ - Irregular: `~(p q r)`
89+
90+`%*` Same as `%~` except `s` is a list of changes that can be made anywhere in
91+the context, not just to input data.
92+
93+
94+`%=` Evaluate `p` with changes specified in `q`
95+
96+ - Irregular: `a(p q.p, q p.a)`, where `a` is the code to be executed with changes
97+ specified in the `()`
98+
99+`%_` Same as `%=`, except that product is cast back to type of `p`.
100+
101+##### : : Tuple construction
102+
103+`:-` Tuple of two
104+
105+ - Irregular `[p q ..]` Note: the irregular form can make tuples of arbitrary size
106+
107+`:_` Inverted tuple of two
108+
109+`:+` Tuple of three
110+
111+`:^` Tuple of four
112+
113+
114+`:*` Tuple of arbitrary number of elements, closed with `==`
115+
116+`:~` Null terminated tuple of arbitrary number of elements, closed with `==`.
117+
118+
119+`:/` XX
120+
121+##### | : Object aka "core" construction
122+
123+`|%` Generic core, closed with `--`
124+
125+`|_` Core with input data (aka 'sample), closed with `--`
126+
127+
128+`|=` Function with type-checking at compile time (aka 'dry gate'); called automatically
129+
130+`|*` Function with type-checking at run time (aka 'wet gate'); called automatically
131+
132+`|.` Function (like `|=`) with no argument; called automatically
133+
134+`|-` Function with no arguments (like `|.`); not called automatically
135+
136+
137+`|/` Same as `|_`, but with well typed output, closed with `--`
138+
139+`|^` Same as `|-`, but can contain internal arms, closed with `--`
140+
141+`|+` Function with unreadable argument(s) (aka 'sample'), so as to avoid type conflicts
142+
143+`|?` Same as `|_` but both the input and 'context' are hidden to avoid type conflicts
144+
145+##### $ : Type definitions
146+
147+`$|` Union between atom and cell
148+
149+`$_` 'Unbunt'; create type from example
150+
151+ - Irregular: `_p`, but only when in mold syntax
152+
153+`$:` Tuple of types (aka 'molds')
154+
155+ - Irregular: `{i.p i.t.p i.t.t.p}`
156+
157+`$%` Tagged union
158+
159+`$+` Type of function (type signature)
160+
161+`$&` Union of two cells: one w/cellular head and other w/atomic head
162+
163+`$*` 'Bunt'; produce default value of a type
164+
165+ - Irregular: `*([mold])`
166+
167+`$=` Add variable name; technically changes the type as well
168+
169+ - Irregular: `p=q`, but only when in mold syntax
170+
171+`$?` Union of types; non-empty list of types ('molds'). Default value ('bunt') is the value of the first element
172+
173+ - Irregular: `?([list of molds])`, but only when in mold syntax
174+
175+##### = : Subject ("context") modification XX
176+
177+`=>` Resolve code; use the product of `p` as the subject of `q`
178+
179+ - Irregular: `p:q`
180+
181+`=<` Inverted `=>`, used for code readability
182+
183+
184+`=|` Push default value of type ('mold') onto subject
185+
186+`=+` Push variable/value onto subject
187+
188+`=-` Inverted `=+`; push product of `q` onto subject `p`
189+
190+
191+`=.` One change to subject; produce `r` with `p` in the context (in hoon the
192+'subject') set to `q`
193+
194+`=:` Multiple changes to subject; Make a list of changes to the context (in hoon the 'subject')
195+
196+ XX how do we talk about subject and context.
197+
198+
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
202+
203+`=~` Compose a list of twigs, applying `=>` to the list, using each result as the subject to the subsequent expressions.
204+
205+`=*` Make `p` an alias of `q`
206+
207+##### ^ : Casting
208+
209+`^|` Make core context unreadable so as to avoid type conflicts
210+
211+`^.` Cast `q` to the product type of `p`. Useful when you don't actually want to run a funciton at run time
212+
213+`^-` Traditional Cast `q` to the type of the default value ('bunt') of `p`
214+
215+ - `\`p\`q`
216+
217+`^+` Cast `q` to the type of `p`. Used to cast to types that have previously been made into validator functions with `$,`.
218+
219+`^&` Convert object/core from invariant to covariant
220+
221+`^~` Try to execute `p` statically at compile time. If this fails, `p` remains dynamic
222+
223+`^=` Put on variable name ('face')
224+
225+ - Irregular: `p=q`
226+
227+`^?` Convert core with unreadable context to a core whose input ('sample') and context are unreadable. Used to avoid type conflicts
228+
229+##### . : Nock operations
230+
231+`.^` Nock 11; loads a file from `%clay`
232+
233+`.+` Nock 4; increments an atom
234+
235+ - Irregular: `+(p)`
236+
237+`.*` Compute nock; formula `q` on subject `p`
238+
239+`.=` Nock 5; test `p` and `q` for equality
240+
241+ - Irregular: `=(p q)`
242+
243+`.?` Test if noun is cell or an atom
244+
245+##### # : Pretty printing
246+
247+`#<` Pretty print tape; only used in its irregular form
248+
249+ - Irregular: `<i.p i.t.p i.t.t.p>`
250+
251+`#>` Pretty print `++tank`; used only in it's irregular form
252+
253+ - Irregular: `>i.p i.t.p i.t.t.p<`
254+
255+##### / : Library access
256+
257+`//` Load a file between twigs
258+
259+`/~` Cached computation, similar to a `=+` at the top of the file
260+
261+`/$` Pull in dynamic request data, slam it through a gate
262+
263+`/=` Horn form of `^=`. Puts a face on a cached computation
264+
265+`/^` Horn form of `^-`
266+
267+`/;` Apply gate to result of horn
268+
269+`/,` Appen path to current working beam before computing horn
270+
271+`/:` Replace beam
272+
273+`/%` Reifiy the 'heel' virtual path, letting any requested resource interpret it further
274+
275+`/.` Construct list of specified horns
276+
277+`/*` similar to `/.`, but produces a map instead
278+
279+`/_` descend into each available subdirectory, construct a map from all successfully building versions
280+
281+`/&` Parse directory name as `@da`
282+
283+`/|` Parse directory name as `@dr`
284+
285+##### ~ : Compiler hints
286+
287+`~$` Label computation `q` as `p` for profiling
288+
289+`~|` `p` in stacktrace if `q` crashes
290+
291+`~_` Preformatted stackframe `p` (a trap producing a `++tank`) into stacktrace
292+
293+`~%` i.p i.t.p i.t.t.pRegister jet in core `s`
294+
295+`~/` XX
296+
297+`~<` Hint to product; applies arbitrary hint `p` to the product of `q`, which is computed beforehand
298+
299+`~>` Arbitrary hint `p` to `q`
300+
301+`~+` Memoize computation of `p`
302+
303+`~&` Printf
304+
305+`~=` Hint to avoid duplication
306+
307+`~?` PrintF if `q` is true
308+
309+`~!` Print type on compilation fail
310+
311+##### ! : Special runes
312+
313+`!_` Path and range in stack trace
314+
315+`!>` Produces a cell of both the type and value of `p` (called a `++vase`).
316+Useful for debugging.
317+
318+`!=` Show nock of `p`
319+
320+`!?` Enforce a Hon version restriction
321+
322+`!!` Crash
323+
324+
325+####Data types
326+
327+#####Strings
328+
329+`++tape` - List of chars. Used when you want to manipulate and interpolate text - `"[text]"`
330+ See [list]() section for operations.
331+
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
336+
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)
339+
340+XX Would love to add half a liine about the difference between cords and tapes.
341+
342+#####Numbers
343+
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
348+
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`
360+
361+#####Data structures
362+
363+######Tuples are made with the `:` runes and their irregular `[]` wide forms
364+
365+ To construct, use [`[]`]() (irregular form of [`:` runes]()).
366+
367+`[3 'hello']`
368+
369+Special syntaxes:
370+
371+`~[1 2 3]` > `[1 2 3 ~]`
372+
373+`[1 2 3]~` > `[[1 2 3] ~]`
374+
375+`~[1 2 3]~` > `[[1 2 3 ~] ~]`
376+
377+######Autocons
378+
379+To eliminate need for excess `[]`, tuples automatically group to
380+the right:
381+
382+`[1 [2 [3 ~]]]` == `[1 2 3 ~]`
383+
384+######pair, trel, quad put faces on tuples
385+
386+``=+ a=`(pair term cord)`[%h 'j']`` > `[p=%h q='j']`
387+
388+Faces allow you to access specific axes within your context:
389+
390+`p.a` > `%h` and `p:[p=%h q='j']` > `%h`
391+
392+######Lists are null-terminated and have faces of `i` and `t`
393+
394+- Definition:
395+
396+`++ list |* a=_,* :: null-term list
397+ $|(~ [i=a t=(list a)]) ::
398+`
399+
400+- Constructor: `++limo` makes a list out of a null terminated tuple.
401+
402+`(limo [67 55 201 ~])` > `[i=67 t=[i=55 t=[i=201 t=~]]]`
403+
404+``(list ,@t)`(list ,@)\`~[67 55] > <|C 7|>``
405+
406+- Operations:
407+
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)
415+
416+######Map
417+
418+- Definition:
419+
420+` ++ map |* [a=_,* b=_,*] :: associative tree
421+ $|(~ [n=[p=a q=b] l=(map a b) r=(map a b)]) ::
422+`
423+
424+- Constructor: `++mo` produces a map of key-val pairs from left-right cell pairs of a list
425+
426+`
427+ ~zod/try=> (mo \`(list ,[@t *])\`[[a 1] [b 2] ~])
428+ {[p=a q=1] [p=b q=2]}
429+`
430+
431+- Operations: contained within the `++by` core
432+
433+`++by` accepts a map, then we use `%~` to pull the desired arm, which we then
434+pass the remainder of the arguments
435+
436+`
437+> =m (mo \`(list ,[@t *])\`[['a' 1] ['b' 2] ~])
438+> (~(got by m) 'a')
439+1
440+`
441+
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
458+
459+######Set
460+
461+- Definition:
462+
463+`
464+ ++ set |* a=_,* :: set
465+ $|(~ [n=a l=(set a) r=(set a)]) ::
466+`
467+
468+- Constructor: `++sa`
469+
470+`
471+ ~zod/try=> (sa \`(list ,@)\`[1 2 3 4 5 ~])
472+ {5 4 1 3 2}
473+`
474+
475+- Operations: contained within the `++in` core
476+
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.
479+
480+ > =a (~(gas in `(set ,@t)`~) `(list ,@t)`[`a` `b` `c` ~])
481+ > (~(has in a) `a`)
482+ %.y
483+
484+
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
498+
499+#####Addressing within nouns
500+
501+There are several ways you can address an axes of a noun:
502+
503+1. `[face].[variable-name]`
504+
505+2. `-.+.+.a`: 'the head, within the tail of the tail of `a`.'
506+
507+Can also intersperse faces: `+.a.b` reads 'the tail of `a` within `b`.
508+
509+3. `->+.a`: 'tail within the head of the head of `a`.'
510+
511+Must start with either `-` (head) or `+` (tail), and then follow with either `<` (head) or `>` (tail), so
512+as to not repeat two symbols.
513+
514+4. `|[number].[var]` returns the elements that follow the nth element in a list
515+
516+5. `&[number]` returns the nth element in a list. Cannot return the last element.
517+
518+####Error messages
519+
520+ i. hoon-how to generate the list of errors (Henry)
521+
522+ ii. arvo
523+ %a. Curtis
524+ %b. Philip
525+ %c. PHilip
526+ %d. Curtis || Anton
527+ %e. Anton
528+ %f. Curtis || Anton
529+ %g. Curtis || Anton
530+
531+
532+