The peak.rules.syntax module allows you to define pattern-matching
predicates against snippets of parameterized Python code, such that a
rule expression like:
syntax.match(expr, type(~~x) is ~~y) and isinstance(y, Const)
Will return true if expr is a PEAK-Rules AST of the form:
Compare(Call(Const(type), (v1,)), ('is', Const(v2)))
(where v1 and v2 are arbitrary values).
Table of Contents
Bind variables are placeholders in a pattern that "bind" themselves to the
value found in that location in the matched data structure. Thus, in the
example above, ~~x and ~~y are bind variables, and cause "y"
in the later part of the expression to refer to the right-hand side of the
is operator being matched. (The arbitrary value v2 in the example
above.)
Bind variables are represented within a tree as an AST node created from the variable name:
>>> from peak.rules.syntax import Bind
>>> Bind('x')
Bind('x')
The match_predicate(pattern, expr, binds) function is used to combine a
pattern AST and an expression AST to create a PEAK-Rules predicate object that
will match the specified pattern. The binds argument is a dictionary mapping
from bind-variable names to lists of expression ASTs, and is modified in-place
as the predicate is assembled:
>>> from peak.rules.syntax import match_predicate
Rules defined for this function will determine what to do based on the type of
pattern. If pattern is a bind variable, the binds dictionary is updated
in-place, inserting expr under the bind variable's name, and True is
returned, indicating that this part of the pattern will always match:
>>> from peak.util.assembler import Local
>>> b = {}
>>> match_predicate(Bind('x'), Local('y'), b)
True
>>> b
{'x': [Local('y')]}
If there's already an entry for that variable in the binds dictionary, a more complex predicate is returned, performing an equality comparison between the new binding and the old binding of the variable, and the value in binds is updated:
>>> match_predicate(Bind('x'), Local('z'), b)
Test(Truth(Compare(Local('z'), (('==', Local('y')),))), True)
This is so that patterns like ~~x is not ~~x will actually compare the two
"x"s and see if they're equal. Of course, if you bind the same variable more
than once to equal expression ASTs, you will not get back a comparison, and
the binds will be unchanged:
>>> match_predicate(Bind('x'), Local('z'), b)
True
>>> b
{'x': [Local('y'), Local('z')]}
Finally, there is a special exception for bind variables named ~~_: that
is, a single underscore. Bind variables of this name are never stored in the
binds, and always return True as a predicate, allowing you to use them as
"don't care" placeholders:
>>> any = Bind('_')
>>> match_predicate(any, Local('q'), b)
True
>>> b
{'x': [Local('y'), Local('z')]}
For most node types other than Bind, the predicates are a bit more complex.
By default, the predicate should be an exact (istype) match of the node
type, intersected with a recursive application of match_predicate() to each
of the target node's children. For example:
>>> b = {}
>>> from peak.util.assembler import *
>>> from peak.rules.codegen import *
>>> match_predicate(Add(any, any), Local('q'), b)
Test(IsInstance(Local('q')), istype(<class '...Add'>, True))
>>> b
{}
Each child is defined via a Getitem() operation on the target node, so that
any placeholders and criteria will target the right part of the tree:
>>> match_predicate(Add(Bind('x'), Bind('y')), Local('q'), b)
Test(IsInstance(Local('q')), istype(<class '...Add'>, True))
>>> b
{'y': [Getitem(Local('q'), Const(2))],
'x': [Getitem(Local('q'), Const(1))]}
Non-node patterns are treated as equality comparisons:
>>> b = {}
>>> match_predicate(42, Local('q'), b)
Test(Comparison(Local('q')), Value(42, True))
>>> b
{}
Except for None, which produces an is None test:
>>> match_predicate(None, Local('q'), b)
Test(Identity(Local('q')), IsObject(None, True))
>>> b
{}
And sequences are matched by comparing their length:
>>> match_predicate((), Local('q'), b)
Test(Comparison(Call(Const(<... len>), (Local('q'),),...)), Value(0, True))
>>> match_predicate([], Local('q'), b)
Test(Comparison(Call(Const(<... len>), (Local('q'),),...)), Value(0, True))
>>> b
{}
And recursively matching their contents:
>>> match_predicate((Bind('x'), Add(Bind('y'), any)), Local('q'), b)
Signature([Test(Comparison(Call(Const(<... len>), (Local('q'),),...)),
Value(2, True)),
Test(IsInstance(Getitem(Local('q'), Const(1))),
istype(<class '...Add'>, True))])
>>> b
{'y': [Getitem(Getitem(Local('q'), Const(1)), Const(1))],
'x': [Getitem(Local('q'), Const(0))]}
The syntax.SyntaxBuilder class is used to parse Python expressions into
AST patterns suitable for use with match_predicate:
>>> from peak.rules.syntax import SyntaxBuilder, match
>>> builder = SyntaxBuilder({}, locals(), globals(), __builtins__)
>>> pe = builder.parse
It parses double-inverted identifiers into Bind nodes:
>>> pe('type(~~x) is ~~y')
Compare(Call(Const(<... 'type'>), (Bind('x'),), (), (), (), True),
(('is', Bind('y')),))
In all other respects, it's essentially the same as codegen.ExprBuilder.
This isn't really a function, but you can use it in a predicate string in order
to perform a pattern match on a PEAK-Rules AST. It's mainly intended for use
in extending PEAK-Rules to recognize and replace various kinds of subexpression
patterns (e.g. by adding rules to predicates.expressionSignature()), but it
can of course also be used in any other tools you build atop PEAK-Rules'
expression machinery.
In this example, we show it being used to define a rule that will recognize
expressions of the form "type(x) is y", where x and y are arbitrary
expressions:
>>> from peak.rules.syntax import match
>>> from peak.rules.predicates import CriteriaBuilder
>>> builder = CriteriaBuilder(
... {'expr':Local('expr')}, locals(), globals(), __builtins__
... )
>>> pe = builder.parse
>>> pe('match(expr, type(~~x) is ~~y)')
Signature([Test(IsInstance(Local('expr')),
istype(<class 'peak.util.assembler.Compare'>, True)),
Test(IsInstance(Getitem(Local('expr'), Const(1))),
istype(<class 'peak.util.assembler.Call'>, True)),
Test(Comparison(Getitem(Getitem(Local('expr'), Const(1)),
Const(1))),
Value(Const(<... 'type'>), True)),
Test(Comparison(Call(Const(<... len>),
(Getitem(Getitem(Local('expr'),
Const(1)), Const(2)),), (),
(), (), True)),
Value(1, True)),
Test(Comparison(Call(Const(<... len>),
(Getitem(Getitem(Local('expr'), Const(1)),
Const(3)),), (), (), (), True)),
Value(0, True)),
Test(Comparison(Call(Const(<... len>),
(Getitem(Getitem(Local('expr'), Const(1)),
Const(4)),), (), (), (), True)),
Value(0, True)),
Test(Comparison(Call(Const(<... len>),
(Getitem(Getitem(Local('expr'), Const(1)),
Const(5)),), (), (), (), True)),
Value(0, True)),
Test(Comparison(Getitem(Getitem(Local('expr'), Const(1)),
Const(6))),
Value(True, True)),
Test(Comparison(Call(Const(<... len>),
(Getitem(Local('expr'), Const(2)),), (),
(), (), True)),
Value(1, True)),
Test(Comparison(Call(Const(<... len>),
(Getitem(Getitem(Local('expr'), Const(2)),
Const(0)),), (), (), (), True)),
Value(2, True)),
Test(Comparison(Getitem(Getitem(Getitem(Local('expr'),
Const(2)), Const(0)),
Const(0))),
Value('is', True))])
>>> builder.bindings[0]
{'y': Getitem(Getitem(Getitem(Local('expr'), Const(2)), Const(0)), Const(1)),
'x': Getitem(Getitem(Getitem(Local('expr'), Const(1)), Const(2)), Const(0))}