Future Parser: Reserved Words and Acceptable Names

Reserved Words

Several words in the Puppet language are reserved. This means they:

• Cannot be used as bare word strings — you must quote these words if you wish to use them as strings.
• Cannot be used as names for custom functions.
• Cannot be used as names for classes.
• Cannot be used as names for custom resource types or defined resource types.

The following words are reserved:

• and — expression operator
• application — reserved for future use; logs warning instead of error
• attr — reserved for future use
• case — language keyword
• class — language keyword
• consumes — reserved for future use; logs warning instead of error
• default — language keyword
• define — language keyword
• else — language keyword
• elsif — language keyword
• false — boolean value
• function — reserved for future use
• if — language keyword
• import — former language keyword (now removed)
• in — expression operator
• inherits — language keyword
• node — language keyword
• or — expression operator
• private — reserved for future use
• produces — reserved for future use; logs warning instead of error
• true — boolean value
• type — reserved for future use
• undef — special value
• unless — language keyword

Additionally:

• You cannot use the name of any existing resource type or function as the name of a function.
• You cannot use the name of any existing resource type as the name of a defined type.
• You shouldn’t use the name of any existing data type (e.g. integer) as the name of a defined type, as this will make it inconvenient to interact with. (You can’t directly reference a resource of that defined type with only its uppercased name — instead of writing a resource reference like Integer[title], you would have to use Resource[integer, title].)

Reserved Class Names

The following are built-in namespaces used by Puppet and so must not be used as class names:

• main — Puppet automatically creates a main class, which contains any resources not contained by any other class.
• settings — The automatically created settings namespace contains variables with the settings available to the compiler (that is, the Puppet master’s settings).

Additionally, the names of data types can’t be used as class names:

• any, Any
• array, Array
• boolean, Boolean
• catalogentry, catalogEntry, CatalogEntry
• class, Class
• collection, Collection
• callable, Callable
• data, Data
• default, Default
• enum, Enum
• float, Float
• hash, Hash
• integer, Integer
• numeric, Numeric
• optional, Optional
• pattern, Pattern
• resource, Resource
• runtime, Runtime
• scalar, Scalar
• string, String
• struct, Struct
• tuple, Tuple
• type, Type
• undef, Undef
• variant, Variant

Reserved Variable Names

The following variable names are reserved, and you must not assign values to them:

• Every variable name consisting only of digits, starting with $0 — These regex capture variables are automatically set by regular expressions used in conditional statements, and their values do not persist outside their associated code block or selector value. Puppet will raise an error if you try to assign to these variables.
• Puppet’s built-in variables and facts are reserved at top scope, but can be safely re-used at node or local scope.
• If enabled, the $trusted and $facts variables are reserved for facts and cannot be reassigned at local scopes.

Reserved Parameter Names

The following are special variable names that may not be used as parameters in classes or defined types:

• $title – the title of a class or defined type
• $name – a synonym for $title

Acceptable Characters in Names

Puppet limits the characters you can use when naming language constructs.

Note: In some cases, names containing unsupported characters will still work. These cases should be considered bugs, and may cease to work at any time. Removal of these bug cases will not be limited to major releases.

Variables

Variable names begin with a $ (dollar sign) and are case-sensitive.

Most variable names must start with a lowercase letter or an underscore. The exception is regex capture variables, which are named with only numbers.

Variable names can include:

• Uppercase and lowercase letters
• Numbers
• Underscores (_)

If the first character is an underscore, that variable should only be accessed from its own local scope; using qualified variable names where any namespace segment begins with _ is deprecated.

Note that some variable names are reserved.

Qualified Variable Names

Qualified variable names are prefixed with the name of their scope and the :: (double colon) namespace separator. (For example, the $vhostdir variable from the apache::params class would be $apache::params::vhostdir.)

Optionally, the name of the very first namespace may be empty, representing the top namespace. In previous versions of the Puppet language, this was often used to work around bugs, but it’s not necessary in this version. The main use is to indicate to readers that you’re accessing a top-scope variable, e.g. $::is_virtual.

Regular Expressions For Variable Names

Short variable names should match the following regular expression:

\A\$[a-z0-9_][a-zA-Z0-9_]*\Z

Qualified variable names should match the following regular expression:

\A\$([a-z][a-z0-9_]*)?(::[a-z][a-z0-9_]*)*::[a-z0-9_][a-zA-Z0-9_]*\Z

Classes and Defined Types

The names of classes and defined types can consist of one or more namespace segments. Each namespace segment must begin with a lowercase letter and can include:

• Lowercase letters
• Digits
• Underscores

Namespace segments should match the following regular expression:

\A[a-z][a-z0-9_]*\Z

The one exception is the top namespace, whose name is the empty string.

Multiple namespace segments can be joined together in a class or defined type name with the :: (double colon) namespace separator.

Class names with multiple namespaces should match the following regular expression:

\A([a-z][a-z0-9_]*)?(::[a-z][a-z0-9_]*)*\Z

Note that some class names are reserved, and reserved words cannot be used as class or defined type names.

Additionally, you cannot use the name <MODULE NAME>::init for a class or defined type. This is because init.pp is a reserved filename, which should contain a class named after the module.

Modules

Module names obey the same rules as individual namespace segments (like in a class or defined type name). That is, they must begin with a lowercase letter and can include:

• Lowercase letters
• Digits
• Underscores

Module names should match the following regular expression:

\A[a-z][a-z0-9_]*\Z

Note that reserved words and reserved class names cannot be used as module names.

Parameters

Class and defined type parameters begin with a $ (dollar sign), and their first non-$ character must be a lowercase letter. They can include:

• Lowercase letters
• Digits
• Underscores

Parameter names should match the following regular expression:

\A\$[a-z][a-z0-9_]*\Z

Tags

Tags must begin with a lowercase letter, number, or underscore, and can include:

• Lowercase letters
• Digits
• Underscores
• Colons
• Periods
• Hyphens

Tag names should match the following regular expression:

\A[a-z0-9_][a-z0-9_:\.\-]*\Z

Resources

Resource titles can contain any characters whatsoever. They are case-sensitive.

Resource names (or namevars) might be limited by the underlying system being managed. (E.g., most systems have limits on the characters allowed in the name of a user account.) The user is generally responsible for knowing the name limits on the platforms they manage.

Nodes

The set of characters allowed in node names is undefined in this version of Puppet. For best future compatibility, you should limit node names to letters, digits, periods, underscores, and dashes. (That is, node names should match /\A[a-z0-9._-]+\Z/.)

Environments

Environment names can contain lowercase letters, numbers, and underscores. That is, they must match the following regular expression:

\A[a-z0-9_]+\Z