@@ -440,29 +440,150 @@ parser making use of `+knee` and `~+` throughout.
440440
441441In this section we will be applying what we have learned to write a parser for
442442arithmetic expressions in Hoon. That is, we will make a `rule` that takes in
443−`tape`s of the form `"(2+3)*4*"` and returns `20` as a `@ud`.
443+`tape`s of the form `"(2+3)*4"` and returns `20` as a `@ud`.
444444
445445We call a `tape` consisting of some consistent arithmetic string of numbers,
446−`+,*`, `(`, and `)` an _expression_.
446+`+,*`, `(`, and `)` an _expression_. We wish to build a `rule` that takes in an
447+expression and returns the result of the arithmetic computation described by the
448+expression as a `@ud`.
449+
450+To build a parser it is a helpful exercise to first describe its
451+[grammar](https://en.wikipedia.org/wiki/Parsing_expression_grammar). This has a
452+formal mathematical definition, but we will manage to get by here describing the grammar
453+for arithmetic expressions informally.
454+
455+First lets look at the code we're going to use, and then dive into explaining
456+it. If you'd like to follow along, save the following as `expr-parse.hoon` in
457+your `gen/` folder.
458+```hoon
459+:: This generator parses arithmetic expressions
460+::
461+|= [xprs=tape]
462+=<
463+(print xprs)
464+|%
465+++ int @ud
466+++ factor
467+ %+ knee *int
468+ |. ~+ ;~ pose
469+ dem
470+ (ifix [lit rit] expr)
471+ ==
472+++ turm
473+ %+ knee *int
474+ |. ~+ ;~ pose
475+ ((slug mul) tar ;~(pose factor turm))
476+ factor
477+ ==
478+++ expr
479+ %+ knee *int
480+ |. ~+ ;~ pose
481+ ((slug add) lus ;~(pose turm expr))
482+ turm
483+ ==
484+++ print
485+ |= [message=tape]
486+ (scan message expr)
487+--
488+```
489+
490+### Factors, terms, and expressions
491+
492+Our grammar consists of three `rule`s: one for factors, one for terms, and one
493+for expressions.
494+
495+#### Factors
496+
497+```hoon
498+++ factor
499+ %+ knee *int
500+ |. ~+ ;~ pose
501+ dem
502+ (ifix [lit rit] expr)
503+ ==
504+```
505+
506+A _factor_ is either a decimal number or an expression surrounded by parentheses. Put
507+into Hoon terms, a decimal number is parsed by the `rule` `+dem` and an
508+expression is parsed by removing the surrounding parentheses and then passing
509+the result to the expression parser arm `+expr`, given by the `rule` `(ifix [lit
510+rit] expr)`. Since we want to parse our expression with one or the other, we
511+chain these two `rule`s together using the monadic composition rune `;~` along
512+with `+pose`, which says to try each rule in succession until one of them works.
513+
514+Since expressions ultimately reduce to factors, we are actually building a
515+recursive rule. Thus we need to make use of `+knee`. The first argument for
516+`+knee` is `*int`, since our final answer should be a `@ud`, to which we have
517+assigned the macro `int`.
518+
519+Then follows the definition of the gate utilized by `+knee`:
520+```hoon
521+ |. ~+ ;~ pose
522+ dem
523+ (ifix [lit rit] expr)
524+ ==
525+```
526+`|.` is used instead of `|-` since... `~+` is used to cache results as we go -
527+there is no point in computing `2+2` more than once. Then follows the `rule` we
528+described above.
529+
530+#### Parsing expressions
531+
532+An _expression_ is either a term plus an expression or a term.
533+
534+In the case of a
535+term plus an expression, we actually must compute what that equals. Thus we will
536+make use of [`+slug`](@/docs/reference/library/4f.md#slug), which parses a
537+delimited list into `tape`s separated by a given delimiter and then composes
538+them by folding with a binary gate. In this case, our delimiter is `+` and our
539+binary gate is `+add`. That is to say, we will split the input string into terms
540+and expressions separated by luses, parse each term and expression until they
541+reduce to a `@ud`, and then add them together. This is accomplished with the
542+rule `((slug add) lus ;~(pose turm expr))`.
447543
448−I probably need to figure out how to break this into a tree and do all the
449−adding and multiplying at the end
544+If the above `rule` does not parse the expression, it must be a `turm`, so we
545+pass the `tape` to `+turm` to be evaluated. Again we use `;~` and `pose` to
546+accomplish this:
547+
548+```hoon
549+;~ pose
550+ ((slug add) lus ;~(pose turm expr))
551+ turm
552+ ==
553+```
554+
555+The rest of the `+expr` arm is structured just like how `+factor` is, and for
556+the same reasons.
450557
451−### Parsing expressions
452558
453−An expression is either a term plus an expression or a term.
559+#### Parsing terms
454560
455−### Parsing terms
561+A _term_ is either a factor times a term or a factor. This is handled similarly
562+for expressions, we just need to swap `lus` for `tar`, `add` for `mul`, and
563+`;~(pose factor turm)` instead of `;(pose turm expr)`.
456564
457−A term is either a factor times a term or a factor.
565+```hoon
566+++ expr
567+ %+ knee *int
568+ |. ~+ ;~ pose
569+ ((slug add) lus ;~(pose turm expr))
570+ turm
571+ ==
572+```
458573
459−### Parsing factors
574+### Try it out
460575
461−A factor is either an expression surrounded by parentheses or an integer. To parse
462−a factor, we first check if it is a number and apply `dem` if so, otherwise
463−we strip the parentheses and apply the `rule` for parsing expressions.
576+Let's feed some expressions to `+expr-parse` and see how it does.
464577
465578```
466−> (scan "(5)" ;~(pose dem (ifix [lit rit] dem)))
467−5
579+> +expr-parse "3"
580+3
581+> +expr-parse "3+3"
582+6
583+> +expr-parse "3+3+(2*3)+(4+2)*(4+1)"
584+42
585+> +expr-parse "3+3+2*3"
586+12
468587```
588+
589+As an exercise, add exponentiation (e.g. `2^3 = 8`) to `+expr-parse`.