UL4 supports generator expressions with look like list comprehensions without the square brackets. Generator expression do not create lists in memory but instead return an iterable that can be iterated once. Function and methods that require an iterable argument can directly consume such iterables:

<?print ", ".join("(" + c + ")" for c in "gurk")?>

will output:

(g), (u), (r), (k)

Outside of function/method arguments (or when more that one argument is passed) parentheses are required around generator expressions:

<?code ge = ("(" + c + ")" for c in "gurk")?>
<?print ", ".join(ge)?>

Index and slice access is available for all container types, i.e. in the expression a[b] the following type combinations are supported:

• string, integer: Returns the bth character from the string a. Note that negative b values are supported and are relative to the end, so a[-1] is the last character.

• list, integer: Returns the bth list entry of the list a. Negative b values are supported too.

• dict, string: Return the value from the dictionary a corresponding to the key b. Note that some implementations might support keys other than strings too. (The Python and Java implementations do for example. The Javascript implementation does too, if Map is supported.)

If the specified key doesn't exist or the index is out of range for the string or list, a special "undefined" object is returned.

Slices are also supported (for list and string objects). As in Python one or both of the indexes may be missing to start at the first or end after the last character/item. Negative indexes are relative to the end. Indexes that are out of bounds are simply clipped:

• <?print "Hello, World!"[7:-1]?> prints World.

• <?print "Hello, World!"[:-8]?> prints Hello.

For string keys it's also possible to access dictionary entries via the attribute access operator ., i.e. foo.key is the same as foo["key"] if foo is a dictionary.

A function call in UL4 looks like this: date(2014, 10, 9, 17, 29). (this returns the date object @(2014-10-09T17:29)). Some of the trailing arguments in a function call might be optional and have default values. For example the first three arguments for the date function (year, month and day) are required, the remaining four arguments (hour, minute, second and microsecond) are optional and default to 0.

Parameter values can also be passed via keyword arguments, i.e. date(2014, 10, 9) could also be written as date(day=9, month=10, year=2014).

Furthermore Python's * and ** syntax is supported for passing additional positional or keyword arguments. For example:

<?code args = [2014, 10, 9, 17, 29]?>
<?code d = date(*args)?>

is the same as:

<?code d = date(2014, 10, 9, 17, 29)?>

The same can also be done with a keyword dictionary and the ** syntax:

<?code kwargs = {"day": 9, "month": 10, "year": 2014, "hour": 17: "minute": 29}?>
<?code d = date(**kwargs)?>

Of course it's also possible to mix argument passing mechanics:

<?code d = date(2014, *[10, 9], **{"hour": 17, "minute": 29})?>

or:

<?code d = date(2014, month=10, day=9, **{'hour': 17, 'minute': 29})?>

However the * and ** arguments can only be use at the end of the argument list and positional arguments must always be before keyword arguments.

A list of builtin functions can be found in a later chapter.

The bitwise and operator & returns the bitwise "and" combination of its operands (which must be integer of boolean values). E.g. 6 & 3 returns 2.

As with the unary operator ~, negative numbers are interpreted as having an unlimited number of leading 1 bits.

The bitwise exclusive or operator ^ returns the bitwise exclusive "or" combination of its operands (which must be integer of boolean values). E.g. 6 ^ 3 returns 5.

Negative numbers are again interpreted as having an unlimited number of leading 1 bits.

The bitwise inclusive or operator | returns the bitwise inclusive "or" combination of its operands (which must be integer of boolean values). E.g. 6 | 3 returns 7.

Negative numbers are again interpreted as having an unlimited number of leading 1 bits.

The comparison operators ==, !=, <, <=, > and >= compare the value of the two operands. == and != support comparison of all types of object. All others support comparsison of "compatible" objects, which means all "number" objects (integer, float and boolean) can be compared with each other, all other objects can only be compared to objects of the same type.

The comparison operators is and is not test whether both operands refer to the same object or not.

Note that the behaviour of these operators for "atomic" immutable objects (like integers, floats and strings) is implementation defined.

The unary operator not inverts the truth value of its operand. I.e. not x is True for None, False, the undefined value, 0, 0.0, empty lists, strings, dictionaries and other empty container and False for everything else.

The binary operator and returns whether both of its operands are true. It work like in Python by short-circuiting operand evaluation, i.e. if the result is clear from the first operand the seconds won't be evaluated.

Furthermore and always return one of the operands.

So a and b first evaluates a; if a is false, its value is returned; otherwise, b is evaluated and the resulting value is returned.

The binary operator or returns whether any of it's operands is true. Like and evaluation is short-circuited and one of the operands is returned.

For example, the following code will output the data.title object if it's true, else data.id will be output:

<?printx data.title or data.id?>

