bolt 0.20.0 → 0.20.2

data/vendored/puppet/lib/puppet/parser/functions.rb

@@ -0,0 +1,277 @@
+require 'puppet/util/autoload'
+require 'puppet/parser/scope'
+require 'puppet/pops/adaptable'
+
+# A module for managing parser functions.  Each specified function
+# is added to a central module that then gets included into the Scope
+# class.
+#
+# @api public
+module Puppet::Parser::Functions
+  Environment = Puppet::Node::Environment
+
+  class << self
+    include Puppet::Util
+  end
+
+  # Reset the list of loaded functions.
+  #
+  # @api private
+  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.to_s}.") do |vals|
+        send(level, vals.join(" "))
+      end
+    end
+  end
+
+  # Accessor for singleton autoloader
+  #
+  # @api private
+  def self.autoloader
+    @autoloader ||= Puppet::Util::Autoload.new(self, "puppet/parser/functions")
+  end
+
+  # An adapter that ties the anonymous module that acts as the container for all 3x functions to the environment
+  # where the functions are created. This adapter ensures that the life-cycle of those functions doesn't exceed
+  # the life-cycle of the environment.
+  #
+  # @api private
+  class AnonymousModuleAdapter < Puppet::Pops::Adaptable::Adapter
+    attr_accessor :module
+  end
+
+  # Get the module that functions are mixed into corresponding to an
+  # environment
+  #
+  # @api private
+  def self.environment_module(env)
+    AnonymousModuleAdapter.adapt(env) do |a|
+      a.module ||= 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.module
+  end
+
+  # 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](https://forge.puppetlabs.com/puppetlabs/stdlib) use this method to
+  # extend the behavior and functionality of Puppet.
+  #
+  # See also [Docs: Custom
+  # Functions](https://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](https://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
+  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
+          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
+
+  # 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
+  def self.function(name, environment = Puppet.lookup(:current_environment))
+    name = name.intern
+
+    unless func = get_function(name, environment)
+      autoloader.load(name, environment)
+      func = get_function(name, environment)
+    end
+
+    if func
+      func[:name]
+    else
+      false
+    end
+  end
+
+  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
+
+  # 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
+  def self.rvalue?(name, environment = Puppet.lookup(:current_environment))
+    func = get_function(name, environment)
+    func ? func[:type] == :rvalue : false
+  end
+
+  # 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
+  def self.arity(name, environment = Puppet.lookup(:current_environment))
+    func = get_function(name, environment)
+    func ? func[:arity] : -1
+  end
+
+  class << self
+    private
+
+    def merged_functions(environment)
+      root = environment_module(Puppet.lookup(:root_environment))
+      env = environment_module(environment)
+
+      root.all_function_info.merge(env.all_function_info)
+    end
+
+    def get_function(name, environment)
+      environment_module(environment).get_function_info(name.intern) || environment_module(Puppet.lookup(:root_environment)).get_function_info(name.intern)
+    end
+  end
+
+  class Error
+    def self.is4x(name)
+      raise Puppet::ParseError, _("%{name}() can only be called using the 4.x function API. See Scope#call_function") % { name: name }
+    end
+  end
+end

data/vendored/puppet/lib/puppet/parser/functions/assert_type.rb

