Built-in functions¶

Logical¶

and(x, y, …)¶

Perform logical “and” between given boolean values, i.e. return true if all arguments are equivalent to true (see Value type for details about conversion to boolean).

Cottle template
{and(2 < 3, 5 > 1)}
Rendering output
true

Note

This function is equivalent to operator &&.

cmp(x, y)¶

Compare x against y, and return -1 if x is lower than y, 0 if they’re equal, or 1 otherwise. When used on numeric values, the cmp function uses numerical order. When used on strings, it uses alphabetical order. When used on maps, it first performs numerical comparison on their length then compares keys and values two by two. Two values of different types are always different, but the order between them is undefined.

Cottle template
{cmp("abc", "bcd")}
{cmp(9, 6)}
{cmp([2, 4], [2, 4])}
Rendering output
-1
1
0

default(primary, fallback)¶

Return primary if primary is equivalent to true (see Value type for details about conversion to boolean) or fallback otherwise.

Cottle template
{set x to 3}
{default(x, "invisible")}
{default(y, "visible")}
Rendering output
3
visible

defined(x)¶

Check whether value x is defined by checking it has a non-void type.

This is different than checking whether a value is equivalent to true (see Value type for details about conversion to boolean), for example integer 0 is equivalent to false when used as a boolean expression but defined(0) is true. This function is mostly useful for testing whether a variable has been assigned a value or not.

Cottle template
{dump defined(undefined)}
{set a to 0}
{dump defined(a)}
Rendering output
<false>
<true>

eq(x, y, …)¶

Return true if all arguments are equal or false otherwise. It uses the same comparison algorithm than function cmp(x, y).

Cottle template
{eq(7, 7)}
{eq(1, 4)}
{eq("test", "test")}
{eq(1 = 1, 2 = 2, 3 = 3)}
Rendering output
true
false
true
true

Note

This function is equivalent to operator = when used with 2 arguments.

ge(x, y)¶

Return true if x has a value greater than or equal to y or false otherwise. It uses the same comparison algorithm than function cmp(x, y).

Cottle template
{ge(7, 3)}
{ge(2, 2)}
{ge("abc", "abx")}
Rendering output
true
true
false

Note

This function is equivalent to operator >=.

gt(x, y)¶

Return true if x has a value greater than y or false otherwise. It uses the same comparison algorithm than function cmp(x, y).

Cottle template
{gt(7, 3)}
{gt(2, 2)}
{gt("abc", "abx")}
Rendering output
true
false
false

Note

This function is equivalent to operator >.

has(map, key)¶

Return true if given map has a value associated to given key or false otherwise.

Cottle template
{has(["name": "Paul", "age": 37, "sex": "M"], "age")}
Rendering output
true

Note

Result of this function is close to but not strictly equivalent to defined(map[key]) as the former will return true if map contains a key key associated to an undefined value while the later will return false.

le(x, y)¶

Return true if x has a value lower than or equal to y or false otherwise. It uses the same comparison algorithm than function cmp(x, y).

Cottle template
{le(3, 7)}
{le(2, 2)}
{le("abc", "abx")}
Rendering output
true
true
true

Note

This function is equivalent to operator <=.

lt(x, y)¶

Return true if x has a value lower than y or false otherwise. It uses the same comparison algorithm than function cmp(x, y).

Cottle template
{lt(3, 7)}
{lt(2, 2)}
{lt("abc", "abx")}
Rendering output
true
false
true

Note

This function is equivalent to operator <.

ne(x, y)¶

Return true if x equals y or false otherwise. It uses the same comparison algorithm than function cmp(x, y).

Cottle template
{ne(7, 7)}
{ne(1, 4)}
{ne("test", "test")}
Rendering output
false true false

Note

This function is equivalent to operator != when used with 2 arguments.

not(x)¶

Perform logical “not” on given boolean value, i.e return false if value was equivalent to true (see Value type for details about conversion to boolean) or false otherwise.

Cottle template
{not(1 = 2)}
Rendering output
true

Note

This function is equivalent to operator !.

or(x, y, …)¶

Perform logical “or” between given boolean values, i.e. return true if at least one argument is equivalent to true (see Value type for details about conversion to boolean).

Cottle template
{or(2 = 3, 5 > 1)}
Rendering output
true

Note

This function is equivalent to operator ||.

