pyPEG – a PEG Parser-Interpreter in Python

pyPEG 2.15.3 of We May 05 2021 – Copyleft 2009-2021, Volker Birk

Requires Python 3.x or 2.7
Older versions: pyPEG 1.x

Parser Engine

Class Parser

Offers parsing and composing capabilities. Implements an intrinsic Packrat parser.

pyPEG uses memoization as speed enhancement. Create a Parser instance to have a reset cache memory. Usually this is recommended if you're parsing another text – the cache memory will not provide wrong results but a reset will save memory consumption. If you're altering the grammar then clearing the cache memory for the respective things is required for having correct parsing results. Please use the clear_memory() method in that case.

Instance variables

The instance variables are representing the parser's state.

whitespace

Regular expression to scan whitespace; default: re.compile(r"(?m)\s+"). Set to None to disable automatic whitespace removing.

comment

grammar to parse comments; default: None. If a grammar is set here, comments will be removed from the source text automatically.

last_error

after parsing, SyntaxError which ended parsing

indent

string to use to indent while composing; default: four spaces

indention_level

level to indent to; default: 0

text

original text to parse; set for decorated syntax errors

filename

filename where text is origin from

autoblank

add blanks while composing if grammar would possibly be violated otherwise; default: True

keep_feeble_things

keep otherwise cropped things like comments and whitespace; these things are being put into the feeble_things attribute

Method __init__()

Synopsis

__init__(self)

Initialize instance variables to their defaults.

Method clear_memory()

Synopsis

clear_memory(self, thing=None)

Clear cache memory for packrat parsing.

This method clears the cache memory for thing. If None is given as thing, it clears the cache completely.

Arguments

thing

thing for which cache memory is cleared; default: None

Method parse()

Synopsis

parse(self, text, thing, filename=None)

(Partially) parse text following thing as grammar and return the resulting things.

This method parses as far as possible. It does not raise a SyntaxError if the source text does not parse completely. It returns a SyntaxError object as result part of the return value if the beginning of the source text does not comply with grammar thing.

Arguments

text

text to parse

thing

grammar for things to parse

filename

filename where text is origin from

Returns

Returns (text, result) with:

text

unparsed text

result

generated objects

Raises

ValueError

if input does not match types

TypeError

if output classes have wrong syntax for their respective __init__(self, ...)

GrammarTypeError

if grammar contains an object of unkown type

GrammarValueError

if grammar contains an illegal cardinality value

Example:

rd
)◊
)◊
])
||

Method compose()

Synopsis

compose(self, thing, grammar=None)

Compose text using thing with grammar. If thing.compose() exists, execute it, otherwise use grammar to compose.

Arguments

thing

thing containing other things with grammar

grammar

grammar to use for composing thing; default: type(thing).grammar

Returns

Composed text

Raises

ValueError

if thing does not match grammar

GrammarTypeError

if grammar contains an object of unkown type

GrammarValueError

if grammar contains an illegal cardinality value

Example:

>>> from pypeg2 import Parser, csl, word
>>> p = Parser()
>>> p.compose(['hello', 'world'], csl(word))
'hello, world'

Method generate_syntax_error()

Synopsis

generate_syntax_error(self, msg, pos)

Generate a syntax error construct.

msg

string with error message

pos

(lineNo, charInText) with positioning information

Returns

Instance of SyntaxError with error text

Convenience functions

Function parse()

Synopsis

parse(text, thing, filename=None, whitespace=whitespace,
        comment=None, keep_feeble_things=False)

Parse text following thing as grammar and return the resulting things or raise an error.

Arguments

text

text to parse

thing

grammar for things to parse

filename

filename where text is origin from

whitespace

regular expression to skip whitespace; default: re.compile(r"(?m)\s+")

comment

grammar to parse comments; default: None

keep_feeble_things

keep otherwise cropped things like comments and whitespace; these things are being put into the feeble_things attribute; default: False

Returns

generated things

Raises

SyntaxError

if text does not match the grammar in thing

ValueError

if input does not match types

TypeError

if output classes have wrong syntax for __init__()

GrammarTypeError

if grammar contains an object of unkown type

GrammarValueError

if grammar contains an illegal cardinality value

Example:

>>> from pypeg2 import parse, csl, word
>>> parse("hello, world", csl(word))
['hello', 'world']

Function compose()

Synopsis

compose(thing, grammar=None, indent=" ", autoblank=True)

Compose text using thing with grammar.

Arguments

thing

thing containing other things with grammar

grammar

grammar to use to compose thing; default: thing.grammar

indent

string to use to indent while composing; default: four spaces

autoblank

add blanks if grammar would possibly be violated otherwise; default: True

Returns

composed text

Raises

ValueError

if input does not match grammar

GrammarTypeError

if grammar contains an object of unkown type

GrammarValueError

if grammar contains an illegal cardinality value

Example:

>>> from pypeg2 import compose, csl, word
>>> compose(['hello', 'world'], csl(word))
'hello, world'

Function attributes()

Synopsis

attributes(grammar, invisible=False)

Iterates all attributes of a grammar.

This function can be used to iterate through all attributes which will be generated for the top level object of the grammar. If invisible is False omit attributes whose names are starting with an underscore _.

Example:

>>> from pypeg2 import attr, name, attributes, word, restline
>>> class Me:
...     grammar = name(), attr("typing", word), restline
... 
>>> for a in attributes(Me.grammar): print(a.name)
... 
name
typing
>>> 

Function how_many()

Synopsis

how_many(grammar)

Determines the possibly parsed objects of grammar.

This function is meant to check if the results of a grammar can be stored in a single object or a collection will be needed.

Returns

0

if there will be no objects

1

if there will be a maximum of one object

2

if there can be more than one object

Raises

GrammarTypeError

if grammar contains an object of unkown type

GrammarValueError

if grammar contains an illegal cardinality value

Example:

>>> from pypeg2 import how_many, word, csl
>>> how_many("some")
0
>>> how_many(word)
1
>>> how_many(csl(word))
2

Exceptions

GrammarError

Base class for all errors pyPEG delivers.

GrammarTypeError

A grammar contains an object of a type which cannot be parsed, for example an instance of an unknown class or of a basic type like float. It can be caused by an int at the wrong place, too.

GrammarValueError

A grammar contains an object with an illegal value, for example an undefined cardinality.

Want to download? Go to the ^Top^ and look to the right ;-)