Commits

Anonymous committed f39abd1

RC1

  • Participants
  • Parent commits 47d7b49

Comments (0)

Files changed (6)

docs/grammar_elements.en.yhtml2

 
     h2 id=basic > Basic Grammar Elements
 
-    h3 id=literals > «str» instances
+    h3 id=literals > str instances
 
     h4 > Parsing
 
         'give me=◊a value\\n◊'
         ||
 
-    h3 id=tuple > «tuple» instances
+    h3 id=tuple > tuple instances
 
     h4 > Parsing
 
         ◊'give me=a value\\n'◊
         ||
 
-    h3 id=lists > «list» instances
+    h3 id=lists > list instances
 
     h4 > Parsing
 
         '23'
         ||
 
-    h3 id=none > Constant «None»
+    h3 id=none > Constant None
 
     p   >>
         «None» parses to nothing. And it composes to nothing. It represents
 
     h2 id=goclasses > Grammar Element Classes
 
-    h3 id=symbol > Class «Symbol(str)»
+    h3 id=symbol > Class Symbol
+ 
+    h4 > Class definition
+    p > «Symbol(str)»
 
     p > Used to scan a «Symbol».
 
         '◊that one◊=foo bar'
         ||
 
-    h3 id=keyword > Class «Keyword(Symbol)»
+    h3 id=keyword > Class Keyword
+
+    h4 > Class definition
+    p > «Keyword(Symbol)»
 
     p > Used to access the keyword table.
 
         'do'
         ||
 
-    h3 id=list > Class «List(list)»
+    h3 id=list > Class List
+
+    h4 > Class definition
+    p > «List(list)»
 
     p > A List of things.
     
         '{ hello, world }'
         ||
 
-    h3 id=namespace > Class «Namespace(collections.UserDict)»
+    h3 id=namespace > Class Namespace
+
+    h4 > Class definition
+    p > «Namespace(collections.UserDict)»
 
     p > A dictionary of things, indexed by their name.
 
         [Number 3]
         ||
 
-    h3 id=enum > Class «Enum(Namespace)»
+    h3 id=enum > Class Enum
+
+    h4 > Class definition
+    p > «Enum(Namespace)»
 
     p   >>
         A Namespace which is being treated as an Enum. Enums can only contain
         meant to be used in a «grammar» directly.
         >>
 
-    h3 id=some > Cardinality function «some(*thing)»
+    h3 id=some > Function some()
+    
+    h4 > Synopsis
+    p > «some(*thing)»
 
     p   >>
         At least one occurrence of thing, + operator. Inserts «-2» as
         >>> 
         ||
 
-    h3 id=maybesome > Cardinality function «maybe_some(*thing)»
+    h3 id=maybesome > Function maybe_some()
+
+    h4 > Synopsis
+    p > «maybe_some(*thing)»
 
     p   >>
         No thing or some of them, * operator. Inserts «-1» as cardinality
         ''
         ||
 
-    h3 id=optional > Cardinality function «optional(*thing)»
+    h3 id=optional > Function optional()
+
+    h4 > Synopsis
+    p > «optional(*thing)»
 
     p > Thing or no thing, ? operator. Inserts «0» as cardinality before thing.
 
         ''
         ||
 
-    h3 id=csl > Function «csl(*thing)»
+    h3 id=csl > Function csl()
+
+    h4 > Synopsis
+    p > «csl(*thing)»
 
     p > Generate a grammar for a simple comma separated list.
 
         «Something, maybe_some(",", blank, Something)»
         >>
 
-    h3 id=attr > Function «attr(name, thing=word, subtype=None)»
+    h3 id=attr > Function attr()
+
+    h4 > Synopsis
+    p > «attr(name, thing=word, subtype=None)»
 
     p   >>
         Generate an «Attribute» with that «name», referencing the «thing». An
         'int x'
         ||
 
-    h3 id=flag > Function «flag(name, thing)»
+    h3 id=flag > Function flag()
+
+    h4 > Synopsis
+    p > «flag(name, thing)»
 
     p   >>
         Generate an «Attribute» with that «name» which is valued «True» or
         '◊not◊ valid'
         ||
 
-    h3 id=name > Function «name()»
+    h3 id=name > Function name()
+
+    h4 > Synopsis
+    p > «name()»
 
     p   >>
         Generate a grammar for a Symbol with a name. This is a shortcut for
         «attr("name", Symbol)».
         >>
 
-    h3 id=ignore > Function «ignore(*grammar)»
+    h3 id=ignore > Function ignore()
+
+    h4 > Synopsis
+    p > «ignore(*grammar)»
 
     p > Ignore what matches to the grammar.
 
         only. In common grammars it will not be there.
         >>
 
