1. Quattor Advanced Tutorial, LAL
PAN Advanced Tutorial
Michel Jouvin
LAL, Orsay
Quattor Advanced Tutorial, LAL
December 18, 2008

2. Outline Reminder about PAN concepts Templates Include Assignment
undef and null
DML and return value
Functions
Built-in global variables
Conditional blocks
Loops
Path auto-escaping
Annotation
Debugging
18/01/201918/12/2008
PAN Advanced Tutorial

3. PAN Concepts… PAN is a declarative-like language
Main statement is value assignment
No conditional block and for loops
Every statement returns a value
Left hand sign of an assignment may be
A configuration path: must be enclosed between ‘’ or “”
A variable: variable identifier
A function: function identifier
A type: type identifier
Strongly dynamic typed language
Type is assigned at first assignment
Type can be changed only if variable is undef
Configuration path can be bound to a type: bind
Once bounded, cannot be changed
A path can be bounded to several types
18/01/201918/12/2008
PAN Advanced Tutorial

4. … PAN Concepts When binding ‘/’ to a type, it defines a schema
A type may be a complex structure with both required and optional attributes
An attribute bound to a simple type is called a property
An attribute bound to a list (array) or nlist (hash) is called a resource
Hash keys have some restrictions: must not start with a number, cannot contain / and –
A default value can be defined for required attributes
When defined for optional attributes, they are always defined and thus no longer optional!
Every statement can be multi-line but must end with ‘;’
Compilation fails if a configuration path is left undefined, a required configuration path is missing or if resulting type of an assignment doesn’t match the bounded type
18/01/201918/12/2008
PAN Advanced Tutorial

5. Templates
A template is a file containing PAN statements and must start with a line:
[keyword] template dir/to/template;
Optional keyword may be:
object: this is the main template of a node profile
Cannot be included
structure: defines relative path name assigned to a parent with create()
declaration: a template that can contain only type and function definitions
unique: a standard template that must be ignored after the first inclusion
Must be used for every template except when the template really requires to be included several times
dir/to/template must match template name and relative location
18/01/201918/12/2008
PAN Advanced Tutorial

6. Include
Template are like Russian puppets: one template includes others which include others…
Starts from the object template
Main form of include is with include statement
include { dml };
Previous syntax (without {} is deprecated)
In panc v9 {} will become optional if the dml is a simple statement, as for assignment
If dml returns undef or null, include statement is just ignored
Built-in function if_exists('template_name') returns undef it the template doesn’t exist
Another form is function create(): defines relative path of a parent (path or variable assigned)
Template must be a structure template
In both case, template name must match the internal template name (defined in line 'template…')
18/01/201918/12/2008
PAN Advanced Tutorial

7. Assignment PAN has 2 assignment operators : ‘=‘ and ‘?=‘
‘=‘: overwrite the existing value, if any
‘?=‘: assign the value only if none already defined
Declarative-like assignment where the first assignment win
Sometimes called in PAN the default value operator
undef and null value are considered undefined values
It is recommended to use ‘?=‘ everywhere, except in circumstances where overwrite must be enforced
PAN paradygm is to define specific values before more general ones
This is the only way to ensure that the specific context is taken into account when executing of generic actions
‘?=‘ operator is not available in DML or functions
18/01/201918/12/2008
PAN Advanced Tutorial

8. undef and null
undef is the value assigned to a variable when it is created until it receives an explicit value
Function is_defined() can be used to test if a variable is undef (function returns false)
null is a specific value different from undef
When assigned to a path, the path is deleted
When assigned to a variable, null value is retained by the variable and further assignement of the variable to a path deletes the path
Function is_null() may be used to test is a variable value is null
A variable whose value is null is also considered undefined
include statement treats undef and null as equivalent
Can be converted to string with to_string()
Useful for printing
18/01/201918/12/2008
PAN Advanced Tutorial

