Module: Puppet::Parser::Functions

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

Overview

Copyright (C) 2009 Thomas Bellman

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THOMAS BELLMAN BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Except as contained in this notice, the name of Thomas Bellman shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from Thomas Bellman.

Defined Under Namespace

Classes: AnonymousModuleAdapter, AutoloaderDelegate, Error

Constant Summary collapse

Environment =
Puppet::Node::Environment

Constants included from Util

Util::AbsolutePathPosix, Util::AbsolutePathWindows, Util::DEFAULT_POSIX_MODE, Util::DEFAULT_WINDOWS_MODE, Util::RFC_3986_URI_REGEX

Constants included from Util::SymbolicFileMode

Util::SymbolicFileMode::SetGIDBit, Util::SymbolicFileMode::SetUIDBit, Util::SymbolicFileMode::StickyBit, Util::SymbolicFileMode::SymbolicMode, Util::SymbolicFileMode::SymbolicSpecialToBit

Constants included from Util::POSIX

Util::POSIX::LOCALE_ENV_VARS, Util::POSIX::USER_ENV_VARS

Class Method Summary collapse

Methods included from Util

absolute_path?, benchmark, chuser, clear_environment, default_env, deterministic_rand, deterministic_rand_int, exit_on_fail, get_env, get_environment, logmethods, merge_environment, path_to_uri, pretty_backtrace, replace_file, safe_posix_fork, set_env, symbolizehash, thinmark, uri_encode, uri_query_encode, uri_to_path, which, withenv, withumask

Methods included from Util::SymbolicFileMode

#normalize_symbolic_mode, #symbolic_mode_to_int, #valid_symbolic_mode?

Methods included from Util::POSIX

#get_posix_field, #gid, groups_of, #idfield, #methodbyid, #methodbyname, #search_posix_field, #uid

Class Method Details

.arity(name, environment = Puppet.lookup(:current_environment)) ⇒ Integer

Return the number of arguments a function expects.


287
288
289
290
# File 'lib/puppet/parser/functions.rb', line 287

def self.arity(name, environment = Puppet.lookup(:current_environment))
  func = get_function(name, environment)
  func ? func[:arity] : -1
end

.autoloaderObject

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


68
69
70
# File 'lib/puppet/parser/functions.rb', line 68

def self.autoloader
  @autoloader ||= AutoloaderDelegate.new
end

.environment_module(env) ⇒ Object

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


85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
# File 'lib/puppet/parser/functions.rb', line 85

def self.environment_module(env)
  AnonymousModuleAdapter.adapt(env) do |a|
    a.module ||= Module.new do
       = {}

      def self.all_function_info
        
      end

      def self.get_function_info(name)
        [name]
      end

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

.function(name, environment = Puppet.lookup(:current_environment)) ⇒ Symbol, false

Determine if a function is defined


232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
# File 'lib/puppet/parser/functions.rb', line 232

def self.function(name, environment = Puppet.lookup(:current_environment))
  name = name.intern

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

  if func
    func[:name]
  else
    false
  end
end

.functiondocs(environment = Puppet.lookup(:current_environment)) ⇒ Object


248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
# File 'lib/puppet/parser/functions.rb', line 248

def self.functiondocs(environment = Puppet.lookup(:current_environment))
  autoloader.delegatee.loadall(environment)

  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

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

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


177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
# File 'lib/puppet/parser/functions.rb', line 177

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(self.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

.resetObject

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
31
# File 'lib/puppet/parser/functions.rb', line 20

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

.rvalue?(name, environment = Puppet.lookup(:current_environment)) ⇒ Boolean

Determine whether a given function returns a value.


274
275
276
277
# File 'lib/puppet/parser/functions.rb', line 274

def self.rvalue?(name, environment = Puppet.lookup(:current_environment))
  func = get_function(name, environment)
  func ? func[:type] == :rvalue : false
end