This module contains the compile-time state of a parser, which is used to aid code generation.

Since: 1.4.0.0

Subroutines are the representations of let-bindings or recursive parsers in the original user program. They are factored out to prevent code-explosion.

The names of these bindings are helpfully stored within the Ctx and can be accessed statically. While the initial context is always populated with the top-level recursive bindings, additional bindings can be added "dynamically" during evaluation, for instance iterative bindings and recursive bindings that capture their free-registers.

Similar to the subroutines, join points (or Φ-nodes) are used by the parsley engine to factor out common branches of code. When generated, access to these bindings is available via the Ctx.

Registers are used within parsley to persist state across different parts of a parser. Across recursion and call-boundaries, these materialise as STRefs. These are stored in the Ctx and can be looked up when required.

However, parsley does not mandate that registers must exist in this form. Registers can be subject to caching, where a register's static "most-recently known" may be stored within the Ctx in addition to the "true" binding. This can, in effect, mean that registers do not exist at runtime. Both forms of register data can be extracted, however exceptions will guard against mis-management.

The debug combinator generates runtime diagnostic information. To make this more ergonomic, it would be nice to indent nested debug info. To do this perfectly, a debug level that controls indentation would need to be added to Γ. This is problematic since, without a lot of work and complexity, it would introduce a runtime penalty for not just debug parsers, but all other parsers too. As a compromise, the debug level is stored purely statically in the Ctx: the consequence is that the indentation level resets across a call-boundary.

The Offset type refines dynamic offsets with statically known properties such as input consumed and the source of the offset. These sources are unique and must be generated statically, with "local" Reader semantics. This means that the Ctx lends itself nicely to managing the pool of fresh offset names.

Parsley has analysis in place to factor out length checks when it is statically known that n tokens must be consumed in order for a parser to succeed. Part of this analysis is the cut analysis performed in the frontend, and then the coins analysis in the backend during code generation. The meta instructions that reference "coins" interact with a system during interpretation called the "Piggy-bank" system: this is all stored and accessed via the Ctx.

The system works like this:

• The Ctx stores two components: some coins and some piggybanks.
• When there are coins present in the Ctx, these can be "spent" to read a token without emitting a length check for it (the guarantee is that a length check was generated to get hold of those coins).
• When the coins run out a piggy-bank can be broken to get more coins: this should generate a length check for value of the coins in the bank
• When all the piggy-banks are exhausted, a length check must be generated for each token that is consumed.
• When adding coins into the system, if the Ctx is bankrupt, then the coins are added immediately along with a length check, otherwise a piggy-bank is added.

These are the basic principles behind this system, and it works effectively. There are some extra edge-case operations that are described in their corresponding documentation. The reason why piggy-banks are stored in the context and not consumed immediately to add to the coin count is so that length checks are delayed to the last possible moment: you should have used all of your current allocation before asking for more!

In addition to this above system, Parsley stores previously read characters in a rewind queue: this means that when backtracking is performed (i.e. when looking ahead) the characters can be statically rewound and made available for free.