pyPEG – XML Backend

pyPEG – a PEG Parser-Interpreter in Python

pyPEG 2.15.0 of Fr Jan 10 2014 – Copyleft 2009-2014, Volker Birk

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

# XML Backend of pyPEG

## etree functions

The pyPEG XML Backend uses Python's `etree` semantic. This way it can easily be integrated into existing working code using XML. The usage of lxml is recommended. If the module `lxml` is installed, pyPEG uses it automatically.

### Function create_tree()

#### Synopsis

`create_tree(thing, parent=None, object_names=False)`

Create an XML etree from a thing.

#### Arguments

`thing` | `thing` to interpret
`parent` | `etree.Element` to put subtree into; default: create a new `Element` tree
`object_names` | experimental feature: if `True` tag names are object names instead of types

#### Returns

`etree.Element` instance created

Example:

    >>> from pypeg2.xmlast import create_tree
    >>> from pypeg2 import name, restline
    >>> class Key(str):
    ...     grammar = name(), "=", restline
    ...
    >>> k = Key("world")
    >>> k.name = "hello"
    >>> t = create_tree(k)
    >>> t.attrib["name"]
    'hello'
    >>> t.text
    'world'
    >>> type(t)
    <class 'lxml.etree._Element'>

### Function create_thing()

#### Synopsis

`create_thing(element, symbol_table)`

Create thing from an XML element.

#### Arguments

`element` | `etree.Element` instance to read
`symbol_table` | symbol table where the classes can be found; usually call `globals()`

#### Returns

`thing` created

Example:

    >>> from pypeg2.xmlast import create_thing, etree
    >>> from pypeg2 import name, restline
    >>> class Key(str):
    ...     grammar = name(), "=", restline
    ...
    >>> e = etree.fromstring("<Key name='hello'>world</Key>")
    >>> k = create_thing(e, globals())
    >>> k.name
    Symbol('hello')
    >>> k
    'world'
    >>> type(k)
    <class '__main__.Key'>

## XML convenience functions

### Function thing2xml()

#### Synopsis

`thing2xml(thing, pretty=False, object_names=False)`

Create XML text from a thing.

#### Arguments

`thing` | `thing` to interpret
`pretty` | `True` if XML should be indented, `False` if XML should be plain (this feature requires lxml)
`object_names` | experimental feature: if `True` tag names are object names instead of types

#### Returns

`bytes` with encoded XML

Example:

    >>> from pypeg2 import name, restline
    >>> from pypeg2.xmlast import thing2xml
    >>> class Key(str):
    ...     grammar = name(), "=", restline
    ...
    >>> k = Key("world")
    >>> k.name = "hello"
    >>> thing2xml(k)
    b'<Key name="hello">world</Key>'

### Function xml2thing()

#### Synopsis

`xml2thing(xml, symbol_table)`

Create `thing` from XML text.

#### Arguments

`xml` | `bytes` with encoded XML
`symbol_table` | symbol table where the classes can be found; usually call `globals()`

#### Returns

created `thing`

Example:

    >>> from pypeg2 import name, restline
    >>> from pypeg2.xmlast import xml2thing
    >>> class Key(str):
    ...     grammar = name(), "=", restline
    ...
    >>> k = xml2thing(b"<Key name='hello'>world</Key>", globals())
    >>> k.name
    Symbol('hello')
    >>> k
    'world'

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