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