parcon
index
/home/boydam/workspace/Parcon-python/parcon/parcon.py

parcon.py
 
Parser combinator library written by Alexander Boyd.
 
Copyright 2011 Alexander Boyd. Released under the terms of the GNU Lesser
General Public License. 
 
2011.05.31
 
(I wrote the initial version of this thing in three hours, which goes to show
the power and simplicity of combinatorial parsing.)
 
To get started, look at all of the subclasses of the Parser class, and
specifically, look at Parser's parseString method. And perhaps try running this:
 
parser = "(" + ZeroOrMore(SignificantLiteral("a") + SignificantLiteral("b")) + ")"
print parser.parseString("(abbaabaab)")
print parser.parseString("(a)")
print parser.parseString("")
print parser.parseString("(a")
print parser.parseString("(ababacababa)")
 
The Parser class, and hence all of its subclasses, overload a few operators
that can be used to make writing parsers easier. Here's what each operator
ends up translating to:
 
x + y is the same as Then(x, y).
x | y is the same as First(x, y).
-x is the same as Optional(x).
+x is the same as OneOrMore(x).
x - y is the same as Except(x, y).
x[min:max] is the same as Repeat(x, min, max).
x[function] is the same as Translate(x, function).
"x" op some_parser or some_parser op "x" is the same as Literal("x") op 
       some_parser or some_parser op Literal("x"), respectively.

 
Modules
       
itertools

 
Classes
       
__builtin__.object
Parser
AnyChar
CharIn
Alpha
Alphanum
Digit
Lower
Upper
Whitespace
Discard
Exact
Except
First
Forward
InfixExpr
Invalid
Keyword
Literal
SignificantLiteral
OneOrMore
Optional
Repeat
Then
Translate
ZeroOrMore
Result

 
class Alpha(CharIn)
    Same as CharIn(upper_chars + lower_chars).
 
 
Method resolution order:
Alpha
CharIn
Parser
__builtin__.object

Methods defined here:
__init__(self)

Methods inherited from CharIn:
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Alphanum(CharIn)
    Same as CharIn(upper_chars + lower_chars + digit_chars).
 
 
Method resolution order:
Alphanum
CharIn
Parser
__builtin__.object

Methods defined here:
__init__(self)

Methods inherited from CharIn:
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class AnyChar(Parser)
    A parser that matches any single character. It returns the character that
it matched.
 
 
Method resolution order:
AnyChar
Parser
__builtin__.object

Methods defined here:
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class CharIn(Parser)
    A parser that matches a single character as long as it is in the specified
sequence (which can be a string or a list of one-character strings). It
returns the character matched.
 
 
Method resolution order:
CharIn
Parser
__builtin__.object

Methods defined here:
__init__(self, chars)
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Digit(CharIn)
    Same as CharIn(digit_chars).
 
 
Method resolution order:
Digit
CharIn
Parser
__builtin__.object

Methods defined here:
__init__(self)

Methods inherited from CharIn:
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Discard(Parser)
    A parser that matches if the parser it's constructed with matches. It
consumes the same amount of input that the specified parser does, but this
parser always returns None as the result. Since instances of Then treat
None values specially, you'll likely use this parser in conjunction with
Then in some grammars.
 
 
Method resolution order:
Discard
Parser
__builtin__.object

Methods defined here:
__init__(self, parser)
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Exact(Parser)
    A parser that returns whatever the specified parser returns, but Invalid()
will be passed as the whitespace parser to the specified parser when its
parse method is called. This allows for sections of the grammar to take
whitespace significantly, which is useful in, for example, string literals.
 
 
Method resolution order:
Exact
Parser
__builtin__.object

Methods defined here:
__init__(self, parser)
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Except(Parser)
    A parser that matches and returns whatever the specified parser matches
and returns, as long as the specified avoidParser does not also match at
the same location. For example, Except(AnyChar(), Literal("*/")) would
match any character as long as that character was not a * followed
immediately by a / character. This would most likely be useful in, for
example, a parser designed to parse C-style comments.
 
 
Method resolution order:
Except
Parser
__builtin__.object

Methods defined here:
__init__(self, parser, avoidParser)
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class First(Parser)
    A parser that tries all of its specified parsers in order. As soon as one
matches, its result is returned. If none of them match, this parser fails.
 
 
Method resolution order:
First
Parser
__builtin__.object

Methods defined here:
__init__(self, *parsers)
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Forward(Parser)
    A parser that allows forward-definition. In other words, you can create a
Forward and use it in a parser grammar, and then set the parser that it
actually represents later on. This is useful for defining grammars that
need to include themselves (for example, parentheses in a numerical
expression contain yet another numberical expression, which is an example
of where this would be used).
 
You create a forward with something like this:
 
forward = Forward()
 
You can then use it in your grammar as you would a normal parser. When
you're ready to set the parser that the Forward should actually represent,
you can do it either with:
 
forward << parser
 
or with:
 
forward.set(parser)
 
