Documentation

Type synonym for the name of a production rule. This will be the name of the type constructor for the corresponding type that will be created, so this must be a valid Haskell type constructor name.

If you are creating a terminal, option, list, list1, or wrap, the RuleName will also be used for the name of the single data construtor. If you are creating a nonTerminal, you will specify the name of each data constructor with AlternativeName.

Type synonym the the name of an alternative in a nonTerminal. This name must not conflict with any other data constructor, either one specified as an AlternativeName or one that was created using terminal, option, list, or list1.

A branch in a sum rule. In Branch s ls, s is the name of the data constructor, and ls is the list of rules that this branch produces.

A single production rule. It may be a terminal or a non-terminal.

Name a Rule for use in error messages. If you do not name a rule using this combinator, the rule's type name will be used in error messages.

Infix form of label for use in a Pinchot; handy for use in do or mdo notation.

Errors that may arise when constructing an AST.

Constructs new Rules. t is the type of the token; often this will be Char.

Pinchot is a Monad and an Applicative so you can combine computations using the usual methods of those classes. Also, Pinchot is a MonadFix. This allows you to construct a Rule that depends on itself, and to construct sets of Rules that have mutually recursive dependencies. MonadFix also allows you to use the GHC RecursiveDo extension. Put

{-# LANGUAGE RecursiveDo #-}

at the top of your module, then use mdo instead of do. Because an mdo block is recursive, you can use a binding before it is defined, just as you can in a set of let bindings.

Runs a Pinchot with a starting empty state. Fails in the Q monad if the grammar is bad.

Creates a terminal production rule.

Creates a production for a sequence of terminals. Useful for parsing specific words.

Creates a new non-terminal production rule.

Creates a new non-terminal production rule where each alternative produces only one rule. The constructor name for each alternative is

RULE_NAME'PRODUCTION_NAME

where RULE_NAME is the name of the rule itself, and PRODUCTION_NAME is the rule name for what is being produced. For an example, see Suffix.

Currently there is no way to change the names of the constructors; however, you can use nonTerminal, which is more flexible.

Creates a new non-terminal production rule with only one alternative where each field has a record name. The name of each record is:

_r'RULE_NAME'INDEX'FIELD_TYPE

where RULE_NAME is the name of this rule, INDEX is the index number for this field (starting with 0), and FIELD_TYPE is the type of the field itself. For an example, see Address.

Currently there is no way to change the names of the record fields.

Creates a rule for the production of a sequence of other rules. The name for the created Rule is the name of the Rule to which this function is applied, with 'Seq appended.

Creates a rule for a production that appears at least once. The name for the created Rule is the name of the Rule to which this function is applied, with 'Seq1 appended.

Creates a rule for a production that optionally produces another rule. The name for the created Rule is the name of the Rule to which this function is applied, with 'Maybe appended to the end.

Creates a newtype wrapper.

Gets all ancestor Rules. Skips duplicates.

Returns both this Rule and any Rules that are ancestors.

Given a sequence of Rule, determine which rules are on a right-hand side before they are defined.

Field name - without a leading underscore

TH helper like dyn but for patterns

Creates a prism for a terminal type. Although a newtype wraps each terminal, do not make a Wrapped or an Iso, because the relationship between the outer type and the type that it wraps typically is not isometric. Thus, use a Prism instead, which captures this relationship properly.

Should optics be made?

Creates optics.

If you use this option, you will need {-# LANGUAGE TypeFamilies #-}

at the top of the module into which you splice in the declarations, because you will get instances of Wrapped.

Creates the listed optics for each kind of Rule, as follows:

• terminal: Prism' a b, where a is the type of the terminal token (often Char) and b is the type of this particular production. For an example, see _Comma.

>>> ',' ^? _Comma
Just (Comma ',')
>>> 'a' ^? _Comma
Nothing
>>> Comma ',' ^. re _Comma
','

Thus this gives you a safe way to insert tokens into types made with terminal (useful if you want to construct a syntax tree.)

• terminalSeq: Prism' (Seq a) b, where a is the type of the terminal token (often Char) and b is the type of this particular production. As with terminal this gives you a safe way to insert values into the types made with terminalSeq.
• nonTerminal: one Prism' for each data constructor (even if there is only one data constructor)
• union: one Prism for each data constructor (even if there is only one data constructor)
• record: one Lens for each field
• list: Wrapped, wrapping a Seq a
• list1: Wrapped, wrapping a pair (a, Seq a)
• option: Wrapped, wrapping a Maybe a
• wrap: Wrapped, wrapping the underlying type

Do not make any optics.

Creates data types for every Rule created in the Pinchot. The data types are created in the same order in which they were created in the Pinchot. When spliced, the DecsQ is a list of declarations, each of which is an appropriate data or newtype. For an example use of allRulesToTypes, see Pinchot.Examples.PostalAstAllRules.

Also creates bindings whose names are prefixed with t'. Each of these is a function that, when given a particular production, reduces it to a sequence of terminal symbols.

Creates data types only for the Rule returned from the Pinchot, and for its ancestors.

Also creates bindings whose names are prefixed with t'. Each of these is a function that, when given a particular production, reduces it to a sequence of terminal symbols.

Creates a lazy pattern for all the given names. Adds an empty pattern onto the front. This is the counterpart of bigTuple. All of the given names are bound. In addition, a single, wildcard pattern is bound to the front.

For example, lazyPattern (map mkName ["x", "y", "z"]) gives a pattern that looks like

~(_, (x, (y, (z, ()))))

The idea is that the named patterns are needed so that the recursive do notation works, and that the wildcard pattern is the return value, which is not needed here.

Creates a big tuple. It is nested in the second element, such as (1, (2, (3, (4, ())))). Thus, the big tuple is terminated with a unit value. It resembles a list where each tuple is a cons cell and the terminator is unit.

Creates an Earley grammar for a given Rule. For examples of how to use this, see the source code for Pinchot.Examples.PostalAstRuleTree and for Pinchot.Examples.PostalAstAllRules.

Builds a recursive do expression (because TH has no support for mdo notation).

Creates an Earley grammar for each Rule created in a Pinchot. For a Pinchot with a large number of Rules, this can create a large number of declarations that can take a long time to compile--sometimes several minutes. For lower compilation times, try earleyProduct.

Creates a production declaration for a Rule.

Many functions take an argument that holds the name qualifier for the module that contains the data types created by applying ruleTreeToTypes or allRulesToTypes to the 'Pinchot.'

You have to make sure that the data types you created with ruleTreeToTypes, allRulesToTypes, or allRulesRecord are in scope. The spliced Template Haskell code has to know where to look for these data types. If you did an unqualified import or if the types are in the same module as is the splice of earleyParser, just pass the empty string here. If you did a qualified import, use the appropriate qualifier here.

For example, if you used import qualified MyAst, pass "MyAst" here. If you used import qualified Data.MyLibrary.MyAst as MyLibrary.MyAst, pass "MyLibrary.MyAst" here.

I recommend that you always create a new module and that all you do in that module is apply ruleTreeToTypes or allRulesToTypes, and that you then perform an import qualified to bring those names into scope in the module in which you use a function that takes a Qualifier argument. This avoids unlikely, but possible, issues that could otherwise arise due to naming conflicts.

Creates a record data type that holds a value of type

Prod r String t a

for every rule created in the Pinchot. r is left universally quantified, t is the token type (typically Char) and a is the type of the rule.

This always creates a single product type whose name is Productions; currently the name cannot be configured.

For an example of the use of allRulesRecord, please see Pinchot.Examples.AllRulesRecord.

Creates a Grammar that contains a Prod for every Rule created in the Pinchot.