@@ -0,0 +1,60 @@
+Puppet::Parser::Functions::newfunction(
+  :assert_type,
+  :type => :rvalue,
+  :arity => -3,
+  :doc => <<DOC
+Returns the given value if it is of the given
+[data type](https://docs.puppetlabs.com/puppet/latest/reference/lang_data.html), or
+otherwise either raises an error or executes an optional two-parameter
+[lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html).
+
+The function takes two mandatory arguments, in this order:
+
+1. The expected data type.
+2. A value to compare against the expected data type.
+
+**Example**: Using `assert_type`
+
+~~~ puppet
+$raw_username = 'Amy Berry'
+
+# Assert that $raw_username is a non-empty string and assign it to $valid_username.
+$valid_username = assert_type(String[1], $raw_username)
+
+# $valid_username contains "Amy Berry".
+# If $raw_username was an empty string or a different data type, the Puppet run would
+# fail with an "Expected type does not match actual" error.
+~~~
+
+You can use an optional lambda to provide enhanced feedback. The lambda takes two
+mandatory parameters, in this order:
+
+1. The expected data type as described in the function's first argument.
+2. The actual data type of the value.
+
+**Example**: Using `assert_type` with a warning and default value
+
+~~~ puppet
+$raw_username = 'Amy Berry'
+
+# Assert that $raw_username is a non-empty string and assign it to $valid_username.
+# If it isn't, output a warning describing the problem and use a default value.
+$valid_username = assert_type(String[1], $raw_username) |$expected, $actual| {
+  warning( "The username should be \'${expected}\', not \'${actual}\'. Using 'anonymous'." )
+  'anonymous'
+}
+
+# $valid_username contains "Amy Berry".
+# If $raw_username was an empty string, the Puppet run would set $valid_username to
+# "anonymous" and output a warning: "The username should be 'String[1, default]', not
+# 'String[0, 0]'. Using 'anonymous'."
+~~~
+
+For more information about data types, see the
+[documentation](https://docs.puppetlabs.com/puppet/latest/reference/lang_data.html).
+
+- Since 4.0.0
+DOC
+) do |args|
+  Puppet::Parser::Functions::Error.is4x('assert_type')
+end

data/vendored/puppet/lib/puppet/parser/functions/binary_file.rb

@@ -0,0 +1,24 @@
+Puppet::Parser::Functions::newfunction(
+  :binary_file,
+  :type => :rvalue,
+  :arity => 1,
+:doc => <<-DOC
+Loads a binary file from a module or file system and returns its contents as a Binary.
+
+The argument to this function should be a `<MODULE NAME>/<FILE>`
+reference, which will load `<FILE>` from a module's `files`
+directory. (For example, the reference `mysql/mysqltuner.pl` will load the
+file `<MODULES DIRECTORY>/mysql/files/mysqltuner.pl`.)
+
+This function also accepts an absolute file path that allows reading
+binary file content from anywhere on disk.
+
+An error is raised if the given file does not exists.
+
+To search for the existence of files, use the `find_file()` function.
+
+- since 4.8.0
+DOC
+) do |args|
+  Puppet::Parser::Functions::Error.is4x('binary_file')
+end

data/vendored/puppet/lib/puppet/parser/functions/break.rb

@@ -0,0 +1,39 @@
+Puppet::Parser::Functions::newfunction(
+  :break,
+  :arity => 0,
+  :doc => <<-DOC
+Breaks the innermost iteration as if it encountered an end of input.
+This function does not return to the caller.
+
+The signal produced to stop the iteration bubbles up through
+the call stack until either terminating the innermost iteration or
+raising an error if the end of the call stack is reached.
+
+The break() function does not accept an argument.
+
+**Example:** Using `break`
+
+```puppet
+$data = [1,2,3]
+notice $data.map |$x| { if $x == 3 { break() } $x*10 }
+```
+
+Would notice the value `[10, 20]`
+
+**Example:** Using a nested `break`
+
+```puppet
+function break_if_even($x) {
+  if $x % 2 == 0 { break() }
+}
+$data = [1,2,3]
+notice $data.map |$x| { break_if_even($x); $x*10 }
+```
+Would notice the value `[10]`
+
+* Also see functions `next` and `return`
+* Since 4.8.0
+DOC
+) do |args|
+  Puppet::Parser::Functions::Error.is4x('break')
+end

data/vendored/puppet/lib/puppet/parser/functions/contain.rb

@@ -0,0 +1,30 @@
+# Called within a class definition, establishes a containment
+# relationship with another class
+
+Puppet::Parser::Functions::newfunction(
+  :contain,
+  :arity => -2,
+  :doc => "Contain one or more classes inside the current class. If any of
+these classes are undeclared, they will be declared as if called with the
+`include` function. Accepts a class name, an array of class names, or a
+comma-separated list of class names.
+
+A contained class will not be applied before the containing class is
+begun, and will be finished before the containing class is finished.
+
+You must use the class's full name;
+relative names are not allowed. In addition to names in string form,
+you may also directly use Class and Resource Type values that are produced by
+evaluating resource and relationship expressions.
+
+The function returns an array of references to the classes that were contained thus
+allowing the function call to `contain` to directly continue.
+
+- Since 4.0.0 support for Class and Resource Type values, absolute names
+- Since 4.7.0 an Array[Type[Class[n]]] is returned with all the contained classes
+"
+) do |classes|
+  # Call the 4.x version of this function in case 3.x ruby code uses this function
+  Puppet.warn_once('deprecations', '3xfunction#contain', _("Calling function_contain via the Scope class is deprecated. Use Scope#call_function instead"))
+  call_function('contain', classes)
+end

data/vendored/puppet/lib/puppet/parser/functions/create_resources.rb

@@ -0,0 +1,112 @@
+Puppet::Parser::Functions::newfunction(:create_resources, :arity => -3, :doc => <<-'ENDHEREDOC') do |args|
+    Converts a hash into a set of resources and adds them to the catalog.
+
+    This function takes two mandatory arguments: a resource type, and a hash describing
+    a set of resources. The hash should be in the form `{title => {parameters} }`:
+
+        # A hash of user resources:
+        $myusers = {
+          'nick' => { uid    => '1330',
+                      gid    => allstaff,
+                      groups => ['developers', 'operations', 'release'], },
+          'dan'  => { uid    => '1308',
+                      gid    => allstaff,
+                      groups => ['developers', 'prosvc', 'release'], },
+        }
+
+        create_resources(user, $myusers)
+
+    A third, optional parameter may be given, also as a hash:
+
+        $defaults = {
+          'ensure'   => present,
+          'provider' => 'ldap',
+        }
+
+        create_resources(user, $myusers, $defaults)
+
+    The values given on the third argument are added to the parameters of each resource
+    present in the set given on the second argument. If a parameter is present on both
+    the second and third arguments, the one on the second argument takes precedence.
+
+    This function can be used to create defined resources and classes, as well
+    as native resources.
+
+    Virtual and Exported resources may be created by prefixing the type name
+    with @ or @@ respectively.  For example, the $myusers hash may be exported
+    in the following manner:
+
+        create_resources("@@user", $myusers)
+
+    The $myusers may be declared as virtual resources using:
+
+        create_resources("@user", $myusers)
+
+    Note that `create_resources` will filter out parameter values that are `undef` so that normal
+    data binding and puppet default value expressions are considered (in that order) for the
+    final value of a parameter (just as when setting a parameter to `undef` in a puppet language
+    resource declaration).
+  ENDHEREDOC
+  if Puppet[:tasks]
+    raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+      Puppet::Pops::Issues::CATALOG_OPERATION_NOT_SUPPORTED_WHEN_SCRIPTING,
+      {:operation => 'create_resources'})
+  end
+
+  raise ArgumentError, (_("create_resources(): wrong number of arguments (%{count}; must be 2 or 3)") % { count: args.length }) if args.length > 3
+  raise ArgumentError, (_('create_resources(): second argument must be a hash')) unless args[1].is_a?(Hash)
+  if args.length == 3
+    raise ArgumentError, (_('create_resources(): third argument, if provided, must be a hash')) unless args[2].is_a?(Hash)
+  end
+
+  type, instances, defaults = args
+  defaults ||= {}
+  type_name = type.sub(/^@{1,2}/, '').downcase
+
+  # Get file/line information from the puppet stack (where call comes from in puppet source)
+  # If relayed via other puppet functions in ruby that do not nest their calls, the source position
+  # will be in the original puppet source.
+  #
+  stacktrace = Puppet::Pops::PuppetStack.stacktrace()
+  if stacktrace.size > 0
+    file, line = stacktrace[0]
+  else
+    file = nil
+    line = nil
+  end
+
+  if type.start_with? '@@'
+    exported = true
+    virtual = true
+  elsif type.start_with? '@'
+    virtual = true
+  end
+
+  if type_name == 'class' && (exported || virtual)
+    # cannot find current evaluator, so use another
+    evaluator = Puppet::Pops::Parser::EvaluatingParser.new.evaluator
+    # optionally fails depending on configured severity of issue
+    evaluator.runtime_issue(Puppet::Pops::Issues::CLASS_NOT_VIRTUALIZABLE)
+  end
+
+  instances.map do |title, params|
+    # Add support for iteration if title is an array
+    resource_titles = title.is_a?(Array) ? title  : [title]
+    Puppet::Pops::Evaluator::Runtime3ResourceSupport.create_resources(
+      file, line,
+      self,
+      virtual, exported,
+      type_name,
+      resource_titles,
+      defaults.merge(params).map do |name, value|
+        value = nil if value == :undef
+        Puppet::Parser::Resource::Param.new(
+          :name   => name,
+          :value  => value, # wide open to various data types, must be correct
+          :source => self.source, # TODO: support :line => line, :file => file,
+          :add    => false
+        )
+      end.compact
+      )
+  end.flatten.compact
+end