The conditional expression (also called an "inline if") a if c else b first evaluates the condition c. If it is true a is evaluated and returned else b is evaluated and returned.

now() returns the current date and time as a date object.

utcnow() returns the current date and time as a date object in UTC.

date() creates a date object from the parameter passed in. date() supports from three parameters (year, month, day) upto seven parameters (year, month, day, hour, minute, second, microsecond).

timedelta returns an object that represents a timespan. timedelta allows from zero to three arguments specifying the numbers of days, seconds and microseconds. Passing negative values or values that are out of bounds (e.g. 24*60*60+1 seconds) is allowed. Arguments default to 0, i.e. timedelta() returns the timespan for "0 days, 0 seconds, 0 microseconds". In a boolean context this object is treated as false (i.e. bool(timedelta())) returns False). The following arithmetic operations are supported:

• date + timedelta

• date - timedelta

• timedelta + timedelta

• timedelta - timedelta

• number * timedelta

• timedelta * number

• timedelta / number

• timedelta // int

monthdelta returns an object that represents a timespan of a number of months. monthdelta allows zero or one arguments. With zero arguments monthdelta returns the timespan for "0 months". In a boolean context this object is treated as false (i.e. bool(monthdelta())) or bool(monthdelta(0))) return False). The following arithmetic operations are supported:

• date + monthdelta

• date - monthdelta

• monthdelta + monthdelta

• monthdelta - monthdelta

• int * monthdelta

• monthdelta // int

For operations involving date objects, if the resulting day falls out of the range of valid days for the target month, the last day for the target month will be used instead, i.e. <?print @(2000-01-31) + monthdelta(1)?> prints 2000-02-29 00:00:00.

isundefined(foo) returns True if foo is Undefined, else False is returned:

data is <?if isundefined(data)?>undefined<?else?>defined<?end if?>!

isdefined(foo) returns False if foo is Undefined, else True is returned:

data is <?if isdefined(data)?>defined<?else?>undefined<?end if?>!

isnone(foo) returns True if foo is None, else False is returned:

data is <?if isnone(data)?>None<?else?>something else<?end if?>!

isbool(foo) returns True if foo is True or False, else False is returned.

isint(foo) returns True if foo is an integer object, else False is returned.

isfloat(foo) returns True if foo is a float object, else False is returned.

isstr(foo) returns True if foo is a string object, else False is returned.

isdate(foo) returns True if foo is a date object, else False is returned.

istimedelta(foo) returns True if foo is a timedelta object, else False is returned.

ismonthdelta(foo) returns True if foo is a monthdelta object, else False is returned.

islist(foo) returns True if foo is a list object, else False is returned.

isdict(foo) returns True if foo is a dictionary object, else False is returned.

iscolor(foo) returns True if foo is a color object, else False is returned.

istemplate(foo) returns True if foo is a template object, else False is returned.

bool(foo) converts foo to an boolean. I.e. True or False is returned according to the truth value of foo. Calling bool without arguments returns False.

int(foo) converts foo to an integer. foo can be a string, a float, a boolean or an integer. int can also be called with two arguments. In this case the first argument must be a string and the second is the number base for the conversion. Calling int without arguments returns 0.

float(foo) converts foo to a float. foo can be a string, a float, a boolean or an integer. Calling float without arguments returns 0.0.

str(foo) converts foo to a string. If foo is None or Undefined the result will be the empty string. For lists and dictionaries the exact format is undefined, but should follow Python's repr format. For color objects the result is a CSS expression (e.g. "#fff"). Calling str without arguments returns the empty string.

repr(foo) converts foo to a string representation that is useful for debugging proposes. The output in most cases looks that the UL4 constant that could be used to recreate the object.

list(foo) converts foo to a list. This works for lists, strings and all iterable objects. Calling list without arguments returns an empty list.

set(foo) converts foo to a set. This works for lists, strings and all iterable objects. Calling set without arguments returns an empty set.

slice returns a slice from a sequence or iterator. You can either pass the stop index (i.e. slice(foo, 10) is an iterator over the first 10 items from foo), or a start and stop index (slice(foo, 10, 20) return the 11th upto to 20th item from foo) or a start and stop index and a step size. If given start and stop must be non-negative and step must be positive.

asjson(foo) returns a JSON representation of the object foo. (Date objects, color objects and templates are not supported by JSON, but asjson will output the appropriate Javascript code for those objects).

fromjson(foo) decodes the JSON string foo and returns the resulting object. (Date objects, color objects and templates are not supported by fromjson).

asul4on(foo) returns the UL4ON representation of the object foo.

fromul4on(foo) decodes the UL4ON string foo and returns the resulting object.

len(foo) returns the length of a string, or the number of items in a list or dictionary.

any(foo) returns True if any of the items in the iterable foo is true. Otherwise False is returns. If foo is empty False is returned.

