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.
Match expr zero or more times, returning a list of matches.
Match expr one or more times, returning a list of matches.
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.
Match expr n times exactly.
Negative lookahead. Fails if the next item in the input matches expr. Consumes no input.
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.
Match the literal character ‘x’.
Returns the string consumed by matching expr. Good for tokenizing rules.
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!
Invoke a Python expression as an action.
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>, tracefunc=None)[source]

Create a class from a Parsley grammar.

  • 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.

Access the internal parser class for a Parsley grammar object.


Build a TermL term tree from a string.


Build a quasiterm from a string.

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

Create a Twisted Protocol factory from a Parsley grammar.

  • 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.

A nullary callable which will return an instance of ParserProtocol.


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:


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


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.


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() is called after the ParserProtocol has established a connection, and is passed the ParserProtocol instance itself.

Parameters:parserProtocol – An instance of ProtocolParser.

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

Matches a single character from the input.
Matches a single ASCII letter.
Matches a decimal digit.
Combines the above.
Matches the end of input.
Matches zero or more spaces, tabs, or newlines.
Matches the character char.