pyparsing.ParseResults

Module pyparsing :: Class ParseResults |
[frames] | no frames]

# Class ParseResults

source code

    object --+
             |
            ParseResults

Structured parse results, to provide multiple means of access to the parsed data:

- as a list (`len(results)`)
- by list index (`results[0], results[1]`, etc.)
- by attribute (`results.<resultsName>` - see ParserElement.setResultsName)

Example:

       integer = Word(nums)
       date_str = (integer.setResultsName("year") + '/'
                       + integer.setResultsName("month") + '/'
                       + integer.setResultsName("day"))
       # equivalent form:
       # date_str = integer("year") + '/' + integer("month") + '/' + integer("day")

       # parseString returns a ParseResults object
       result = date_str.parseString("1999/12/31")

       def test(s, fn=repr):
           print("%s -> %s" % (s, fn(eval(s))))
       test("list(result)")
       test("result[0]")
       test("result['month']")
       test("result.day")
       test("'month' in result")
       test("'minutes' in result")
       test("result.dump()", str)

prints:

       list(result) -> ['1999', '/', '12', '/', '31']
       result[0] -> '1999'
       result['month'] -> '12'
       result.day -> '31'
       'month' in result -> True
       'minutes' in result -> False
       result.dump() -> ['1999', '/', '12', '/', '31']
       - day: 31
       - month: 12
       - year: 1999

Instance Methods
__init__(self, toklist=None, name=None, asList=True, modal=True, isinstance=<built-in function isinstance>) x.__init__(...) initializes x; see help(type(x)) for signature | source code
__getitem__(self, i) | source code
__setitem__(self, k, v, isinstance=<built-in function isinstance>) | source code
__delitem__(self, i) | source code
__contains__(self, k) | source code
__len__(self) | source code
__bool__(self) | source code
__nonzero__(self) | source code
__iter__(self) | source code
__reversed__(self) | source code
iterkeys(self) Returns an iterator of all named result keys (Python 2.x only). | source code
itervalues(self) Returns an iterator of all named result values (Python 2.x only). | source code
iteritems(self) Returns an iterator of all named result key-value tuples (Python 2.x only). | source code
keys(self) Returns all named result keys (as a list in Python 2.x, as an iterator in Python 3.x). | source code
values(self) Returns all named result values (as a list in Python 2.x, as an iterator in Python 3.x). | source code
items(self) Returns all named result key-values (as a list of tuples in Python 2.x, as an iterator in Python 3.x). | source code
haskeys(self) Since keys() returns an iterator, this method is helpful in bypassing code that looks for the existence of any defined results names. | source code
pop(self, *args, **kwargs) Removes and returns item at specified index (default=`last`). | source code
get(self, key, defaultValue=None) Returns named result matching the given key, or if there is no such name, then returns the given `defaultValue` or `None` if no `defaultValue` is specified. | source code
insert(self, index, insStr) Inserts new element at location index in the list of parsed tokens. | source code
append(self, item) Add single element to end of ParseResults list of elements. | source code
extend(self, itemseq) Add sequence of elements to end of ParseResults list of elements. | source code
clear(self) Clear all elements and results names. | source code
__getattr__(self, name) | source code
__add__(self, other) | source code
__iadd__(self, other) | source code
__radd__(self, other) | source code
__repr__(self) repr(x) | source code
__str__(self) str(x) | source code
asList(self) Returns the parse results as a nested list of matching tokens, all converted to strings. | source code
asDict(self) Returns the named parse results as a nested dictionary. | source code
copy(self) Returns a new copy of a `ParseResults` object. | source code
asXML(self, doctag=None, namedItemsOnly=False, indent=`'````'`, formatted=True) (Deprecated) Returns the parse results as XML. | source code
getName(self) Returns the results name for this token expression. | source code
dump(self, indent=`'````'`, depth=0, full=True) Diagnostic method for listing out the contents of a `ParseResults`. | source code
pprint(self, *args, **kwargs) Pretty-printer for parsed results as a list, using the `pprint` module. | source code
__getstate__(self) | source code
__setstate__(self, state) | source code
__getnewargs__(self) | source code
__dir__(self) | source code
Inherited from `object`: `__delattr__`, `__format__`, `__getattribute__`, `__hash__`, `__reduce__`, `__reduce_ex__`, `__setattr__`, `__sizeof__`, `__subclasshook__`

