PAN Advanced Tutorial Michel Jouvin LAL Orsay jouvinlal

PAN Advanced Tutorial Michel Jouvin LAL, Orsay jouvin@lal. in 2 p 3. fr http: //grif. fr Quattor Advanced Tutorial, LAL December 18, 2008

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 13/12/202118/12/2008 PAN Advanced Tutorial 2

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 A configuration path: must be enclosed between ‘’ or “” variable: variable identifier function: function identifier 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 13/12/202118/12/2008 PAN Advanced Tutorial 3

… 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 • A default value can be defined for required attributes • • • Hash keys have some restrictions: must not start with a number, cannot contain / and – 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 13/12/202118/12/2008 PAN Advanced Tutorial 4

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 • - 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 • • Cannot be included 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 13/12/202118/12/2008 PAN Advanced Tutorial 5

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) • - 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) • - • In panc v 9 {} will become optional if the dml is a simple statement, as for assignment Template must be a structure template In both case, template name must match the internal template name (defined in line 'template…') 13/12/202118/12/2008 PAN Advanced Tutorial 6

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 13/12/202118/12/2008 PAN Advanced Tutorial 7

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 13/12/202118/12/2008 PAN Advanced Tutorial 8

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 13/12/202118/12/2008 PAN Advanced Tutorial 9

Functions A function can be thank as a named DML • - If a function is called as a validation function, it must return true or false • - • 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 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 13/12/202118/12/2008 PAN Advanced Tutorial 10

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 13/12/202118/12/2008 PAN Advanced Tutorial 11

Conditional Blocks Conditional blocks are possible only inside a DML Syntax: if ( cond ) { dml 1 } [else { dml 2 }]; • • • No '; ' between dml 1 and else If dml 1 or dml 2 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 13/12/202118/12/2008 PAN Advanced Tutorial 12

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 13/12/202118/12/2008 PAN Advanced Tutorial 13

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; - 13/12/202118/12/2008 }; PAN Advanced Tutorial 14

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 13/12/202118/12/2008 PAN Advanced Tutorial 15

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 13/12/202118/12/2008 PAN Advanced Tutorial 16

Useful Links PAN Language Reference: look for last version… • - http: //ovh. dl. sourceforge. net/sourceforge/quattor/panlanguage-manual-8. 2. 4. pdf Quattor QWG wiki: additional information and examples • - https: //trac. lal. in 2 p 3. fr/LCGQWG 13/12/202118/12/2008 PAN Advanced Tutorial 17