9. DML and Return Value
A DML is a block of instruction on assignment RHS and is delimited by {}
Followed by ';' like any PAN statement
Every instruction in the DML is delimited by ';'
Value returned by DML is assigned to object on LHS
Every PAN statement returns a value
If not explicitly set, it is undef
For example 'if (x) 'true';' returns undef if x is false
Object on LHS can be referenced into DML through SELF variable
SELF variable cannot be modified in a DML
When it is a list or nlist, the content of the list/nlist can be modified and SELF must be returned as the DML value
SELF is initialized as a list/nlist at first assignment if undef
return() should be avoided on "natural" exit
Just reference the variable whose value must be returned
18/01/201918/12/2008
PAN Advanced Tutorial

10. Functions A function can be thank as a named DML
Name is assigned with:
function identifier = { … };
A function can be called either in place of a DML or inside a DML with a standard function call : identifier(…)
Arguments passed when function is called can be retrieved in global list ARGV (argument count is ARGC)
It may be defined in any template, except a structure template
It must have been defined before being called
If a function is called as a validation function, it must return true or false
A validation function is a function called as part of a type definition
If a function is called from another function, SELF refers to the global variable or config path assigned, not to the local variable in the calling function
18/01/201918/12/2008
PAN Advanced Tutorial

11. Built-in Global Variables
All built-in global variables have a name in uppercase
This is the pan convention for global variables
SELF: refers to the global object being assigned
Either a configuration path or a global variable
ARGC/ARGV: arguments passed to a function
LOADPATH:
OBJECT: name of the object template (profile) being compiled
TEMPLATE: name of the current template
18/01/201918/12/2008
PAN Advanced Tutorial

12. Conditional Blocks Conditional blocks are possible only inside a DML
Syntax:
if ( cond ) { dml1 } [else { dml2 }];
No ';' between dml1 and else
If dml1 or dml2 are simple statements, {} can be omitted
'if () else …;' is a simple statement
Operators are the same as C operators
Both arguments in comparisons must have the same type
No implicit type conversion
Use functions to_xxx() if needed
Functions exists() and is_xxx() allows to test existence, definition and type of variables and paths
exists() implicitly done by all is_xxx()
Existence and definition are different
18/01/201918/12/2008
PAN Advanced Tutorial

13. Loops Loops are possible only inside a DML
First form : foreach (key;value;variable) { … }
Variable must be a list or nlist
If the variable is a list, key is the index
No way to exit prematurely the loop
Value may be modified
Second form: while (condition) { … }
May iterate over a list/nlist using first()/next() functions
Both functions return true if they are able to get a new element from the list
first()/next() functions have an argument order different from foreach : (variable,key,value)
Less efficient than foreach for processing an entire list
18/01/201918/12/2008
PAN Advanced Tutorial

14. Path Auto-Escaping
If an element in a path contains characters like '/' or '.' or is beginning with a number but is not a list index, it must be escaped
Used to be done by assigning a DML to the parent and doing escaping in the DML
An example is pkg_xxx() functions
It is now possible to escape part of a path on LHS
'/my/path/{a/b}' = 'test';
This is equivalent to:
'/my/path' = {
SELF[escape('A/b')] = 'test';
SELF; };
18/01/201918/12/2008
PAN Advanced Tutorial

15. Annotations
Since panc 8.2.4, it is possible to put annotations in PAN templates
Annotation is a specially formatted comment that can be processed by documentation generation tools like doxygen
Format is key/value pairs between () and introduced by @(
author = loomis
desc = some descriptive text
args = 3
argnames = alpha, beta, gamma )
Valid keys are not defined by the grammar
'(', ')' and '=' cannot be part of the description
Can appear every where in a template
18/01/201918/12/2008
PAN Advanced Tutorial

16. Debugging
debug('text') allows to print messages only if debugging is enabled
Doesn't trig an error like error()
Since panc 8.2.4, print of debugging messages is enabled on a per template basis, giving regexp of (namespaced) template names where to enable/disable debugging
In SCDB, this is controlled by –Dpan.debug.include="…" and –Dpan.debug.exclude="…" in ant command
Ex: -Dpan.debug.include="common/gip/.*"
To print non-string variables with debug() (or error()), use function to_string()
to_string() can process any type, including list/nlit and values like undef and null
18/01/201918/12/2008
PAN Advanced Tutorial

17. Useful Links PAN Language Reference: look for last version…
language-manual pdf
Quattor QWG wiki: additional information and examples
18/01/201918/12/2008
PAN Advanced Tutorial