Module: Puppet::Parser::Functions

Extended by:
Util
Defined in:
lib/puppet/parser/functions.rb,
lib/puppet/parser/functions/split.rb,
lib/puppet/parser/functions/hiera.rb,
lib/puppet/parser/functions/extlookup.rb,
lib/puppet/parser/functions/hiera_hash.rb,
lib/puppet/parser/functions/hiera_array.rb,
lib/puppet/parser/functions/hiera_include.rb

Overview

A module for managing parser functions. Each specified function is added to a central module that then gets included into the Scope class.

Constant Summary

Class Method Summary (collapse)

Methods included from Util

exit_on_fail, exit_on_fail, which, which

Class Method Details

+ (Integer) arity(name)

Return the number of arguments a function expects.

Parameters:

  • name (Symbol) —

    the function

Returns:

  • (Integer) —

    The arity of the function. See newfunction for the meaning of negative values.



221
222
223
224
 
# File 'lib/puppet/parser/functions.rb', line 221

def self.arity(name)
  func = get_function(name)
  func ? func[:arity] : -1
end

+ (Object) autoloader  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Accessor for singleton autoloader



35
36
37
38
39
 
# File 'lib/puppet/parser/functions.rb', line 35

def self.autoloader
  @autoloader ||= Puppet::Util::Autoload.new(
    self, "puppet/parser/functions", :wrap => false
  )
end

+ (Object) environment_module(env = nil)  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get the module that functions are mixed into corresponding to an environment



45
46
47
48
49
50
51
52
 
# File 'lib/puppet/parser/functions.rb', line 45

def self.environment_module(env = nil)
  if env and ! env.is_a?(Puppet::Node::Environment)
    env = Puppet::Node::Environment.new(env)
  end
  @modules.synchronize {
    @modules[ (env || Environment.current || Environment.root).name ] ||= Module.new
  }
end

+ (Symbol, false) function(name)

Determine if a function is defined

Parameters:

  • name (Symbol) —

    the function

Returns:

  • (Symbol, false) —

    The name of the function if it’s defined, otherwise false.



167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/puppet/parser/functions.rb', line 167

def self.function(name)
  name = name.intern

  func = nil
  @functions.synchronize do
    unless func = get_function(name)
      autoloader.load(name, Environment.current)
      func = get_function(name)
    end
  end

  if func
    func[:name]
  else
    false
  end
end

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

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 use this method to extend the behavior and functionality of Puppet.

See also Docs: Custom Functions

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:

>> scope = Puppet::Parser::Scope.new_for_test_harness('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 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.

Returns:

  • (Hash) —

    describing the function.



121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/puppet/parser/functions.rb', line 121

def self.newfunction(name, options = {}, &block)
  name = name.intern

  Puppet.warning "Overwriting previous definition for function #{name}" if get_function(name)

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

  unless ftype == :statement or ftype == :rvalue
    raise Puppet::DevError, "Invalid statement 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.send(:define_method, real_fname, &block)

  fname = "function_#{name}"
  environment_module.send(:define_method, fname) do |*args|
    if args[0].is_a? Array
      if arity >= 0 and args[0].size != arity
        raise ArgumentError, "#{name}(): Wrong number of arguments given (#{args[0].size} for #{arity})"
      elsif arity < 0 and args[0].size < (arity+1).abs
        raise ArgumentError, "#{name}(): Wrong number of arguments given (#{args[0].size} for minimum #{(arity+1).abs})"
      end
      self.send(real_fname, args[0])
    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

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

  add_function(name, func)
  func
end

+ (Object) reset  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Reset the list of loaded functions.



20
21
22
23
24
25
26
27
28
29
30
 
# File 'lib/puppet/parser/functions.rb', line 20

def self.reset
  @functions = Hash.new { |h,k| h[k] = {} }.extend(MonitorMixin)
  @modules = Hash.new.extend(MonitorMixin)

  # Runs a newfunction to create a function for each of the log levels
  Puppet::Util::Log.levels.each do |level|
    newfunction(level, :doc => "Log a message on the server at level #{level.to_s}.") do |vals|
      send(level, vals.join(" "))
    end
  end
end

+ (Boolean) rvalue?(name)

Determine whether a given function returns a value.

Parameters:

  • name (Symbol) —

    the function

Returns:

  • (Boolean) 


209
210
211
212
 
# File 'lib/puppet/parser/functions.rb', line 209

def self.rvalue?(name)
  func = get_function(name)
  func ? func[:type] == :rvalue : false
end