Changeset 5318:56ac432123d0 in livinglogic.python.xist

Show
Ignore:
Timestamp:
02/06/13 20:00:24 (6 years ago)
Author:
Walter Doerwald <walter@…>
Branch:
default
Message:

Update documentation.

Files:
1 modified

Legend:

Unmodified
Added
Removed
  • docs/UL4.rst

    r5309 r5318  
    362362 
    363363 
    364 ``code`` 
    365 -------- 
    366  
    367 The ``code`` tag can be used to define or modify variables. Apart from the 
     364``exe`` 
     365------- 
     366 
     367The ``exe`` tag can contain statements that define or modify variables or 
     368expressions which will be evaluated for their side effects. Apart from the 
    368369assigment operator ``=``, the following augmented assignment operators are 
    369370supported: 
     
    380381For example the following template will output ``40``:: 
    381382 
    382     <?code x = 17?> 
    383     <?code x += 23?> 
     383    <?exe x = 17?> 
     384    <?exe x += 23?> 
    384385    <?print x?> 
    385386 
    386387 
    387 ``render`` 
    388 ---------- 
    389  
    390 The ``render`` tag allows one template to call other templates. The following Python 
    391 code demonstrates this:: 
    392  
    393     from ll import ul4c 
    394  
    395     # Template 1 
    396     source1 = """\ 
    397     <?if data?>\ 
    398     <ul> 
    399     <?for i in data?><?render itemtmpl.render(item=i)?><?end for?>\ 
    400     </ul> 
    401     <?end if?>\ 
    402     """ 
    403  
    404     tmpl1 = ul4c.Template(source1) 
    405  
    406     # Template 2 
    407     source2 = "<li><?print xmlescape(item)?></li>\n" 
    408  
    409     tmpl2 = ul4c.Template(source2) 
    410  
    411     # Data object for the outer template 
    412     data = ["Python", "Java", "Javascript", "PHP"] 
    413  
    414     print(tmpl1.renders(itemtmpl=tmpl2, data=data)) 
    415  
    416 This will output:: 
    417  
    418     <ul> 
    419     <li>Python</li> 
    420     <li>Java</li> 
    421     <li>Javascript</li> 
    422     <li>PHP</li> 
    423     </ul> 
    424  
    425 I.e. templates can be passed just like any other object as a variable. 
    426 ``<?render itemtmpl.render(item=i)?>`` renders the ``itemtmpl`` template and 
    427 passes the ``i`` variable, which will be available in the inner template under 
    428 the name ``item``. 
    429  
    430  
    431 ``template`` 
    432 ------------ 
    433  
    434 The ```template`` tag defined a new template as a variable. Usage looks like 
    435 this:: 
    436  
    437     <?template quote?>"<?print text?>"<?end template?> 
     388``def`` 
     389------- 
     390 
     391The ```def`` tag defined a new template as a variable. Usage looks like this:: 
     392 
     393    <?def quote?>"<?print text?>"<?end def?> 
    438394 
    439395This defines a local variable ``quote`` that is a template object. This template 
     
    441397template:: 
    442398 
    443     <?render quote.render(text="foo")?> 
     399    <?exe quote.render(text="foo")?> 
     400 
     401(Here an ``<?exe?>`` tag is used. The expression in the ``<?exe?>`` tag is 
     402evaluated for the side effect of generating output) 
    444403 
    445404 
     
    459418example will output ``1``:: 
    460419 
    461     <?code i = 1?> 
     420    <?exe i = 1?> 
    462421    <?template x?> 
    463422        <?print i?> 
    464423    <?end template?> 
    465     <?code i = 2?> 
     424    <?exe i = 2?> 
    466425    <?render x.render()?> 
    467426 
     
    547506expressions:: 
    548507 
    549     <?code ge = ("(" + c + ")" for c in "gurk")?> 
     508    <?exe ge = ("(" + c + ")" for c in "gurk")?> 
    550509    <?print ", ".join(ge)?> 
    551510 
     
    12041163``**`` syntax:: 
    12051164 
    1206     <?code output = template.renders(a=17, b=23)?> 
    1207     <?code data = {'a': 17, 'b': 23)?> 
    1208     <?code output = template.renders(**data)?> 
     1165    <?exe output = template.renders(a=17, b=23)?> 
     1166    <?exe data = {'a': 17, 'b': 23)?> 
     1167    <?exe output = template.renders(**data)?> 
    12091168 
    12101169 
     
    12421201above (except for the linefeeds of course):: 
    12431202 
    1244     <?code weekdays = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']?> 
    1245     <?code months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']?> 
    1246     <?code t = @(2010-02-22T17:38:40.123456)?> 
     1203    <?exe weekdays = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']?> 
     1204    <?exe months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']?> 
     1205    <?exe t = @(2010-02-22T17:38:40.123456)?> 
    12471206    <?print weekdays[t.weekday()]?>, 
    12481207    <?print format(t.day(), '02')?> 
     
    12781237 
    12791238prints ``365``. 
     1239 
     1240 
     1241Templates as functions 
     1242====================== 
     1243 
     1244UL4 templates can be used as functions too. Calling a template as a function 
     1245will ignore any output from the template. The return value will be the value of 
     1246the first ``<?return?>`` tag:: 
     1247 
     1248    from ll import ul4c 
     1249 
     1250    code = ''' 
     1251        <?for item in data?> 
     1252            <?if "i" in item?> 
     1253                <?return item?> 
     1254            <?end if?> 
     1255        <?end for?> 
     1256    ''' 
     1257 
     1258    function = ul4c.Function(code) 
     1259 
     1260    output = function(data=["Python", "Java", "Javascript", "PHP"])) 
     1261 
     1262With this, ``output`` will be the string ``"Javascript"``. 
     1263 
     1264 
     1265When no ``<?return?>`` tag is encountered, ``None`` will be returned. 
    12801266 
    12811267 
     
    13161302 
    13171303    '\n\t\n\t\t0\n\t\t;\n\t\n\t\t1\n\t\t;\n\t\n\t\t2... 
    1318  
    1319  
    1320 Functions 
    1321 ========= 
    1322  
    1323 Besides templates UL4 supports functions too. Where a template produces an 
    1324 output string by interleaving literal output and logic, a function returns a 
    1325 single value (via the ``<?return?>`` tag):: 
    1326  
    1327     from ll import ul4c 
    1328  
    1329     code = ''' 
    1330         <?for item in data?> 
    1331             <?if "i" in item?> 
    1332                 <?return item?> 
    1333             <?end if?> 
    1334         <?end for?> 
    1335     ''' 
    1336  
    1337     function = ul4c.Function(code) 
    1338  
    1339     output = function(data=["Python", "Java", "Javascript", "PHP"])) 
    1340  
    1341 With this, ``output`` will be the string ``"Javascript"``. 
    1342  
    1343  
    1344 It is also possible to define UL4 functions inside other functions or templates 
    1345 with the ``<?function?>`` tag:: 
    1346  
    1347     <?function findindex?> 
    1348         <?for (i, item) in enumerate(container)?> 
    1349             <?if i == index?> 
    1350                 <?return item?> 
    1351             <?end if?> 
    1352         <?end for?> 
    1353     <?end function?> 
    1354     <?print findindex(index=2, container="spam")?> 
    1355  
    1356 This will print ``a``. 
    1357  
    1358 Inside such a function definition literal text and the ``<?render?>`` tag will 
    1359 be ignored.