Custom functions in Ruby overview
Get started with an overview of Ruby custom functions.
Syntax of Ruby functions
Puppet::Functions.create_functionmethod. You don’t need to
requireany Puppet libraries. Puppet handle libraries automatically when it loads the function.
Puppet::Functions.create_function(:<FUNCTION NAME>) do dispatch :<METHOD NAME> do param '<DATA TYPE>', :<ARGUMENT NAME (displayed in docs/errors)> ... end def <METHOD NAME>(<ARGUMENT NAME (for local use)>, ...) <IMPLEMENTATION> end end
- A function name.
- A block of code (which takes no arguments). This block contains:
- One or more signatures to configure the function’s arguments.
- An implementation method for each signature. The return value of the implementation method is the return value of the function.
# /etc/puppetlabs/code/environments/production/modules/mymodule/lib/puppet/functions/mymodule/upcase.rb Puppet::Functions.create_function(:'mymodule::upcase') do dispatch :up do param 'String', :some_string end def up(some_string) some_string.upcase end end
Place a Ruby function in its own file, in the
lib/puppet/functions directory of either a module or an
environment. The filename must match the name of the function, and have the
.rb extension. For namespaced functions, each segment prior to the
final one must be a subdirectory of
functions, and the final
segment must be the filename.
|Function name||File location|
metadata.jsonfile, it loads custom functions only from those specific dependencies.
Function names are similar to class names. They consist of one or more segments. Each segment must start with a lowercase letter, and can include:
If a name has multiple segments, separate them with a double-colon (
::) namespace separator.
Match each segment with this regular expression:
Match the full name with this regular expression:
Function names can be either global or namespaced:
Global names have only one segment (
str2bool), and can be used in any module or environment. Global names are shorter, but they’re not guaranteed to be unique — if you use a function name that is already in use by another module, Puppet might load the wrong module when you call it.
Namespaced names have multiple segments (
stdlib::str2bool), and are guaranteed to be unique. The first segment is dictated by the function’s location:
In an environment, use
In a module, use the module’s name (
stdlib::str2boolfor a function stored in the
Most functions have two name segments, although it’s legal to use more.
Examples of legal function names:
num2bool(a function that could come from anywhere)
postgresql::acls_to_resource_hash(a function in the
environment::hash_from_api_call(a function in an environment)
Examples of illegal function names:
6_pack(must start with a letter)
_hash_from_api_call(must start with a letter)
Find-Resource(can only contain lowercase letters, numbers, and underscores)
Passing names to
create_function as symbols
When you call the
pass the function’s name to it as a Ruby symbol.
To turn a function name into a symbol:
If the name is global, prefix it with a colon (
If it’s namespaced: put the name in quotation marks, and prefix the full quoted string with a colon (
Related topics: Puppet modules, Environments, Main manifest, Module metadata, Ruby symbols.