@@ -0,0 +1,79 @@
2+title = "Parsing tutorial"
9+This document serves as an introduction to parsing text with Hoon. No prior
10+knowledge of parsing is required, and we will explain the basic structure of how
11+parsing works in a purely functional language such as Hoon before moving on to
12+how it is implemented in Hoon.
16+A program which takes a raw sequence of characters as an input and produces a data
17+structure as an output is known as a _parser_. The data structure produced
18+depends on the use case, but often it may be represented as a tree, and the
19+output is thought of as a structural representation of the input. Parsers are ubiquitous in
20+computing, commonly used in applications such as reading files, compiling
21+source code, or understanding commands input in a command line interface.
23+Parsing a string is rarely done all at once. Instead, it is usually done
24+character-by-character, and the return contains the data structure representing
25+what has been parsed thus far as well as the remainder of the string to be
26+parsed. They also need to be able to fail in case the input is improperly formed.
30+How parsers are built varies greatly depending on what sort of programming
31+language it is written in. As Hoon is a functional programming language, we will
32+be focused on understanding _functional parsers_, also known as _combinator
35+Functional parsers are built piece by piece from simple irreducible components
36+that are plugged into one another in various ways to form more complex
39+The basic building blocks, or primitives, are parsers that read only a
40+single character. There are frequently a few types of possible input characters,
41+such as letters, numbers, and symbols. For example, `parse(integer, "1")` calls
42+the parsing routine on the string `"1"` and looks for an integer, and so it
43+returns the integer `1`. However, taking into account what was said above about
44+parsers returning the unparsed portion of the string as well, we should
45+represent this return as a tuple. So we should expect something like this:
49+> parse(integer, "123")
52+What if we wish to parse the rest of the string? We would need to apply the
53+`parse(integer, -)` function again:
55+> parse(integer, parse(integer, "123"))
57+> parse(integer, parse(integer, parse(integer, "123")))
60+So we see that we can parse strings larger than one character by stringing
61+together parsing functions for single characters. Thus in addition to parsing
62+functions for single input characters, we want _parser combinators_ that
63+allow you to combine two or more simple parsers to form more complex ones.
64+Combinators come in a few shapes and sizes, and typical operations they may
65+perform would be to repeat the same parsing operation until the string is
66+consumed, try a few different parsing operations until one of them works,
67+or perform a sequence of parsing operations. We will see how all of this is done
68+with Hoon in the [Parsing in Hoon](#parsing-in-hoon) section.
72+In this section we will cover the basic types and functions that are utilized for parsing in
73+Hoon, and then build some simple parsers.
79+## Parsing arithmetic expressions