xor(x, y, …)¶

Perform logical “xor” between given boolean values, i.e. return true if exactly one argument is true and all the others are false.

Cottle template
{xor(2 < 3, 1 = 2)}
Rendering output
true

when(condition[, truthy[, falsy]])¶

Return truthy if condition is equivalent to true (see Value type for details about conversion to boolean) or falsy otherwise (or an undefined value if falsy is missing). This function is intended to act as the ternary operator you can find in some programming languages.

Cottle template
{set x to 3}
{set y to 0}
{when(x, "x is true", "x is false")}
{when(y, "y is true", "y is false")}
Rendering output
x is true
y is false

Mathematical¶

abs(x)¶

Return the absolute value of given numeric value x.

Cottle template
{abs(-3)}
{abs(5)}
Rendering output
3
5

Return the sum of two numeric values.

Cottle template
Rendering output
10

Note

This function is equivalent to operator +.

ceil(x)¶

Returns the smallest integer greater than or equal to number value x.

Cottle template
{ceil(2.7)}
Rendering output
3

cos(x)¶

Get the cosine of angle x in radians.

Cottle template
{cos(-1.57)}
Rendering output
0.000796326710733263

div(x, y)¶

Return the numeric value of x divided by the numeric value of y, or an undefined value if y was equal to zero.

Cottle template
{div(5, 2)}
Rendering output
2.5

Note

This function is equivalent to operator /.

floor(x)¶

Returns the largest integer less than or equal to number value x.

Cottle template
{floor(2.7)}
Rendering output
2

max(x[, y[, z, …]])¶

Return the highest numeric value among given ones.

Cottle template
{max(7, 5)}
{max(6, 8, 5, 7, 1, 2)}
Rendering output
7
8

Note

Combine with function call(func, map) if you want to get the highest numeric value from an array.

min(x[, y[, z, …]])¶

Return the lowest numeric value among given ones.

Cottle template
{min(9, 3)}
{min(6, 8, 5, 7, 1, 2)}
Rendering output
3
1

Note

Combine with function call(func, map) if you want to get the lowest numeric value from an array.

mod(x, y)¶

Return the value of x modulo y, or an undefined value if y was equal to zero.

Cottle template
{mod(7, 3)}
Rendering output
1

Note

This function is equivalent to operator %.

mul(x, y)¶

Return the numeric value of x times y.

Cottle template
{mul(3, 4)}
Rendering output
12

Note

This function is equivalent to operator *.

pow(x, y)¶

Get specified number x raised to the power y.

Cottle template
{pow(2, 10)}
Rendering output
1024

rand([a[, b]])¶

Get a pseudo-random numeric value between 0 and 2.147.483.647 inclusive. If numeric a value is specified, return a pseudo-random numeric value between 0 and a exclusive. If both numeric values a and b are specified, return a pseudo-random numeric value between a inclusive and b exclusive.

Cottle template
{rand()}
{rand(1, 7)}
Rendering output
542180393
5

round(x[, digits])¶

Rounds number value x to a specified number of fractional digits digits, or to the nearest integral value if digits is not specified.

Cottle template
{round(1.57)}
{round(1.57, 1)}
Rendering output
2
1.6

sin(x)¶

Get the sine of angle x in radians.

Cottle template
{sin(1.57)}
Rendering output
0.999999682931835

sub(x, y)¶

Return the numeric value of x minus y.

Cottle template
{sub(3, 5)}
Rendering output
-2

Note

This function is equivalent to operator -.

Collection¶

cat(a, b, …)¶

Concatenate all input maps or strings into a single one. Keys are not preserved when this function used on map values.

Cottle template
{dump cat("Hello, ", "World!")}
{dump cat([1, 2], )}
Rendering output
"Hello, World!"
[1, 2, 3]

Warning

All arguments must share the same type than first one, either map or string.

cross(map1, map2, …)¶

Return a map containing all pairs from map1 having a key that also exists in map2 and all following maps. Output pair values will always be taken from map1.

Cottle template
{dump cross([1: "a", 2: "b", 3: "c"], [1: "x", 3: "y"])}
Rendering output
[1: "a", 3: "c"]

except(map1, map2, …)¶

Return a map containing all pairs from map1 having a key that does not exist in map2 and any of following maps. This function can also be used to remove a single pair from a map (if you are sure that it’s key is not used by any other pair, otherwise all pairs using that key would be removed also).

