parser_instances.rst

Creating new Parser instances

parsy

Normally you will create Parser instances using the provided primitives </ref/primitives> and combinators </ref/methods_and_combinators>.

However it is also possible to create them manually, as below.

The Parser constructor should be passed a function that takes the string/list to be parsed and an index into that string, and returns a Result object. The Result object will be created either using Result.success or Result.failure to indicate success or failure respectively. Result.success should be passed the next index to continue parsing with, and the value that is returned from the parsing. Result.failure should return the index at which failure occurred i.e. the index passed in, and a string indicating what the parser expected to find.

The Parser constructor will usually be called using decorator syntax. In order to pass parameters to the Parser instance, it is typically created using a closure. In the example below, we create a parser that matches any string/list of tokens of a given length. This could also be written as something like any_char.times(n).concat() but the following will be more efficient:

def consume(n):

    @Parser
    def consumer(stream, index):
        items = stream[index:index + n]
        if len(items) == n:
            return Result.success(index + n, items)
        else:
            return Result.failure(index, "{0} items".format(n))

    return consumer

>>> consume(3).many().parse('abc123def')
['abc', '123', 'def']

Result objects

success(next_index, value)

Creates a Result object indicating parsing succeeded. The index to continue parsing at, and the value retrieved from the parsing, should be passed.

failure(index, expected)

Creates a Result object indicating parsing failed. The index to continue parsing at, and a string representing what the parser expected to find, should be passed.