Safe Haskell | None |
---|---|
Language | Haskell2010 |
Pinchot provides a simple language that you use to write a Haskell program that describes a context-free grammar. When run, this program creates a value that stores your context-free grammar. You can then use Template Haskell to take this value and generate a series of data types that correspond to your context-free grammar. You can also use Template Haskell to create an Earley parser that will parse all strings in the context-free language.
For examples, please consult Pinchot.Examples.
You should also look at the BNF Converter.
http://bnfc.digitalgrammars.com
Primary differences between BNFC and this library:
- the BNF Converter works as a standalone binary that parses text BNF files. With Pinchot you specify your grammar in Haskell.
- the BNF Converter currently generates many more outputs, such as LaTeX. It also generates code for many languages. Pinchot only works in Haskell.
- the BNF Converter generates input for parser generators like Happy and Bison. Pinchot currently only generates input for the Haskell Earley library.
- Pinchot integrates seamlessly into Haskell using Template Haskell.
- the BNF Converter is GPL. Pinchot is BSD3.
Pinchot grows and harvests syntax trees, so it is named after Gifford Pinchot, first chief of the United States Forest Service.
- data Intervals a
- include :: a -> a -> Intervals a
- exclude :: a -> a -> Intervals a
- solo :: a -> Intervals a
- pariah :: a -> Intervals a
- data Pinchot t a
- type RuleName = String
- type AlternativeName = String
- data Rule t
- terminal :: RuleName -> Intervals t -> Pinchot t (Rule t)
- terminalSeq :: RuleName -> Seq t -> Pinchot t (Rule t)
- nonTerminal :: RuleName -> Seq (AlternativeName, Seq (Rule t)) -> Pinchot t (Rule t)
- union :: RuleName -> Seq (Rule t) -> Pinchot t (Rule t)
- record :: RuleName -> Seq (Rule t) -> Pinchot t (Rule t)
- list :: Rule t -> Pinchot t (Rule t)
- list1 :: Rule t -> Pinchot t (Rule t)
- option :: Rule t -> Pinchot t (Rule t)
- wrap :: RuleName -> Rule t -> Pinchot t (Rule t)
- label :: String -> Rule t -> Rule t
- (<?>) :: Pinchot t (Rule t) -> String -> Pinchot t (Rule t)
- type MakeOptics = Bool
- makeOptics :: MakeOptics
- noOptics :: MakeOptics
- allRulesToTypes :: Lift t => MakeOptics -> Name -> Seq Name -> Pinchot t a -> DecsQ
- ruleTreeToTypes :: Lift t => MakeOptics -> Name -> Seq Name -> Pinchot t (Rule t) -> DecsQ
- allRulesRecord :: Qualifier -> Name -> Pinchot t a -> DecsQ
- type Qualifier = String
- earleyGrammar :: Lift t => Qualifier -> Pinchot t (Rule t) -> Q Exp
- allEarleyGrammars :: Lift t => Qualifier -> Name -> Pinchot t a -> DecsQ
- earleyProduct :: Lift t => Qualifier -> Qualifier -> Pinchot t a -> ExpQ
Intervals
include :: a -> a -> Intervals a Source
Include a range of symbols in the Intervals
. For instance, to
include the characters
, a
, and b
, use c
include
.a
c
Simple production rules
Constructs new Rule
s. 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 Rule
s 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.
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 AlternativeName = String Source
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 single production rule. It may be a terminal or a non-terminal.
Creates a terminal production rule.
Creates a production for a sequence of terminals. Useful for parsing specific words.
:: RuleName | |
-> Seq (AlternativeName, Seq (Rule t)) | Alternatives. There must be at least one alternative;
otherwise, an error will result. In each pair |
-> Pinchot t (Rule t) |
Creates a new non-terminal production rule.
:: RuleName | |
-> Seq (Rule t) | List of alternatives. There must be at least one alternative; otherwise a compile-time error will occur. |
-> Pinchot t (Rule t) |
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.
:: RuleName | The name of this rule, which is used both as the type name and the name of the sole data constructor. |
-> Seq (Rule t) | The right-hand side of this rule. This sequence can be empty, which results in an epsilon production. |
-> Pinchot t (Rule t) |
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.
Rules that modify other rules
Creates a newtype wrapper.
label :: String -> Rule t -> Rule t Source
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.
Transforming a Pinchot value to code
Creating data types
type MakeOptics = Bool Source
Should optics be made?
makeOptics :: MakeOptics Source
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
:
, wherePrism'
a ba
is the type of the terminal token (oftenChar
) andb
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
:
, wherePrism'
(Seq
a) ba
is the type of the terminal token (oftenChar
) andb
is the type of this particular production. As withterminal
this gives you a safe way to insert values into the types made withterminalSeq
.nonTerminal
: onePrism'
for each data constructor (even if there is only one data constructor)union
: onePrism
for each data constructor (even if there is only one data constructor)record
: oneLens
for each fieldlist
:Wrapped
, wrapping aSeq
alist1
:Wrapped
, wrapping a pair(a,
Seq
a)option
:Wrapped
, wrapping aMaybe
awrap
:Wrapped
, wrapping the underlying type
Do not make any optics.
:: Lift t | |
=> MakeOptics | |
-> Name | Terminal type constructor name. Typically you will use the Template Haskell quoting mechanism to get this. |
-> Seq Name | What to derive. For instance, you might use |
-> Pinchot t a | The return value from the |
-> DecsQ |
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.
:: Lift t | |
=> MakeOptics | |
-> Name | Terminal type constructor name. Typically you will use the Template Haskell quoting mechanism to get this. |
-> Seq Name | What to derive. For instance, you might use |
-> Pinchot t (Rule t) | A data type is created for the |
-> DecsQ |
:: Qualifier | Qualifier for data types created with |
-> Name | Name of terminal type. Typically you will get this through
the Template Haskell quoting mechanism, such as |
-> Pinchot t a | A record is created that holds a value for each |
-> DecsQ | When spliced, this will create a single declaration that is a
record with the name a'NAME where |
Creates a record data type that holds a value of type
Prod
rString
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.
Creating Earley grammars
type Qualifier = String Source
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.
:: Lift t | |
=> Qualifier | Qualifier for data types crated with |
-> Pinchot t (Rule t) | Creates an Earley parser for the |
-> Q Exp | When spliced, this expression has type
where
|
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.
:: Lift t | |
=> Qualifier | Qualifier for data types created with |
-> Name | Name for the terminal type; often this is |
-> Pinchot t a | Creates an Earley grammar for each |
-> DecsQ | When spliced, this is a list of declarations. Each
declaration has type
where
The name of each declaration is g'TYPE_NAME where TYPE_NAME is the name of the type defined in the
corresponding |
Creates an Earley grammar for each Rule
created in a
Pinchot
. For a Pinchot
with a large number of Rule
s, 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
.
:: Lift t | |
=> Qualifier | Qualifier for data types created with |
-> Qualifier | Module prefix for the type created with |
-> Pinchot t a | Creates an Earley grammar that contains a |
-> ExpQ | When spliced, |