Cottle template
{dump except([1: "a", 2: "b", 3: "c"], [2: "x", 4: "y"])}
Rendering output
[1: "a", 3: "c"]

find(subject, search[, start])¶

Find index of given search value in a map or sub-string in a string. Returns 0-based index of match if found or -1 otherwise. Search starts at index 0 unless start argument is specified.

Cottle template
{find([89, 3, 572, 35, 7], 35)}
{find("hello, world!", "o", 5)}
{find("abc", "d")}
Rendering output
3
8
-1

filter(map, predicate[, a, b, …])¶

Return a map containing all pairs having a value that satisfies given predicate. Function predicate is invoked for each value from map with this value as its first argument, and pair is added to output map if predicate result is equivalent to true (see Value type for details about conversion to boolean).

Optional arguments can be specified when calling filter and will be passed to each invocation of predicate as second, third, forth argument and so on.

Cottle template
{dump filter(["a", "", "b", "", "c"], len)}

{declare multiple_of(x, y) as:
{return x % y = 0}
}

{dump filter([1, 6, 7, 4, 9, 5, 0], multiple_of, 3)}
Rendering output
["a", "b", "c"]
[6, 9, 0]

flip(map)¶

Return a map were pairs are created by swapping each key and value pair from input map. Using resulting map with the for command will still iterate through each pair even if there was duplicates, but only the last occurrence of each duplicate can be accessed by key.

Cottle template
{dump flip([1: "hello,", 2: "world!"])}
{dump flip(["a": 0, "b": 0])}
Rendering output
["hello,": 1, "world!": 2]
["a", 0: "b"]

join(map[, string])¶

Concatenate all values from given map pairs, using given string as a separator (or empty string if no separator is provided).

Cottle template
{join(["2011", "01", "01"], "/")}
Rendering output
2011/01/01

len(x)¶

Return number of elements in given value, which means the number of pairs for a map or the number of character for a string.

Cottle template
{len("Hello!")}
{len([17, 22, 391, 44])}
Rendering output
6
4

map(source, modifier[, a, b, …])¶

Return a map where values are built by applying given modifier to map values, while preserving keys. Function modifier is invoked for each value in source with this value as its first argument.

Optional arguments can be specified when calling map and will be passed to each invocation of modifier as second, third, forth argument and so on.

Cottle template
{declare square(x) as:
{return x * x}
}

{dump map([1, 2, 3, 4], square)}
{dump map(["a": 1, "b": 7, "c": 4, "d": 5, "e": 3, "f": 2, "g": 6], lt, 4)}
Rendering output
[1, 4, 9, 16]
["a": 1, "b": 0, "c": 0, "d": 0, "e": 1, "f": 1, "g": 0]

range([start, ]stop[, step])¶

Generate a map where value of the i-th pair is start + step * i and last value is lower (or higher if step is a negative integer) than stop. Default base index is 0 if the start argument is omitted, and default value for step is 1 if start < stop or -1 otherwise.

Cottle template
{for v in range(5): {v}}
{for v in range(2, 20, 3): {v}}
Rendering output
0 1 2 3 4
2 5 8 11 14 17

slice(subject, index[, count])¶

Extact sub-string from a string or elements from a map (keys are not preserved when used with maps). count items or characters are extracted from given 0-based numeric index. If no count argument is specified, all elements starting from given index are extracted.

Cottle template
{for v in slice([68, 657, 54, 3, 12, 9], 3, 2): {v}}
{slice("abchello", 4)}
Rendering output
3 12
hello

sort(map[, callback])¶

Return a sorted copy of given map. First argument is the input map, and will be sorted using natural order (numerical or alphabetical, depending on value types) by default. You can specify a second argument as comparison delegate, that should accept two arguments and return -1 if the first should be placed “before” the second, 0 if they are equal, or 1 otherwise.

Cottle template
{set shuffled to ["in", "order", "elements" "natural"]}
{for item in sort(shuffled):
{item}
}

{declare by_length(a, b) as:
{return cmp(len(b), len(a))}
}
{set shuffled to ["by their", "are sorted", "length", "these strings"]}
{for item in sort(shuffled, by_length):
{item}
}
Rendering output
elements in natural order
these strings are sorted by their length