all(foo) returns True if all of the items in the iterable foo are true. Otherwise False is returns. If foo is empty True is returned.

Enumerates the items of the argument (which must be iterable, i.e. a string, a list or dictionary) and for each item in the original iterable returns a two item list containing the item position and the item itself. For example the following code:

<?for (i, c) in enumerate("foo")?>
    (<?print c?>=<?print i?>)
<?end for?>

prints:

(f=0)(o=1)(o=2)

Iterates through items of the argument (which must be iterable, i.e. a string, a list or dictionary) and gives information about whether the item is the first and/or last in the iterable. For example the following code:

<?for (first, last, c) in isfirstlast("foo")?>
    <?if first?>[<?end if?>
    (<?print c?>)
    <?if last?>]<?end if?>
<?end for?>

prints:

[(f)(o)(o)]

Iterates through items of the argument (which must be iterable, i.e. a string, a list or dictionary) and gives information about whether the item is the first in the iterable. For example the following code:

<?for (first, c) in isfirst("foo")?>
    <?if first?>[<?end if?>
    (<?print c?>)
<?end for?>

prints:

[(f)(o)(o)

Iterates through items of the argument (which must be iterable, i.e. a string, a list or dictionary) and gives information about whether the item is the last in the iterable. For example the following code:

<?for (last, c) in islast("foo")?>
    (<?print c?>)
    <?if last?>]<?end if?>
<?end for?>

prints:

(f)(o)(o)]

This function is a combination of enumerate and isfirstlast. It iterates through items of the argument (which must be iterable, i.e. a string, a list or dictionary) and gives information about whether the item is the first and/or last in the iterable and its position. For example the following code:

<?for (index, first, last, c) in enumfl("foo")?>
    <?if first?>[<?end if?>
    (<?print c?>=<?print index?>)
    <?if last?>]<?end if?>
<?end for?>

prints:

[(f=0)(o=1)(o=2)]

first returns the first element produced by an iterable object. If the iterable is empty the default value (which is the second parameter and defaults to None) is returned.

last returns the last element produced by an iterable object. If the iterable is empty the default value (which is the second parameter and defaults to None) is returned.

sum returns the sum of the number from the iterable passed in. The second parameter is the start value (i.e. the value that will be added to the total sum) and defaults to 0. For example the template <?print sum(range(101))?> will output 5050.

xmlescape takes a string as an argument. It returns a new string where the characters &, <, >, ' and " have been replaced with the appropriate XML entity or character reference. For example:

<?print xmlescape("<'foo' & 'bar'>")?>

prints:

<'foo' & ;'bar&#39>

If the argument is not a string, it will be converted to a string first.

<?printx foo?> is a shortcut for <?print xmlescape(foo)?>.

min returns the minimum value of its two or more arguments. If it's called with one argument, this argument must be iterable and min returns the minimum value of this argument.

max returns the maximum value of its two or more arguments. If it's called with one argument, this argument must be iterable and max returns the maximum value of this argument.

sum returns the sum of the values in the passed in iterable. The second argument specifies the starting value (defaulting to 0).

sorted returns a sorted list with the items from its argument. For example:

<?for c in sorted('abracadabra')?><?print c?><?end for?>

prints:

aaaaabbcdrr

Supported arguments are iterable objects, i.e. strings, lists, dictionaries and colors.

chr(x) returns a one-character string containing the character with the code point x. x must be an integer. For example <?print chr(0x61)?> outputs a.

This is the inverse function to chr The argument for ord must be a one-character string. ord returns the code point of that character as an integer. For example <?print ord('a')?> outputs 97.

Return the hexadecimal representation of the integer argument (with a leading 0x). For example <?print hex(42)?> outputs 0x2a.

Return the octal representation of the integer argument (with a leading 0o). For example <?print oct(42)?> outputs 0o52.

Return the binary representation of the integer argument (with a leading 0b). For example <?print bin(42)?> outputs 0b101010.

range returns an object that can be iterated and will produce consecutive integers up to the specified argument. With two arguments the first is the start value and the second is the stop value. With three arguments the third one is the step size (which can be negative). For example the following template:

<?for i in range(4, 10, 2)?>(<?print i?>)<?end for?>

outputs:

(4)(6)(8)