-    h3 id=indent > Function «indent(*thing)»
+    h3 id=indent > Function indent()
+
+    h4 > Synopsis
+    p > «indent(*thing)»
 
     p   >>
         Indent thing by one level. Inserts «-3» as cardinality before thing.
         while parsing.
         >>
 
-    h3 id=blank > Callback function «blank(thing, parser)»
+    h3 id=blank > Callback function blank()
+
+    h4 > Synopsis
+    p > «blank(thing, parser)»
 
     p > Space marker for composing text.
 
     p > «blank» is outputting a space character (ASCII 32) when called.
 
-    h3 id=endl > Callback function «endl(thing, parser)»
+    h3 id=endl > Callback function endl()
+
+    h4 > Synopsis
+    p > «endl(thing, parser)»
 
     p > End of line marker for composing text.
  
         «endl» while composing.
         >>
 
-    h3 id=udcf > User defined callback functions «callback_function(thing, parser)»
+    h3 id=udcf > User defined callback functions
+
+    h4 > Synopsis
+    p > «callback_function(thing, parser)»
 
     p   >>
         Arbitrary callback functions can be defined and put into the «grammar».

docs/heading.en.yinc2

     include xml grammar_elements.xml
     P a href="parser_engine.html" > Parser Engine
     include xml parser_engine.xml
+    P a href="xml_backend.html" > XML Backend
+    include xml xml_backend.xml
 
     P "I want this!";
     menu {

docs/parser_engine.en.yhtml2

         Offers parsing and composing capabilities. Implements an intrinsic
         ∫Packrat parser∫.
         >>
-    
+ 
+    p   >>
+        ƒpyPEG uses memoization as speed enhancement. Create a «Parser»
+        instance to have a reset memory. Usually this is recommended if you're
+        parsing another text – the memory will not provide wrong results but
+        a reset will save memory consumption. If you're altering the grammar
+        then a memory reset is required for having correct parsing results.
+        >>
+
     h3 id=parser_vars > Instance variables
 
     p   >>
 
     glossary {
         term "whitespace"
-            > regular expression to scan whitespace; default: «re.compile(r"(?m)\s+")»
+            >>
+            Regular expression to scan whitespace; default: «re.compile(r"(?m)\s+")».
+            Set to «None» to disable automatic «whitespace» removing.
+            >>
         term "comment"
-            > «grammar» to parse comments; default: «None»
+            >>
+            «grammar» to parse comments; default: «None».
+            If a «grammar» is set here, comments will be removed from the
+            source text automatically.
+            >>
         term "last_error"
             > after parsing, «SyntaxError» which ended parsing
         term "indent"
             > filename where text is origin from
     }
 
-    h3 id=parser_init > Method «__init__(self)»
+    h3 id=parser_init > Method init()
+
+    h4 > Synopsis
+    p > «__init__(self)»
 
     p > Initialize instance variables to their defaults.
 
-    h3 id=parser_parse > Method «parse(self, text, thing, filename=None)»
+    h3 id=parser_parse > Method parse()
+
+    h4 > Synopsis
+    p > «parse(self, text, thing, filename=None)»
 
     p   >>
-        (Partial) parse text following thing.grammar and return the resulting
-        things.
+        (Partially) parse «text» following «thing.grammar» and return the
+        resulting things.
         >>
 
     p   >>
         This method parses as far as possible. It does not generate a
-        «SyntaxError» if the source «text» does not parse completely.  It
+        «SyntaxError» if the source «text» does not parse completely. It
         returns a «SyntaxError» object as «result» part of the return value if
-        the source «text» does not comply with grammar «thing».
+        the beginning of the source «text» does not comply with grammar
+        «thing».
         >>
 
     h4 > Arguments
         term "GrammarValueError"
             > if grammar contains an illegal cardinality value
     }
