@@ -70,7 +70,7 @@ Combinators come in a few shapes and sizes, and typical operations they may
7070perform would be to repeat the same parsing operation until the string is
7171consumed, try a few different parsing operations until one of them works,
7272or perform a sequence of parsing operations. We will see how all of this is done
73−with Hoon in the [Parsing in Hoon](#parsing-in-hoon) section.
73+with Hoon in the next section.
7474
7575# Parsing in Hoon
7676
@@ -157,7 +157,7 @@ Glyphs)](/docs/hoon/reference/stdlib/4h), [4i: Parsing (Useful
157157Idioms)](/docs/hoon/reference/stdlib/4i), [4j: Parsing (Bases and Base
158158Digits)](/docs/hoon/reference/stdlib/4j), [4l: Atom Parsing](/docs/hoon/reference/stdlib/4l).
159159
160−### `+just`
160+### [`+just`](/docs/hoon/reference/stdlib/4f/#just)
161161
162162The most basic rule builder, `+just` takes in a single `char` and produces a
163163`rule` that attempts to match that `char` to the first character in the `tape`
@@ -190,7 +190,7 @@ parsing has failed.
190190Later we will use [+star](#star) to string together a sequence of `+just`s in
191191order to parse multiple characters at once.
192192
193−### `+jest`
193+### [`+jest`](/docs/hoon/reference/stdlib/4f/#jest)
194194
195195`+jest` is a `rule` builder used to match a `cord`. It takes an input `cord` and
196196produces a `rule` that attempts to match that `cord` against the beginning of
@@ -236,7 +236,7 @@ beginning the parse failed. We will see in [parser
236236combinators](#parser-combinators) how to modify this `rule` so that it
237237finds `bc` successfully.
238238
239−### `+shim`
239+### [`+shim`](/docs/hoon/reference/stdlib/4f/#shim)
240240
241241`+shim` is used to parse characters within a given range. It takes in two atoms
242242and returns a `rule`.
@@ -246,7 +246,17 @@ and returns a `rule`.
246246[p=[p=1 q=2] q=[~ [p='a' q=[p=[p=1 q=2] q="bc"]]]]
247247```
248248
249−### `+cold`
249+### [`+next`](/docs/hoon/reference/stdlib/4f/#next)
250+
251+`+next` is a simple `rule` that takes in the next character and returns it as the
252+parsing result.
253+
254+```
255+> (next [[1 1] "abc"])
256+[p=[p=1 q=2] q=[~ [p='a' q=[p=[p=1 q=2] q="bc"]]]]
257+```
258+
259+### [`+cold`](/docs/hoon/reference/stdlib/4f/#cold)
250260
251261`+cold` is a `rule` builder that takes in a constant noun we'll call `cus` and a
252262`rule` we'll call `sef`. It returns a `rule` identical to the `sef` except it
@@ -264,7 +274,7 @@ One common scenario where `+cold` sees play is when writing [command line
264274interface (CLI) apps](/docs/hoon/guides/cli-tutorial). We usher the
265275reader there to find an example where `+cold` is used.
266276
267−### `+knee`
277+### [`+knee`](/docs/hoon/reference/stdlib/4f/#knee)
268278
269279Another important function in the parser builder library is `+knee`, used for building
270280recursive parsers. We delay discussion of `+knee` to the
@@ -284,11 +294,11 @@ alongside a `rule`, and attempt to parse the input with the `rule`. If the
284294parse succeeds, it returns the result. There are crashing and unitized versions
285295of each caller, corresponding to what happens when a parse fails.
286296
287−For additional information including additional examples see [4g: Parsing (Outside Caller)](/docs/hoon/reference/stdlib/4g).
297+For additional information including examples see [4g: Parsing (Outside Caller)](/docs/hoon/reference/stdlib/4g).
288298
289299### Parsing `tape`s
290300
291−`+scan` takes in a `tape` and a `rule` and attempts to parse the `tape` with the
301+[`+scan`](/docs/hoon/reference/stdlib/4g/#scan) takes in a `tape` and a `rule` and attempts to parse the `tape` with the
292302`rule`.
293303
294304```
@@ -299,7 +309,7 @@ For additional information including additional examples see [4g: Parsing (Outsi
299309'syntax-error'
300310```
301311
302−`+rust` is the unitized version of `+scan`.
312+[`+rust`](/docs/hoon/reference/stdlib/4g/#rust) is the unitized version of `+scan`.
303313
304314```
305315> (rust "a" (just 'a'))
@@ -309,25 +319,26 @@ For additional information including additional examples see [4g: Parsing (Outsi
309319```
310320
311321For the remainder of this tutorial we will make use of `+scan` so that we do not
312−need to deal directly with `nail`s except where it is ilustrative to do so.
322+need to deal directly with `nail`s except where it is illustrative to do so.
313323
314324### Parsing atoms
315325
316326[Recall](/docs/hoon/hoon-school/lists) that `cord`s are atoms with the aura
317327`@t` and are typically used to represent strings internally as data, as atoms
318328are faster for the computer to work with than `tape`s, which are `list`s of
319−`@tD` atoms. `+rash` and `+rush` are for parsing atoms, with `+rash` being
320−analogous to `+scan` and `+rush` being analogous to `rust`. Under the hood, `+rash`
329+`@tD` atoms. [`+rash`](/docs/hoon/reference/stdlib/4g/#rash) and [`+rush`](/docs/hoon/reference/stdlib/4g/#rush) are for parsing atoms, with `+rash` being
330+analogous to `+scan` and `+rush` being analogous to `+rust`. Under the hood, `+rash`
321331calls `+scan` after converting the input atom to a `tape`, and `+rush` does
322332similary for `+rust`.
323333
324334## Parser modifiers
325335
326−The standard library provides a number of gates that take a `rule` and
327−produce a new modified `rule` according to some process. We call these _parser modifiers_. These are
328−documented among the [parser builders](/docs/hoon/reference/stdlib/4f).
336+The standard library provides a number of gates that take a `rule` and produce a
337+new modified `rule` according to some process. We call these _parser modifiers_.
338+These are documented among the [parser
339+builders](/docs/hoon/reference/stdlib/4f).
329340
330−### `+ifix`
341+### [`+ifix`](/docs/hoon/reference/stdlib/4f/#ifix)
331342
332343`+ifix` modifies a `rule` so that it matches that `rule` only when it is
333344surrounded on both sides by text that matches a pair of `rule`s, which is discarded.
@@ -341,7 +352,7 @@ surrounded on both sides by text that matches a pair of `rule`s, which is discar
341352ASCII glyphs have counterparts of this sort, documented
342353[here](/docs/hoon/reference/stdlib/4h).
343354
344−### `+star` {#star}
355+### [`+star`](/docs/hoon/reference/stdlib/4f/#star) {#star}
345356
346357`+star` is used to apply a `rule` repeatedly. Recall that `+just` only parses
347358the first character in the input `tape.`
@@ -365,11 +376,32 @@ and we note that the parsing ceases when it fails.
365376[p=[p=1 q=4] q=[~ [p=[i='a' t=<|a a|>] q=[p=[p=1 q=4] q="b"]]]]
366377```
367378
379+We can combine `+star` with `+next` to just return the whole input:
380+
381+```
382+> ((star next) [[1 1] "aaabc"])
383+[p=[p=1 q=6] q=[~ [p=[i='a' t=<|a a b c|>] q=[p=[p=1 q=6] q=""]]]]
384+```
385+
386+### [`+cook`](/docs/hoon/reference/stdlib/4f/#cook)
387+
388+`+cook` takes a `rule` and a gate and produces a modified version of the `rule`
389+that passes the result of a successful parse through the given gate.
390+
391+Let's modify the rule `(just 'a')` so that it when it successfully parses `a`,
392+it returns the following letter `b` as the result.
393+
394+```
395+((cook |=(a=@ `@t`+(a)) (just 'a')) [[1 1] "abc"])
396+[p=[p=1 q=2] q=[~ u=[p='b' q=[p=[p=1 q=2] q="bc"]]]]
397+```
398+
399+
368400## Parser combinators
369401
370402Building complex parsers from simpler parsers is accomplished in Hoon with the
371403use of two tools: the monadic applicator rune
372−[`;~`](/docs/hoon/reference/rune/mic#micsig) and [parsing
404+[`;~`](/docs/hoon/reference/rune/mic/#-micsig) and [parsing
373405combinators](/docs/hoon/reference/stdlib/4e). First we introduce a few
374406combinators, then we examine more closely how `;~` is used to chain them together.
375407
@@ -380,11 +412,11 @@ The syntax to combine `rule`s is
380412```
381413
382414The `rule`s are composed together using the combinator as an
383−intermediate function, which takes product of a `rule` (an `edge`) and a `rule` and turns
415+intermediate function, which takes the product of a `rule` (an `edge`) and a `rule` and turns
384416it into a sample (a `nail`) for the next `rule` to handle. We elaborate on this
385417behavior [below](#micsig).
386418
387−### `+plug`
419+### [`+plug`](/docs/hoon/reference/stdlib/4e/#plug)
388420
389421`+plug` simply takes the `nail` in the `edge` produced by one rule and passes it
390422to the next `rule`, forming a cell of the results as it proceeds.
@@ -394,7 +426,7 @@ to the next `rule`, forming a cell of the results as it proceeds.
394426['star' 'ship']
395427```
396428
397−### `+pose`
429+### [`+pose`](/docs/hoon/reference/stdlib/4e/#pose)
398430
399431`+pose` tries each `rule` you hand it successively until it finds one that
400432works.
@@ -406,7 +438,7 @@ works.
406438'b'
407439```
408440
409−### `+glue`
441+### [`+glue`](/docs/hoon/reference/stdlib/4e/#glue)
410442
411443`+glue` parses a delimiter in between each `rule` and forms a cell of the
412444results of each `rule`.
@@ -417,15 +449,17 @@ results of each `rule`.
417449> (scan "a,b,a" ;~((glue com) (just 'a') (just 'b')))
418450{1 4}
419451syntax error
452+> (scan "a,b,a" ;~((glue com) (just 'a') (just 'b') (just 'a')))
453+['a' 'b' 'a']
420454```
421455
422−### `;~` {#micsig}
456+### [`;~`](/docs/hoon/reference/rune/mic/#-micsig) {#micsig}
423457
424458Understanding the rune `;~` is essential to building parsers with Hoon. Let's
425459take this opportunity to think about it carefully.
426460
427−The `rule` created by `;~(combinator [list rule])` may be understood
428−inductively. To do this, let's consider the base case where our `[list rule]` has only a
461+The `rule` created by `;~(combinator (list rule))` may be understood
462+inductively. To do this, let's consider the base case where our `(list rule)` has only a
429463single entry.
430464
431465```
@@ -433,9 +467,9 @@ single entry.
433467'star'
434468```
435469
436−Our output is identical to that given by `scan "star" (jest 'star')`. This is to
470+Our output is identical to that given by `(scan "star" (jest 'star'))`. This is to
437471be expected. The combinator `+plug` is specifically used for chaining together
438−`rule`s in the `[list rule]`, but if there is only one `rule`, there is nothing
472+`rule`s in the `(list rule)`, but if there is only one `rule`, there is nothing
439473to chain. Thus, swapping out `+plug` for another combinator makes no difference here:
440474
441475```
@@ -445,7 +479,7 @@ to chain. Thus, swapping out `+plug` for another combinator makes no difference
445479'star'
446480```
447481
448−`;~` and the combinator only begin to play a role once the `[list rule]` has at
482+`;~` and the combinator only begin to play a role once the `(list rule)` has at
449483least two elements. So let's look at an example done with `+plug`, the simplest
450484combinator.
451485
@@ -470,8 +504,9 @@ syntax error
470504## Parsing numbers
471505
472506Functions for parsing numbers are documented in [4j: Parsing (Bases and Base
473−Digits)](/docs/hoon/reference/stdlib/4j). In particular, `dem` is a `rule`
474−for parsing decimal numbers.
507+Digits)](/docs/hoon/reference/stdlib/4j). In particular,
508+[`dem`](/docs/hoon/reference/stdlib/4i/#dem) is a `rule` for parsing decimal
509+numbers.
475510
476511```
477512> (scan "42" dem)
@@ -485,18 +520,23 @@ for parsing decimal numbers.
485520Naively attempting to write a recursive `rule`, i.e. like
486521
487522```
488−> |-(;~(pose den ;~(pose $ (easy ~))))
523+> |-(;~(plug prn ;~(pose $ (easy ~))))
489524```
490525
491−results in an error.
492−
526+results in an error:
493527```
494528-find.,.+6
495529-find.,.+6
496530rest-loop
497531```
498532
499−Thus some special sauce is required, the `+knee` function.
533+Here, [`+prn`](/docs/hoon/reference/stdlib/4i/#prn) is a `rule` used
534+to parse any printable character, and
535+[`+easy`](/docs/hoon/reference/stdlib/4f/#easy) is a `rule` that always returns a
536+constant (`~` in this case) regardless of the input.
537+
538+Thus some special sauce is required, the
539+[`+knee`](/docs/hoon/reference/stdlib/4f/#knee) function.
500540
501541`+knee` takes in a noun that is the default value of the parser, typically given
502542as the bunt value of the type that the `rule` produces, as well as a gate that
@@ -505,19 +545,11 @@ in the `rule` in a manner acceptable to the compiler. Thus the preferred manner
505545to write the above `rule` is as follows:
506546
507547```hoon
508−++ pars
509− |-
510− ;~ plug prn
511− ;~ pose
512− (knee *tape |.(^$))
513− (easy ~)
514− ==
515− ==
548+|-(;~(plug prn ;~(pose (knee *tape |.(^$)) (easy ~))))
516549```
517550
518551You may want to utilize the `~+` rune when writing recursive parsers to cache
519−the parser to improve performance. In [parsing arithmetic
520−expressions](#parsing-arithmetic-expressions) we will be writing a recursive
552+the parser to improve performance. In the following section, we will be writing a recursive
521553parser making use of `+knee` and `~+` throughout.
522554
523555# Parsing arithmetic expressions
@@ -536,15 +568,15 @@ To build a parser it is a helpful exercise to first describe its
536568formal mathematical definition, but we will manage to get by here describing the grammar
537569for arithmetic expressions informally.
538570
539−First lets look at the code we're going to use, and then dive into explaining
571+First let's look at the code we're going to use, and then dive into explaining
540572it. If you'd like to follow along, save the following as `expr-parse.hoon` in
541573your `gen/` folder.
542574
543575```hoon
544576:: expr-parse: parse arithmetic expressions
545577::
546−|= xprs=tape
547−|^ (scan xprs expr)
578+|= math=tape
579+|^ (scan math expr)
548580++ factor
549581 %+ knee *@ud
550582 |. ~+
@@ -552,19 +584,19 @@ your `gen/` folder.
552584 dem
553585 (ifix [pal par] expr)
554586 ==
555−++ turm
587+++ term
556588 %+ knee *@ud
557589 |. ~+
558590 ;~ pose
559− ((slug mul) tar ;~(pose factor turm))
591+ ((slug mul) tar ;~(pose factor term))
560592 factor
561593 ==
562594++ expr
563595 %+ knee *@ud
564596 |. ~+
565597 ;~ pose
566− ((slug add) lus ;~(pose turm expr))
567− turm
598+ ((slug add) lus ;~(pose term expr))
599+ term
568600 ==
569601--
570602```
@@ -627,16 +659,16 @@ them by folding with a binary gate. In this case, our delimiter is `+` and our
627659binary gate is `+add`. That is to say, we will split the input string into terms
628660and expressions separated by luses, parse each term and expression until they
629661reduce to a `@ud`, and then add them together. This is accomplished with the
630−rule `((slug add) lus ;~(pose turm expr))`.
662+`rule` `((slug add) lus ;~(pose term expr))`.
631663
632−If the above `rule` does not parse the expression, it must be a `turm`, so the
633−`tape` is automatically passed to `+turm` to be evaluated. Again we use `;~` and `pose` to
664+If the above `rule` does not parse the expression, it must be a `term`, so the
665+`tape` is automatically passed to `+term` to be evaluated. Again we use `;~` and `pose` to
634666accomplish this:
635667
636668```hoon
637669;~ pose
638− ((slug add) lus ;~(pose turm expr))
639− turm
670+ ((slug add) lus ;~(pose term expr))
671+ term
640672==
641673```
642674
@@ -647,15 +679,15 @@ the same reasons.
647679
648680A _term_ is either a factor times a term or a factor. This is handled similarly
649681for expressions, we just need to swap `lus` for `tar`, `add` for `mul`, and
650−`;~(pose factor turm)` instead of `;~(pose turm expr)`.
682+`;~(pose factor term)` instead of `;~(pose term expr)`.
651683
652684```hoon
653685++ expr
654686 %+ knee *@ud
655687 |. ~+
656688 ;~ pose
657− ((slug add) lus ;~(pose turm expr))
658− turm
689+ ((slug add) lus ;~(pose term expr))
690+ term
659691 ==
660692```
661693