Squashed 'lib/puppet/stdlib/' content from commit bcb169b1

git-subtree-dir: lib/puppet/stdlib
git-subtree-split: bcb169b1047cbcd18d2d8a04c7081df6a3a08ba8

lib/puppet/functions/is_a.rb

+# Boolean check to determine whether a variable is of a given data type. This is equivalent to the `=~` type checks.
+#
+# @example how to check a data type
+#   # check a data type
+#       foo = 3
+#       $bar = [1,2,3]
+#       $baz = 'A string!'
+#
+#       if $foo.is_a(Integer) {
+#         notify  { 'foo!': }
+#       }
+#       if $bar.is_a(Array) {
+#         notify { 'bar!': }
+#       }
+#       if $baz.is_a(String) {
+#         notify { 'baz!': }
+#       }
+#
+# See the documentation for "The Puppet Type System" for more information about types.
+# See the `assert_type()` function for flexible ways to assert the type of a value.
+#
+Puppet::Functions.create_function(:is_a) do
+  dispatch :is_a do
+    param 'Any', :value
+    param 'Type', :type
+  end
+
+  def is_a(value, type) # rubocop:disable Style/PredicateName : Used in to many other places to rename at this time, attempting to refactor caused Rubocop to crash.
+    # See puppet's lib/puppet/pops/evaluator/evaluator_impl.rb eval_MatchExpression
+    Puppet::Pops::Types::TypeCalculator.instance?(type, value)
+  end
+end

lib/puppet/functions/is_absolute_path.rb

+Puppet::Functions.create_function(:is_absolute_path) do
+  dispatch :deprecation_gen do
+    param 'Any', :scope
+    repeated_param 'Any', :args
+  end
+  # Workaround PUP-4438 (fixed: https://github.com/puppetlabs/puppet/commit/e01c4dc924cd963ff6630008a5200fc6a2023b08#diff
+  #   -c937cc584953271bb3d3b3c2cb141790R221) to support puppet < 4.1.0 and puppet < 3.8.1.
+  def call(scope, *args)
+    manipulated_args = [scope] + args
+    self.class.dispatcher.dispatch(self, scope, manipulated_args)
+  end
+
+  def deprecation_gen(scope, *args)
+    call_function('deprecation', 'is_absolute_path', 'This method is deprecated, please use match expressions with Stdlib::Compat::Absolute_Path instead. They are described at https://docs.puppet.com/puppet/latest/reference/lang_data_type.html#match-expressions.')
+    scope.send('function_is_absolute_path', args)
+  end
+end

lib/puppet/functions/is_array.rb

+Puppet::Functions.create_function(:is_array) do
+  dispatch :deprecation_gen do
+    param 'Any', :scope
+    repeated_param 'Any', :args
+  end
+  # Workaround PUP-4438 (fixed: https://github.com/puppetlabs/puppet/commit/e01c4dc924cd963ff6630008a5200fc6a2023b08#diff
+  #   -c937cc584953271bb3d3b3c2cb141790R221) to support puppet < 4.1.0 and puppet < 3.8.1.
+  def call(scope, *args)
+    manipulated_args = [scope] + args
+    self.class.dispatcher.dispatch(self, scope, manipulated_args)
+  end
+
+  def deprecation_gen(scope, *args)
+    call_function('deprecation', 'is_array', 'This method is deprecated, please use match expressions with Stdlib::Compat::Array instead. They are described at https://docs.puppet.com/puppet/latest/reference/lang_data_type.html#match-expressions.')
+    scope.send('function_is_array', args)
+  end
+end

lib/puppet/functions/is_bool.rb

