@@ -0,0 +1,79 @@
1++++
2+title = "Parsing tutorial"
3+weight = 12
4+template = "doc.html"
5++++
6+
7+# Parsing Tutorial
8+
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.
13+
14+## What is parsing?
15+
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.
22+
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.
27+
28+## Functional parsers
29+
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
33+parsers_.
34+
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
37+parsers.
38+
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:
46+```
47+> parse(integer, "1")
48+(1, "")
49+> parse(integer, "123")
50+(1, "23")
51+```
52+What if we wish to parse the rest of the string? We would need to apply the
53+`parse(integer, -)` function again:
54+```
55+> parse(integer, parse(integer, "123"))
56+(12, "3")
57+> parse(integer, parse(integer, parse(integer, "123")))
58+(123, "")
59+```
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.
69+
70+# Parsing in Hoon
71+
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.
74+
75+## Basic types
76+
77+hair, edge, etc
78+
79+## Parsing arithmetic expressions