Static Methods
a new object with type S, a subtype of T |
__new__(cls, toklist=None, name=None, asList=True, modal=True) | source code

Properties
Inherited from `object`: `__class__`

Method Details

### __new__(cls, toklist=None, name=None, asList=True, modal=True) Static Method | source code
Returns: a new object with type S, a subtype of T Overrides: object.__new__ (inherited documentation)

### __init__(self, toklist=None, name=None, asList=True, modal=True, isinstance=<built-in function isinstance>) (Constructor) | source code
x.__init__(...) initializes x; see help(type(x)) for signature Overrides: object.__init__ (inherited documentation)

### pop(self, *args, **kwargs) | source code
Removes and returns item at specified index (default=`last`). Supports both `list` and `dict` semantics for `pop()`. If passed no argument or an integer argument, it will use `list` semantics and pop tokens from the list of parsed tokens. If passed a non-integer argument (most likely a string), it will use `dict` semantics and pop the corresponding value from any defined results names. A second default return value argument is supported, just as in `dict.pop()`. Example:
       def remove_first(tokens):
           tokens.pop(0)
       print(OneOrMore(Word(nums)).parseString("0 123 321")) # -> ['0', '123', '321']
       print(OneOrMore(Word(nums)).addParseAction(remove_first).parseString("0 123 321")) # -> ['123', '321']

       label = Word(alphas)
       patt = label("LABEL") + OneOrMore(Word(nums))
       print(patt.parseString("AAB 123 321").dump())

       # Use pop() in a parse action to remove named result (note that corresponding value is not
       # removed from list form of results)
       def remove_LABEL(tokens):
           tokens.pop("LABEL")
           return tokens
       patt.addParseAction(remove_LABEL)
       print(patt.parseString("AAB 123 321").dump())
prints:
       ['AAB', '123', '321']
       - LABEL: AAB

       ['AAB', '123', '321']

### get(self, key, defaultValue=None) | source code
Returns named result matching the given key, or if there is no such name, then returns the given `defaultValue` or `None` if no `defaultValue` is specified. Similar to `dict.get()`. Example:
       integer = Word(nums)
       date_str = integer("year") + '/' + integer("month") + '/' + integer("day")

       result = date_str.parseString("1999/12/31")
       print(result.get("year")) # -> '1999'
       print(result.get("hour", "not specified")) # -> 'not specified'
       print(result.get("hour")) # -> None

### insert(self, index, insStr) | source code
Inserts new element at location index in the list of parsed tokens. Similar to `list.insert()`. Example:
       print(OneOrMore(Word(nums)).parseString("0 123 321")) # -> ['0', '123', '321']

       # use a parse action to insert the parse location in the front of the parsed results
       def insert_locn(locn, tokens):
           tokens.insert(0, locn)
       print(OneOrMore(Word(nums)).addParseAction(insert_locn).parseString("0 123 321")) # -> [0, '0', '123', '321']

### append(self, item) | source code
Add single element to end of ParseResults list of elements. Example:
       print(OneOrMore(Word(nums)).parseString("0 123 321")) # -> ['0', '123', '321']

       # use a parse action to compute the sum of the parsed integers, and add it to the end
       def append_sum(tokens):
           tokens.append(sum(map(int, tokens)))
       print(OneOrMore(Word(nums)).addParseAction(append_sum).parseString("0 123 321")) # -> ['0', '123', '321', 444]

### extend(self, itemseq) | source code
Add sequence of elements to end of ParseResults list of elements. Example:
       patt = OneOrMore(Word(alphas))

       # use a parse action to append the reverse of the matched strings, to make a palindrome
       def make_palindrome(tokens):
           tokens.extend(reversed([t[::-1] for t in tokens]))
           return ''.join(tokens)
       print(patt.addParseAction(make_palindrome).parseString("lskdj sdlkjf lksd")) # -> 'lskdjsdlkjflksddsklfjkldsjdksl'

