diff --git a/REFERENCE.md b/REFERENCE.md index 1bc69ce8f..09b065737 100644 --- a/REFERENCE.md +++ b/REFERENCE.md @@ -41,7 +41,7 @@ string, or key from a hash. from an array or key from a hash. * [`delete_undef_values`](#delete_undef_values): Returns a copy of input hash or array with all undefs deleted. * [`delete_values`](#delete_values): Deletes all instances of a given value from a hash. -* [`deprecation`](#deprecation): Function to print deprecation warnings, Logs a warning once for a given key. The uniqueness key - can appear once. The msg is the message te +* [`deprecation`](#deprecation): Function to print deprecation warnings, Logs a warning once for a given key. * [`deprecation`](#deprecation): Function to print deprecation warnings (this is the 3.X version of it). * [`difference`](#difference): This function returns the difference between two arrays. * [`dirname`](#dirname): Returns the dirname of a path. @@ -54,8 +54,7 @@ resource. resource. * [`fact`](#fact): Digs into the facts hash using dot-notation * [`fqdn_rand_string`](#fqdn_rand_string): DEPRECATED. Use the namespaced function [`stdlib::fqdn_rand_string`](#stdlibfqdn_rand_string) instead. -* [`fqdn_rotate`](#fqdn_rotate): Rotates an array or string a random number of times, combining the `$fqdn` fact -and an optional seed for repeatable randomness. +* [`fqdn_rotate`](#fqdn_rotate): DEPRECATED. Use the namespaced function [`stdlib::fqdn_rotate`](#stdlibfqdn_rotate) instead. * [`fqdn_uuid`](#fqdn_uuid): Returns a [RFC 4122](https://tools.ietf.org/html/rfc4122) valid version 5 UUID based on an FQDN string under the DNS namespace * [`get_module_path`](#get_module_path): Returns the absolute path of the specified module for the current @@ -64,8 +63,8 @@ environment. * [`glob`](#glob): Uses same patterns as Dir#glob. * [`grep`](#grep): This function searches through an array and returns any elements that match the provided regular expression. -* [`has_interface_with`](#has_interface_with): Returns boolean based on kind and value. * [`has_interface_with`](#has_interface_with): DEPRECATED. Use the namespaced function [`stdlib::has_interface_with`](#stdlibhas_interface_with) instead. +* [`has_interface_with`](#has_interface_with): Returns boolean based on kind and value. * [`has_ip_address`](#has_ip_address): Returns true if the client has the requested IP address on some interface. * [`has_ip_network`](#has_ip_network): Returns true if the client has an IP address within the requested network. * [`intersection`](#intersection): This function returns an array of the intersection of two. @@ -79,9 +78,8 @@ in the corresponding native data type. * [`loadyaml`](#loadyaml): Load a YAML file containing an array, string, or hash, and return the data in the corresponding native data type. * [`member`](#member): This function determines if a variable is a member of an array. -* [`merge`](#merge): Merges two or more hashes together and returns the resulting hash. * [`merge`](#merge): DEPRECATED. Use the namespaced function [`stdlib::merge`](#stdlibmerge) instead. -* [`nested_values`](#nested_values): This function will return list of Hash values, the return value will be Array NOTE : This function is expecting only Hash and return value wi +* [`merge`](#merge): Merges two or more hashes together and returns the resulting hash. * [`num2bool`](#num2bool): This function converts a number or a string representation of a number into a true boolean. * [`os_version_gte`](#os_version_gte): DEPRECATED. Use the namespaced function [`stdlib::os_version_gte`](#stdlibos_version_gte) instead. @@ -126,10 +124,14 @@ the provided regular expression. last Period). * [`stdlib::fqdn_rand_string`](#stdlib--fqdn_rand_string): Generates a random alphanumeric string. Combining the `$fqdn` fact and an optional seed for repeatable randomness. +* [`stdlib::fqdn_rotate`](#stdlib--fqdn_rotate): Rotates an array or string a random number of times, combining the `fqdn` fact and an optional seed for repeatable randomness. +* [`stdlib::has_function`](#stdlib--has_function): Returns whether the Puppet runtime has access to a given function. * [`stdlib::has_interface_with`](#stdlib--has_interface_with): Returns boolean based on network interfaces present and their attribute values. * [`stdlib::ip_in_range`](#stdlib--ip_in_range): Returns true if the ipaddress is within the given CIDRs * [`stdlib::merge`](#stdlib--merge): Merges two or more hashes together or hashes resulting from iteration, and returns the resulting hash. +* [`stdlib::nested_values`](#stdlib--nested_values): Get list of nested values from given hash +This function will return list of nested Hash values and returns list of values in form of Array * [`stdlib::os_version_gte`](#stdlib--os_version_gte): Checks if the OS version is at least a certain version. * [`stdlib::parsehocon`](#stdlib--parsehocon): This function accepts HOCON as a string and converts it into the correct Puppet structure @@ -1452,37 +1454,31 @@ Type: Ruby 4.x API Function to print deprecation warnings, Logs a warning once for a given key. -The uniqueness key - can appear once. -The msg is the message text including any positional information that is formatted by the -user/caller of the method. -It is affected by the puppet setting 'strict', which can be set to :error -(outputs as an error message), :off (no message / error is displayed) and :warning -(default, outputs a warning) *Type*: String, String. - -#### `deprecation(String $key, String $message)` - -Function to print deprecation warnings, Logs a warning once for a given key. +#### `deprecation(String $key, String $message, Optional[Boolean] $use_strict_setting)` -The uniqueness key - can appear once. -The msg is the message text including any positional information that is formatted by the -user/caller of the method. -It is affected by the puppet setting 'strict', which can be set to :error -(outputs as an error message), :off (no message / error is displayed) and :warning -(default, outputs a warning) *Type*: String, String. +The deprecation function. -Returns: `Any` deprecated warnings +Returns: `Any` ##### `key` Data type: `String` - +The uniqueness key. This function logs once for any given key. ##### `message` Data type: `String` +Is the message text including any positional information that is formatted by the user/caller of the function. + +##### `use_strict_setting` +Data type: `Optional[Boolean]` + +When `true`, (the default), the function is affected by the puppet setting 'strict', which can be set to :error +(outputs as an error message), :off (no message / error is displayed) and :warning +(default, outputs a warning). ### `deprecation` @@ -1800,36 +1796,21 @@ Data type: `Any` ### `fqdn_rotate` -Type: Ruby 3.x API - -Rotates an array or string a random number of times, combining the `$fqdn` fact -and an optional seed for repeatable randomness. - -#### Examples - -##### Example Usage: +Type: Ruby 4.x API -```puppet -fqdn_rotate(['a', 'b', 'c', 'd']) -fqdn_rotate('abcd') -fqdn_rotate([1, 2, 3], 'custom seed') -``` +DEPRECATED. Use the namespaced function [`stdlib::fqdn_rotate`](#stdlibfqdn_rotate) instead. -#### `fqdn_rotate()` +#### `fqdn_rotate(Any *$args)` The fqdn_rotate function. -Returns: `Any` rotated array or string +Returns: `Any` -##### Examples +##### `*args` + +Data type: `Any` -###### Example Usage: -```puppet -fqdn_rotate(['a', 'b', 'c', 'd']) -fqdn_rotate('abcd') -fqdn_rotate([1, 2, 3], 'custom seed') -``` ### `fqdn_uuid` @@ -2043,6 +2024,24 @@ Returns: `Any` array of elements that match the provided regular expression. grep(['aaa','bbb','ccc','aaaddd'], 'aaa') # Returns ['aaa','aaaddd'] ``` +### `has_interface_with` + +Type: Ruby 4.x API + +DEPRECATED. Use the namespaced function [`stdlib::has_interface_with`](#stdlibhas_interface_with) instead. + +#### `has_interface_with(Any *$args)` + +The has_interface_with function. + +Returns: `Any` + +##### `*args` + +Data type: `Any` + + + ### `has_interface_with` Type: Ruby 3.x API @@ -2085,24 +2084,6 @@ has_interface_with("ipaddress", "127.0.0.1") # Returns `true` has_interface_with("lo") # Returns `true` ``` -### `has_interface_with` - -Type: Ruby 4.x API - -DEPRECATED. Use the namespaced function [`stdlib::has_interface_with`](#stdlibhas_interface_with) instead. - -#### `has_interface_with(Any *$args)` - -The has_interface_with function. - -Returns: `Any` - -##### `*args` - -Data type: `Any` - - - ### `has_ip_address` Type: Ruby 3.x API @@ -2445,49 +2426,11 @@ member(['a', 'b', 'c'], ['d', 'b']) # Returns: false ### `merge` -Type: Ruby 3.x API - -When there is a duplicate key, the key in the rightmost hash will "win." - -Note that since Puppet 4.0.0 the same merge can be achieved with the + operator. - `$merged_hash = $hash1 + $h - -#### Examples - -##### **Usage** - -```puppet -$hash1 = {'one' => 1, 'two', => 2} -$hash2 = {'two' => 'dos', 'three', => 'tres'} -$merged_hash = merge($hash1, $hash2) # $merged_hash = {'one' => 1, 'two' => 'dos', 'three' => 'tres'} -``` - -#### `merge()` - -When there is a duplicate key, the key in the rightmost hash will "win." - -Note that since Puppet 4.0.0 the same merge can be achieved with the + operator. - `$merged_hash = $hash1 + $h - -Returns: `Hash` The merged hash - -##### Examples - -###### **Usage** - -```puppet -$hash1 = {'one' => 1, 'two', => 2} -$hash2 = {'two' => 'dos', 'three', => 'tres'} -$merged_hash = merge($hash1, $hash2) # $merged_hash = {'one' => 1, 'two' => 'dos', 'three' => 'tres'} -``` - -### `merge` - Type: Ruby 4.x API DEPRECATED. Use the namespaced function [`stdlib::merge`](#stdlibmerge) instead. -#### `merge(Any *$args)` +#### `merge(Any *$args, Optional[Variant[Callable[2,2], Callable[3,3]]] &$block)` The merge function. @@ -2499,58 +2442,50 @@ Data type: `Any` -### `nested_values` +##### `&block` -Type: Ruby 4.x API +Data type: `Optional[Variant[Callable[2,2], Callable[3,3]]]` -This function will return list of Hash values, the return value will be Array -NOTE : This function is expecting only Hash and return value will be Array -$hash = { - "key1" => "value1", - "key2" => { "key2.1" => "value2.1"} -} -$hash.nested_values -Output : ["value1", "value2.1"] +### `merge` + +Type: Ruby 3.x API + +When there is a duplicate key, the key in the rightmost hash will "win." + +Note that since Puppet 4.0.0 the same merge can be achieved with the + operator. + `$merged_hash = $hash1 + $h #### Examples -##### : +##### **Usage** ```puppet - +$hash1 = {'one' => 1, 'two', => 2} +$hash2 = {'two' => 'dos', 'three', => 'tres'} +$merged_hash = merge($hash1, $hash2) # $merged_hash = {'one' => 1, 'two' => 'dos', 'three' => 'tres'} ``` -#### `nested_values(Hash $options)` - -This function will return list of Hash values, the return value will be Array -NOTE : This function is expecting only Hash and return value will be Array +#### `merge()` -$hash = { - "key1" => "value1", - "key2" => { "key2.1" => "value2.1"} -} -$hash.nested_values +When there is a duplicate key, the key in the rightmost hash will "win." -Output : ["value1", "value2.1"] +Note that since Puppet 4.0.0 the same merge can be achieved with the + operator. + `$merged_hash = $hash1 + $h -Returns: `Array` +Returns: `Hash` The merged hash ##### Examples -###### : +###### **Usage** ```puppet - +$hash1 = {'one' => 1, 'two', => 2} +$hash2 = {'two' => 'dos', 'three', => 'tres'} +$merged_hash = merge($hash1, $hash2) # $merged_hash = {'one' => 1, 'two' => 'dos', 'three' => 'tres'} ``` -##### `options` - -Data type: `Hash` - - - ### `num2bool` Type: Ruby 3.x API @@ -3427,10 +3362,10 @@ Optionally, you can specify a character set for the function (defaults to alphan ```puppet stdlib::fqdn_rand_string(10) stdlib::fqdn_rand_string(10, 'ABCDEF!@$%^') -stdlib::fqdn_rand_string(10, '', 'custom seed') +stdlib::fqdn_rand_string(10, undef, 'custom seed') ``` -#### `stdlib::fqdn_rand_string(Integer[1] $length, Optional[String] $charset, Optional[Any] *$seed)` +#### `stdlib::fqdn_rand_string(Integer[1] $length, Optional[Optional[String]] $charset, Optional[Any] *$seed)` Optionally, you can specify a character set for the function (defaults to alphanumeric). @@ -3443,7 +3378,7 @@ Returns: `String` ```puppet stdlib::fqdn_rand_string(10) stdlib::fqdn_rand_string(10, 'ABCDEF!@$%^') -stdlib::fqdn_rand_string(10, '', 'custom seed') +stdlib::fqdn_rand_string(10, undef, 'custom seed') ``` ##### `length` @@ -3454,7 +3389,7 @@ The length of the resulting string. ##### `charset` -Data type: `Optional[String]` +Data type: `Optional[Optional[String]]` The character set to use. @@ -3464,6 +3399,114 @@ Data type: `Optional[Any]` The seed for repeatable randomness. +### `stdlib::fqdn_rotate` + +Type: Ruby 4.x API + +Rotates an array or string a random number of times, combining the `fqdn` fact and an optional seed for repeatable randomness. + +#### `stdlib::fqdn_rotate(String $input, Optional[Variant[Integer,String]] *$seeds)` + +The stdlib::fqdn_rotate function. + +Returns: `String` Returns the rotated String + +##### Examples + +###### Rotating a String + +```puppet +stdlib::fqdn_rotate('abcd') +``` + +###### Using a custom seed + +```puppet +stdlib::fqdn_rotate('abcd', 'custom seed') +``` + +##### `input` + +Data type: `String` + +The String you want rotated a random number of times + +##### `*seeds` + +Data type: `Optional[Variant[Integer,String]]` + +One of more values to use as a custom seed. These will be combined with the host's FQDN + +#### `stdlib::fqdn_rotate(Array $input, Optional[Variant[Integer,String]] *$seeds)` + +The stdlib::fqdn_rotate function. + +Returns: `Array` Returns the rotated Array + +##### Examples + +###### Rotating an Array + +```puppet +stdlib::fqdn_rotate(['a', 'b', 'c', 'd']) +``` + +###### Using custom seeds + +```puppet +stdlib::fqdn_rotate([1, 2, 3], 'custom', 'seed', 1) +``` + +##### `input` + +Data type: `Array` + +The Array you want rotated a random number of times + +##### `*seeds` + +Data type: `Optional[Variant[Integer,String]]` + +One of more values to use as a custom seed. These will be combined with the host's FQDN + +### `stdlib::has_function` + +Type: Ruby 4.x API + +Determines whether the Puppet runtime has access to a function by the +name provided. + +#### Examples + +##### Using stdlib::has_function() + +```puppet +stdlib::has_function('stdlib::has_function') # true +stdlib::has_function('not_a_function') # false +``` + +#### `stdlib::has_function(String[1] $function_name)` + +Determines whether the Puppet runtime has access to a function by the +name provided. + +Returns: `Boolean` + +##### Examples + +###### Using stdlib::has_function() + +```puppet +stdlib::has_function('stdlib::has_function') # true +stdlib::has_function('not_a_function') # false +``` + +##### `function_name` + +Data type: `String[1]` + + + ### `stdlib::has_interface_with` Type: Ruby 4.x API @@ -3656,6 +3699,53 @@ Data type: `Callable[2,2]` A block placed on the repeatable param `args` +### `stdlib::nested_values` + +Type: Ruby 4.x API + +Get list of nested values from given hash +This function will return list of nested Hash values and returns list of values in form of Array + +#### Examples + +##### Example Usage: + +```puppet +$hash = { + "key1" => "value1", + "key2" => { "key2.1" => "value2.1"}, + "key3" => "value3" +} +$data = $hash.stdlib::nested_values +#Output : ["value1", "value2.1", "value3"] +``` + +#### `stdlib::nested_values(Hash $hash)` + +The stdlib::nested_values function. + +Returns: `Array` All the values found in the input hash included those deeply nested. + +##### Examples + +###### Example Usage: + +```puppet +$hash = { + "key1" => "value1", + "key2" => { "key2.1" => "value2.1"}, + "key3" => "value3" +} +$data = $hash.stdlib::nested_values +#Output : ["value1", "value2.1", "value3"] +``` + +##### `hash` + +Data type: `Hash` + +A (nested) hash + ### `stdlib::os_version_gte` Type: Ruby 4.x API @@ -5553,6 +5643,8 @@ Alias of `Integer[100, 599]` Validate a HTTP status code +* **DEPRECATED** Use Stdlib::Http::Status + * **See also** * Stdlib::Http::Status diff --git a/lib/puppet/functions/fqdn_rotate.rb b/lib/puppet/functions/fqdn_rotate.rb new file mode 100644 index 000000000..2f067fe43 --- /dev/null +++ b/lib/puppet/functions/fqdn_rotate.rb @@ -0,0 +1,14 @@ +# frozen_string_literal: true + +# THIS FILE WAS GENERATED BY `rake regenerate_unamespaced_shims` + +# @summary DEPRECATED. Use the namespaced function [`stdlib::fqdn_rotate`](#stdlibfqdn_rotate) instead. +Puppet::Functions.create_function(:fqdn_rotate) do + dispatch :deprecation_gen do + repeated_param 'Any', :args + end + def deprecation_gen(*args) + call_function('deprecation', 'fqdn_rotate', 'This function is deprecated, please use stdlib::fqdn_rotate instead.', false) + call_function('stdlib::fqdn_rotate', *args) + end +end diff --git a/lib/puppet/functions/stdlib/fqdn_rotate.rb b/lib/puppet/functions/stdlib/fqdn_rotate.rb new file mode 100644 index 000000000..5d7121b28 --- /dev/null +++ b/lib/puppet/functions/stdlib/fqdn_rotate.rb @@ -0,0 +1,66 @@ +# frozen_string_literal: true + +# @summary Rotates an array or string a random number of times, combining the `fqdn` fact and an optional seed for repeatable randomness. +Puppet::Functions.create_function(:'stdlib::fqdn_rotate') do + # @param input + # The String you want rotated a random number of times + # @param seeds + # One of more values to use as a custom seed. These will be combined with the host's FQDN + # + # @return [String] Returns the rotated String + # + # @example Rotating a String + # stdlib::fqdn_rotate('abcd') + # @example Using a custom seed + # stdlib::fqdn_rotate('abcd', 'custom seed') + dispatch :fqdn_rotate_string do + param 'String', :input + optional_repeated_param 'Variant[Integer,String]', :seeds + return_type 'String' + end + + # @param input + # The Array you want rotated a random number of times + # @param seeds + # One of more values to use as a custom seed. These will be combined with the host's FQDN + # + # @return [String] Returns the rotated Array + # + # @example Rotating an Array + # stdlib::fqdn_rotate(['a', 'b', 'c', 'd']) + # @example Using custom seeds + # stdlib::fqdn_rotate([1, 2, 3], 'custom', 'seed', 1) + dispatch :fqdn_rotate_array do + param 'Array', :input + optional_repeated_param 'Variant[Integer,String]', :seeds + return_type 'Array' + end + + def fqdn_rotate_array(input, *seeds) + # Check whether it makes sense to rotate ... + return input if input.size <= 1 + + result = input.clone + + require 'digest/md5' + seed = Digest::MD5.hexdigest([fqdn_fact, seeds].join(':')).hex + + offset = Puppet::Util.deterministic_rand(seed, result.size).to_i + + offset.times do + result.push result.shift + end + + result + end + + def fqdn_rotate_string(input, *seeds) + fqdn_rotate_array(input.chars, seeds).join + end + + private + + def fqdn_fact + closure_scope['facts']['networking']['fqdn'] + end +end diff --git a/lib/puppet/parser/functions/fqdn_rotate.rb b/lib/puppet/parser/functions/fqdn_rotate.rb deleted file mode 100644 index 1437caa38..000000000 --- a/lib/puppet/parser/functions/fqdn_rotate.rb +++ /dev/null @@ -1,59 +0,0 @@ -# frozen_string_literal: true - -# -# fqdn_rotate.rb -# -Puppet::Parser::Functions.newfunction(:fqdn_rotate, type: :rvalue, doc: <<-DOC - @summary - Rotates an array or string a random number of times, combining the `$fqdn` fact - and an optional seed for repeatable randomness. - - @return - rotated array or string - - @example Example Usage: - fqdn_rotate(['a', 'b', 'c', 'd']) - fqdn_rotate('abcd') - fqdn_rotate([1, 2, 3], 'custom seed') -DOC -) do |args| - raise(Puppet::ParseError, "fqdn_rotate(): Wrong number of arguments given (#{args.size} for 1)") if args.empty? - - value = args.shift - require 'digest/md5' - - raise(Puppet::ParseError, 'fqdn_rotate(): Requires either array or string to work with') unless value.is_a?(Array) || value.is_a?(String) - - result = value.clone - - string = value.is_a?(String) - - # Check whether it makes sense to rotate ... - return result if result.size <= 1 - - # We turn any string value into an array to be able to rotate ... - result = string ? result.chars : result - - elements = result.size - - seed = Digest::MD5.hexdigest([lookupvar('facts'), args].join(':')).hex - # deterministic_rand() was added in Puppet 3.2.0; reimplement if necessary - if Puppet::Util.respond_to?(:deterministic_rand) - offset = Puppet::Util.deterministic_rand(seed, elements).to_i - else - return offset = Random.new(seed).rand(elements) if defined?(Random) == 'constant' && Random.instance_of?(Class) - - old_seed = srand(seed) - offset = rand(elements) - srand(old_seed) - end - offset.times do - result.push result.shift - end - - result = string ? result.join : result - - return result -end - -# vim: set ts=2 sw=2 et : diff --git a/spec/functions/fqdn_rotate_spec.rb b/spec/functions/fqdn_rotate_spec.rb index ea0e2ddd5..7906c42c2 100644 --- a/spec/functions/fqdn_rotate_spec.rb +++ b/spec/functions/fqdn_rotate_spec.rb @@ -4,9 +4,9 @@ describe 'fqdn_rotate' do it { is_expected.not_to be_nil } - it { is_expected.to run.with_params.and_raise_error(Puppet::ParseError, %r{wrong number of arguments}i) } - it { is_expected.to run.with_params(0).and_raise_error(Puppet::ParseError, %r{Requires either array or string to work with}) } - it { is_expected.to run.with_params({}).and_raise_error(Puppet::ParseError, %r{Requires either array or string to work with}) } + it { is_expected.to run.with_params.and_raise_error(ArgumentError, %r{expects at least 1 argument, got none}) } + it { is_expected.to run.with_params(0).and_raise_error(ArgumentError, %r{parameter 'input' expects a value of type String or Array, got Integer}) } + it { is_expected.to run.with_params({}).and_raise_error(ArgumentError, %r{parameter 'input' expects a value of type String or Array, got Hash}) } it { is_expected.to run.with_params('').and_return('') } it { is_expected.to run.with_params('a').and_return('a') } it { is_expected.to run.with_params('ã').and_return('ã') } @@ -48,8 +48,6 @@ end it 'uses the Puppet::Util.deterministic_rand function' do - skip 'Puppet::Util#deterministic_rand not available' unless Puppet::Util.respond_to?(:deterministic_rand) - expect(Puppet::Util).to receive(:deterministic_rand).with(44_489_829_212_339_698_569_024_999_901_561_968_770, 4) fqdn_rotate('asdf') end @@ -68,9 +66,9 @@ def fqdn_rotate(value, args = {}) # workaround not being able to use let(:facts) because some tests need # multiple different hostnames in one context - allow(scope).to receive(:lookupvar).with('facts').and_return(host) + allow(subject.func.closure_scope).to receive(:[]).with('facts').and_return({ 'networking' => { 'fqdn' => host } }) function_args = [value] + extra - scope.function_fqdn_rotate(function_args) + scope.call_function('fqdn_rotate', function_args) end end