Skip to content

Latest commit

 

History

History
174 lines (116 loc) · 7.19 KB

lang_reserved.markdown

File metadata and controls

174 lines (116 loc) · 7.19 KB
Raw
layout title canonical
default
Language: Reserved Words and Acceptable Names
/puppet/latest/reference/lang_reserved.html

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.
  • Cannot be used as names of resource attributes for custom types (e.g., use "onlyif" instead of "if")

The following words are reserved:

  • and --- expression operator
  • case --- language keyword
  • class --- language keyword
  • default --- language keyword
  • define --- language keyword
  • else --- language keyword
  • elsif --- language keyword
  • false --- boolean value
  • if --- language keyword
  • in --- expression operator
  • import --- language keyword
  • inherits --- language keyword
  • node --- language keyword
  • or --- expression operator
  • true --- boolean value
  • undef --- special value

Additionally, you cannot use the name of any existing resource type or function as the name of a function, and you cannot use the name of any existing resource type as the name of a defined type.

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).

Reserved Variable Names

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

  • $string --- If a variable with this name is present, all templates and inline templates in the current scope will return the value of $string instead of whatever they were meant to return. This is a bug rather than a deliberate design, and can be tracked at issue #14093.
  • Every variable name consisting only of numbers, 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's behavior when these variables are directly assigned a value is undefined.

Additionally, re-using the names of any of Puppet's built-in variables or facts at top scope will cause compilation to fail.

Note: You can safely re-use fact names at node or local scope, but should do so with care, as dynamic scope lookup may cause classes and defined types declared in that scope to receive unexpected data.

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 can include:

  • Uppercase and lowercase letters
  • Numbers
  • Underscores

There is no additional restriction on the first non-$ character of a variable name. Variable names are case-sensitive. Note that some variable names are reserved.

Variable names should match the following regular expression:

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

Variable names can be fully qualified to refer to variables from foreign scopes. Qualified variable names look like $class::name::variable_name. They begin with $, the name of the class that contains the variable, and the :: (double colon) namespace separator, and end with the variable's local name.

Qualified variable names should match the following regular expression:

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

Classes and Types

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

  • Lowercase letters
  • Numbers
  • 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 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 type names.

Modules

Module names obey the same rules as individual class/type namespace segments. That is, they must begin with a lowercase letter and can include:

  • Lowercase letters
  • Numbers
  • 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
  • Numbers
  • 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
  • Numbers
  • Underscores
  • Colons
  • Periods
  • Hyphens

Tag names should match the following regular expression:

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

Resources

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

Resource names (or namevars) may 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, numbers, periods, underscores, and dashes. (That is, node names should match /\A[a-z0-9._-]+\Z/.)