parcon.py
 
Parcon is a parser library written by Alexander Boyd and James Stoker. It's
designed to be fast, easy to use, and to provide informative error messages.
 
(and it's designed to include new, awesome things, like syntax diagram
generators.)
 
Technically, it's a monadic parser combinator library, but you don't need to
know that unless you're doing really fancy things. (The bind and return
operations are provided by the Bind and Return parsers, respectively.) It's
also technically a parser combinator library, but again, you usually won't need
to know that.
 
Parcon grammars are written as Python statements that make use of various
classes provided with Parcon.
 
Parcon also supports generation of graphs and generation of syntax diagrams
(also known as railroad diagrams) from parsers. See the parcon.graph and
parcon.railroad modules, respectively, for information on how to generate these
graphs and diagrams.
 
To get started with Parcon, look at all of the subclasses of Parser, _GParser,
_RParser, and _GRParser, and specifically, their parse_string methods. And
perhaps take a look at this example:
 
>>> parser = "(" + ZeroOrMore(SignificantLiteral("a") | SignificantLiteral("b")) + ")"
>>> parser.parse_string("(abbaabaab)")
['a', 'b', 'b', 'a', 'a', 'b', 'a', 'a', 'b']
>>> parser.parse_string("(a)")
['a']
>>> parser.parse_string("")
Traceback (most recent call last):
ParseException: Parse failure: At position 0: expected one of "("
>>> parser.parse_string("(a")
Traceback (most recent call last):
ParseException: Parse failure: At position 2: expected one of "a", "b", ")"
>>> parser.parse_string("(ababacababa)")
Traceback (most recent call last):
ParseException: Parse failure: At position 6: expected one of "a", "b", ")"
 
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 - y is the same as Except(x, y).
x & y is the same as And(x, y).
-x is the same as Optional(x).
+x is the same as OneOrMore(x).
~x is the same as Discard(x).
x[min:max] is the same as Repeat(x, min, max).
x[some_int] is the same as Repeat(x, some_int, some_int).
x[some_string] is the same as Tag(some_string, x).
x[...] (three literal dots) is the same as ZeroOrMore(x).
x[function] is the same as Translate(x, function).
x(name="test") is the same as Name("test", x).
x(desc="test") or x(description="test") is the same as Desc("test", x)
"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.
 
A simple expression evaluator written using Parcon:
 
>>> from parcon import number, Forward, InfixExpr
>>> import operator
>>> expr = Forward()
>>> term = number[float] | "(" + expr + ")"
>>> term = InfixExpr(term, [("*", operator.mul), ("/", operator.truediv)])
>>> term = InfixExpr(term, [("+", operator.add), ("-", operator.sub)])
>>> expr << term(name="expr")
 
Some example expressions that can now be evaluated using the above
simple expression evaluator:
 
>>> expr.parse_string("1+2")
3.0
>>> expr.parse_string("1+2+3")
6.0
>>> expr.parse_string("1+2+3+4")
10.0
>>> expr.parse_string("3*4")
12.0
>>> expr.parse_string("5+3*4")
17.0
>>> expr.parse_string("(5+3)*4")
32.0
>>> expr.parse_string("10/4")
2.5
 
A syntax diagram can also be generated for the expression parser with:
 
expr.draw_productions_to_png({}, "expr-syntax.png")
 
Another example use of Parcon, this one being a JSON parser (essentially
a reimplementation of Python's json.dumps, without all of the fancy
arguments that it supports, and currently without support for backslash
escapes in JSON string literals):
 
>>> from parcon import *
>>> import operator
>>> cat_dicts = lambda x, y: dict(x.items() + y.items())
>>> json = Forward()
>>> number = (+Digit() + -(SignificantLiteral(".") + +Digit()))[flatten]["".join][float]
>>> boolean = Literal("true")[lambda x: True] | Literal("false")[lambda x: False]
>>> string = ('"' + Exact(ZeroOrMore(AnyChar() - CharIn('\"'))) +  '"')["".join]
>>> null = Literal("null")[lambda x: None]
>>> pair = (string + ":" + json[lambda x: (x,)])[lambda x: {x[0]: x[1]}]
>>> json_object = ("{" + Optional(InfixExpr(pair, [(",", cat_dicts)]), {}) + "}")
>>> json_list = ("[" + Optional(InfixExpr(json[lambda x: [x]], [(",", operator.add)]), []) + "]")
>>> json << (json_object | json_list | string | boolean | null | number)
 
