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, matchexpr2
instead. Like Python’sor
. 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
. ReturnsNone
if it fails to match. expr{n, m}
:- Match
expr
at leastn
times, and no more thanm
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
orruleName(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>, tracefunc=None)[source]¶ 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.
term
(termString)¶ Build a TermL term tree from a string.
-
parsley.
makeProtocol
(source, senderFactory, receiverFactory, bindings=None, name='Grammar')[source]¶ 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)[source]¶ 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, returnx(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 theParserProtocol
from its factory’sbuildProtocol
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 thecurrentRule
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 ofcurrentRule
will be selected to start parsing the incoming stream of data.
-
prepareParsing
(parserProtocol)¶ prepareParsing()
is called after theParserProtocol
has established a connection, and is passed theParserProtocol
instance itself.Parameters: parserProtocol – An instance of ProtocolParser
.
-
finishParsing
(reason)¶ finishParsing()
is called if an exception was raised during parsing, or when theParserProtocol
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.