type returns the type of the object as a string. Possible return values are "undefined", "none", "bool", "int", "float", "str", "list", "dict", "date", "timedelta", "monthdelta", "color", "template" and "function". (If the type isn't recognized None is returned.)

rgb returns a color object. It can be called with

• three arguments, the red, green and blue values. The alpha value will be set to 255;

• four arguments, the red, green, blue and alpha values.

Arguments are treated as values from 0 to 1 and will be clipped accordingly. For example:

<?print rgb(1, 1, 1)?>

prints #fff`.

random() returns a random float value between 0 (included) and 1 (excluded).

randrange(start, stop, step) returns a random integer value between start (included) and stop (excluded). step specifies the step size (i.e. when r is the random value, (r-start) % step will always be 0). step and start can be omitted.

randchoice(seq) returns a random item from the sequence seq.

The upper method of strings returns an uppercase version of the string for which it's called:

<?print 'foo'.upper()?>

prints:

FOO

The lower method of strings returns an lowercase version of the string for which it's called.

The capitalize method of strings returns a copy of the string with its first letter capitalized.

x.startswith(y) returns True if the string x starts with the string y and False otherwise.

x.endswith(y) returns True if the string x ends with the string y and False otherwise.

The string method strip returns a copy of the string with leading and trailing whitespace removed. If an argument chars is given and not None, characters in chars will be removed instead.

The string method lstrip returns a copy of the string with leading whitespace removed. If an argument chars is given and not None, characters in chars will be removed instead.

The string method rstrip returns a copy of the string with trailing whitespace removed. If an argument chars is given and not None, characters in chars will be removed instead.

The string method split splits the string into separate "words" and returns the resulting list. Without any arguments, the string is split on whitespace characters. With one argument the argument specifies the separator to use. The second optional argument specifies the maximum number of splits to do.

The string method rsplit works like split, except that splitting starts from the end (which is only relevant when the maximum number of splits is given).

This method searches for a substring of the string or an item in a list and returns the position of the first appearance of the substring/item or -1 if the string/item can't be found. For example "foobar".find("bar") returns 3. The optional second and third argument specify the start and end position for the search.

This method works like find but searches from the end.

The string method replace has two arguments. It returns a new string where each occurrence of the first argument is replaced by the second argument, i.e. "abracadabra".replace("ab", "ba") returns "baracadbara"

get is a dictionary method. d.get(k, v) returns d[k] if the key k is in d, else v is returned. If v is not given, it defaults to None.

join is a string method. It returns a concatentation of the strings in the argument sequence with the string itself as the separator, i.e.:

<?print "+".join("1234")?>

outputs:

1+2+3+4

The renders method of template objects renders the template and returns the output as a string. The parameter can be passed via keyword argument or via the ** syntax:

<?code output = template.renders(a=17, b=23)?>
<?code data = {'a': 17, 'b': 23)?>
<?code output = template.renders(**data)?>

isoformat is a date method. It returns the date object in ISO 8601 format, i.e.:

<?print now().isoformat()?>

might output:

2010-02-22T18:30:29.569639

mimeformat is a date method. It returns the date object in MIME format (assuming the date object is in UTC), i.e.:

<?print utcnow().mimeformat()?>

might output:

Mon, 22 Feb 2010 17:38:40 GMT

Those methods are date methods. They return a specific attribute of a date object. For example the following reproduces the mimeformat output from above (except for the linefeeds of course):

<?code weekdays = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']?>
<?code months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']?>
<?code t = @(2010-02-22T17:38:40.123456)?>
<?print weekdays[t.weekday()]?>,
<?print format(t.day(), '02')?>
<?print months[t.month()-1]?>
<?print format(t.year(), '04')?>
<?print format(t.hour(), '02')?>:
<?print format(t.minute(), '02')?>:
<?print format(t.second(), '02')?>.
<?print format(t.microsecond(), '06')?> GMT

week is a date method. This method returns the week number of the year. It supports one argument: the weekday number that should be considered the start day of the week (0 for Monday, ... 6 for Sunday). All days in a new year preceding the first week start day are considered to be in week 0. The week start day defaults to 0 (Monday).

yearday is a date method. It returns the number of days since the beginning of the year, so:

<?print @(2010-01-01).yearday()?>

prints 1 and:

<?print @(2010-12-31).yearday()?>

prints 365.

append is a list method. It adds its arguments to the end of the list for which it is called:

<?code v = [1, 2]?>
<?code v.append(3, 4)?>
<?print v?>

prints [1, 2, 3, 4].

insert is a list method. Its first argument in the insert position, the remaining arguments are the items that will be inserted at that position, so:

<?code v = [1, 4]?>
<?code v.insert(1, 2, 3)?>
<?print v?>

prints [1, 2, 3, 4].

pop is a list method. It removes the last item of the list and returns it. If an index is passed the item at that position is removed and returned. A negative index is treated as relative to the end of the list.

update is a dictionary method. It supports an arbitrary number of positional and keyword arguments. Each positional argument may be a dictionary, all the items in the dictionary will be copied to the target dictionary. A positional argument may also be an iterable of (key, value) pairs. These will also be copied to the target dictionary. After each positional argument is copied over in a last step the keyword arguments will be copied to the target dictionary.