Changeset 5309:83859a4f7468 in livinglogic.python.xist

Show
Ignore:
Timestamp:
01/27/13 11:09:42 (7 years ago)
Author:
Walter Doerwald <walter@…>
Branch:
default
Message:

Document functions. Enhance the rest of the documentation.

Files:
1 modified

Legend:

Unmodified
Added
Removed
  • docs/UL4.rst

    r5305 r5309  
    4141    from ll import ul4c 
    4242 
    43     code = '''<?if data?> 
    44     <ul> 
    45     <?for item in data?> 
    46     <li><?print xmlescape(item)?></li> 
    47     <?end for?> 
    48     </ul> 
    49     <?end if?>''' 
    50  
    51     tmpl = ul4c.Template(code) 
    52  
    53     print(tmpl.renders(data=["Python", "Java", "Javascript", "PHP"])) 
     43    code = ''' 
     44        <?if data?> 
     45            <ul> 
     46                <?for item in data?> 
     47                    <li><?print item?></li> 
     48                <?end for?> 
     49            </ul> 
     50        <?end if?> 
     51    ''' 
     52 
     53    template = ul4c.Template(code) 
     54 
     55    print(template.renders(data=["Python", "Java", "Javascript", "PHP"])) 
    5456 
    5557The variables that should be available to the template code can be passed to the 
     
    7577*   lists 
    7678*   dictionaries 
    77 *   templates 
    78  
    79 This is similar to what JSON_ supports (except for date objects, color objects 
    80 and templates). 
     79*   UL4 templates 
     80 
     81This is similar to what JSON_ supports (except for date objects, color objects, 
     82UL4 templates). 
    8183 
    8284    .. _JSON: http://www.json.org/ 
     
    427429 
    428430 
    429 ``def`` 
    430 ------- 
    431 The ```def`` tag defined a new template as a variable. Usage looks like this:: 
    432  
    433     <?def quote?>"<?print text?>"<?end def?> 
    434  
    435 This template can be called like any other template, that has been passed to 
    436 the outermost template:: 
     431``template`` 
     432------------ 
     433 
     434The ```template`` tag defined a new template as a variable. Usage looks like 
     435this:: 
     436 
     437    <?template quote?>"<?print text?>"<?end template?> 
     438 
     439This defines a local variable ``quote`` that is a template object. This template 
     440can be called like any other template, that has been passed to the outermost 
     441template:: 
    437442 
    438443    <?render quote.render(text="foo")?> 
     
    445450 
    446451 
    447 The variable ``stack`` 
    448 ---------------------- 
    449  
    450 A UL4 template can use the variable ``stack``, which is a call stack of the 
    451 currently executing template. So ``stack[-1]`` for example is the template itself. 
    452  
    453  
    454452Nested scopes 
    455453------------- 
    456454 
    457455UL4 templates support lexical scopes. This means that a template that is defined 
    458 (via ``<?def?>``) inside another template has access to the local variables of 
    459 the outer template. The inner template sees that state of the variables at the 
    460 point in time when the ``<?def?>`` tag was executed. The following example will 
    461 output ``1``:: 
     456(via ``<?template?>``) inside another template has access to the local variables 
     457of the outer template. The inner template sees that state of the variables at 
     458the point in time when the ``<?template?>`` tag was executed. The following 
     459example will output ``1``:: 
    462460 
    463461    <?code i = 1?> 
    464     <?def x?> 
     462    <?template x?> 
    465463        <?print i?> 
    466     <?end def?> 
     464    <?end template?> 
    467465    <?code i = 2?> 
    468466    <?render x.render()?> 
     
    491489 
    492490Slices are also supported (for list and string objects). As in Python one or 
    493 both of the indexes may be missing to start at the first or end at the last 
     491both of the indexes may be missing to start at the first or end after the last 
    494492character/item. Negative indexes are relative to the end. Indexes that are out 
    495493of bounds are simply clipped: 
     
    520518    (comparison is done by value not by identity) 
    521519*   string, dict: Checks whether the key ``a`` is in the dictionary ``b``. 
    522     (Note that some implementations might support keys other than strings too.) 
     520    (Note that some implementations might support keys other than strings too. 
     521    E.g. Python and Java do, Javascript doesn't.) 
    523522 
    524523The inverted containment test (via ``not in``) is available too. 
     
    616615*   ``monthdelta`` // ``int`` 
    617616 
    618 For the operations involving ``date`` objects, if the resulting day falls out of 
    619 the range of valid days for the target month, the last day for the target month 
     617For operation involving ``date`` objects, if the resulting day falls out of the 
     618range of valid days for the target month, the last day for the target month 
    620619will be used instead, i.e. ``<?print @(2000-01-31) + monthdelta(1)?>`` prints 
    621620``2000-02-29 00:00:00``. 
     
    738737``iscolor(foo)`` returns ``True`` if ``foo`` is a color object, else ``False`` 
    739738is returned. 
     739 
     740 
     741``istemplate`` 
     742"""""""""""""" 
     743 
     744``istemplate(foo)`` returns ``True`` if ``foo`` is a template object, else 
     745``False`` is returned. 
    740746 
    741747 
     
    778784 
    779785``repr(foo)`` converts ``foo`` to a string representation that is useful for 
    780 debugging proposes. The output is a constant expression that could be used to 
     786debugging proposes. The output looks that the UL constant that could be used to 
    781787recreate the object. 
    782788 
     
    786792 
    787793``asjson(foo)`` returns a JSON representation of the object ``foo``. 
     794(Date objects, color objects and templates are not supported by JSON, but 
     795``asjson`` will output the appropriate Javascript code for those objects) 
    788796 
    789797 
     
    792800 
    793801``fromjson(foo)`` decodes the JSON string ``foo`` and returns the resulting 
    794 object. 
     802object. (Date objects, color objects and templates are not supported by 
     803``fromjson``). 
    795804 
    796805 
     
    827836``all(foo)`` returns ``True`` if all of the items in the iterable ``foo`` are 
    828837true. Otherwise ``False`` is returns. If ``foo`` is empty ``True`` is returned. 
     838 
     839 
     840``enumerate`` 
     841""""""""""""" 
     842 
     843Enumerates the items of the argument (which must be iterable, i.e. a string, 
     844a list or dictionary) and for each item in the original iterable returns a two 
     845item list containing the item position and the item itself. For example the 
     846following code:: 
     847 
     848    <?for (i, c) in enumerate("foo")?> 
     849        (<?print c?>=<?print i?>) 
     850    <?end for?> 
     851 
     852prints:: 
     853 
     854    (f=0)(o=1)(o=2) 
    829855 
    830856 
     
    881907 
    882908 
    883 ``enumerate`` 
    884 """"""""""""" 
    885  
    886 Enumerates the items of the argument (which must be iterable, i.e. a string, 
    887 a list or dictionary). For example the following code:: 
    888  
    889     <?for (i, c) in enumerate("foo")?> 
    890         (<?print c?>=<?print i?>) 
    891     <?end for?> 
    892  
    893 prints:: 
    894  
    895     (f=0)(o=1)(o=2) 
    896  
    897  
    898909``enumfl`` 
    899910"""""""""" 
    900911 
    901 This function is a combination of ``isfirstlast`` and ``enumerate``. It iterates 
     912This function is a combination of ``enumerate`` and ``isfirstlast``. It iterates 
    902913through items of the argument (which must be iterable, i.e. a string, a list 
    903914or dictionary) and gives information about whether the item is the first 
     
    919930 
    920931``xmlescape`` takes a string as an argument. It returns a new string where the 
    921 characters ``&``, ``<``, ``>``, ``'`` and ``"`` are replaced with the 
    922 appropriate XML entity or character references. For example:: 
     932characters ``&``, ``<``, ``>``, ``'`` and ``"`` have been replaced with the 
     933appropriate XML entity or character reference. For example:: 
    923934 
    924935    <?print xmlescape("<'foo' & 'bar'>")?> 
     
    937948 
    938949``min`` returns the minimum value of its two or more arguments. If it's called 
    939 with one argument, this argument must be iterable and ``min`` returns the minimum 
    940 value of this argument. 
     950with one argument, this argument must be iterable and ``min`` returns the 
     951minimum value of this argument. 
    941952 
    942953 
     
    945956 
    946957``max`` returns the maximum value of its two or more arguments. If it's called 
    947 with one argument, this argument must be iterable and ``max`` returns the maximum 
    948 value of this argument. 
     958with one argument, this argument must be iterable and ``max`` returns the 
     959maximum value of this argument. 
    949960 
    950961 
     
    952963"""""""""" 
    953964 
    954 ``sorted`` returns a sorted list with the items from it's argument. For 
    955 example:: 
    956  
    957     <?for c in sorted('bar')?><?print c?><?end for?> 
     965``sorted`` returns a sorted list with the items from its argument. For example:: 
     966 
     967    <?for c in sorted('abracadabra')?><?print c?><?end for?> 
    958968 
    959969prints:: 
    960970 
    961     abr 
     971    aaaaabbcdrr 
    962972 
    963973Supported arguments are iterable objects, i.e. strings, lists, dictionaries 
     
    968978""""""" 
    969979 
    970 ``chr(x)`` returns a one-character string with a character with the codepoint 
    971 ``x``. ``x`` must be an integer. For example ``<?print chr(0x61)?>`` outputs 
    972 ``a``. 
     980``chr(x)`` returns a one-character string containing the character with the 
     981codepoint ``x``. ``x`` must be an integer. For example ``<?print chr(0x61)?>`` 
     982outputs ``a``. 
    973983 
    974984 
     
    10101020the step size (which can be negative). For example the following template:: 
    10111021 
    1012     <?for i in range(2, 10, 2)?>(<?print i?>)<?end for?> 
     1022    <?for i in range(4, 10, 2)?>(<?print i?>)<?end for?> 
    10131023 
    10141024outputs:: 
    10151025 
    1016     (2)(4)(6)(8) 
     1026    (4)(6)(8) 
    10171027 
    10181028 
     
    10211031 
    10221032``type`` returns the type of the object as a string. Possible return values are 
    1023 ``"none"``, ``"bool"``, ``"int"``, ``"float"``, ``"str"``, ``"list"``, 
    1024 ``"dict"``, ``"date"``, ``"color"`` and ``"template"``. (If the type isn't 
    1025 recognized ``None`` is returned.) 
     1033``"undefined"``, ``"none"``, ``"bool"``, ``"int"``, ``"float"``, ``"str"``, 
     1034``"list"``, ``"dict"``, ``"date"``, ``"color"``, ``"template"`` and 
     1035``"function"``. (If the type isn't recognized ``None`` is returned.) 
    10261036 
    10271037 
     
    11611171""""""""""" 
    11621172 
    1163 This string method replace has two arguments. It returns a new string where 
    1164 each occurrence of the first argument is replaced by the second argument. 
     1173The string method ``replace`` has two arguments. It returns a new string where 
     1174each occurrence of the first argument is replaced by the second argument, i.e. 
     1175``"abracadabra".replace("ab", "ba")`` returns ``"baracadbara"`` 
    11651176 
    11661177 
     
    11791190argument sequence with the string itself as the separator, i.e.:: 
    11801191 
    1181     <?print "+".join(["1", "2", "3", "4"])?> 
     1192    <?print "+".join("1234")?> 
    11821193 
    11831194outputs:: 
     
    12481259 
    12491260``week`` is a date method. This method returns the week number of the year. 
    1250 It supports one argument: the weekday number (0 for Monday, ... 6 for Sunday) 
    1251 that should be considered the start day of the week. All days in a new year 
     1261It supports one argument: the weekday number that should be considered the start 
     1262day of the week (0 for Monday, ... 6 for Sunday). All days in a new year 
    12521263preceding the first week start day are considered to be in week 0. The week 
    12531264start day defaults to 0 (Monday). 
     
    13011312    '0;1;2;3;4;5;6;7;8;9;' 
    13021313 
    1303 Using ``keepws=True`` (the default) the output would include al the line feeds 
     1314Using ``keepws=True`` (the default) the output would include all the line feeds 
    13041315and whitespace:: 
    13051316 
    13061317    '\n\t\n\t\t0\n\t\t;\n\t\n\t\t1\n\t\t;\n\t\n\t\t2... 
     1318 
     1319 
     1320Functions 
     1321========= 
     1322 
     1323Besides templates UL4 supports functions too. Where a template produces an 
     1324output string by interleaving literal output and logic, a function returns a 
     1325single 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 
     1341With this, ``output`` will be the string ``"Javascript"``. 
     1342 
     1343 
     1344It is also possible to define UL4 functions inside other functions or templates 
     1345with 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 
     1356This will print ``a``. 
     1357 
     1358Inside such a function definition literal text and the ``<?render?>`` tag will 
     1359be ignored.