+Puppet::Functions.create_function(:is_bool) do
+  dispatch :deprecation_gen do
+    param 'Any', :scope
+    repeated_param 'Any', :args
+  end
+  # Workaround PUP-4438 (fixed: https://github.com/puppetlabs/puppet/commit/e01c4dc924cd963ff6630008a5200fc6a2023b08#diff
+  #   -c937cc584953271bb3d3b3c2cb141790R221) to support puppet < 4.1.0 and puppet < 3.8.1.
+  def call(scope, *args)
+    manipulated_args = [scope] + args
+    self.class.dispatcher.dispatch(self, scope, manipulated_args)
+  end
+
+  def deprecation_gen(scope, *args)
+    call_function('deprecation', 'is_bool', 'This method is deprecated, please use match expressions with Stdlib::Compat::Bool instead. They are described at https://docs.puppet.com/puppet/latest/reference/lang_data_type.html#match-expressions.')
+    scope.send('function_is_bool', args)
+  end
+end

lib/puppet/functions/is_float.rb

+Puppet::Functions.create_function(:is_float) do
+  dispatch :deprecation_gen do
+    param 'Any', :scope
+    repeated_param 'Any', :args
+  end
+  # Workaround PUP-4438 (fixed: https://github.com/puppetlabs/puppet/commit/e01c4dc924cd963ff6630008a5200fc6a2023b08#diff
+  #   -c937cc584953271bb3d3b3c2cb141790R221) to support puppet < 4.1.0 and puppet < 3.8.1.
+  def call(scope, *args)
+    manipulated_args = [scope] + args
+    self.class.dispatcher.dispatch(self, scope, manipulated_args)
+  end
+
+  def deprecation_gen(scope, *args)
+    call_function('deprecation', 'is_float', 'This method is deprecated, please use match expressions with Stdlib::Compat::Float instead. They are described at https://docs.puppet.com/puppet/latest/reference/lang_data_type.html#match-expressions.')
+    scope.send('function_is_float', args)
+  end
+end

lib/puppet/functions/is_ip_address.rb

+Puppet::Functions.create_function(:is_ip_address) do
+  dispatch :deprecation_gen do
+    param 'Any', :scope
+    repeated_param 'Any', :args
+  end
+  # Workaround PUP-4438 (fixed: https://github.com/puppetlabs/puppet/commit/e01c4dc924cd963ff6630008a5200fc6a2023b08#diff
+  #   -c937cc584953271bb3d3b3c2cb141790R221) to support puppet < 4.1.0 and puppet < 3.8.1.
+  def call(scope, *args)
+    manipulated_args = [scope] + args
+    self.class.dispatcher.dispatch(self, scope, manipulated_args)
+  end
+
+  def deprecation_gen(scope, *args)
+    call_function('deprecation', 'is_ip_address', 'This method is deprecated, please use match expressions with Stdlib::Compat::Ip_address instead. They are described at https://docs.puppet.com/puppet/latest/reference/lang_data_type.html#match-expressions.')
+    scope.send('function_is_ip_address', args)
+  end
+end

lib/puppet/functions/is_ipv4_address.rb

+Puppet::Functions.create_function(:is_ipv4_address) do
+  dispatch :deprecation_gen do
+    param 'Any', :scope
+    repeated_param 'Any', :args
+  end
+  # Workaround PUP-4438 (fixed: https://github.com/puppetlabs/puppet/commit/e01c4dc924cd963ff6630008a5200fc6a2023b08#diff
+  #   -c937cc584953271bb3d3b3c2cb141790R221) to support puppet < 4.1.0 and puppet < 3.8.1.
+  def call(scope, *args)
+    manipulated_args = [scope] + args
+    self.class.dispatcher.dispatch(self, scope, manipulated_args)
+  end
+
+  def deprecation_gen(scope, *args)
+    call_function('deprecation', 'is_ipv4_address', 'This method is deprecated, please use match expressions with Stdlib::Compat::Ipv4 instead. They are described at https://docs.puppet.com/puppet/latest/reference/lang_data_type.html#match-expressions.')
+    scope.send('function_is_ipv4_address', args)
+  end
+end

lib/puppet/functions/is_ipv6_address.rb

