pan/functions Template

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