Changeset 3466:bea8815e1f2c in livinglogic.python.xist

Show
Ignore:
Timestamp:
07/08/08 17:44:38 (11 years ago)
Author:
Walter Doerwald <walter@…>
Branch:
default
Message:

More docstrings. Fix opcode iteration in format method.

Files:
1 modified

Legend:

Unmodified
Added
Removed
  • src/ll/ul4c.py

    r3465 r3466  
    234234    following attributes: 
    235235 
    236     :attr:`type` : string or :const:`None` 
     236    :attr:`code` : string or :const:`None` 
    237237        The opcode type (see below for a list). 
    238238 
     
    247247        The location of the tag to which this opcode belongs. 
    248248 
    249     The following opcodes are available: 
     249    The following opcode types are available: 
    250250 
    251251    :const:`None`: 
     
    566566 
    567567class Template(object): 
     568    """ 
     569    A template object can be compiled via the class method :meth:`compile` from 
     570    source. It can be loaded from the compiled format via :meth:`load` (from a 
     571    stream) or :meth:`loads` (from a string). 
     572     
     573    The compiled format can be generated with the methods :meth:`dump` (which 
     574    dumps the format to a stream) or :meth:`dumps` (which returns a string with 
     575    the compiled format). 
     576 
     577    Rendering the template can be done with the methods :meth:`render` (which 
     578    returns a generator) or :meth:`renders` (which returns a string). 
     579    """ 
    568580    version = "2" 
    569581 
     
    578590    @classmethod 
    579591    def loads(cls, data): 
     592        """ 
     593        The class method :meth:`loads` loads the template from string :var:`data`. 
     594        :var:`data` must contain the template in compiled format. 
     595        """ 
    580596        def _readint(term): 
    581597            i = 0 
     
    665681    @classmethod 
    666682    def load(cls, stream): 
     683        """ 
     684        The class method :meth:`load` loads the template from the stream 
     685        :var:`stream`. The stream must contain the template in compiled format. 
     686        """ 
    667687        return cls.loads(stream.read()) 
    668688 
    669689    def iterdump(self): 
     690        """ 
     691        This generator outputs the template in compiled format. 
     692        """ 
    670693        def _writeint(term, number): 
    671694            yield unicode(number) 
     
    711734 
    712735    def dump(self, stream): 
     736        """ 
     737        :meth:`dump` dumps the template in compiled format to the stream 
     738        :var:`stream`. 
     739        """ 
    713740        for part in self.iterdump(): 
    714741            stream.write(part) 
    715742 
    716743    def dumps(self): 
    717         return ''.join(self.iterdump()) 
     744        """ 
     745        :meth:`dumps` returns the template in compiled format (as a string). 
     746        """ 
     747        return "".join(self.iterdump()) 
    718748 
    719749    def pythonsource(self, function=None): 
     750        """ 
     751        Return the template as Python source code. If :var:`function` is specified 
     752        the code will be wrapped in a function with this name. 
     753        """ 
    720754        indent = 0 
    721755        output = [] 
     
    961995 
    962996    def pythonfunction(self): 
     997        """ 
     998        Return a Python generator that can be called to render the template. 
     999        The argument signature of the function will be 
     1000        ``templates={}, **variables``. 
     1001        """ 
    9631002        if self._pythonfunction is None: 
    9641003            code = self.pythonsource("render") 
    9651004            ns = {} 
    966             exec code.encode("utf-8") in ns 
     1005            exec code.encode("utf-8") in ns # FIXME: no need to encode in Python 3.0 
    9671006            self._pythonfunction = ns["render"] 
    9681007        return self._pythonfunction 
     
    9721011 
    9731012    def render(self, templates={}, **variables): 
     1013        """ 
     1014        Render the template iteratively (i.e. this is a generator). 
     1015        :var:`templates` contains the templates that should be available to the 
     1016        ``<?render?>`` tag. :var:`variables` contains the top level variables 
     1017        available to the template code. 
     1018        """ 
    9741019        return self.pythonfunction()(templates, **variables) 
    9751020 
    9761021    def renders(self, templates={}, **variables): 
     1022        """ 
     1023        Render the template as a string. :var:`templates` contains the templates 
     1024        that should be available to the ``<?render?>`` tag. :var:`variables` 
     1025        contains the top level variables available to the template code. 
     1026        """ 
    9771027        return "".join(self.render(templates, **variables)) 
    9781028 
     
    9841034        """ 
    9851035        i = 0 
    986         for opcode in self: 
     1036        for opcode in self.opcodes: 
    9871037            if opcode.code in ("else", "endif", "endfor"): 
    9881038                i -= 1 
     
    9991049 
    10001050    def _tokenize(self, source, startdelim, enddelim): 
     1051        """ 
     1052        Tokenize the template source code :var:`source` into tags and non-tag 
     1053        text. :var:`startdelim` and :var:`enddelim` are used as the tag delimiters. 
     1054 
     1055        This is a generator which produces :class:`Location` objects for each tag 
     1056        or non-tag text. It will be called by :meth:`_compile` internally. 
     1057        """ 
    10011058        pattern = u"%s(print|code|for|if|elif|else|end|render)(\s*((.|\\n)*?)\s*)?%s" % (re.escape(startdelim), re.escape(enddelim)) 
    10021059        pos = 0 
     
    10111068 
    10121069    def _allocreg(self): 
     1070        """ 
     1071        Allocates a free register from the pool of available registers. 
     1072        """ 
    10131073        try: 
    10141074            return self.registers.pop() 
     
    10171077 
    10181078    def _freereg(self, register): 
     1079        """ 
     1080        Returns the register :var:`register` to the pool of available registers. 
     1081        """ 
    10191082        self.registers.add(register) 
    10201083 
    1021     def opcode(self, name, r1=None, r2=None, r3=None, r4=None, r5=None, arg=None): 
    1022         self.opcodes.append(Opcode(name, r1, r2, r3, r4, r5, arg, self.location)) 
     1084    def opcode(self, code, r1=None, r2=None, r3=None, r4=None, r5=None, arg=None): 
     1085        """ 
     1086        Creates an :class:`Opcode` object and appends it to :var:`self`\s list of 
     1087        opcodes. 
     1088        """ 
     1089        self.opcodes.append(Opcode(code, r1, r2, r3, r4, r5, arg, self.location)) 
    10231090 
    10241091    def _compile(self, source, startdelim, enddelim): 
     1092        """ 
     1093        Compile the template source code :var:`source` into opcodes. 
     1094        :var:`startdelim` and :var:`enddelim` are used as the tag delimiters. 
     1095        """ 
    10251096        self.startdelim = startdelim 
    10261097        self.enddelim = enddelim