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

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.