Groups of terminals. Create an Intervals using include, exclude, solo and pariah. Combine Intervals using mappend, which will combine both the included and excluded terminal symbols from each operand.

Include a range of symbols in the Intervals. For instance, to include the characters a, b, and c, use include a c. Example: rLetter.

Exclude a range of symbols in the Intervals. Each symbol that is excluded is not included in the Intervals, even if it is also included.

Include a single symbol. Example: rNorth.

Exclude a single symbol.

A non-empty sequence.

Convert a NonEmpty to a Seq.

Converts a non-empty Seq to a NonEmpty; Nothing if the Seq is empty.

Prepends a Seq to a NonEmpty.

Appends a Seq to a NonEmpty.

Associative operation that appends to NonEmpty.

Place a single item at the head of the NonEmpty.

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. Typically each context-free grammar that you write will have several production rules; you will want to make sure that every RuleName that you create for a single context-free grammar is unique. However, Pinchot currently does not check for uniqueness. If you use names that are not unique, GHC will give an error message when you try to splice the resulting code, as the data types will not have unique names.

A single production rule.

Type synonym the the name of an alternative in a nonTerminal. This name must not conflict with any other data constructor in your grammar.

Creates a terminal production rule. Example: rLetter.

Creates a non-terminal production rule. This is the most flexible way to create non-terminals. You can even create a non-terminal that depends on itself. Example: rLetters.

Creates a non-terminal production rule where each branch has only one production. This function ultimately uses nonTerminal. Each branch is assigned a BranchName that 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.

Example: rDirection.

Creates a production for a sequence of terminals. Useful for parsing specific words. Ultimately this is simply a function that creates a Rule using the record function.

In terminals n s, For each Char in the String, a Rule is created whose RuleName is n followed by an apostrophe followed by the index of the position of the Char.

Examples: rBoulevard.

Creates a newtype wrapper. Example: rCity.

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.

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

Example: rAddress.

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 'Opt appended to the end.

Example: rOptNewline.

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 'Star appended.

Example: rPreSpacedWord.

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 'Plus appended.

Example: rDigits.

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 synonym for label. Example: rDigit.

Many functions take an argument that holds the name qualifier for the module that contains the data types created by applying a function such as syntaxTrees or earleyProduct.

You will have to make sure that these data types 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 the function that takes a Qualifier argument, 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 syntaxTrees or earleyProduct, 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.

Makes the top-level declarations for each given Rule and for all ancestors of the given Rules. Since ancestors are included, you can get the entire tree of types that you need by applying this function to a single start symbol. Example: Pinchot.Examples.SyntaxTrees.

Creates a record data type that holds a value of type

Prod r String (t, a) (p t a)

where

• r is left universally quantified
• t is the token type (often Char)
• a is any additional information about each token (often Loc)
• p is the type of the particular production

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

Example: Pinchot.Examples.SyntaxTrees.

Creates a Wrapped instance for each Rule and its ancestors, if there is an instance. Only terminal, wrap, opt, star, and plus get instances of Wrapped.

This must be spliced in the same module in which the syntax tree types are created; this way, no orphans are created. Since ancestors are included, you can get the entire tree of types that you need by applying this function to a single start symbol.

Example: Pinchot.Examples.SyntaxTrees.

Creates optics declarations for a Rule, if optics can be made for the Rule:

• terminal gets a single Prism
• nonTerminal gets a Prism for each constructor
• record gets a single Lens
• wrap, opt, star, and plus do not get optics.

Each rule in the sequence of Rule, as well as all ancestors of those Rules, will be handled.

Example: Pinchot.Examples.RulesToOptics.

Creates an expression that has type

Grammar r (Prod r String (c, a) (p c a))

where r is left universally quantified; c is the terminal type (often Char), a is arbitrary metadata about each token (often Loc) and p is the data type corresponding to the given Rule.

Example: addressGrammar.

Creates a Grammar that contains a Prod for every given Rule and its ancestors. Example: addressAllProductions.

For the given rule, returns an expression that has type of either

Production a -> Seq (t, a)

or

Production a -> NonEmpty (t, a)

where Production is the production corresponding to the given Rule, and t is the terminal token type. NonEmpty is returned for productions that must always contain at least one terminal symbol; for those that can be empty, Seq is returned.

Example: terminalizeAddress.

For all the given rules and their ancestors, creates declarations that reduce the rule and all its ancestors to terminal symbols. Each rule gets a declaration named t'RULE_NAME where RULE_NAME is the name of the rule. The type of the declaration is either

Production a -> Seq (t, a)

or

Production a -> NonEmpty (t, a)

where Production is the production corresponding to the given Rule, t is the terminal token type (often Char), and a is arbitrary metadata about each token (often Loc). NonEmpty is returned for productions that must always contain at least one terminal symbol; for those that can be empty, Seq is returned.

Example: Pinchot.Examples.Terminalize.

A location.

Takes any ListLike value based on Char (Seq, Text, String, etc.) and creates a Seq which pairs each Char with its location. Example: locatedFullParses.

Breaks a ListLike into a Seq but does not assign locations.

Obtains all full Earley parses from a given input string, after assigning a location to every Char. Example: address.