Method: Puppet::Parser::Functions.newfunction

Defined in:

lib/puppet/parser/functions.rb

.newfunction(name, options = {}, &block) ⇒ Hash

Create a new Puppet DSL function.

**The newfunction method provides a public API.**

This method is used both internally inside of Puppet to define parser functions. For example, template() is defined in template.rb using the newfunction method. Third party Puppet modules such as [stdlib](forge.puppetlabs.com/puppetlabs/stdlib) use this method to extend the behavior and functionality of Puppet.

See also [Docs: Custom Functions](puppet.com/docs/puppet/5.5/lang_write_functions_in_puppet.html)

Examples:

Define a new Puppet DSL Function

>> Puppet::Parser::Functions.newfunction(:double, :arity => 1,
     :doc => "Doubles an object, typically a number or string.",
     :type => :rvalue) {|i| i[0]*2 }
=> {:arity=>1, :type=>:rvalue,
    :name=>"function_double",
    :doc=>"Doubles an object, typically a number or string."}

Invoke the double function from irb as is done in RSpec examples:

>> require 'puppet_spec/scope'
>> scope = PuppetSpec::Scope.create_test_scope_for_node('example')
=> Scope()
>> scope.function_double([2])
=> 4
>> scope.function_double([4])
=> 8
>> scope.function_double([])
ArgumentError: double(): Wrong number of arguments given (0 for 1)
>> scope.function_double([4,8])
ArgumentError: double(): Wrong number of arguments given (2 for 1)
>> scope.function_double(["hello"])
=> "hellohello"

Parameters:

• name (Symbol) —

  the name of the function represented as a ruby Symbol. The newfunction method will define a Ruby method based on this name on the parser scope instance.

• block (Proc) —

  the block provided to the newfunction method will be executed when the Puppet DSL function is evaluated during catalog compilation. The arguments to the function will be passed as an array to the first argument of the block. The return value of the block will be the return value of the Puppet DSL function for :rvalue functions.

• options (Hash) (defaults to: {}) —

  a customizable set of options

Options Hash (options):

• :type (:rvalue, :statement) — default: :statement —

  the type of function. Either :rvalue for functions that return a value, or :statement for functions that do not return a value.

• :doc (String) — default: '' —

  the documentation for the function. This string will be extracted by documentation generation tools.

• :arity (Integer) — default: -1 —

  the [arity](en.wikipedia.org/wiki/Arity) of the function. When specified as a positive integer the function is expected to receive exactly the specified number of arguments. When specified as a negative number, the function is expected to receive _at least_ the absolute value of the specified number of arguments incremented by one. For example, a function with an arity of -4 is expected to receive at minimum 3 arguments. A function with the default arity of -1 accepts zero or more arguments. A function with an arity of 2 must be provided with exactly two arguments, no more and no less. Added in Puppet 3.1.0.

• :environment (Puppet::Node::Environment) — default: nil —

  can explicitly pass the environment we wanted the function added to. Only used to set logging functions in root environment

Returns:

• (Hash) —

  describing the function.

# File 'lib/puppet/parser/functions.rb', line 188

def self.newfunction(name, options = {}, &block)
  name = name.intern
  environment = options[:environment] || Puppet.lookup(:current_environment)

  Puppet.warning _("Overwriting previous definition for function %{name}") % { name: name } if get_function(name, environment)

  arity = options[:arity] || -1
  ftype = options[:type] || :statement

  unless ftype == :statement or ftype == :rvalue
    raise Puppet::DevError, _("Invalid statement type %{type}") % { type: ftype.inspect }
  end

  # the block must be installed as a method because it may use "return",
  # which is not allowed from procs.
  real_fname = "real_function_#{name}"
  environment_module(environment).send(:define_method, real_fname, &block)

  fname = "function_#{name}"
  env_module = environment_module(environment)

  env_module.send(:define_method, fname) do |*args|
    Puppet::Util::Profiler.profile(_("Called %{name}") % { name: name }, [:functions, name]) do
      if args[0].is_a? Array
        if arity >= 0 and args[0].size != arity
          raise ArgumentError, _("%{name}(): Wrong number of arguments given (%{arg_count} for %{arity})") % { name: name, arg_count: args[0].size, arity: arity }
        elsif arity < 0 and args[0].size < (arity + 1).abs
          raise ArgumentError, _("%{name}(): Wrong number of arguments given (%{arg_count} for minimum %{min_arg_count})") % { name: name, arg_count: args[0].size, min_arg_count: (arity + 1).abs }
        end

        r = Puppet::Pops::Evaluator::Runtime3FunctionArgumentConverter.convert_return(send(real_fname, args[0]))
        # avoid leaking aribtrary value if not being an rvalue function
        options[:type] == :rvalue ? r : nil
      else
        raise ArgumentError, _("custom functions must be called with a single array that contains the arguments. For example, function_example([1]) instead of function_example(1)")
      end
    end
  end

  func = { :arity => arity, :type => ftype, :name => fname }
  func[:doc] = options[:doc] if options[:doc]

  env_module.add_function_info(name, func)

  func
end