### __repr__(self) (Representation operator) | source code
repr(x) Overrides: object.__repr__ (inherited documentation)

### __str__(self) (Informal representation operator) | source code
str(x) Overrides: object.__str__ (inherited documentation)

### asList(self) | source code
Returns the parse results as a nested list of matching tokens, all converted to strings. Example:
       patt = OneOrMore(Word(alphas))
       result = patt.parseString("sldkj lsdkj sldkj")
       # even though the result prints in string-like form, it is actually a pyparsing ParseResults
       print(type(result), result) # -> <class 'pyparsing.ParseResults'> ['sldkj', 'lsdkj', 'sldkj']

       # Use asList() to create an actual list
       result_list = result.asList()
       print(type(result_list), result_list) # -> <class 'list'> ['sldkj', 'lsdkj', 'sldkj']

### asDict(self) | source code
Returns the named parse results as a nested dictionary. Example:
       integer = Word(nums)
       date_str = integer("year") + '/' + integer("month") + '/' + integer("day")

       result = date_str.parseString('12/31/1999')
       print(type(result), repr(result)) # -> <class 'pyparsing.ParseResults'> (['12', '/', '31', '/', '1999'], {'day': [('1999', 4)], 'year': [('12', 0)], 'month': [('31', 2)]})

       result_dict = result.asDict()
       print(type(result_dict), repr(result_dict)) # -> <class 'dict'> {'day': '1999', 'year': '12', 'month': '31'}

       # even though a ParseResults supports dict-like access, sometime you just need to have a dict
       import json
       print(json.dumps(result)) # -> Exception: TypeError: ... is not JSON serializable
       print(json.dumps(result.asDict())) # -> {"month": "31", "day": "1999", "year": "12"}

### asXML(self, doctag=None, namedItemsOnly=False, indent=`'````'`, formatted=True) | source code
(Deprecated) Returns the parse results as XML. Tags are created for tokens and lists that have defined results names.

### getName(self) | source code
Returns the results name for this token expression. Useful when several different expressions might match at a particular location. Example:
       integer = Word(nums)
       ssn_expr = Regex(r"\d\d\d-\d\d-\d\d\d\d")
       house_number_expr = Suppress('#') + Word(nums, alphanums)
       user_data = (Group(house_number_expr)("house_number")
                   | Group(ssn_expr)("ssn")
                   | Group(integer)("age"))
       user_info = OneOrMore(user_data)

       result = user_info.parseString("22 111-22-3333 #221B")
       for item in result:
           print(item.getName(), ':', item[0])
prints:
       age : 22
       ssn : 111-22-3333
       house_number : 221B

### dump(self, indent=`'````'`, depth=0, full=True) | source code
Diagnostic method for listing out the contents of a `ParseResults`. Accepts an optional `indent` argument so that this string can be embedded in a nested display of other data. Example:
       integer = Word(nums)
       date_str = integer("year") + '/' + integer("month") + '/' + integer("day")

       result = date_str.parseString('12/31/1999')
       print(result.dump())
prints:
       ['12', '/', '31', '/', '1999']
       - day: 1999
       - month: 31
       - year: 12

### pprint(self, *args, **kwargs) | source code
Pretty-printer for parsed results as a list, using the `pprint` module. Accepts additional positional or keyword args as defined for the `pprint.pprint` method. (http://docs.python.org/3/library/pprint.html#pprint.pprint) Example:
       ident = Word(alphas, alphanums)
       num = Word(nums)
       func = Forward()
       term = ident | num | Group('(' + func + ')')
       func <<= ident + Group(Optional(delimitedList(term)))
       result = func.parseString("fna a,b,(fnb c,d,200),100")
       result.pprint(width=40)
prints:
       ['fna',
        ['a',
         'b',
         ['(', 'fnb', ['c', 'd', '200'], ')'],
         '100']]