emitter.py

Go to the documentation of this file.

#!/usr/bin/env python3
# Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
# for details. All rights reserved. Use of this source code is governed by a
# BSD-style license that can be found in the LICENSE file.
"""Templating to help generate structured text."""
 
import logging
import re
 
_logger = logging.getLogger('emitter')
 
 
def Format(template, **parameters):
    """Create a string using the same template syntax as Emitter.Emit."""
    e = Emitter()
    e._Emit(template, parameters)
    return ''.join(e.Fragments())
 
 
class Emitter(object):
    """An Emitter collects string fragments to be assembled into a single string.
  """
 
    def __init__(self, bindings=None):
        self._items = []  # A new list
        self._bindings = bindings or Emitter.Frame({}, None)
 
    def EmitRaw(self, item):
        """Emits literal string with no substitution."""
        self._items.append(item)
 
    def Emit(self, template_source, **parameters):
        """Emits a template, substituting named parameters and returning emitters to
    fill the named holes.
 
    Ordinary substitution occurs at $NAME or $(NAME).  If there is no parameter
    called NAME, the text is left as-is. So long as you don't bind FOO as a
    parameter, $FOO in the template will pass through to the generated text.
 
    Substitution of $?NAME and $(?NAME) yields an empty string if NAME is not a
    parameter.
 
    Values passed as named parameters should be strings or simple integral
    values (int or long).
 
    Named holes are created at $!NAME or $(!NAME).  A hole marks a position in
    the template that may be filled in later.  An Emitter is returned for each
    named hole in the template.  The holes are filled by emitting to the
    corresponding emitter.
 
    Subtemplates can be created by using $#NAME(...), where text can be placed
    inside of the parentheses and will conditionally expand depending on if
    NAME is set to True or False. The text inside the parentheses may use
    further $#NAME and $NAME substitutions, but is not permitted to create
    holes.
 
    Emit returns either a single Emitter if the template contains one hole or a
    tuple of emitters for several holes, in the order that the holes occur in
    the template.
 
    The emitters for the holes remember the parameters passed to the initial
    call to Emit.  Holes can be used to provide a binding context.
    """
        return self._Emit(template_source, parameters)
 
    def _Emit(self, template_source, parameters):
        """Implementation of Emit, with map in place of named parameters."""
        template = self._ParseTemplate(template_source)
        parameter_bindings = self._bindings.Extend(parameters)
 
        hole_names = template._holes
 
        if hole_names:
            hole_map = {}
            replacements = {}
            for name in hole_names:
                emitter = Emitter(parameter_bindings)
                replacements[name] = emitter._items
                hole_map[name] = emitter
            full_bindings = parameter_bindings.Extend(replacements)
        else:
            full_bindings = parameter_bindings
 
        self._ApplyTemplate(template, full_bindings, self._items)
 
        # Return None, a singleton or tuple of the hole names.
        if not hole_names:
            return None
        if len(hole_names) == 1:
            return hole_map[hole_names[0]]
        else:
            return tuple(hole_map[name] for name in hole_names)
 
    def Fragments(self):
        """Returns a list of all the string fragments emitted."""
 
        def _FlattenTo(item, output):
            if isinstance(item, list):
                for subitem in item:
                    _FlattenTo(subitem, output)
            elif isinstance(item, Emitter.DeferredLookup):
                value = item._environment.Lookup(item._lookup._name,
                                                 item._lookup._value_if_missing)
                if item._lookup._subtemplate:
                    _FlattenSubtemplate(item, value, output)
                else:
                    _FlattenTo(value, output)
            else:
                output.append(str(item))
 
        def _FlattenSubtemplate(item, value, output):
            """Handles subtemplates created by $#NAME(...)"""
            if value is True:
                # Expand items in subtemplate
                _FlattenTo(item._lookup._subitems, output)
            elif value is not False:
                if value != item._lookup._value_if_missing:
                    raise RuntimeError(
                        'Value for NAME in $#NAME(...) syntax must be a boolean'
                    )
                # Expand it into the string literal composed of $#NAME(,
                # the values inside the parentheses, and ).
                _FlattenTo(value, output)
                _FlattenTo(item._lookup._subitems, output)
                _FlattenTo(')', output)
 
        output = []
        _FlattenTo(self._items, output)
        return output
 
    def Bind(self, var, template_source, **parameters):
        """Adds a binding for var to this emitter."""
        template = self._ParseTemplate(template_source)
        if template._holes:
            raise RuntimeError('Cannot have holes in Emitter.Bind')
        bindings = self._bindings.Extend(parameters)
        value = Emitter(bindings)
        value._ApplyTemplate(template, bindings, self._items)
        self._bindings = self._bindings.Extend({var: value._items})
        return value
 
    def _ParseTemplate(self, source):
        """Converts the template string into a Template object."""
        # TODO(sra): Cache the parsing.
        items = []
        holes = []
 
        # Break source into a sequence of text fragments and substitution lookups.
        pos = 0
        while True:
            match = Emitter._SUBST_RE.search(source, pos)
            if not match:
                items.append(source[pos:])
                break
            text_fragment = source[pos:match.start()]
            if text_fragment:
                items.append(text_fragment)
            pos = match.end()
            term = match.group()
            name = match.group(1) or match.group(2)  # $NAME and $(NAME)
            if name:
                item = Emitter.Lookup(name, term, term)
                items.append(item)
                continue
            name = match.group(3) or match.group(4)  # $!NAME and $(!NAME)
            if name:
                item = Emitter.Lookup(name, term, term)
                items.append(item)
                holes.append(name)
                continue
            name = match.group(5) or match.group(6)  # $?NAME and $(?NAME)
            if name:
                item = Emitter.Lookup(name, term, '')
                items.append(item)
                holes.append(name)
                continue
            name = match.group(7)                    # $#NAME(...)
            if name:
                # Since it's possible for this to nest, find the matching right
                # paren for this left paren.
                paren_count = 1
                curr_pos = pos
                while curr_pos < len(source):
                    if source[curr_pos] == ')':
                        paren_count -= 1
                        if paren_count == 0:
                            break
                    elif source[curr_pos] == '(':
                        # Account for nested parentheses
                        paren_count += 1
                    curr_pos += 1
                if curr_pos == len(source):
                    # No matching right paren, so not a lookup. Ignore and
                    # continue.
                    items.append(term)
                    continue
                matched_template = self._ParseTemplate(source[pos:curr_pos])
                if len(matched_template._holes) > 0:
                    raise RuntimeError(
                        '$#NAME syntax cannot contains holes in its arguments')
                item = Emitter.Lookup(name, term, term, matched_template)
                items.append(item)
                # Continue after the right paren
                pos = curr_pos + 1
                continue
            raise RuntimeError('Unexpected group')
 
        if len(holes) != len(set(holes)):
            raise RuntimeError('Cannot have repeated holes %s' % holes)
        return Emitter.Template(items, holes)
 
    _SUBST_RE = re.compile(
        #  $FOO    $(FOO)      $!FOO    $(!FOO)      $?FOO     $(?FOO)       $#FOO(
        r'\$(\w+)|\$\‍((\w+)\‍)|\$!(\w+)|\$\‍(!(\w+)\‍)|\$\?(\w+)|\$\‍(\?(\w+)\‍)|\$#(\w+)\‍('
    )
 
    def _ApplyTemplate(self, template, bindings, items_list):
        """Emits the items from the parsed template."""
        result = []
        for item in template._items:
            if isinstance(item, str):
                if item:
                    result.append(item)
            elif isinstance(item, Emitter.Lookup):
                # Bind lookup to the current environment (bindings)
                # TODO(sra): More space efficient to do direct lookup.
                result.append(Emitter.DeferredLookup(item, bindings))
                # If the item has a subtemplate, apply the subtemplate and save
                # the result in the item's subitems
                if item._subtemplate:
                    self._ApplyTemplate(item._subtemplate, bindings,
                                        item._subitems)
            else:
                raise RuntimeError('Unexpected template element')
        # Collected fragments are in a sublist, so self._items contains one element
        # (sublist) per template application.
        items_list.append(result)
 
    class Lookup(object):
        """An element of a parsed template."""
 
        def __init__(self, name, original, default, subtemplate=None):
            self._name = name
            self._original = original
            self._value_if_missing = default
            self._subtemplate = subtemplate
            self._subitems = []
 
    class DeferredLookup(object):
        """A lookup operation that is deferred until final string generation."""
 
        # TODO(sra): A deferred lookup will be useful when we add expansions that
        # have behaviour conditional on the contents, e.g. adding separators between
        # a list of items.
        def __init__(self, lookup, environment):
            self._lookup = lookup
            self._environment = environment
 
    class Template(object):
        """A parsed template."""
 
        def __init__(self, items, holes):
            self._items = items  # strings and lookups
            self._holes = holes
 
    class Frame(object):
        """A Frame is a set of bindings derived from a parent."""
 
        def __init__(self, map, parent):
            self._map = map
            self._parent = parent
 
        def Lookup(self, name, default):
            if name in self._map:
                return self._map[name]
            if self._parent:
                return self._parent.Lookup(name, default)
            return default
 
        def Extend(self, map):
            return Emitter.Frame(map, self)