Packrat caches for the core/parse function.

A single cache instance is *not* intended to be used for multiple
texts. Create a new cache for each new text.

Caches are implemented using the Cache protocol. This way you can
implement your own, if desired.

(fn
  ([text index]
    ...)
  ([text index result state]
   ...))

Parsers combinator functions.

Each combinator functions creates a parser function that is suitable
for use with core's main parse function, and many take other parser
functions as their argument; they are composable.

If you want to implement your own parser combinator, read on.
Otherwise, just look at the docstrings of the combinators
themselves.

The parsers returned by the combinators do not call other parsers
directly, as this could lead to stack overflows. So next to a
`->success` or `->error` result, it can also return a `->push`
result. This pushes another parser onto the virtual stack.

For this reason, a parser function has the following signature:

    (fn
      ([text index]
        ...)
      ([text index result state]
       ...))

The 2-arity variant is called when the parser was pushed onto the
stack. It receives the entire text and the index it should begin
parsing. If it returns a `push` result, the 4-arity variant is
called when that parser is done. It again receives the text and the
original index, but also the result of the pushed parser and any
state that was pushed with it.

Both arities can return a success, a set of errors, or a push. The
`crustimoney.results` namespace should be used for creating and
reading these results.

Before you write your own combinator, do realise that the provided
combinators are complete in the sense that they can parse any text.

(require '[crustimoney.combinators.experimental :as e])

(create-parser
  "root= <- stream
   expr= <- '{' [0-9]+ '}'"
  {:stream [::e/stream handle-expr
            [::e/recover [:ref :expr] [:regex ".*?}"]]})

Experimental combinators. These may get promoted, or changed,
or dismissed.

These combinators are not available in the string- or data-driven
grammar (yet). To use them with those, you can use the
`other-parsers` parameter of their respective `create-parser`
functions, like:

    (require '[crustimoney.combinators.experimental :as e])

    (create-parser
      "root= <- stream
       expr= <- '{' [0-9]+ '}'"
      {:stream [::e/stream handle-expr
                [::e/recover [:ref :expr] [:regex ".*?}"]]})

Note that the other-parsers here is written in vector-grammar
format. This is a little power-user trick, and allows you to declare
`ref`s that do not have to resolve immediatly on their creation.

The main parsing functions.

Create a parser based on a data grammar. The data is translated into
combinators.

Result constructors, accessors and predicates

Create a parser based on a string grammar. The grammar is translated
into combinators.

A basic vector-driven parser generator.