Both of them cause the forward to act as if it was really just the
specified parser.
 
The parser must be set before parse is called on anything using the
Forward instance for the first time. This normally shouldn't be a problem.
 
 
Method resolution order:
Forward
Parser
__builtin__.object

Methods defined here:
__init__(self)
__lshift__ = set(self, parser)
parse(self, text, position, space)
set(self, parser)
Sets the parser that this Forward should use. After you call this
method, this Forward acts just like it were really the specified parser.

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class InfixExpr(Parser)
    A parser that's created with a component parser and a series of operator
parsers, which can be literal strings (and will be translated to Literal
instances), and two-argument functions for each of these operator parsers.
It parses expressions of the form "component" or "component op component"
or "component op component op component" etc. For each op it encounters in
the result it parses, it calls the two-arg function supplied with that
operator, passing in the value of the parser on its left and the value of
the parser on its right. It then stores the result, and moves onto the next
operator, this time using the aforementioned result as the left-hand value
for the next operator.
 
This reduction of values proceeds from left to right, which makes InfixExpr
implement a left-associative infix grammar. In the future, there will be a
way to specify that certain operators should be right-associative instead.
 
If only a single component is present, InfixExpr will match that and return
whatever the component resulted in. If not even a single component is
present, InfixExpr will fail to match.
 
 
Method resolution order:
InfixExpr
Parser
__builtin__.object

Methods defined here:
__init__(self, component_parser, operators)
Creates an InfixExpr. component_parser is the parser that will parse
the individual components of the expression. operators is a list of
2-tuples; each tuple represents an operator, with the first item in the
tuple being a parser that parses the operator itself (or a literal
string, such as "+", "-", etc, which will be wrapped with a Literal
instance) and the second item being a two-arg function that will be
used to reduce components on either side of the operator to get a
result.
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Invalid(Parser)
    A parser that never matches any input and always fails.
 
 
Method resolution order:
Invalid
Parser
__builtin__.object

Methods defined here:
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Keyword(Parser)
    A parser that matches the specified parser as long as it is followed
immediately by the specified terminator parser, or by whitespace
(according to the current whitespace parser) if a terminator parser is not
specified.
 
 
Method resolution order:
Keyword
Parser
__builtin__.object

Methods defined here:
__init__(self, parser, terminator=None)
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Literal(Parser)
    A parser that matches the specified literal piece of text. It succeeds
only if that piece of text is found, and it returns None when it succeeds.
If you need the return value to be the literal piece of text, you should
probably use SignificantLiteral instead.
 
 
Method resolution order:
Literal
Parser
__builtin__.object

Methods defined here:
__init__(self, text)
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Lower(CharIn)
    Same as CharIn(lower_chars).
 
 
Method resolution order:
Lower
CharIn
Parser
__builtin__.object

Methods defined here:
__init__(self)

Methods inherited from CharIn:
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class OneOrMore(Parser)
    Same as ZeroOrMore, but requires that the specified parser match at least
once. If it does not, this parser will fail.
 
 
Method resolution order:
OneOrMore
Parser
__builtin__.object

Methods defined here:
__init__(self, parser)
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Optional(Parser)
    A parser that returns whatever its underlying parser returns, except that
if the specified parser fails, this parser succeeds and returns None.
 
 
Method resolution order:
Optional
Parser
__builtin__.object

Methods defined here:
__init__(self, parser)
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Parser(__builtin__.object)
    A parser. This class cannot itself be instantiated; you can only use one of
its subclasses. Most classes in this module are Parser subclasses.
 
The method you'll typically use on Parser objects is parseString.
 
  Methods defined here:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parse(self, text, position, space)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Repeat(Parser)
    A parser that matches its underlying parser a certain number of times. If
the underlying parser did not match at least min times, this parser fails.
This parser stops parsing after max times, even if the underlying parser
would still match. The results of all of the parses are returned as a list.
 
If max is None, no maximum limit will be enforced. The same goes for min.
 
Repeat(parser, 0, None) is the same as ZeroOrMore(parser), and
Repeat(parser, 1, None) is the same as OneOrMore(parser).
 
 
Method resolution order:
Repeat
Parser
__builtin__.object

Methods defined here:
__init__(self, parser, min, max)
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Result(__builtin__.object)
    A result from a parser. Parcon users usually won't have any use for
instances of this class since it's primarily used internally by Parcon, but
if you're implementing your own Parser subclass, then you'll likely find
this class useful since you'll be returning instances of it.
 
  Methods defined here:
__init__(self, end, value, expected)
__nonzero__(self)
__repr__ = __str__(self)
__str__(self)

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class SignificantLiteral(Literal)
    A parser that matches the specified literal piece of text. Is succeeds
only if that piece of text is found. Unlike Literal, however,
SignificantLiteral returns the literal string passed into it instead of
None.
 
 
Method resolution order:
SignificantLiteral
Literal
Parser
__builtin__.object