Thereafter, json.parse_string(text) can be used as a replacement for
Python's json.loads.
 
An interesting fact: the set of all Parcon parsers form a monoid with the
binary operation being the Then parser (or the + operator, since it produces a
Then parser) and the identity element being Return(None).

Package Contents
		binary bnf graph options ordered_dict pargen (package) pargon (package) railroad (package) socket static testframework tests

Classes
		__builtin__.object Expectation EAnyChar EAnyCharIn EAnyCharNotIn ECustomExpectation ERegex EStringLiteral EUnsatisfiable Parser Expected Limit Word Result __builtin__.tuple(__builtin__.object) Pair exceptions.Exception(exceptions.BaseException) ParseException _GParser(Parser, parcon.graph.Graphable) Bind CharNotIn Chars End Invalid Not Present Preserve Repeat _GRParser(Parser, parcon.graph.Graphable, parcon.railroad.Railroadable) And AnyCase AnyChar CharIn Alpha Alphanum Digit Lower Upper Whitespace Description Description Discard Exact Except First Forward InfixExpr Keyword Literal SignificantLiteral Longest Name OneOrMore Optional Return Tag Then Translate ZeroOrMore _RParser(Parser, parcon.railroad.Railroadable) Regex   class Alpha(CharIn)     Same as CharIn(upper_chars + lower_chars).     Method resolution order: Alpha CharIn _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self) do_graph(self, graph) Methods inherited from CharIn: __repr__(self) create_railroad(self, options) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Alphanum(CharIn)     Same as CharIn(upper_chars + lower_chars + digit_chars).     Method resolution order: Alphanum CharIn _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self) do_graph(self, graph) Methods inherited from CharIn: __repr__(self) create_railroad(self, options) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class And(_GRParser)     A parser that matches whatever its specified parser matches as long as its specified check_parser also matches at the same location. This could be considered the opposite of Except: And matches when the second parser it's passed also matches, while Except matches when the second parser it's passed does not match. Wrapping the second parser with Not can make And behave as Except and vice versa, although using whichever one makes more sense will likely lead to more informative error messages when parsing fails.     Method resolution order: And _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, parser, check_parser) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class AnyCase(_GRParser)     A case-insensitive version of Literal. Behaves exactly the same as Literal does, but without regard to the case of the input.   If enough people request a version that returns the matched text instead of None (send me an email if you're one of these people; my email is at the top of this file, in the module docstring), I'll provide such a parser. For now, though, you can use a Regex parser to accomplish the same thing.     Method resolution order: AnyCase _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, text) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class AnyChar(_GRParser)     A parser that matches any single character. It returns the character that it matched.     Method resolution order: AnyChar _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Bind(_GParser)     A parser that functions similar to Then, but that allows the second parser to be determined from the value that the first parser produced. It's constructed as Bind(parser, function). parser is the first parser to run. function is a function that accepts one argument, the value that the first parser produced. It will be called whenever the first parser succeeds; the value that the first parser produced will be passed in, and the function should return a second parser. This parser will then be applied immediately after where the first parser finished parsing from (similar to how Then starts its second parser parsing after where its first parser finished). Bind then returns the value that the second parser produced.   Those of you familiar with functional programming will notice that this parser implements a monadic bind, hence its name.     Method resolution order: Bind _GParser Parser parcon.graph.Graphable __builtin__.object Methods defined here: __init__(self, parser, function) __repr__(self) do_graph(self, graph) parse(self, text, position, end, whitespace) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed.   class CharIn(_GRParser)     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 _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, chars) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class CharNotIn(_GParser)     A parser that matches a single character as long as it is not in the specified sequence. This is much the opposite of CharIn.     Method resolution order: CharNotIn _GParser Parser parcon.graph.Graphable __builtin__.object Methods defined here: __init__(self, chars) __repr__(self) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed.   class Chars(_GParser)     A parser that parses a specific number of characters and returns them as a string. Chars(5), for example, would parse exactly five characters in a row, and return a string of length 5. This would be essentially identical to AnyChar()[5:5]["".join], except for two things: 1, the whitespace parser is not applied in between each character parsed by Chars (although it is applied just before the first character), and 2, Chars is much more efficient than the aforementioned expression using AnyChar.   This can be used in combination with Bind to create a parser that parses a binary protocol where a fixed number of bytes are present that specify the length of the rest of a particular packet, followed by the rest of the packet itself. For example, imagine a protocol where packets look like this:   length b1 b2 b3 ... blength   a.k.a. a byte indicating the length of the data carried in that packet, followed by the actual data of the packet. Such a packet could be parsed into a string containing the data of a single packet with this:   Bind(AnyChar(), lambda x: Chars(ord(x)))     Method resolution order: Chars _GParser Parser parcon.graph.Graphable __builtin__.object Methods defined here: __init__(self, number) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed.   Desc = class Description(_GRParser)       Method resolution order: Description _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, description, parser) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Description(_GRParser)       Method resolution order: Description _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, description, parser) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Digit(CharIn)     Same as CharIn(digit_chars).     Method resolution order: Digit CharIn _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self) do_graph(self, graph) Methods inherited from CharIn: __repr__(self) create_railroad(self, options) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Discard(_GRParser)     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 _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, parser) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class EAnyChar(Expectation)     An expectation indicating that any character was expected.     Method resolution order: EAnyChar Expectation __builtin__.object Methods defined here: __str__(self) format(self) Methods inherited from Expectation: __repr__(self) Data descriptors inherited from Expectation: __dict__ dictionary for instance variables (if defined) __weakref__ list of weak references to the object (if defined)   class EAnyCharIn(Expectation)     An expectation indicating that any character in a particular sequence of characters (a list of one-character strings, or a string containing the expected characters) was expected.     Method resolution order: EAnyCharIn Expectation __builtin__.object Methods defined here: __init__(self, chars) __str__(self) format(self) Methods inherited from Expectation: __repr__(self) Data descriptors inherited from Expectation: __dict__ dictionary for instance variables (if defined) __weakref__ list of weak references to the object (if defined)   class EAnyCharNotIn(Expectation)     An expectation indicating that any character not in a particular sequence of characters (a list of one-character strings, or a string containing the expected characters) was expected.     Method resolution order: EAnyCharNotIn Expectation __builtin__.object Methods defined here: __init__(self, chars) __str__(self) format(self) Methods inherited from Expectation: __repr__(self) Data descriptors inherited from Expectation: __dict__ dictionary for instance variables (if defined) __weakref__ list of weak references to the object (if defined)   class ECustomExpectation(Expectation)     An expectation indicating that some custom value was expected. This is used when instances of the Expected parser fail. Users implementing their own subclass of Parser that don't want to write a corresponding subclass of Expectation but that find that none of the current subclasses of Expectation fit their needs might also want to use ECustomExpectation.     Method resolution order: ECustomExpectation Expectation __builtin__.object Methods defined here: __init__(self, message) __str__(self) format(self) Methods inherited from Expectation: __repr__(self) Data descriptors inherited from Expectation: __dict__ dictionary for instance variables (if defined) __weakref__ list of weak references to the object (if defined)   class ERegex(Expectation)     An expectation indicating that some regular expression was expected.     Method resolution order: ERegex Expectation __builtin__.object Methods defined here: __init__(self, pattern_text) __str__(self) format(self) Methods inherited from Expectation: __repr__(self) Data descriptors inherited from Expectation: __dict__ dictionary for instance variables (if defined) __weakref__ list of weak references to the object (if defined)   class EStringLiteral(Expectation)     An expectation indicating that some literal string was expected. When formatted, the string will be enclosed in double quotes. In the future, I may have the representation as returned from Python's repr function be used instead.     Method resolution order: EStringLiteral Expectation __builtin__.object Methods defined here: __init__(self, text) __str__(self) format(self) Methods inherited from Expectation: __repr__(self) Data descriptors inherited from Expectation: __dict__ dictionary for instance variables (if defined) __weakref__ list of weak references to the object (if defined)   class EUnsatisfiable(Expectation)     An expectation indicating that there is no input that could have been present that would have made the parser in question succeed or consume more input. Invalid(), for example, returns EUnsatisfiable() since nothing will make an Invalid match, and EStringLiteral, when it succeeds, returns EUnsatisfiable() since there isn't any additional text that could be added that would make EStringLiteral consume more of the input.   EUnsatisfiable is treated specially by format_failure; instances of it are removed if there are expectations of any other type in the list provided to format_failure. If there are not, the EUnsatisfiable with the greatest position (expectations are stored as tuples of (position, Expectation)) is used, and the message will look something like "At position n: expected EOF".     Method resolution order: EUnsatisfiable Expectation __builtin__.object Methods defined here: __str__(self) format(self) Methods inherited from Expectation: __repr__(self) Data descriptors inherited from Expectation: __dict__ dictionary for instance variables (if defined) __weakref__ list of weak references to the object (if defined)   class End(_GParser)     A parser that matches only at the end of input. It parses whitespace before checking to see if it's at the end, so it will still match even if there is some whitespace at the end of the input. (If you don't want it to consume any whitespace, you can use Exact(End()).)   This parser's result is always None. End(True) will consume any whitespace that it matches while searching for the end, which can improve performance under certain circumstances by avoiding having to parse out whitespace a second time. End(False) will still skip over whitespace while searching for the end, but it won't consume it, which may be desirable if the whitespace in question is significant to the grammar. End() is the same as End(True).   Note that this parser succeeds at the end of the /logical/ input given to it; specifically, if you've restricted the region to parse with Length, End matches at the end of the limit set by Limit, not at the end of the actual input. A more technical way to put it would be to say that if, after removing whitespace, the resulting position is equal to the end parameter passed to the parse function, then this parser matches. Otherwise, it fails.     Method resolution order: End _GParser Parser parcon.graph.Graphable __builtin__.object Methods defined here: __init__(self, consume=True) Creates a new End parser. consume is described in the class docstring. __repr__(self) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed.   class Exact(_GRParser)     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. For example, the following parser, intended to parse string literals, demonstrates the problem:   >>> stringLiteral = '"' + ZeroOrMore(AnyChar() - '"')["".join] + '"' >>> stringLiteral.parse_string('"Hello, great big round world"') 'Hello,greatbigroundworld'   This is because the whitespace parser (which defaults to Whitespace()) consumed all of the space in the string literal. This can, however, be rewritten using Exact to mitigate this problem:   >>> stringLiteral = Exact('"' + ZeroOrMore(AnyChar() - '"')["".join] + '"') >>> stringLiteral.parse_string('"Hello, great big round world"') 'Hello, great big round world'   This parser produces the correct result, 'Hello, great big round world'.     Method resolution order: Exact _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, parser, space_parser=Invalid()) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Except(_GRParser)     A parser that matches and returns whatever the specified parser matches and returns, as long as the specified avoid_parser 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.   When this parser is converted to a railroad diagram, it simply replaces itself with the underlying parser it wraps. The resulting railroad diagram does not, therefore, mention the avoid parser, so you should be careful that this is really what you want to do.     Method resolution order: Except _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, parser, avoid_parser) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Expectation(__builtin__.object)     NOTE: Most users won't need to know about this class or any of its subclasses. They're usually only used internally by Parcon, but advanced users may wish to use them.   An expectation. Instances of the various subclasses of this class are provided as part of a Result object to indicate what could have made a parser succeed if it failed, or consume more input if it succeeded. Expectations are used to format the error message when Parser.parse_string throws an exception because of a parse error.   This class should not be instantiated directly; one of its various subclasses should be used instead.     Methods defined here: __repr__(self) __str__(self) format(self) Formats this expectation into a human-readable string. For example, EStringLiteral("hello").format() returns '"hello"', and EAnyCharIn("abc").format() returns 'any char in "abc"'.   Subclasses must override this method; Expectation's implementation of the method raises NotImplementedError. Data descriptors defined here: __dict__ dictionary for instance variables (if defined) __weakref__ list of weak references to the object (if defined)   class Expected(Parser)     A parser that allows customization of the error message provided when the parser it's created with fails. For example, let's say that you had a parser that would parse numbers with decimals, such as 1.5:   >>> decimal = +Digit() + "." + +Digit()   Now let's say that in your grammar, you included "true" and "false" as things that could be in the same location as a decimal number:   >>> something = decimal | "true" | "false"   If you call something.parse_string("bogus"), the resulting error message will be:   >>> something.parse_string("bogus") Traceback (most recent call last): ParseException: Parse failure: At position 0: expected one of any char in "0123456789", "true", "false"   which isn't very pretty or informative. If, instead, you did this:   >>> decimal = +Digit() + "." + +Digit() >>> decimal = Expected(decimal, "decimal number") >>> something = decimal | "true" | "false"   Then the error message would instead be something like:   >>> something.parse_string("bogus") Traceback (most recent call last): ParseException: Parse failure: At position 0: expected one of decimal number, "true", "false"   which is more informative as to what's missing.   If the parameter remove_whitespace is True when constructing an instance of Expected, whitespace will be removed before calling the underlying parser's parse method. This will usually make error messages more accurate about the position at which this whole Expected instance was expected. If it's False, whitespace will not be removed, and it will be up to the underlying parser to remove it; as a result, error messages will indicate the position /before/ the removed whitespace as where the error occurred, which is usually not what you want.     Method resolution order: Expected Parser __builtin__.object Methods defined here: __init__(self, parser, expected_message, remove_whitespace=True) __repr__(self) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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(_GRParser)     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.   The parsers can be specified either as arguments (i.e. First(parser1, parser2, parser3) or as a single list or tuple (i.e. First([parser1, parser2, parser3]).     Method resolution order: First _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, *parsers) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Forward(_GRParser)     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.   You can also specify the parser when you create the Forward instance. This is usually somewhat pointless, but it can be useful if you're simply trying to create a mutable parser (the parser can be set into a Forward multiple times, with the effect of changing the underlying parser each time).     Method resolution order: Forward _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, parser=None) __lshift__ = set(self, parser) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, 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.   This method can be called multiple times; each time it's called, it changes the parser in use by this Forward instance. Data descriptors defined here: railroad_children Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_production_delegate = None railroad_production_name = None   class InfixExpr(_GRParser)     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 _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __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. __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Data descriptors defined here: railroad_children Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_production_delegate = None railroad_production_name = None   class Invalid(_GParser)     A parser that never matches any input and always fails.     Method resolution order: Invalid _GParser Parser parcon.graph.Graphable __builtin__.object Methods defined here: __repr__(self) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed.   class Keyword(_GRParser)     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.   If exact_terminator is True, the terminator is matched with Invalid() as its whitespace parser. This prevents the whitespace parser from consuming input that the terminator might have been expecting to see to indicate proper termination of the keyword. If exact_terminator is False, the same whitespace parser passed to Keyword will be passed into the terminator.   If or_end is True, the terminator will be replaced with (terminator | End()) just before attempting to parse it, which would allow the keyword to be present at the end of the input without causing a parse failure due to the keyword not being followed immediately by the terminator.     Method resolution order: Keyword _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, parser, terminator=None, exact_terminator=True, or_end=True) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Limit(Parser)     A parser that imposes a limit on how much input its underlying parser can consume. All parsers, when asked to parse text, are passed the position that they can parse to before they have to stop; normally this is the length of the string being passed in. Limit, however, allows this to be set to a smaller value.   When you construct a Limit instance, you pass in a parser that it will call and the number of characters that the specified parser can consume. If there aren't that many characters left in the input string, no limit is placed on what the specified parser can consume.   You can also pass a parser instead of a number as the limit for how many characters can be parsed. If you do that, Limit will apply that parser first, then take its result (which should be an int or a long) and use that as the limit when applying the main parser.   The behavior of the latter paragraph allows you to write parsers that parse length-specified values. For example, if you're parsing some sort of string from a piece of binary data where the string is stored as four bytes representing the length of the string followed by the bytes of the string itself, you could do that with Limit(parcon.binary.integer, ZeroOrMore(AnyChar()))[concat].     Method resolution order: Limit Parser __builtin__.object Methods defined here: __init__(self, length, parser) __repr__(self) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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(_GRParser)     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 _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, text) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Longest(_GRParser)     A parser that tries all of its specified parsers. The longest one that succeeds is chosen, and its result is returned. If none of the parsers succeed, Longest fails.   The parsers can be specified either as arguments (i.e. First(parser1, parser2, parser3) or as a single list or tuple (i.e. First([parser1, parser2, parser3]).   Longest is typically more expensive than First since it has to try each parser to see which one consumes the most input whereas First stops trying parsers once one succeeds. Because of this, it's usually better to use First if the parsers to check can be reordered so that those consuming the most input are at the beginning of the list.     Method resolution order: Longest _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, *parsers) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Lower(CharIn)     Same as CharIn(lower_chars).     Method resolution order: Lower CharIn _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self) do_graph(self, graph) Methods inherited from CharIn: __repr__(self) create_railroad(self, options) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Name(_GRParser)       Method resolution order: Name _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, name, parser) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Not(_GParser)     A parser that matches only if the parser it's created with does not. If the aforementioned parser fails, then Not succeeds, consuming no input and  returning None. If the aforementioned parser succeeds, then Not fails.     Method resolution order: Not _GParser Parser parcon.graph.Graphable __builtin__.object Methods defined here: __init__(self, parser) __repr__(self) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed.   class OneOrMore(_GRParser)     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 _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, parser) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Optional(_GRParser)     A parser that returns whatever its underlying parser returns, except that if the specified parser fails, this parser succeeds and returns the default result specified to it (which, itself, defaults to None).     Method resolution order: Optional _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, parser, default=None) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Pair(__builtin__.tuple)     Pair(key, value)     Method resolution order: Pair __builtin__.tuple __builtin__.object Methods defined here: __getnewargs__(self) Return self as a plain tuple.  Used by copy and pickle. __repr__(self) Return a nicely formatted representation string _asdict(self) Return a new OrderedDict which maps field names to their values _replace(_self, **kwds) Return a new Pair object replacing specified fields with new values Class methods defined here: _make(cls, iterable, new=<built-in method __new__ of type object>, len=<built-in function len>) from __builtin__.type Make a new Pair object from a sequence or iterable Static methods defined here: __new__(_cls, key, value) Create new instance of Pair(key, value) Data descriptors defined here: __dict__ Return a new OrderedDict which maps field names to their values key Alias for field number 0 value Alias for field number 1 Data and other attributes defined here: _fields = ('key', 'value') Methods inherited from __builtin__.tuple: __add__(...) x.__add__(y) <==> x+y __contains__(...) x.__contains__(y) <==> y in x __eq__(...) x.__eq__(y) <==> x==y __ge__(...) x.__ge__(y) <==> x>=y __getattribute__(...) x.__getattribute__('name') <==> x.name __getitem__(...) x.__getitem__(y) <==> x[y] __getslice__(...) x.__getslice__(i, j) <==> x[i:j]   Use of negative indices is not supported. __gt__(...) x.__gt__(y) <==> x>y __hash__(...) x.__hash__() <==> hash(x) __iter__(...) x.__iter__() <==> iter(x) __le__(...) x.__le__(y) <==> x<=y __len__(...) x.__len__() <==> len(x) __lt__(...) x.__lt__(y) <==> x<y __mul__(...) x.__mul__(n) <==> x*n __ne__(...) x.__ne__(y) <==> x!=y __rmul__(...) x.__rmul__(n) <==> n*x __sizeof__(...) T.__sizeof__() -- size of T in memory, in bytes count(...) T.count(value) -> integer -- return number of occurrences of value index(...) T.index(value, [start, [stop]]) -> integer -- return first index of value. Raises ValueError if the value is not present.   class ParseException(exceptions.Exception)       Method resolution order: ParseException exceptions.Exception exceptions.BaseException __builtin__.object Methods defined here: __init__(self, message, expectations=None) Data descriptors defined here: __weakref__ list of weak references to the object (if defined) Data and other attributes inherited from exceptions.Exception: __new__ = <built-in method __new__ of type object> T.__new__(S, ...) -> a new object with type S, a subtype of T Methods inherited from exceptions.BaseException: __delattr__(...) x.__delattr__('name') <==> del x.name __getattribute__(...) x.__getattribute__('name') <==> x.name __getitem__(...) x.__getitem__(y) <==> x[y] __getslice__(...) x.__getslice__(i, j) <==> x[i:j]   Use of negative indices is not supported. __reduce__(...) __repr__(...) x.__repr__() <==> repr(x) __setattr__(...) x.__setattr__('name', value) <==> x.name = value __setstate__(...) __str__(...) x.__str__() <==> str(x) __unicode__(...) Data descriptors inherited from exceptions.BaseException: __dict__ args message   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 parse_string.     Methods defined here: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse(self, text, position, end, space) parse_string(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 Present(_GParser)     A lookahead parser; it matches as long as the parser it's constructed with matches at the specified position, but it doesn't actually consume any input, and its result is None. If you need access to the result, you'll probably want to use Preserve instead.     Method resolution order: Present _GParser Parser parcon.graph.Graphable __builtin__.object Methods defined here: __init__(self, parser) __repr__(self) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed.   class Preserve(_GParser)     A lookahead parser; it matches as long as the parser it's constructed with matches at the specified position, but it doesn't actually consume any input. Unlike Present, however, Preserve returns whatever its underlying parser returned, even though it doesn't consume any input.     Method resolution order: Preserve _GParser Parser parcon.graph.Graphable __builtin__.object Methods defined here: __init__(self, parser) __repr__(self) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed.   class Regex(_RParser)     A parser that matches the specified regular expression. Its result depends on the groups_only parameter passed to the constructor: if groups_only is None (the default), the result is the string that the regex matches. If groups_only is True, a list of the values that the groups in the regex matched is true; for example, Regex("(..)(.)(....)", groups_only=True) would parse the string "abcdefg" into ["ab", "c", "defg"]. If groups_only is False, the string that the regex matched is provided as the first item in the list, and the groups are provided as the rest of the items in the list; the above example with groups_only=False would parse the string "abcdefg" into ["abcdefg", "ab", "c", "defg"].   >>> Regex("(..)(.)(....)", groups_only=True).parse_string("abcdefg") ['ab', 'c', 'defg']   If you can avoid using Regex without requiring exorbitant amounts of additional code, it's generally best to, since error messages given by combinations of Parcon parsers are generally more informative than an error message providing a regex. If you really need to use Regex but you still want informative error messages, you could wrap your Regex instance in an instance of Expected.   The specified regex can be either a string representing the regular expression or a pattern compiled with Python's re.compile. If you want to specify flags to the regex, you'll need to compile it with re.compile, then pass the result into Regex.   Unlike the behavior of normal Python regex groups, groups that did not participate in a match are represented in the returned list (if groups_only is not None) by the empty string instead of None. If enough people want the ability for None to be used instead (and my email address is in the docstring for this module, at the top, so send me an email if you're one of the people that want this), I'll add a parameter that can be passed to Regex to switch this back to the usual behavior of using None.     Method resolution order: Regex _RParser Parser parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, regex, groups_only=None) __repr__(self) create_railroad(self, options) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Repeat(_GParser)     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 _GParser Parser parcon.graph.Graphable __builtin__.object Methods defined here: __init__(self, parser, min, max) __repr__(self) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed.   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.   You typically don't create instances of Result directly; instead, you usually call either match() or failure(), which return result objects indicating success or failure, respectively.   Three fields are made available on a Result object:       expected: A list of expectations in the same format as provided to the     failure() function          end: The position at which the parser finished parsing, if this result     indicates success. The value is undefined in the case of a failure.          value: The value that the parser produced, if this result indicates     success. The value is undefined in the case of a failure.   You can test whether or not a result indicates success by using it as a boolean. For example:   >>> successful_result = match(0, "some random value", []) >>> failed_result = failure([(0, EUnsatisfiable())]) >>> if successful_result: ...     print "Yes" ... else: ...     print "No" ... Yes >>> if failed_result: ...     print "Yes" ... else: ...     print "No" ... No     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 Return(_GRParser)     A parser that always succeeds, consumes no input, and always returns a value specified when the Return instance is constructed.   Those of you familiar with functional programming will notice that this parser implements a monadic return, hence its name.     Method resolution order: Return _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, value) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, whitespace) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   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 _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __repr__(self) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Literal: __init__(self, text) create_railroad(self, options) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Tag(_GRParser)     A parser that "tags", so to speak, the value returned from its underlying parser. Specifically, you construct a Tag instance by specifying a tag and a parser, and the specified parser's return value will be wrapped in a Pair(tag, return_value). For example,   >>> Tag("test", AnyChar()).parse_string("a") Pair(key='test', value='a')   The reason why this is useful is that named tuples are treated as objects by Parcon things like Then and the flatten function, so they will be passed around as objects, but they are treated as tuples by Python's dict function. This allows you to use various parsers that assemble values passed through Tag, and then add [flatten][dict] onto the end of that whole parser group; the result of that parser will be a dictionary containing all of the tagged values, with the tags as keys. For example, a parser that parses numbers such as "123.45" into a dict of the form {"integer": "123", "decimal": "45"} could be written as:   >>> decimal_parser = (Tag("integer", (+Digit())[concat]) + Tag("decimal",                              Optional("." + (+Digit())[concat], "")))[dict]   Of course, using the short notation parser["tag"] in place of Tag("tag", parser), we can reduce that further to:   >>> decimal_parser = ((+Digit())[concat]["integer"] + Optional("." +                              (+Digit())[concat], "")["decimal"])[dict]   Note that the short notation of parser[tag] only works if tag is a string (or a unicode instance; anything that subclasses from basestring works). No other datatypes will work; if you want to use those, you'll need to use Tag itself instead of the short notation.   If you want to preserve all values with a particular tag instead of just one of them, you may want to use parser[list_dict] instead of parser[dict]. See the documentation for list_dict for more on what it does.     Method resolution order: Tag _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, tag, parser) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Then(_GRParser)     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).   Named tuples (instances of classes created with collections.namedtuple) are not treated as tuples in the above decision process. In fact, any subclass of tuple is treated as if it were a completely separate object and not a tuple at all.     Method resolution order: Then _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, first, second) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Translate(_GRParser)     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 _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, parser, function) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Upper(CharIn)     Same as CharIn(upper_chars).     Method resolution order: Upper CharIn _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self) do_graph(self, graph) Methods inherited from CharIn: __repr__(self) create_railroad(self, options) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Whitespace(CharIn)     Same as CharIn(whitespace).     Method resolution order: Whitespace CharIn _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self) __repr__(self) do_graph(self, graph) Methods inherited from CharIn: create_railroad(self, options) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None   class Word(Parser)     A parser that parses a word consisting of a certain set of allowed characters. A minimum and maximum word length can also be specified, as can a set of characters of which the first character in the word must be a member.   If min is unspecified, it defaults to 1. Max defaults to None, which places no upper limit on the number of characters that can be in this word.   Word parses as many characters as it can that are in the specified character set until it's parsed the specified maximum number of characters, or it hits a character not in the specified character set. If, at that point, the number of characters parsed is less than min, this parser fails. Otherwise, it succeeds and produces a string containing all the characters.   min can be zero, which will allow this parser to succeed even if there are no characters available or if the first character is not in init_chars. The empty string will be returned in such a case.     Method resolution order: Word Parser __builtin__.object Methods defined here: __init__(self, chars, init_chars=None, min=1, max=None) __repr__(self) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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(_GRParser)     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 _GRParser Parser parcon.graph.Graphable parcon.railroad.Railroadable __builtin__.object Methods defined here: __init__(self, parser) __repr__(self) create_railroad(self, options) do_graph(self, graph) parse(self, text, position, end, space) Methods inherited from Parser: __add__(self, other) __and__(self, other) __call__(self, *args, **kwargs) __getitem__(self, function) __invert__(self) __neg__(self) __or__(self, other) __pos__(self) __radd__(self, other) __rand__(self, other) __ror__(self, other) __rsub__(self, other) __str__(self) __sub__(self, other) consume(self, text, position, end) parse_string(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) Methods inherited from parcon.graph.Graphable: graph(self) Graphs this Graphable object by calling its do_graph and the do_graph functions defined by all of the things that this Graphable depends on. The result will be a Graph object.   Each node in the resulting Graph will be named after its respective object's identity, a.k.a. the value returned by the built-in id function.   The quickest way to use this would be to do something like this:   something.graph().draw("example.png")   For the draw method to work, however, you must have the dot program (which is part of Graphviz) installed. Methods inherited from parcon.railroad.Railroadable: draw_productions_to_png(self, options, filename, tail=[]) draw_railroad_to_png(self, options, filename) Draws a syntax diagram for this object to the specified .png image file using the specified options. For now, just pass {} (i.e. an empty dictionary) as options; I'll document what this actually does at a later date. get_productions(self) Data and other attributes inherited from parcon.railroad.Railroadable: railroad_children = [] railroad_production_delegate = None railroad_production_name = None