@@ -1,532 +0,0 @@
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−