+
+    p > Example:
+
+    Code
+        ||
+        >>> from pypeg2 import Parser, csl, word
+        >>> ◊p = Parser()◊
+        >>> ◊p.parse("hello, world!", csl(word))◊
+        ('!', ['hello', 'world'])
+        ||
+
+
+    h3 id=parser_compose > Method compose()
+
+    h4 > Synopsis
+    p > «compose(self, thing, grammar=None)»
+
+    p > Compose text using «thing» with «grammar».
+
+    h4 > Arguments
+
+    glossary {
+        term "thing" > «thing» containing other things with «grammar»
+        term "grammar" > «grammar» to use for composing «thing»; default: «thing.grammar»
+    }
+
+    h4 > Returns
+   
+    p > Composed text
+
+    h4 > Raises
+
+    glossary {
+        term "ValueError" > if «thing» does not match «grammar»
+        term "GrammarTypeError" > if «grammar» contains an object of unkown type
+        term "GrammarValueError" > if «grammar» contains an illegal cardinality value
+    }
+
+    p > Example:
+
+    Code
+        ||
+        >>> from pypeg2 import Parser, csl, word
+        >>> ◊p = Parser()◊
+        >>> ◊p.compose(['hello', 'world'], csl(word))◊
+        'hello, world'
+        ||
+
+    h2 id=convenience > Convenience functions
+
+    h3 id=parse > Function parse()
+   
+    h4 > Synopsis
+    p > «parse(text, thing, filename=None, whitespace=whitespace, comment=None)»
+
+    p   >>
+        Parse text following «thing.grammar» and return the resulting things or
+        raise an error.
+        >>
+
+    h4 > Arguments
+
+    glossary {
+        term "text"
+            > «text» to parse
+        term "thing"
+            > «grammar» for things to parse
+        term "filename"
+            > «filename» where «text» is origin from
+        term "whitespace"
+            > regular expression to skip «whitespace»; default: «re.compile(r"(?m)\s+")»
+        term "comment"
+            > «grammar» to parse comments; default: «None»
+    }
+
+    h4 > Returns
+        p > generated things
+
+    h4 > Raises
+
+    glossary {
+        term "SyntaxError" > if «text» does not match the «grammar» in «thing»
+        term "ValueError" > if input does not match types
+        term "TypeError" > if output classes have wrong syntax for «__init__()»
+        term "GrammarTypeError"
+            > if «grammar» contains an object of unkown type
+        term "GrammarValueError"
+            > if «grammar» contains an illegal cardinality value
+    }
+
+    p > Example:
+
+    Code
+        ||
+        >>> from pypeg2 import parse, csl, word
+        >>> ◊parse("hello, world", csl(word))◊
+        ['hello', 'world']
+        ||
+
+    h3 id=compose > Function compose()
+
+    h4 > Synopsis
+    p > «compose(thing, grammar=None, indent="    ")»
+
+    p > Compose text using «thing» with «grammar».
+
+    h4 > Arguments
+
+    glossary {
+        term "thing" > «thing» containing other things with «grammar»
+        term "grammar" > «grammar» to use to compose thing; default: «thing.grammar»
+        term "indent" > string to use to indent while composing; default: four spaces
+    }
+
+    h4 > Returns
+    
+    p > composed text
+
+    h4 > Raises
+
+    glossary {
+        term "ValueError" > if input does not match «grammar»
+        term "GrammarTypeError"
+            > if «grammar» contains an object of unkown type
+        term "GrammarValueError"
+            > if «grammar» contains an illegal cardinality value
+    }
+
+    p > Example:
+
+    Code
+        ||
+        >>> from pypeg2 import compose, csl, word
+        >>> ◊compose(['hello', 'world'], csl(word))◊
+        'hello, world'
+        ||
+
+    h3 id=attributes > Function attributes()
+
+    h4 > Synopsis
+    p > «attributes(grammar)»
+
+    p > Iterates all attributes of a «grammar».
+
+    p   >>
+        This function can be used to iterate through all attributes which
+        will be generated for the top level object of the «grammar».
+        >>
+
+    p > Example:
+
+    Code
+        ||
+        >>> 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
+        >>> 
+        ||
+
+    h3 id=howmany > Function how_many()
+
+    h4 > Synopsis
+    p > «how_many(grammar)»
+
+    p > Determines the possibly parsed objects of grammar.
+
+    p   >>
+        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.
+        >>
+
+    h4 > Returns
+
+    glossary {
+        term "0" > if there will be no objects
+        term "1" > if there will be a maximum of one object
+        term "2" > if there can be more than one object
+    }
+
+    h4 > Raises
+
+    glossary {
+        term "GrammarTypeError"
+            > if «grammar» contains an object of unkown type
+        term "GrammarValueError"
+            > if «grammar» contains an illegal cardinality value
+    }
+
+    p > Example:
+
+    Code
+        ||
+        >>> from pypeg2 import how_many, word, csl
+        >>> ◊how_many("some")◊
+        0
+        >>> ◊how_many(word)◊
+        1
+        >>> ◊how_many(csl(word))◊
+        2
+        ||
+
+    div id="bottom" {
+        "Want to download? Go to the "
+        a "#top", "^Top^"; " and look to the right ;-)"
+    }
 }

docs/xml_backend.en.yhtml2

