kessel.primitives — Base parsers

Primitive parsers.

The functions contained are primitive functions for constructing parsers; for creating parsing functions.

A parsing function is any function that:

  • takes an iterator,
  • on success, returns the value parsed and an iterator, and,
  • on failure, raises an instance of ParseError.

You must _always_ use the iterator returned from parsing functions to continue parsing (or to otherwise consume input).

exception kessel.primitives.ParseError(value, it, expected)

Describes an error that occurs during parsing.

  • value – The erroneous item in the stream encountered.
  • it – The remainder of the stream.
  • expected – A set of expected values. This is intended only as a human-readable description.
class Entity(value)

Defines an entity used to display in the error message.


list of weak references to the object (if defined)


list of weak references to the object (if defined)


Returns the iterator with the erroneous item, prepended.

This is useful when the consumption of a single item in the stream needs to be undone. This will also drop sentinel EOF values from the stream.

class kessel.primitives.Proxy

Proxies a parsing function such that it can be defined later.

This is useful in the case of recursive grammars, where a production rule may be defined in terms of itself.


Forwards the stream to the underlying parser.

Parameters:it – The stream to parse.
Raises ValueError:
 If there is no parsing function bound.
Returns:The parse result.



list of weak references to the object (if defined)


Binds a parsing function to the proxy.

This can only be done once.

Parameters:parser – A parsing function to bind.
Raises ValueError:
 If there is already a parsing function bound.

Matches nothing, and will throw an error with the specified expectation.

Parameters:expected – List of expected values appropriate here.
Returns:The parsing function.
kessel.primitives.match(cond, expected=None)

Advances the input stream once and matches against a condition.

If the condition does not hold, then ParseError is thrown.

If end-of-file is reached, ParseError is also thrown, but the value contained in the error will be the special EOF literal.

  • cond – Boolean predicate that the item in the stream should match.
  • expected – List of expected values appropriate here.
Raises ParseError:

If the predicate did not hold.


The parsing function.


Returns the result of the given function without advancing the stream.

Parameters:f – The function to be run.
Returns:The parsing function.