module Puppet::Parser::Functions

add_function_info(name, info) click to toggle source

# File lib/puppet/parser/functions.rb, line 57
def self.add_function_info(name, info)
  @metadata[name] = info
end

all_function_info() click to toggle source

# File lib/puppet/parser/functions.rb, line 49
def self.all_function_info
  @metadata
end

arity(name, environment = Puppet.lookup(:current_environment)) click to toggle source

Return the number of arguments a function expects.

@param [Symbol] name the function @param [Puppet::Node::Environment] environment The environment to find the function in @return [Integer] The arity of the function. See {newfunction} for

the meaning of negative values.

@api public

# File lib/puppet/parser/functions.rb, line 243
def self.arity(name, environment = Puppet.lookup(:current_environment))
  func = get_function(name, environment)
  func ? func[:arity] : -1
end

autoloader() click to toggle source

Accessor for singleton autoloader

@api private

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

environment_module(env) click to toggle source

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

@api private

# File lib/puppet/parser/functions.rb, line 45
def self.environment_module(env)
  @modules[env.name] ||= Module.new do
    @metadata = {}

    def self.all_function_info
      @metadata
    end

    def self.get_function_info(name)
      @metadata[name]
    end

    def self.add_function_info(name, info)
      @metadata[name] = info
    end
  end
end

function(name, environment = Puppet.lookup(:current_environment)) click to toggle source

Determine if a function is defined

@param [Symbol] name the function @param [Puppet::Node::Environment] environment the environment to find the function in

@return [Symbol, false] The name of the function if it’s defined,

otherwise false.

@api public

# File lib/puppet/parser/functions.rb, line 188
def self.function(name, environment = Puppet.lookup(:current_environment))
  name = name.intern

  func = nil
  unless func = get_function(name, environment)
    autoloader.load(name, environment)
    func = get_function(name, environment)
  end

  if func
    func[:name]
  else
    false
  end
end

functiondocs(environment = Puppet.lookup(:current_environment)) click to toggle source

# File lib/puppet/parser/functions.rb, line 204
def self.functiondocs(environment = Puppet.lookup(:current_environment))
  autoloader.loadall

  ret = ""

  merged_functions(environment).sort { |a,b| a[0].to_s <=> b[0].to_s }.each do |name, hash|
    ret << "#{name}\n#{"-" * name.to_s.length}\n"
    if hash[:doc]
      ret << Puppet::Util::Docs.scrub(hash[:doc])
    else
      ret << "Undocumented.\n"
    end

    ret << "\n\n- *Type*: #{hash[:type]}\n\n"
  end

  ret
end

get_function_info(name) click to toggle source

# File lib/puppet/parser/functions.rb, line 53
def self.get_function_info(name)
  @metadata[name]
end

newfunction(name, options = {}, &block) click to toggle source

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 {file:lib/puppet/parser/functions/template.rb 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](docs.puppetlabs.com/guides/custom_functions.html)

@example 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."}

@example 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"

@param [Symbol] name 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.

@param [Proc] block 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.

@option options [:rvalue, :statement] :type (:statement) the type of function.

Either `:rvalue` for functions that return a value, or `:statement` for
functions that do not return a value.

@option options [String] :doc (”) the documentation for the function.

This string will be extracted by documentation generation tools.

@option options [Integer] :arity (-1) the

[arity](http://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.

@option options [Puppet::Node::Environment] :environment (nil) can

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

@return [Hash] describing the function.

@api public

# File lib/puppet/parser/functions.rb, line 135
def self.newfunction(name, options = {}, &block)
  name = name.intern
  environment = options[:environment] || Puppet.lookup(:current_environment)

  Puppet.warning "Overwriting previous definition for function #{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 #{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}", [: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 (#{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
  end

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

  env_module.add_function_info(name, func)

  func
end

reset() click to toggle source

Reset the list of loaded functions.

@api private

# File lib/puppet/parser/functions.rb, line 19
def self.reset
  @modules = {}

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

rvalue?(name, environment = Puppet.lookup(:current_environment)) click to toggle source

Determine whether a given function returns a value.

@param [Symbol] name the function @param [Puppet::Node::Environment] environment The environment to find the function in @return [Boolean] whether it is an rvalue function

@api public

# File lib/puppet/parser/functions.rb, line 230
def self.rvalue?(name, environment = Puppet.lookup(:current_environment))
  func = get_function(name, environment)
  func ? func[:type] == :rvalue : false
end

Constants

Public Class Methods