+Puppet::Functions.create_function(:is_ipv6_address) do
+  dispatch :deprecation_gen do
+    param 'Any', :scope
+    repeated_param 'Any', :args
+  end
+  # Workaround PUP-4438 (fixed: https://github.com/puppetlabs/puppet/commit/e01c4dc924cd963ff6630008a5200fc6a2023b08#diff
+  #   -c937cc584953271bb3d3b3c2cb141790R221) to support puppet < 4.1.0 and puppet < 3.8.1.
+  def call(scope, *args)
+    manipulated_args = [scope] + args
+    self.class.dispatcher.dispatch(self, scope, manipulated_args)
+  end
+
+  def deprecation_gen(scope, *args)
+    call_function('deprecation', 'is_ipv4_address', 'This method is deprecated, please use match expressions with Stdlib::Compat::Ipv6 instead. They are described at https://docs.puppet.com/puppet/latest/reference/lang_data_type.html#match-expressions.')
+    scope.send('function_is_ipv6_address', args)
+  end
+end

lib/puppet/functions/is_numeric.rb

+Puppet::Functions.create_function(:is_numeric) do
+  dispatch :deprecation_gen do
+    param 'Any', :scope
+    repeated_param 'Any', :args
+  end
+  # Workaround PUP-4438 (fixed: https://github.com/puppetlabs/puppet/commit/e01c4dc924cd963ff6630008a5200fc6a2023b08#diff
+  #   -c937cc584953271bb3d3b3c2cb141790R221) to support puppet < 4.1.0 and puppet < 3.8.1.
+  def call(scope, *args)
+    manipulated_args = [scope] + args
+    self.class.dispatcher.dispatch(self, scope, manipulated_args)
+  end
+
+  def deprecation_gen(scope, *args)
+    call_function('deprecation', 'is_numeric', 'This method is deprecated, please use match expressions with Stdlib::Compat::Numeric instead. They are described at https://docs.puppet.com/puppet/latest/reference/lang_data_type.html#match-expressions.')
+    scope.send('function_is_numeric', args)
+  end
+end

lib/puppet/functions/is_string.rb

+Puppet::Functions.create_function(:is_string) do
+  dispatch :deprecation_gen do
+    param 'Any', :scope
+    repeated_param 'Any', :args
+  end
+  # Workaround PUP-4438 (fixed: https://github.com/puppetlabs/puppet/commit/e01c4dc924cd963ff6630008a5200fc6a2023b08#diff
+  #   -c937cc584953271bb3d3b3c2cb141790R221) to support puppet < 4.1.0 and puppet < 3.8.1.
+  def call(scope, *args)
+    manipulated_args = [scope] + args
+    self.class.dispatcher.dispatch(self, scope, manipulated_args)
+  end
+
+  def deprecation_gen(scope, *args)
+    call_function('deprecation', 'is_string', 'This method is deprecated, please use match expressions with Stdlib::Compat::String instead. They are described at https://docs.puppet.com/puppet/latest/reference/lang_data_type.html#match-expressions.')
+    scope.send('function_is_string', args)
+  end
+end

lib/puppet/functions/length.rb

+# A function to eventually replace the old size() function for stdlib
+# The original size function did not handle Puppets new type capabilities, so this function is a Puppet 4 compatible solution.
+#
+# Note: from Puppet 6.0.0, the compatible function with the same name in Puppet core
+# will be used instead of this function.
+#
+Puppet::Functions.create_function(:length) do
+  dispatch :length do
+    param 'Variant[String,Array,Hash]', :value
+  end
+  def length(value)
+    if value.is_a?(String)
+      result = value.length
+    elsif value.is_a?(Array) || value.is_a?(Hash)
+      result = value.size
+    end
+    result
+  end
+end

lib/puppet/functions/os_version_gte.rb

+# Checks if the OS version is at least a certain version. Note that only the
+# major version is taken into account.
+#
+# Example usage:
+#
+#     if os_version_gte('Debian', '9') { }
+#     if os_version_gte('Ubuntu', '18.04') { }
+Puppet::Functions.create_function(:os_version_gte) do
+  dispatch :os_version_gte do
+    param 'String[1]', :os
+    param 'String[1]', :version
+    return_type 'Boolean'
+  end
+
+  def os_version_gte(os, version)
+    facts = closure_scope['facts']
+    (facts['operatingsystem'] == os &&
+     Puppet::Util::Package.versioncmp(version, facts['operatingsystemmajrelease']) >= 0)
+  end
+end