Methods defined here:
parse(self, text, position, space)

Methods inherited from Literal:
__init__(self, text)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Then(Parser)
    A parser that matches the first specified parser followed by the second.
If neither of them matches, or if only one of them matches, this parser
fails. If both of them match, the result is as follows, assuming A and B
are the results of the first and the second parser, respectively:
 
If A is None, the result is B.
If B is None, the result is A.
If A and B are tuples, the result is A + B.
If A is a tuple but B is not, the result is A + (B,).
If B is a tuple but A is not, the result is (A,) + B.
Otherwise, the result is (A, B).
 
 
Method resolution order:
Then
Parser
__builtin__.object

Methods defined here:
__init__(self, first, second)
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Translate(Parser)
    A parser that passes the result of the parser it's created with, if said
parser matches successfully, through a function, and the function's return
value is then used as the result. The function is not called if the
specified parser fails.
 
For example, the following parser would use the flatten function provided
by parcon to flatten any lists and tuples produced by the parser
example_parser:
 
Translate(example_parser, flatten)
 
The following parser would likewise expect another_parser to produce a list
of strings and concatenate them together into a single result string:
 
Translate(another_parser, "".join)
 
 
Method resolution order:
Translate
Parser
__builtin__.object

Methods defined here:
__init__(self, parser, function)
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Upper(CharIn)
    Same as CharIn(upper_chars).
 
 
Method resolution order:
Upper
CharIn
Parser
__builtin__.object

Methods defined here:
__init__(self)

Methods inherited from CharIn:
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Whitespace(CharIn)
    Same as CharIn(whitespace).
 
 
Method resolution order:
Whitespace
CharIn
Parser
__builtin__.object

Methods defined here:
__init__(self)

Methods inherited from CharIn:
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class ZeroOrMore(Parser)
    A parser that matches the specified parser as many times as it can. The
results are collected into a list, which is then returned. Since
ZeroOrMore succeeds even if zero matches were made (the empty list will
be returned in such a case), this parser always succeeds.
 
 
Method resolution order:
ZeroOrMore
Parser
__builtin__.object

Methods defined here:
__init__(self, parser)
parse(self, text, position, space)

Methods inherited from Parser:
__add__(self, other)
__getitem__(self, function)
__neg__(self)
__or__(self, other)
__pos__(self)
__radd__(self, other)
__ror__(self, other)
__rsub__(self, other)
__sub__(self, other)
parseString(self, string, all=True, whitespace=None)
Parses a string using this parser and returns the result, or throws an
exception if the parser does not match. If all is True (the default),
an exception will be thrown if this parser does not match all of the
input. Otherwise, if the parser only matches a portion of the input
starting at the beginning, just that portion will be returned.
 
whitespace is the whitespace parser to use; this parser will be applied
(and its results discarded) between matching every other parser while
attempting to parse the specified string. A typical grammar might have
this parser represent whitespace and comments. An instance of Exact can
be used to suppress whitespace parsing for a portion of the grammar,
which you would most likely use in, for example, string literals. The
default value for this parameter is Whitespace().

Data descriptors inherited from Parser:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
Functions
       
failure(expected)
Returns a Result representing a failure of a parser to match. expected is
a list of expectations that would have had to be satisfied in the text
passed to the parser calling this method in order for it to potentially
succeed. Expectations are 2-tuples of the position at which some particular
piece of text was expected and a string describing the text, such as
'any char' or '"literal-text"'.
flatten(value)
A function that recursively flattens the specified value. Tuples and lists
are flattened into the items that they contain. The result is a list.
 
If a single non-list, non-tuple value is passed in, the result is a list
containing just that item.
 
This function is intended to be used as the function passed to Translate
where the parser passed to Translate could produce multiple nested lists of
tuples and lists, and a single, flat, list is desired.
format_failure(expected)
Formats a list of expectations into a failure message of the form:
 
At position n: expected one of x, y, z
match(end, value, expected)
Returns a Result representing a parser successfully matching. end is the
position in the string just after where the parser finished, or rather,
where the next parser after this one would be expected to start parsing.
value is the value that this parser resulted in, which is typically
specific to the parser calling this function. expected is a list of
expectations that would have allowed this parser to match more input than
it did; this parameter takes the same format as its corresponding parameter
to the failure function.
op_add(first, second)
op_getitem(parser, function)
op_neg(parser)
op_or(first, second)
op_pos(parser)
op_sub(first, second)
parse_space(text, position, space)
Repeatedly applies the specified whitespace parser to the specified text
starting at the specified position until it no longer matches. The result
of all of these parses will be discarded, and the location at which the
whitespace parser failed will be returned.
promote(value)
Converts a value of some type to an appropriate parser. Right now, this
returns the value as is if it's an instance of Parser, or Literal(value) if
the value is a string.

 
Data
        digit_chars = '0123456789'
lower_chars = 'abcdefghijklmnopqrstuvwxyz'
upper_chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
whitespace = ' \t\r\n'