This specification is a technical description of the Puppet Language.
- Puppet Program
- A Program written in the Puppet Language, also known as the "Puppet DSL"
- Program
- A Program written in the Puppet Language unless text refers to some other language like Ruby Program, Java Program etc.
- LHS
- Left Hand Side, the left operand in a binary expression.
- RHS
- Right Hand Side, the right operand in a binary expression.
- Lexing
- The act of turning source text into tokens that are recognized by a parser.
- Parsing
- The act of turning source text into a abstract syntax model.
- Loading
- The act of locating source text, parsing, and evaluating logic to the point where definitions are available (but not necessarily evaluated in full).
- Evaluation
- The act of carrying out the instructions in the Puppet Program being executed.
- Compilation
- The act of producing a Catalog by executing a Puppet Program. Also known as Catalog Building.
- Declaration
- The act of introducing a named and possibly typed element into a Program.
- Definition
- The act of assigning/setting the content/value of an element in the Program
- Manifest
- A file with source code in the Puppet Language. The extension .pp is used for such files.
Grammars (lexical and syntactic) are written in a variant of Extended Backus Naur Form (EBNF) with the following syntax and semantics:
| syntax | meaning |
|---|---|
| 'c' | the terminal character c |
| '\r' | the terminal ascii character CR |
| '\n' | the terminal ascii character NL |
| '\t' | the terminal ascii character TAB |
| '\' | the terminal ascii character BACKSLASH |
| rule: | a rule name, (all uppercase rule is a terminal rule, mixed case is a regular rule) |
| TOKEN: | a terminal token rule |
| ( ) | groups elements |
| ? | the preceding element occurs zero or one time |
| * | the preceding element occurs zero or many times |
| + | the preceding element occurs one or many times |
| | | or |
| /re/ | a regular expression as defined by Ruby 2.0 |
| ; | rule end |
| sym = | symbolic naming of rule to the right |
| sym += | symbolic naming of array containing iterative values from rule on right |
| rule<Type> | A rule call that when evaluated produces the given (runtime type) |
| rule <Type>: | A type safe rule that when evaluated produces the given (runtime type) |
The presence of sym= and sym+= does not alter the grammar, they only provide notation to
be able to refer to the various parts of the rule using symbolic names.
Hello: 'h' 'e' 'l' 'l' 'o' ;
Hi: 'h' 'i' ;
NAME: /[A-Za-z]+/ ;
Greeting: (Hello | Hi ) NAME '!'?;
StringAccess
: Expression<String> '[' from = Int (',' to = Int)? ']'
;
Int <Integer> : Expression ;
ASequenceOfNames
: (names += NAME)+
;
Algebra notation is used in the specification to describe the operations on types as well as other logical constructs. Here is a summary of the set theory notations used in this specification:
X is member of (the set Y) (can be read as exists in)
X ∈ Y
X is not member of (the set Y) (can be read as not exists in)
X ∉ Y
The union of X and Y (all that are in X, in Y, or in both)
X ∪ Y
The intersection of X and Y (all that are in both X and Y)
X ∩ Y
Implies, gives, produces (depending on context)
→
The empty set
∅
The union of the type Integer and the type Float is Numeric:
Integer ∪ Float → Numeric
This means that if there is a collection of objects that consist of integers and float
(but no instances of any other type), then the collection is of
Collection[Numeric] types.