lib/puppet/functions/seeded_rand_string.rb

+# Generates a consistent random string of specific length based on provided seed.
+#
+# @example Generate a consistently random string of length 8 with a seed:
+#   seeded_rand_string(8, "${module_name}::redis_password")
+#
+# @example Generate a random string from a specific set of characters:
+#   seeded_rand_string(5, '', 'abcdef')
+Puppet::Functions.create_function(:seeded_rand_string) do
+  # @param length Length of string to be generated.
+  # @param seed Seed string.
+  # @param charset String that contains characters to use for the random string.
+  #
+  # @return [String] Random string.
+  dispatch :rand_string do
+    param 'Integer[1]', :length
+    param 'String', :seed
+    optional_param 'String[2]', :charset
+  end
+
+  def rand_string(length, seed, charset = nil)
+    require 'digest/sha2'
+
+    charset ||= '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
+
+    random_generator = Random.new(Digest::SHA256.hexdigest(seed).to_i(16))
+
+    Array.new(length) { charset[random_generator.rand(charset.size)] }.join
+  end
+end

lib/puppet/functions/sprintf_hash.rb

+# Uses sprintf with named references.
+#
+# The first parameter is format string describing how the rest of the parameters in the hash
+# should be formatted. See the documentation for the `Kernel::sprintf` function in Ruby for
+# all the details.
+#
+# In the given argument hash with parameters, all keys are converted to symbols so they work
+# with the `sprintf` function.
+#
+# @example Format a string and number
+#   $output = sprintf_hash('String: %<foo>s / number converted to binary: %<number>b',
+#                          { 'foo' => 'a string', 'number' => 5 })
+#   # $output = 'String: a string / number converted to binary: 101'
+#
+# Note that since Puppet 4.10.10, and 5.3.4 this functionality is supported by the
+# `sprintf` function in puppet core.
+#
+Puppet::Functions.create_function(:sprintf_hash) do
+  # @param format The format to use.
+  # @param arguments Hash with parameters.
+  # @return The formatted string.
+  dispatch :sprintf_hash do
+    param 'String', :format
+    param 'Hash', :arguments
+    # Disabled for now. This gives issues on puppet 4.7.1.
+    # return_type 'String'
+  end
+
+  def sprintf_hash(format, arguments)
+    call_function('deprecation', 'sprintf_hash', 'This method is deprecated. From Puppet 4.10.10/5.3.4 please use the built-in sprintf instead')
+
+    Kernel.sprintf(format, Hash[arguments.map { |(k, v)| [k.to_sym, v] }])
+  end
+end

lib/puppet/functions/stdlib/extname.rb

+# Returns the Extension (the Portion of Filename in Path starting from the
+# last Period).
+#
+# If Path is a Dotfile, or starts with a Period, then the starting Dot is not
+# dealt with the Start of the Extension.
+#
+# An empty String will also be returned, when the Period is the last Character
+# in Path.
+
+Puppet::Functions.create_function(:'stdlib::extname') do
+  # @param filename The Filename
+  # @return [String] The Extension starting from the last Period
+  # @example Determining the Extension of a Filename
+  #   stdlib::extname('test.rb')       => '.rb'
+  #   stdlib::extname('a/b/d/test.rb') => '.rb'
+  #   stdlib::extname('test')          => ''
+  #   stdlib::extname('.profile')      => ''
+  dispatch :extname do
+    param 'String', :filename
+    return_type 'String'
+  end
+
+  def extname(filename)
+    File.extname(filename)
+  end
+end

lib/puppet/functions/to_json.rb

