pan/functions Template
TracNav
Table of Contents
Several pan programming patterns or idioms occur frequently in machine configurations. The functions defined in the "pan/functions" template provide shortcuts to using those idioms. To access the functions, the template must be included in the machine configuration:
include { 'pan/functions' };
After this is included, any of the defined functions can be used from within DML blocks.
'self' Utility Functions
Often one want to add elements to a resource (list or hash) incrementally with a sequence of assignment statements. Those assignment statements usually being in different templates. The following functions provide simple mechanisms to do so.
push(element...)
This function will return a copy of self with the given value(s) appended to the end. If self is undefined, the function will create a new list with the arguments and return that. An example is
'/mylist' = push('a');
'/mylist' = push('b');
The final value for '/mylist' will be a two-element list containing 'a' and 'b'.
Be careful, however, because the value of self is not directly modified by the push() function. This means that the following:
'/mylist' = {
push('a');
push('b');
};
will leave '/mylist' with the one-element list 'b'.
push_if(boolean, element...)
This function behaves exactly like push() except that the first argument determines whether or not to add the rest of the arguments to the value of self. If the value is false, the function will return an empty list. As for push(), this function will create a new list if self is undefined. See also the warning about multiple calls to push() within the same DML block; this warning also applies here.
npush(element...)
This function will return a copy of self with the given value(s) inserted into the nlist. The number of arguments must be even; each pair will be treated as a key/value. If self is undefined, the function will create a new nlist with the arguments and return that. An example is
'/mylist' = npush('a',1);
'/mylist' = npush('b',2);
The final value for '/mylist' will be a two-element nlist containing the key/value pairs ('a',1) and ('b',2).
Be careful because the value of self is not directly modified by the npush() function. This means that the following:
'/mylist' = {
npush('a',1);
npush('b',2);
};
will leave '/mylist' with the one-element nlist with the key/value pair ('b',2).
'object' Utility Functions
In standard usage, the name of the object template corresponds to the machine name (either with or without the domain). The host and domain names are very frequently needed in the configuration. These values can be hardcoded within variables, but then one risks to have an inconsistency between the name of the object template and those hardcoded values. A better method is to extract the host and domain names from the 'object' variable. The functions here do that for you.
hostname_from_object()
This function will return the short host name (i.e. without the domain). If the profile has a prefix "profile_", that prefix will be stripped from the returned hostname. The function verifies that the returned name is a valid hostname.
domainname_from_object(string)
This function will return the domain name from the 'object' variable. If there is no domain in the 'object' variable, then the string argument will be used as the default domain name. The function checks that the value is a valid domain name.
full_hostname_from_object(string)
This function returns the full hostname of the machine as determined from the 'object' variable. If value in the 'object' variable does not contain a domain, the string argument is used as the default domain. The function checks that the returned value is a valid host name.
