Expressions

DESCRIPTION

At some places in the Director configuration and within LDAP objects the use of expressions rather than mere strings is allowed. Expressions are strings with the possibility to use variable references expanding to the contents of some entities (most of the time the values of attributes of an LDAP object) and to manipulate this contents with modifiers.

SYNTAX

Each expression is composed of parts with a static character string and variable references as in the following example:

This is ${variable1} in order to ${variable2}

In the above case "This is " and "in order to " are static parts of the expression, while "${variable1} and ${variable2} are references to two variables.

Each variable reference is always like

${variable}
${variable:modifier}

The optional modifier part describes an operation that should be performed to the value of variable before including the results in the result string. The result of the modifier itself may be modified, thus

${variable:modifier1:modifier2}

and so on is a valid expression.

Modifiers may accept arguments. Arguments are passed like in

${variable:modifier1.arg1:modifier2.arg1.arg2}

SPECIAL VARIABLES

Besides the set of context specific variables, the expression expander itself defines a few variables with specific semantics:

empty name

(${} or ${:modifier)) expands to an empty string. This is often used together with modifiers that are not requiring any input string.

<

expands to the whole string on the left side of this variable reference.

(

marks the beginning of a section (see below). The contents of $( is the empty string.

)

marks the end of a section. Expands to the whole text between the corresponding section begin mark $( and the current position. Example: "Some text.$( Value: ${testvar}${):ifdef.testvar}" expands to "Some text." if testvar is not set, otherwise to "Some text. Value: $testvar".

KNOWN MODIFIERS

lowercase

returns the input string in lowercase letters

uppercase

returns the input string in uppercase letters

finduid[.lowlimit[.highlimit]]

searches the user objects in the directory and returns a free uid within a given range. Finduid accepts two arguments: the first being the lower, the second being the higher limit of the uid range (defaults to 1000 and 5000).

findgid[.lowlimit[.highlimit]]

searches the group objects in the directory and returns a free gid within a given range. Findgid accepts two arguments: the first being the lower, the second being the higher limit of the gid range (defaults to 1000 and 5000).

substr[.startpos[.length]]

extracts a substring from the input string. Substr accepts two arguments, the first being the position (starting from 0) in the string where the substring starts, the second being the length of the substring. The start position defaults to 0, the length to the length of the entire input string. Using out-of-bounds start position or length will result in some reasonable behaviour (empty result if start position is beyond string length, truncation if length is to high).

*.multiplier

interprets the input string as an integer number and multiplies it by the multiplier.

*.divisor

interprets the input string as an integer number and divides it by the divisor.

+.summand

interprets the input string as an integer number and adds the summand.

-.subtrahend

interprets the input string as an integer number and subtracts the subtrahend.

masterhost

returns the name of the configured master host.

firsthost.class

returns the name of one host that is a member of the host class with the given name.

uniquelogin

expects the input string to be a login name, checks if this login name is used and builds an unused login name by adding a number to the input string if necessary.

initials

Starting characters of each word.

asciify

translates non-ASCII characters in the input string into a corresponding ASCII representation (i.e. removes accents). Be warned, however, that this is not complete and only few replacements are known to asciify - other non-ASCII characters are just dropped.

shell.cmd[.arg1[.arg2...]]

runs a shell command (cmd plus optional args), passes the input string down via its standard input and reads the result from its standard output.

if.[.arg1[.arg2...]]

if the input string is non-empty, the result string is arg1, otherwise arg2. Missing arg1/arg2 are treated as empty strings.

ifdef.arg1

if the variable with the name in arg1 is defined, the result is the input, otherwise an empty string. This is especially useful with the $( and $) special variables.

printbytesize

interpretes the input string as an integer figure specifying a byte size and converts it into a human readable form

xmlencode

encodes special characters in the value by their XML escape sequence.

default.arg1

if value is empty, then arg1 is taken as the new value

genmacaddr

generate a random local domain MAC address. Value is supposed to be the host name, the same host name generates the same MAC during the same session. An empty value generates an empty MAC address.

timestamp

current date and time

ticketid generate a unique issue tracking id