union(map1, map2, …)¶

Return a map containing all pairs from input maps, but without duplicating any key. If a key exists more than once in all input maps, the last one will overwrite any previous pair using it.

Cottle template
{dump union([1: "a", 2: "b"], [2: "x", 3: "c"], [4: "d"])}
Rendering output
[1: "a", 2: "x", 3: "c", 4: "d"]

zip(k, v)¶

Combine given maps of same length to create a new one. The n-th pair in result map will use the n-th value from k as its key and the n-th value from v as its value.

Cottle template
{set k to ["key1", "key2", "key3"]}
{set v to ["value1", "value2", "value3"]}
{dump zip(k, v)}
Rendering output
["key1": "value1", "key2": "value2", "key3": "value3"]

Text¶

char(codepoint)¶

Get a 1-character string from its Unicode code point integer value. See more about Unicode and code points on Wikipedia.

Cottle template
{char(97)}
{char(916)}
Rendering output
a
Δ

format(value, format[, culture])¶

Convert any value to a string using given formatting from format string expression. Format should use syntax str or t:str where t indicates the type of the formatter to use and str is the associated .NET format string. Available formatter types are:

• a: automatic (default, used if t is omitted)
• b: System.Boolean
• d or du: System.DateTime (UTC)
• dl: System.DateTime (local)
• i: System.Int64
• n: System.Double
• s: System.String

Cottle template
{format(1339936496, "d:yyyy-MM-dd HH:mm:ss")}
{format(0.165, "n:p2", "fr-FR")}
{format(1, "b:n2")}
Rendering output
2012-06-17 12:34:56
16,50 %
True

Formatters use current culture, unless a culture name is specified in the culture argument. See documentation of CultureInfo.GetCultureInfo method to read more about culture names.

lcase(string)¶

Return a lowercase conversion of given string value.

Cottle template
{lcase("Mixed Case String"}
Rendering output
mixed case string

match(subject, pattern)¶

Match subject against given regular expression pattern. If match is successful, a map containing full match followed by captured groups is returned, otherwise result is an undefined value. See .NET Framework Regular Expressions for more information.

Cottle template
{dump match("abc123", "^[a-z]+([0-9]+)\$")}
{dump match("xyz", "^[a-z]+([0-9]+)\$")}
Rendering output
["abc123", "123"]
<void>

ord(character)¶

Get the Unicode code point value of the first character of given string. See more about Unicode and code points on Wikipedia.

Cottle template
{ord("a")}
{ord("Δ")}
Rendering output
97
916

split(subject, separator)¶

Split subject string according to given string separator separator. Result is an map where pair values contain split sub-strings.

Cottle template
{dump split("2011/01/01", "/")}
Rendering output
["2011", "01", "01"]

token(subject, search, index[, replace])¶

Either return the n-th section of a string delimited by separator substring search if no replace argument is provided, or replace this section by replace else. This function can be used as a faster alternative to combined split/slice/join calls in some cases.

Cottle template
{token("First.Second.Third", ".", 1)}
{token("A//B//C//D", "//", 2)}
{token("XX-??-ZZ", "-", 1, "YY")}
{token("1;2;3", ";", 3, "4")}
Rendering output
Second
C
XX-YY-ZZ
1;2;3;4

ucase(string)¶

Return an uppercase conversion of given string value.

Cottle template
{ucase("Mixed Case String"}
Rendering output
MIXED CASE STRING

Type¶

cast(value, type)¶

Get value converted to requested scalar type. Type must be a string value specifying desired type:

• "b" or "boolean": convert to boolean value
• "n" or "number": convert to numeric value
• "s" or "string": convert to string value
Cottle template
{dump cast("2", "n") = 2}
{dump ["value for key 0"][cast("0", "n")]}
{dump cast("some string", "b")}
Rendering output
<true>
"value for key 0"
<true>

type(value)¶

Retrieve type of given value as a string. Possible return values are "boolean", "function", "map", "number", "string" or "void".

Cottle template
{type(15)}
{type("test")}
Rendering output
number
string

Dynamic¶

call(func, map)¶

Call function func with values from map as arguments (keys are ignored).

Cottle template
{call(cat, ["Hello", ", ", "World", "!"])}
{call(max, [3, 8, 2, 7])}
Rendering output
Hello, World!
8