cly.parser
CLY parser classes.
Constructs for parsing user input with a :class:`~cly.builder.Grammar`.
class HelpParser()
Extract the help for children of the specified Node.
Help is extracted from the Node's children, following branches, and returned ordered by group, order and finally help key and string.
__init__(self, context, node)(Not documented)
__iter__(self)Iterate over each (key, help) help pair.
>>> from cly.builder import Grammar, Node, Help >>> context = Context(None, None) >>> class Test(Node): ... def help(self, context): ... return 'HELP!' >>> help = HelpParser(context, Grammar( ... one=Node(help='1'), ... two=Node(help=Help.pair('<two>', '2'), group=2), ... three=Test(help='HELP!'), ... )) >>> list(help) [(0, 'one', '1'), (0, 'three', 'HELP!'), (2, '<two>', '2')]format(self)Format help into a human readable form.
Output is formatted for use with cly.console.
Returns a list of lines of text.
>>> from cly.builder import Grammar, Node, Help >>> import sys >>> context = Context(None, None) >>> grammar = Grammar( ... one=Node(help='1'), ... two=Node(help=Help.pair('<two>', '2'), group=2)) >>> help = HelpParser(context, grammar) >>> print '\n'.join(help.format()) ^Bone ^B 1 <BLANKLINE> ^B<two>^B 2
class Context()
Represents the parsing context for a single command.
A Context is created automatically when input is parsed. It contains all the information needed to maintain state during the parse, including the current cursor position in the input stream, the current node in the grammar, variables collected and a history of nodes traversed.
Basic usage is:
parser = Parser(grammar) context = parser.parse('some input text') print context.varsIf the input is invalid the context will have consumed as much input as possible. The attributes parsed and remaining contain how much text has been consumed and remains, respectively.
Useful attributes:
__init__(self, parser, command, data=None)(Not documented)
execute(self)Execute the current (terminal) node. If there is still input remaining an exception will be thrown.
>>> from cly.builder import Grammar, Node, Action >>> def test(): print 'OK' >>> parser = Parser(Grammar(one=Node()(Action(callback=test)))) >>> context = parser.parse('one') >>> context.execute() OKadvance(self, distance)Advance cursor.
>>> context = Context(None, 'one two') >>> context.cursor 0 >>> context.advance(4) >>> context.cursor 4
candidates(self, text=None)Return potential candidates from children of last successfully parsed node.
- Arguments:
text: If provided, return candidates after text, otherwise the remaining unparsed text in the current command will be used.
>>> from cly.builder import Grammar, Node >>> parser = Parser(Grammar(one=Node()(two=Node(), ... three=Node()), four=Node())) >>> context = parser.parse('one') >>> list(context.candidates()) ['three ', 'two '] >>> list(context.candidates('th')) ['three ']help(self)Return a HelpParser object describing the last successfully parsed node.
>>> import sys >>> from cly.builder import Grammar, Node >>> parser = Parser(Grammar(one=Node(help='4', two=Node(help='2'), ... three=Node(help='3')), four=Node(help='4'))) >>> context = parser.parse('one') >>> help = context.help() >>> print '\n'.join(help.format()) ^Bthree^B 3 ^Btwo ^B 2selected(self, node)The given node has been selected and will be followed.
traversed(self, node)How many times has node been traversed in this context?
>>> from cly.builder import Grammar, Node, Alias >>> parser = Parser(Grammar(one=Node(traversals=0)(Alias(target='/one')))) >>> node = parser.find('/one') >>> for i in range(4): ... context = parser.parse('one ' * i) ... print context.traversed(node), context.parsed # doctest: +NORMALIZE_WHITESPACE 0 1 one 2 one one 3 one one oneupdate_locals(self, locals)Update locals before XML evaluation.
__repr__(self)(Not documented)
class Parser()
Parse and execute user input against a :class:`~cly.builder.Grammar`.
For each parse, the parser creates a :class:`Context` containing the state for the run and parses the input, and executes any callbacks.
After parsing, the returned :class:`Context` can be interrogated for information or used to execute any :class:`~cly.builder.Action`s.
- Arguments:
grammar: Grammar to parse with.
data: User data to attach to Context.
context_factory: A callable used to create new :class:`Context` objects.
__init__(self, grammar, data=None, context_factory=Context)Construct a new Parser.
parse(self, command, data=None)Parse command using the current :class:`~cly.builder.Grammar`.
This will return a :class:`Context` object that can be used to inspect the state of the parser.
- Arguments:
command: String to parse.
data: Used to pass user data through to callbacks. The :class:`Context` object has this as an attribute , available to any :class:`~cly.builder.Action` node callbacks that have set with_context=True.
>>> from cly import * >>> parser = Parser(Grammar(one=Node(), two=Node(three=Node( ... action=Action(callback=lambda: "foo bar"))))) >>> context = parser.parse('two three') >>> context <Context command:'two three' remaining:''> >>> context.execute() 'foo bar' >>> parser.parse('two four') <Context command:'two four' remaining:'four'>merge(self, grammar, where=None)Merge another grammar into this one.
- Arguments:
where: A label or path to a node. grammar: Grammar to merge.
execute(self, command, data=None)Parse and execute the given command.
This is a convenience function that calls :meth:`~Context.execute` on the :class:`Context` object returned by :meth:`parse`.
Arguments are the same as for :meth:`parse`.
>>> from cly.builder import Grammar, Node, Action >>> parser = Parser(Grammar(one=Node(), two=Node(three=Node( ... action=Action(callback=lambda: "foo bar"))))) >>> parser.execute('two three') 'foo bar'find(self, path)Find a node by its absolute path.
>>> from cly.builder import Grammar, Node, Action >>> parser = Parser(Grammar(one=Node(), two=Node(three=Node()))) >>> parser.find('/two/three') <Node:/two/three>