+# Take a data structure and output it as JSON
+#
+# @example how to output JSON
+#   # output json to a file
+#     file { '/tmp/my.json':
+#       ensure  => file,
+#       content => to_json($myhash),
+#     }
+#
+#
+require 'json'
+
+Puppet::Functions.create_function(:to_json) do
+  dispatch :to_json do
+    param 'Any', :data
+  end
+
+  def to_json(data)
+    data.to_json
+  end
+end

lib/puppet/functions/to_json_pretty.rb

+# Take a data structure and output it as pretty JSON
+#
+# @example how to output pretty JSON
+#   # output pretty json to a file
+#     file { '/tmp/my.json':
+#       ensure  => file,
+#       content => to_json_pretty($myhash),
+#     }
+#
+# @example how to output pretty JSON skipping over keys with undef values
+#   # output pretty JSON to a file skipping over undef values
+#     file { '/tmp/my.json':
+#       ensure  => file,
+#       content => to_json_pretty({
+#         param_one => 'value',
+#         param_two => undef,
+#       }),
+#     }
+#
+require 'json'
+
+Puppet::Functions.create_function(:to_json_pretty) do
+  dispatch :to_json_pretty do
+    param 'Variant[Hash, Array]', :data
+    optional_param 'Boolean', :skip_undef
+  end
+
+  def to_json_pretty(data, skip_undef = false)
+    if skip_undef
+      if data.is_a? Array
+        data = data.reject { |value| value.nil? }
+      elsif data.is_a? Hash
+        data = data.reject { |_, value| value.nil? }
+      end
+    end
+    JSON.pretty_generate(data) << "\n"
+  end
+end

lib/puppet/functions/to_yaml.rb

+# Take a data structure and output it as YAML
+#
+# @example how to output YAML
+#   # output yaml to a file
+#     file { '/tmp/my.yaml':
+#       ensure  => file,
+#       content => to_yaml($myhash),
+#     }
+#
+#
+require 'yaml'
+
+Puppet::Functions.create_function(:to_yaml) do
+  dispatch :to_yaml do
+    param 'Any', :data
+  end
+
+  def to_yaml(data)
+    data.to_yaml
+  end
+end

lib/puppet/functions/type_of.rb

+# Returns the type when passed a value.
+#
+# @example how to compare values' types
+#   # compare the types of two values
+#   if type_of($first_value) != type_of($second_value) { fail("first_value and second_value are different types") }
+# @example how to compare against an abstract type
+#   unless type_of($first_value) <= Numeric { fail("first_value must be Numeric") }
+#   unless type_of{$first_value) <= Collection[1] { fail("first_value must be an Array or Hash, and contain at least one element") }
+#
+# See the documentation for "The Puppet Type System" for more information about types.
+# See the `assert_type()` function for flexible ways to assert the type of a value.
+#
+# The built-in type() function in puppet is generally preferred over this function
+# this function is provided for backwards compatibility.
+Puppet::Functions.create_function(:type_of) do
+  def type_of(value)
+    Puppet::Pops::Types::TypeCalculator.infer_set(value)
+  end
+end

lib/puppet/functions/validate_absolute_path.rb

+Puppet::Functions.create_function(:validate_absolute_path) do
+  dispatch :deprecation_gen do
+    param 'Any', :scope
+    repeated_param 'Any', :args
+  end
+  # Workaround PUP-4438 (fixed: https://github.com/puppetlabs/puppet/commit/e01c4dc924cd963ff6630008a5200fc6a2023b08#diff
+  #   -c937cc584953271bb3d3b3c2cb141790R221) to support puppet < 4.1.0 and puppet < 3.8.1.
+  def call(scope, *args)
+    manipulated_args = [scope] + args
+    self.class.dispatcher.dispatch(self, scope, manipulated_args)
+  end
+
+  def deprecation_gen(scope, *args)
+    call_function('deprecation', 'validate_absolute_path', 'This method is deprecated, please use the stdlib validate_legacy function,
+                    with Stdlib::Compat::Absolute_Path. There is further documentation for validate_legacy function in the README.')
+    scope.send('function_validate_absolute_path', args)
+  end
+end