+page "pyPEG – XML Backend", "counter-reset: chapter 3;" {
+    h1 id=xmlbackend > XML Backend of ƒpyPEG
+
+    h2 id=workhorses > «etree» functions
+
+    p   >>
+        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
+        ¬http://lxml.de/ lxml¬ is recommended. If the module «lxml» is
+        installed, ƒpyPEG uses it automatically.
+        >>
+
+    h3 id=create_tree > Function create_tree()
+
+    h4 > Synopsis
+    p > «create_tree(thing, parent=None, object_names=False)»
+
+    p > Create an XML etree from a thing.
+
+    h4 > Arguments
+
+    glossary {
+        term "thing" > «thing» to interpret
+        term "parent" > «etree.Element» to put subtree into; default: create a new «Element» tree
+        term "object_names"
+            >>
+            experimental feature: if «True» tag names are object
+            names instead of types
+            >>
+    }
+
+    h4 > Returns
+
+    p > «etree.Element» instance created
+
+    p > Example:
+
+    Code
+        ||
+        >>> 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'>
+        ||
+
+    h3 id=create_thing > Function create_thing()
+
+    h4 > Synopsis
+    p > «create_thing(element, symbol_table)»
+
+    p > Create thing from an XML element.
+
+    h4 > Arguments
+
+    glossary {
+        term "element" > «etree.Element» instance to read
+        term "symbol_table" > symbol table where the classes can be found; usually call «globals()»
+    }
+
+    h4 > Returns
+
+    p > «thing» created
+
+    p > Example:
+
+    Code
+        ||
+        >>> 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'>
+        ||
+
+    h2 id=xmlconvenience > XML convenience functions
+
+    h3 id=thing2xml > Function thing2xml()
+
+    h4 > Synopsis
+    p > «thing2xml(thing, pretty=False, object_names=False)»
+
+    p > Create XML text from a thing.
+
+    h4 > Arguments
+
+    glossary {
+        term "thing" > «thing» to interpret
+        term "pretty"
+            >>
+            «True» if XML should be indented, «False» if XML should be plain
+            (this feature requires ¬http://lxml.de lxml¬)
+            >>
+        term "object_names"
+            >>
+            experimental feature: if «True» tag names are object
+            names instead of types
+            >>
+    }
+
+    h4 > Returns
+
+    p > «bytes» with encoded XML 
+
+    p > Example:
+
+    Code
+        ||
+        >>> 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>'
+        ||
+
+    h3 id=xml2thing > Function xml2thing()
+
+    h4 > Synopsis
+    p > «xml2thing(xml, symbol_table)»
+
+    p > Create «thing» from XML text.
+
+    h4 > Arguments
+
+    glossary {
+        term "xml" > «bytes» with encoded XML
+        term "symbol_table" > symbol table where the classes can be found; usually call «globals()»
+    }
+
+    h4 > Returns
+
+    p > created «thing»
+
+    p > Example:
+
+    Code
+        ||
+        >>> 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'
+        ||
+
+    div id="bottom" {
+        "Want to download? Go to the "
+        a "#top", "^Top^"; " and look to the right ;-)"
+    }
+}

pypeg2/__init__.py

         comment     grammar to parse comments
                     default: None
 
-    Returns generated objects.
+    Returns generated things.
 
     Raises:
         SyntaxError if text does not match the grammar in thing
         self._got_endl = False
 
     def parse(self, text, thing, filename=None):
-        """(Partial) parse text following thing grammar and return the
+        """(Partially) parse text following thing grammar and return the
         resulting things.
 
         Arguments:
 
         Arguments:
             thing           thing containing other things with grammar
-            grammar         grammar to use to compose thing
+            grammar         grammar to use for composing thing
                             default: thing.grammar
 
         Returns text
 
         Raises:
-            ValueError      if input does not match grammar
+            ValueError      if thing does not match grammar
             GrammarTypeError
                             if grammar contains an object of unkown type
             GrammarValueError
 import pypeg2
 
 
-def create_tree(thing, object_names=False, parent=None):
+def 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 object created
+        etree.Element instance created
     """
 
     try:
                 found = True
                 break
         if not found:
-            create_tree(value, object_names, me)
+            create_tree(value, me, object_names)
 
     if isinstance(thing, list):
         things = thing
             else:
                 me.text = str(t)
         else:
-            last = create_tree(t, object_names, me)
+            last = create_tree(t, me, object_names)
 
     if isinstance(thing, str):
         me.text = str(thing)
 
     Arguments:
         thing           thing to interpret
-        pretty          True if xml should be indented
-                        False if xml should be plain
+        pretty          True if XML should be indented
+                        False if XML should be plain
+        object_names    experimental feature: if True tag names are object
+                        names instead of types
 
     Returns:
         bytes with encoded XML 
     """
 
-    tree = create_tree(thing, object_names)
+    tree = create_tree(thing, None, object_names)
     try:
         if lxml:
             return etree.tostring(tree, pretty_print=pretty)
 
 
 def create_thing(element, symbol_table):
-    """Create thing from an XML eelement.
+    """Create thing from an XML element.
 
     Arguments:
-        element         Element instance to read
+        element         etree.Element instance to read
         symbol_table    symbol table where the classes can be found
 
     Returns: