nsz Git - libfirm/blob - scripts/jinja2/nodes.py

   1 # -*- coding: utf-8 -*-
   2 """
   3     jinja2.nodes
   4     ~~~~~~~~~~~~
   5
   6     This module implements additional nodes derived from the ast base node.
   7
   8     It also provides some node tree helper functions like `in_lineno` and
   9     `get_nodes` used by the parser and translator in order to normalize
  10     python and jinja nodes.
  11
  12     :copyright: 2008 by Armin Ronacher.
  13     :license: BSD, see LICENSE for more details.
  14 """
  15 import operator
  16 from itertools import chain, izip
  17 from collections import deque
  18 from jinja2.utils import Markup
  19
  20
  21 _binop_to_func = {
  22     '*':        operator.mul,
  23     '/':        operator.truediv,
  24     '//':       operator.floordiv,
  25     '**':       operator.pow,
  26     '%':        operator.mod,
  27     '+':        operator.add,
  28     '-':        operator.sub
  29 }
  30
  31 _uaop_to_func = {
  32     'not':      operator.not_,
  33     '+':        operator.pos,
  34     '-':        operator.neg
  35 }
  36
  37 _cmpop_to_func = {
  38     'eq':       operator.eq,
  39     'ne':       operator.ne,
  40     'gt':       operator.gt,
  41     'gteq':     operator.ge,
  42     'lt':       operator.lt,
  43     'lteq':     operator.le,
  44     'in':       lambda a, b: a in b,
  45     'notin':    lambda a, b: a not in b
  46 }
  47
  48
  49 class Impossible(Exception):
  50     """Raised if the node could not perform a requested action."""
  51
  52
  53 class NodeType(type):
  54     """A metaclass for nodes that handles the field and attribute
  55     inheritance.  fields and attributes from the parent class are
  56     automatically forwarded to the child."""
  57
  58     def __new__(cls, name, bases, d):
  59         for attr in 'fields', 'attributes':
  60             storage = []
  61             storage.extend(getattr(bases[0], attr, ()))
  62             storage.extend(d.get(attr, ()))
  63             assert len(bases) == 1, 'multiple inheritance not allowed'
  64             assert len(storage) == len(set(storage)), 'layout conflict'
  65             d[attr] = tuple(storage)
  66         d.setdefault('abstract', False)
  67         return type.__new__(cls, name, bases, d)
  68
  69
  70 class Node(object):
  71     """Baseclass for all Jinja2 nodes.  There are a number of nodes available
  72     of different types.  There are three major types:
  73
  74     -   :class:`Stmt`: statements
  75     -   :class:`Expr`: expressions
  76     -   :class:`Helper`: helper nodes
  77     -   :class:`Template`: the outermost wrapper node
  78
  79     All nodes have fields and attributes.  Fields may be other nodes, lists,
  80     or arbitrary values.  Fields are passed to the constructor as regular
  81     positional arguments, attributes as keyword arguments.  Each node has
  82     two attributes: `lineno` (the line number of the node) and `environment`.
  83     The `environment` attribute is set at the end of the parsing process for
  84     all nodes automatically.
  85     """
  86     __metaclass__ = NodeType
  87     fields = ()
  88     attributes = ('lineno', 'environment')
  89     abstract = True
  90
  91     def __init__(self, *fields, **attributes):
  92         if self.abstract:
  93             raise TypeError('abstract nodes are not instanciable')
  94         if fields:
  95             if len(fields) != len(self.fields):
  96                 if not self.fields:
  97                     raise TypeError('%r takes 0 arguments' %
  98                                     self.__class__.__name__)
  99                 raise TypeError('%r takes 0 or %d argument%s' % (
 100                     self.__class__.__name__,
 101                     len(self.fields),
 102                     len(self.fields) != 1 and 's' or ''
 103                 ))
 104             for name, arg in izip(self.fields, fields):
 105                 setattr(self, name, arg)
 106         for attr in self.attributes:
 107             setattr(self, attr, attributes.pop(attr, None))
 108         if attributes:
 109             raise TypeError('unknown attribute %r' %
 110                             iter(attributes).next())
 111
 112     def iter_fields(self, exclude=None, only=None):
 113         """This method iterates over all fields that are defined and yields
 114         ``(key, value)`` tuples.  Per default all fields are returned, but
 115         it's possible to limit that to some fields by providing the `only`
 116         parameter or to exclude some using the `exclude` parameter.  Both
 117         should be sets or tuples of field names.
 118         """
 119         for name in self.fields:
 120             if (exclude is only is None) or \
 121                (exclude is not None and name not in exclude) or \
 122                (only is not None and name in only):
 123                 try:
 124                     yield name, getattr(self, name)
 125                 except AttributeError:
 126                     pass
 127
 128     def iter_child_nodes(self, exclude=None, only=None):
 129         """Iterates over all direct child nodes of the node.  This iterates
 130         over all fields and yields the values of they are nodes.  If the value
 131         of a field is a list all the nodes in that list are returned.
 132         """
 133         for field, item in self.iter_fields(exclude, only):
 134             if isinstance(item, list):
 135                 for n in item:
 136                     if isinstance(n, Node):
 137                         yield n
 138             elif isinstance(item, Node):
 139                 yield item
 140
 141     def find(self, node_type):
 142         """Find the first node of a given type.  If no such node exists the
 143         return value is `None`.
 144         """
 145         for result in self.find_all(node_type):
 146             return result
 147
 148     def find_all(self, node_type):
 149         """Find all the nodes of a given type."""
 150         for child in self.iter_child_nodes():
 151             if isinstance(child, node_type):
 152                 yield child
 153             for result in child.find_all(node_type):
 154                 yield result
 155
 156     def set_ctx(self, ctx):
 157         """Reset the context of a node and all child nodes.  Per default the
 158         parser will all generate nodes that have a 'load' context as it's the
 159         most common one.  This method is used in the parser to set assignment
 160         targets and other nodes to a store context.
 161         """
 162         todo = deque([self])
 163         while todo:
 164             node = todo.popleft()
 165             if 'ctx' in node.fields:
 166                 node.ctx = ctx
 167             todo.extend(node.iter_child_nodes())
 168         return self
 169
 170     def set_lineno(self, lineno, override=False):
 171         """Set the line numbers of the node and children."""
 172         todo = deque([self])
 173         while todo:
 174             node = todo.popleft()
 175             if 'lineno' in node.attributes:
 176                 if node.lineno is None or override:
 177                     node.lineno = lineno
 178             todo.extend(node.iter_child_nodes())
 179         return self
 180
 181     def set_environment(self, environment):
 182         """Set the environment for all nodes."""
 183         todo = deque([self])
 184         while todo:
 185             node = todo.popleft()
 186             node.environment = environment
 187             todo.extend(node.iter_child_nodes())
 188         return self
 189
 190     def __eq__(self, other):
 191         return type(self) is type(other) and \
 192                tuple(self.iter_fields()) == tuple(other.iter_fields())
 193
 194     def __ne__(self, other):
 195         return not self.__eq__(other)
 196
 197     def __repr__(self):
 198         return '%s(%s)' % (
 199             self.__class__.__name__,
 200             ', '.join('%s=%r' % (arg, getattr(self, arg, None)) for
 201                       arg in self.fields)
 202         )
 203
 204
 205 class Stmt(Node):
 206     """Base node for all statements."""
 207     abstract = True
 208
 209
 210 class Helper(Node):
 211     """Nodes that exist in a specific context only."""
 212     abstract = True
 213
 214
 215 class Template(Node):
 216     """Node that represents a template.  This must be the outermost node that
 217     is passed to the compiler.
 218     """
 219     fields = ('body',)
 220
 221
 222 class Output(Stmt):
 223     """A node that holds multiple expressions which are then printed out.
 224     This is used both for the `print` statement and the regular template data.
 225     """
 226     fields = ('nodes',)
 227
 228
 229 class Extends(Stmt):
 230     """Represents an extends statement."""
 231     fields = ('template',)
 232
 233
 234 class For(Stmt):
 235     """The for loop.  `target` is the target for the iteration (usually a
 236     :class:`Name` or :class:`Tuple`), `iter` the iterable.  `body` is a list
 237     of nodes that are used as loop-body, and `else_` a list of nodes for the
 238     `else` block.  If no else node exists it has to be an empty list.
 239
 240     For filtered nodes an expression can be stored as `test`, otherwise `None`.
 241     """
 242     fields = ('target', 'iter', 'body', 'else_', 'test', 'recursive')
 243
 244
 245 class If(Stmt):
 246     """If `test` is true, `body` is rendered, else `else_`."""
 247     fields = ('test', 'body', 'else_')
 248
 249
 250 class Macro(Stmt):
 251     """A macro definition.  `name` is the name of the macro, `args` a list of
 252     arguments and `defaults` a list of defaults if there are any.  `body` is
 253     a list of nodes for the macro body.
 254     """
 255     fields = ('name', 'args', 'defaults', 'body')
 256
 257
 258 class CallBlock(Stmt):
 259     """Like a macro without a name but a call instead.  `call` is called with
 260     the unnamed macro as `caller` argument this node holds.
 261     """
 262     fields = ('call', 'args', 'defaults', 'body')
 263
 264
 265 class FilterBlock(Stmt):
 266     """Node for filter sections."""
 267     fields = ('body', 'filter')
 268
 269
 270 class Block(Stmt):
 271     """A node that represents a block."""
 272     fields = ('name', 'body')
 273
 274
 275 class Include(Stmt):
 276     """A node that represents the include tag."""
 277     fields = ('template', 'with_context')
 278
 279
 280 class Import(Stmt):
 281     """A node that represents the import tag."""
 282     fields = ('template', 'target', 'with_context')
 283
 284
 285 class FromImport(Stmt):
 286     """A node that represents the from import tag.  It's important to not
 287     pass unsafe names to the name attribute.  The compiler translates the
 288     attribute lookups directly into getattr calls and does *not* use the
 289     subscript callback of the interface.  As exported variables may not
 290     start with double underscores (which the parser asserts) this is not a
 291     problem for regular Jinja code, but if this node is used in an extension
 292     extra care must be taken.
 293
 294     The list of names may contain tuples if aliases are wanted.
 295     """
 296     fields = ('template', 'names', 'with_context')
 297
 298
 299 class ExprStmt(Stmt):
 300     """A statement that evaluates an expression and discards the result."""
 301     fields = ('node',)
 302
 303
 304 class Assign(Stmt):
 305     """Assigns an expression to a target."""
 306     fields = ('target', 'node')
 307
 308
 309 class Expr(Node):
 310     """Baseclass for all expressions."""
 311     abstract = True
 312
 313     def as_const(self):
 314         """Return the value of the expression as constant or raise
 315         :exc:`Impossible` if this was not possible:
 316
 317         >>> Add(Const(23), Const(42)).as_const()
 318         65
 319         >>> Add(Const(23), Name('var', 'load')).as_const()
 320         Traceback (most recent call last):
 321           ...
 322         Impossible
 323
 324         This requires the `environment` attribute of all nodes to be
 325         set to the environment that created the nodes.
 326         """
 327         raise Impossible()
 328
 329     def can_assign(self):
 330         """Check if it's possible to assign something to this node."""
 331         return False
 332
 333
 334 class BinExpr(Expr):
 335     """Baseclass for all binary expressions."""
 336     fields = ('left', 'right')
 337     operator = None
 338     abstract = True
 339
 340     def as_const(self):
 341         f = _binop_to_func[self.operator]
 342         try:
 343             return f(self.left.as_const(), self.right.as_const())
 344         except:
 345             raise Impossible()
 346
 347
 348 class UnaryExpr(Expr):
 349     """Baseclass for all unary expressions."""
 350     fields = ('node',)
 351     operator = None
 352     abstract = True
 353
 354     def as_const(self):
 355         f = _uaop_to_func[self.operator]
 356         try:
 357             return f(self.node.as_const())
 358         except:
 359             raise Impossible()
 360
 361
 362 class Name(Expr):
 363     """Looks up a name or stores a value in a name.
 364     The `ctx` of the node can be one of the following values:
 365
 366     -   `store`: store a value in the name
 367     -   `load`: load that name
 368     -   `param`: like `store` but if the name was defined as function parameter.
 369     """
 370     fields = ('name', 'ctx')
 371
 372     def can_assign(self):
 373         return self.name not in ('true', 'false', 'none',
 374                                  'True', 'False', 'None')
 375
 376
 377 class Literal(Expr):
 378     """Baseclass for literals."""
 379     abstract = True
 380
 381
 382 class Const(Literal):
 383     """All constant values.  The parser will return this node for simple
 384     constants such as ``42`` or ``"foo"`` but it can be used to store more
 385     complex values such as lists too.  Only constants with a safe
 386     representation (objects where ``eval(repr(x)) == x`` is true).
 387     """
 388     fields = ('value',)
 389
 390     def as_const(self):
 391         return self.value
 392
 393     @classmethod
 394     def from_untrusted(cls, value, lineno=None, environment=None):
 395         """Return a const object if the value is representable as
 396         constant value in the generated code, otherwise it will raise
 397         an `Impossible` exception.
 398         """
 399         from compiler import has_safe_repr
 400         if not has_safe_repr(value):
 401             raise Impossible()
 402         return cls(value, lineno=lineno, environment=environment)
 403
 404
 405 class TemplateData(Literal):
 406     """A constant template string."""
 407     fields = ('data',)
 408
 409     def as_const(self):
 410         if self.environment.autoescape:
 411             return Markup(self.data)
 412         return self.data
 413
 414
 415 class Tuple(Literal):
 416     """For loop unpacking and some other things like multiple arguments
 417     for subscripts.  Like for :class:`Name` `ctx` specifies if the tuple
 418     is used for loading the names or storing.
 419     """
 420     fields = ('items', 'ctx')
 421
 422     def as_const(self):
 423         return tuple(x.as_const() for x in self.items)
 424
 425     def can_assign(self):
 426         for item in self.items:
 427             if not item.can_assign():
 428                 return False
 429         return True
 430
 431
 432 class List(Literal):
 433     """Any list literal such as ``[1, 2, 3]``"""
 434     fields = ('items',)
 435
 436     def as_const(self):
 437         return [x.as_const() for x in self.items]
 438
 439
 440 class Dict(Literal):
 441     """Any dict literal such as ``{1: 2, 3: 4}``.  The items must be a list of
 442     :class:`Pair` nodes.
 443     """
 444     fields = ('items',)
 445
 446     def as_const(self):
 447         return dict(x.as_const() for x in self.items)
 448
 449
 450 class Pair(Helper):
 451     """A key, value pair for dicts."""
 452     fields = ('key', 'value')
 453
 454     def as_const(self):
 455         return self.key.as_const(), self.value.as_const()
 456
 457
 458 class Keyword(Helper):
 459     """A key, value pair for keyword arguments where key is a string."""
 460     fields = ('key', 'value')
 461
 462     def as_const(self):
 463         return self.key, self.value.as_const()
 464
 465
 466 class CondExpr(Expr):
 467     """A conditional expression (inline if expression).  (``{{
 468     foo if bar else baz }}``)
 469     """
 470     fields = ('test', 'expr1', 'expr2')
 471
 472     def as_const(self):
 473         if self.test.as_const():
 474             return self.expr1.as_const()
 475
 476         # if we evaluate to an undefined object, we better do that at runtime
 477         if self.expr2 is None:
 478             raise Impossible()
 479
 480         return self.expr2.as_const()
 481
 482
 483 class Filter(Expr):
 484     """This node applies a filter on an expression.  `name` is the name of
 485     the filter, the rest of the fields are the same as for :class:`Call`.
 486
 487     If the `node` of a filter is `None` the contents of the last buffer are
 488     filtered.  Buffers are created by macros and filter blocks.
 489     """
 490     fields = ('node', 'name', 'args', 'kwargs', 'dyn_args', 'dyn_kwargs')
 491
 492     def as_const(self, obj=None):
 493         if self.node is obj is None:
 494             raise Impossible()
 495         filter = self.environment.filters.get(self.name)
 496         if filter is None or getattr(filter, 'contextfilter', False):
 497             raise Impossible()
 498         if obj is None:
 499             obj = self.node.as_const()
 500         args = [x.as_const() for x in self.args]
 501         if getattr(filter, 'environmentfilter', False):
 502             args.insert(0, self.environment)
 503         kwargs = dict(x.as_const() for x in self.kwargs)
 504         if self.dyn_args is not None:
 505             try:
 506                 args.extend(self.dyn_args.as_const())
 507             except:
 508                 raise Impossible()
 509         if self.dyn_kwargs is not None:
 510             try:
 511                 kwargs.update(self.dyn_kwargs.as_const())
 512             except:
 513                 raise Impossible()
 514         try:
 515             return filter(obj, *args, **kwargs)
 516         except:
 517             raise Impossible()
 518
 519
 520 class Test(Expr):
 521     """Applies a test on an expression.  `name` is the name of the test, the
 522     rest of the fields are the same as for :class:`Call`.
 523     """
 524     fields = ('node', 'name', 'args', 'kwargs', 'dyn_args', 'dyn_kwargs')
 525
 526
 527 class Call(Expr):
 528     """Calls an expression.  `args` is a list of arguments, `kwargs` a list
 529     of keyword arguments (list of :class:`Keyword` nodes), and `dyn_args`
 530     and `dyn_kwargs` has to be either `None` or a node that is used as
 531     node for dynamic positional (``*args``) or keyword (``**kwargs``)
 532     arguments.
 533     """
 534     fields = ('node', 'args', 'kwargs', 'dyn_args', 'dyn_kwargs')
 535
 536     def as_const(self):
 537         obj = self.node.as_const()
 538
 539         # don't evaluate context functions
 540         args = [x.as_const() for x in self.args]
 541         if getattr(obj, 'contextfunction', False):
 542             raise Impossible()
 543         elif getattr(obj, 'environmentfunction', False):
 544             args.insert(0, self.environment)
 545
 546         kwargs = dict(x.as_const() for x in self.kwargs)
 547         if self.dyn_args is not None:
 548             try:
 549                 args.extend(self.dyn_args.as_const())
 550             except:
 551                 raise Impossible()
 552         if self.dyn_kwargs is not None:
 553             try:
 554                 kwargs.update(self.dyn_kwargs.as_const())
 555             except:
 556                 raise Impossible()
 557         try:
 558             return obj(*args, **kwargs)
 559         except:
 560             raise Impossible()
 561
 562
 563 class Getitem(Expr):
 564     """Get an attribute or item from an expression and prefer the item."""
 565     fields = ('node', 'arg', 'ctx')
 566
 567     def as_const(self):
 568         if self.ctx != 'load':
 569             raise Impossible()
 570         try:
 571             return self.environment.getitem(self.node.as_const(),
 572                                             self.arg.as_const())
 573         except:
 574             raise Impossible()
 575
 576     def can_assign(self):
 577         return False
 578
 579
 580 class Getattr(Expr):
 581     """Get an attribute or item from an expression that is a ascii-only
 582     bytestring and prefer the attribute.
 583     """
 584     fields = ('node', 'attr', 'ctx')
 585
 586     def as_const(self):
 587         if self.ctx != 'load':
 588             raise Impossible()
 589         try:
 590             return self.environment.getattr(self.node.as_const(), arg)
 591         except:
 592             raise Impossible()
 593
 594     def can_assign(self):
 595         return False
 596
 597
 598 class Slice(Expr):
 599     """Represents a slice object.  This must only be used as argument for
 600     :class:`Subscript`.
 601     """
 602     fields = ('start', 'stop', 'step')
 603
 604     def as_const(self):
 605         def const(obj):
 606             if obj is None:
 607                 return obj
 608             return obj.as_const()
 609         return slice(const(self.start), const(self.stop), const(self.step))
 610
 611
 612 class Concat(Expr):
 613     """Concatenates the list of expressions provided after converting them to
 614     unicode.
 615     """
 616     fields = ('nodes',)
 617
 618     def as_const(self):
 619         return ''.join(unicode(x.as_const()) for x in self.nodes)
 620
 621
 622 class Compare(Expr):
 623     """Compares an expression with some other expressions.  `ops` must be a
 624     list of :class:`Operand`\s.
 625     """
 626     fields = ('expr', 'ops')
 627
 628     def as_const(self):
 629         result = value = self.expr.as_const()
 630         try:
 631             for op in self.ops:
 632                 new_value = op.expr.as_const()
 633                 result = _cmpop_to_func[op.op](value, new_value)
 634                 value = new_value
 635         except:
 636             raise Impossible()
 637         return result
 638
 639
 640 class Operand(Helper):
 641     """Holds an operator and an expression."""
 642     fields = ('op', 'expr')
 643
 644 if __debug__:
 645     Operand.__doc__ += '\nThe following operators are available: ' + \
 646         ', '.join(sorted('``%s``' % x for x in set(_binop_to_func) |
 647                   set(_uaop_to_func) | set(_cmpop_to_func)))
 648
 649
 650 class Mul(BinExpr):
 651     """Multiplies the left with the right node."""
 652     operator = '*'
 653
 654
 655 class Div(BinExpr):
 656     """Divides the left by the right node."""
 657     operator = '/'
 658
 659
 660 class FloorDiv(BinExpr):
 661     """Divides the left by the right node and truncates conver the
 662     result into an integer by truncating.
 663     """
 664     operator = '//'
 665
 666
 667 class Add(BinExpr):
 668     """Add the left to the right node."""
 669     operator = '+'
 670
 671
 672 class Sub(BinExpr):
 673     """Substract the right from the left node."""
 674     operator = '-'
 675
 676
 677 class Mod(BinExpr):
 678     """Left modulo right."""
 679     operator = '%'
 680
 681
 682 class Pow(BinExpr):
 683     """Left to the power of right."""
 684     operator = '**'
 685
 686
 687 class And(BinExpr):
 688     """Short circuited AND."""
 689     operator = 'and'
 690
 691     def as_const(self):
 692         return self.left.as_const() and self.right.as_const()
 693
 694
 695 class Or(BinExpr):
 696     """Short circuited OR."""
 697     operator = 'or'
 698
 699     def as_const(self):
 700         return self.left.as_const() or self.right.as_const()
 701
 702
 703 class Not(UnaryExpr):
 704     """Negate the expression."""
 705     operator = 'not'
 706
 707
 708 class Neg(UnaryExpr):
 709     """Make the expression negative."""
 710     operator = '-'
 711
 712
 713 class Pos(UnaryExpr):
 714     """Make the expression positive (noop for most expressions)"""
 715     operator = '+'
 716
 717
 718 # Helpers for extensions
 719
 720
 721 class EnvironmentAttribute(Expr):
 722     """Loads an attribute from the environment object.  This is useful for
 723     extensions that want to call a callback stored on the environment.
 724     """
 725     fields = ('name',)
 726
 727
 728 class ExtensionAttribute(Expr):
 729     """Returns the attribute of an extension bound to the environment.
 730     The identifier is the identifier of the :class:`Extension`.
 731
 732     This node is usually constructed by calling the
 733     :meth:`~jinja2.ext.Extension.attr` method on an extension.
 734     """
 735     fields = ('identifier', 'name')
 736
 737
 738 class ImportedName(Expr):
 739     """If created with an import name the import name is returned on node
 740     access.  For example ``ImportedName('cgi.escape')`` returns the `escape`
 741     function from the cgi module on evaluation.  Imports are optimized by the
 742     compiler so there is no need to assign them to local variables.
 743     """
 744     fields = ('importname',)
 745
 746
 747 class InternalName(Expr):
 748     """An internal name in the compiler.  You cannot create these nodes
 749     yourself but the parser provides a
 750     :meth:`~jinja2.parser.Parser.free_identifier` method that creates
 751     a new identifier for you.  This identifier is not available from the
 752     template and is not threated specially by the compiler.
 753     """
 754     fields = ('name',)
 755
 756     def __init__(self):
 757         raise TypeError('Can\'t create internal names.  Use the '
 758                         '`free_identifier` method on a parser.')
 759
 760
 761 class MarkSafe(Expr):
 762     """Mark the wrapped expression as safe (wrap it as `Markup`)."""
 763     fields = ('expr',)
 764
 765     def as_const(self):
 766         return Markup(self.expr.as_const())
 767
 768
 769 class ContextReference(Expr):
 770     """Returns the current template context."""
 771
 772
 773 class Continue(Stmt):
 774     """Continue a loop."""
 775
 776
 777 class Break(Stmt):
 778     """Break a loop."""
 779
 780
 781 # make sure nobody creates custom nodes
 782 def _failing_new(*args, **kwargs):
 783     raise TypeError('can\'t create custom node types')
 784 NodeType.__new__ = staticmethod(_failing_new); del _failing_new