Parsley Reference — Parsley 1.1 documentation

### Navigation

- index
- modules |
- previous |
- Parsley 1.1 documentation »

# Parsley Reference

## Basic syntax

`foo = ....`:
  Define a rule named foo.
`expr1 expr2`:
  Match expr1, and then match expr2 if it succeeds, returning the value of expr2. Like Python’s `and`.
`expr1 | expr2`:
  Try to match `expr1` — if it fails, match `expr2` instead. Like Python’s `or`.
`expr*`:
  Match `expr` zero or more times, returning a list of matches.
`expr+`:
  Match `expr` one or more times, returning a list of matches.
`expr?`:
  Try to match `expr`. Returns `None` if it fails to match.
`expr{n, m}`:
  Match `expr` at least `n` times, and no more than `m` times.
`expr{n}`:
  Match `expr` `n` times exactly.
`~expr`:
  Negative lookahead. Fails if the next item in the input matches `expr`. Consumes no input.
`~~expr`:
  Positive lookahead. Fails if the next item in the input does not match `expr`. Consumes no input.
`ruleName` or `ruleName(arg1 arg2 etc)`:
  Call the rule `ruleName`, possibly with args.
`'x'`:
  Match the literal character ‘x’.
`<expr>`:
  Returns the string consumed by matching `expr`. Good for tokenizing rules.
`expr:name`:
  Bind the result of expr to the local variable `name`.
`-> pythonExpression`:
  Evaluate the given Python expression and return its result. Can be used inside parentheses too!
`!(pythonExpression)`:
  Invoke a Python expression as an action.
`?(pythonExpression)`:
  Fail if the Python expression is false, Returns True otherwise.
`expr ^(CustomLabel)`:
  If the expr fails, the exception raised will contain CustomLabel. Good for providing more context when a rule is broken. CustomLabel can contain any character other than “(” and ”)”.

Comments like Python comments are supported as well, starting with # and extending to the end of the line.

## Python API

`parsley.` `makeGrammar`(source, bindings, name='Grammar', unwrap=False, extends=<function makeParser at 0x10268aa28>, tracefunc=None)

  Create a class from a Parsley grammar.

  Parameters: | source – A grammar, as a string. bindings – A mapping of variable names to objects. name – Name used for the generated class. unwrap – If True, return a parser class suitable for subclassing. If False, return a wrapper with the friendly API. extends – The superclass for the generated parser class. tracefunc – A 3-arg function which takes a fragment of grammar source, the start/end indexes in the grammar of this fragment, and a position in the input. Invoked for terminals and rule applications.

`parsley.` `unwrapGrammar`(w)

  Access the internal parser class for a Parsley grammar object.

`parsley.` `term`(termString)

  Build a TermL term tree from a string.

`parsley.` `quasiterm`(termString)

  Build a quasiterm from a string.

`parsley.` `makeProtocol`(source, senderFactory, receiverFactory, bindings=None, name='Grammar')

  Create a Twisted `Protocol` factory from a Parsley grammar.

  Parameters: | source – A grammar, as a string. senderFactory – A one-argument callable that takes a twisted `Transport` and returns a sender. receiverFactory – A one-argument callable that takes the sender returned by the `senderFactory` and returns a receiver. bindings – A mapping of variable names to objects which will be accessible from python code in the grammar. name – The name used for the generated grammar class.
  Returns: | A nullary callable which will return an instance of `ParserProtocol`.

`parsley.` `stack`(*wrappers)

  Stack some senders or receivers for ease of wrapping.

  `stack(x, y, z)` will return a factory usable as a sender or receiver factory which will, when called with a transport or sender as an argument, return `x(y(z(argument)))`.

### Protocol parsing API

class `ometa.protocol.` `ParserProtocol`

  The Twisted `Protocol` subclass used for parsing stream protocols using Parsley. It has two public attributes:

  `sender`

    After the connection is established, this attribute will refer to the sender created by the sender factory of the `ParserProtocol`.

  `receiver`

    After the connection is established, this attribute will refer to the receiver created by the receiver factory of the `ParserProtocol`.

  It’s common to also add a `factory` attribute to the `ParserProtocol` from its factory’s `buildProtocol` method, but this isn’t strictly required or guaranteed to be present.

  Subclassing or instantiating `ParserProtocol` is not necessary; `makeProtocol()` is sufficient and requires less boilerplate.

class `ometa.protocol.` `Receiver`

  `Receiver` is not a real class but is used here for demonstration purposes to indicate the required API.

  `currentRule`

    `ParserProtocol` examines the `currentRule` attribute at the beginning of parsing as well as after every time a rule has completely matched. At these times, the rule with the same name as the value of `currentRule` will be selected to start parsing the incoming stream of data.

  `prepareParsing`(parserProtocol)

    `prepareParsing()` is called after the `ParserProtocol` has established a connection, and is passed the `ParserProtocol` instance itself.

    Parameters: | parserProtocol – An instance of `ProtocolParser`.

  `finishParsing`(reason)

    `finishParsing()` is called if an exception was raised during parsing, or when the `ParserProtocol` has lost its connection, whichever comes first. It will only be called once.

    An exception raised during parsing can be due to incoming data that doesn’t match the current rule or an exception raised calling python code during matching.

    Parameters: | reason – A Failure encapsulating the reason parsing has ended.

Senders do not have any required API as `ParserProtocol` will never call methods on a sender.

## Built-in Parsley Rules

`anything`:
  Matches a single character from the input.
`letter`:
  Matches a single ASCII letter.
`digit`:
  Matches a decimal digit.
`letterOrDigit`:
  Combines the above.
`end`:
  Matches the end of input.
`ws`:
  Matches zero or more spaces, tabs, or newlines.
`exactly(char)`:
  Matches the character char.

### Navigation

- index
- modules |
- previous |
- Parsley 1.1 documentation »