puppet 8.3.1 → 8.4.0

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

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
+
 Puppet::Parser::Functions::newfunction(
-    :fail,
-    :arity => -1,
-    :doc   => <<DOC
-Fail with a parse error. Any parameters will be stringified,
-concatenated, and passed to the exception-handler.
-DOC
+  :fail,
+  :arity => -1,
+  :doc => <<~DOC
+    Fail with a parse error. Any parameters will be stringified,
+    concatenated, and passed to the exception-handler.
+  DOC
 ) do |vals|
-    vals = vals.collect { |s| s.to_s }.join(" ") if vals.is_a? Array
-    raise Puppet::ParseError, vals.to_s
+  vals = vals.collect { |s| s.to_s }.join(" ") if vals.is_a? Array
+  raise Puppet::ParseError, vals.to_s
 end

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

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
+
 require_relative '../../../puppet/file_system'
 
 Puppet::Parser::Functions::newfunction(
   :file, :arity => -2, :type => :rvalue,
-  :doc => "Loads a file from a module and returns its contents as a string.
+         :doc => "Loads a file from a module and returns its contents as a string.
 
   The argument to this function should be a `<MODULE NAME>/<FILE>`
   reference, which will load `<FILE>` from a module's `files`
@@ -17,18 +18,18 @@ Puppet::Parser::Functions::newfunction(
   found, skipping any files that don't exist.
   "
 ) do |vals|
-    path = nil
-    vals.each do |file|
-      found = Puppet::Parser::Files.find_file(file, compiler.environment)
-      if found && Puppet::FileSystem.exist?(found)
-        path = found
-        break
-      end
+  path = nil
+  vals.each do |file|
+    found = Puppet::Parser::Files.find_file(file, compiler.environment)
+    if found && Puppet::FileSystem.exist?(found)
+      path = found
+      break
     end
+  end
 
-    if path
-      Puppet::FileSystem.read_preserve_line_endings(path)
-    else
-      raise Puppet::ParseError, _("Could not find any files from %{values}") % { values: vals.join(", ") }
-    end
+  if path
+    Puppet::FileSystem.read_preserve_line_endings(path)
+  else
+    raise Puppet::ParseError, _("Could not find any files from %{values}") % { values: vals.join(", ") }
+  end
 end

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

@@ -1,80 +1,81 @@
 # frozen_string_literal: true
+
 Puppet::Parser::Functions::newfunction(
   :filter,
   :type => :rvalue,
   :arity => -3,
-  :doc => <<-DOC
-Applies a [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html)
-to every value in a data structure and returns an array or hash containing any elements
-for which the lambda evaluates to a truthy value (not `false` or `undef`).
-
-This function takes two mandatory arguments, in this order:
-
-1. An array or hash the function will iterate over.
-2. A lambda, which the function calls for each element in the first argument. It can
-request one or two parameters.
-
-**Example**: Using the `filter` function
-
-`$filtered_data = $data.filter |$parameter| { <PUPPET CODE BLOCK> }`
-
-or
-
-`$filtered_data = filter($data) |$parameter| { <PUPPET CODE BLOCK> }`
-
-When the first argument (`$data` in the above example) is an array, Puppet passes each
-value in turn to the lambda and returns an array containing the results.
-
-**Example**: Using the `filter` function with an array and a one-parameter lambda
-
-~~~ puppet
-# For the array $data, return an array containing the values that end with "berry"
-$data = ["orange", "blueberry", "raspberry"]
-$filtered_data = $data.filter |$items| { $items =~ /berry$/ }
-# $filtered_data = [blueberry, raspberry]
-~~~
-
-When the first argument is a hash, Puppet passes each key and value pair to the lambda
-as an array in the form `[key, value]` and returns a hash containing the results.
-
-**Example**: Using the `filter` function with a hash and a one-parameter lambda
-
-~~~ puppet
-# For the hash $data, return a hash containing all values of keys that end with "berry"
-$data = { "orange" => 0, "blueberry" => 1, "raspberry" => 2 }
-$filtered_data = $data.filter |$items| { $items[0] =~ /berry$/ }
-# $filtered_data = {blueberry => 1, raspberry => 2}
-~~~
-
-When the first argument is an array and the lambda has two parameters, Puppet passes the
-array's indexes (enumerated from 0) in the first parameter and its values in the second
-parameter.
-
-**Example**: Using the `filter` function with an array and a two-parameter lambda
-
-~~~ puppet
-# For the array $data, return an array of all keys that both end with "berry" and have
-# an even-numbered index
-$data = ["orange", "blueberry", "raspberry"]
-$filtered_data = $data.filter |$indexes, $values| { $indexes % 2 == 0 and $values =~ /berry$/ }
-# $filtered_data = [raspberry]
-~~~
-
-When the first argument is a hash, Puppet passes its keys to the first parameter and its
-values to the second parameter.
-
-**Example**: Using the `filter` function with a hash and a two-parameter lambda
-
-~~~ puppet
-# For the hash $data, return a hash of all keys that both end with "berry" and have
-# values less than or equal to 1
-$data = { "orange" => 0, "blueberry" => 1, "raspberry" => 2 }
-$filtered_data = $data.filter |$keys, $values| { $keys =~ /berry$/ and $values <= 1 }
-# $filtered_data = {blueberry => 1}
-~~~
-
-- Since 4.0.0
-DOC
-) do |args|
+  :doc => <<~DOC
+    Applies a [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html)
+    to every value in a data structure and returns an array or hash containing any elements
+    for which the lambda evaluates to a truthy value (not `false` or `undef`).
+    
+    This function takes two mandatory arguments, in this order:
+    
+    1. An array or hash the function will iterate over.
+    2. A lambda, which the function calls for each element in the first argument. It can
+    request one or two parameters.
+    
+    **Example**: Using the `filter` function
+    
+    `$filtered_data = $data.filter |$parameter| { <PUPPET CODE BLOCK> }`
+    
+    or
+    
+    `$filtered_data = filter($data) |$parameter| { <PUPPET CODE BLOCK> }`
+    
+    When the first argument (`$data` in the above example) is an array, Puppet passes each
+    value in turn to the lambda and returns an array containing the results.
+    
+    **Example**: Using the `filter` function with an array and a one-parameter lambda
+    
+    ~~~ puppet
+    # For the array $data, return an array containing the values that end with "berry"
+    $data = ["orange", "blueberry", "raspberry"]
+    $filtered_data = $data.filter |$items| { $items =~ /berry$/ }
+    # $filtered_data = [blueberry, raspberry]
+    ~~~
+    
+    When the first argument is a hash, Puppet passes each key and value pair to the lambda
+    as an array in the form `[key, value]` and returns a hash containing the results.
+    
+    **Example**: Using the `filter` function with a hash and a one-parameter lambda
+    
+    ~~~ puppet
+    # For the hash $data, return a hash containing all values of keys that end with "berry"
+    $data = { "orange" => 0, "blueberry" => 1, "raspberry" => 2 }
+    $filtered_data = $data.filter |$items| { $items[0] =~ /berry$/ }
+    # $filtered_data = {blueberry => 1, raspberry => 2}
+    ~~~
+    
+    When the first argument is an array and the lambda has two parameters, Puppet passes the
+    array's indexes (enumerated from 0) in the first parameter and its values in the second
+    parameter.
+    
+    **Example**: Using the `filter` function with an array and a two-parameter lambda
+    
+    ~~~ puppet
+    # For the array $data, return an array of all keys that both end with "berry" and have
+    # an even-numbered index
+    $data = ["orange", "blueberry", "raspberry"]
+    $filtered_data = $data.filter |$indexes, $values| { $indexes % 2 == 0 and $values =~ /berry$/ }
+    # $filtered_data = [raspberry]
+    ~~~
+    
+    When the first argument is a hash, Puppet passes its keys to the first parameter and its
+    values to the second parameter.
+    
+    **Example**: Using the `filter` function with a hash and a two-parameter lambda
+    
+    ~~~ puppet
+    # For the hash $data, return a hash of all keys that both end with "berry" and have
+    # values less than or equal to 1
+    $data = { "orange" => 0, "blueberry" => 1, "raspberry" => 2 }
+    $filtered_data = $data.filter |$keys, $values| { $keys =~ /berry$/ and $values <= 1 }
+    # $filtered_data = {blueberry => 1}
+    ~~~
+    
+    - Since 4.0.0
+  DOC
+) do |_args|
   Puppet::Parser::Functions::Error.is4x('filter')
 end

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

@@ -1,29 +1,30 @@
 # frozen_string_literal: true
+
 Puppet::Parser::Functions::newfunction(
   :find_file,
   :type => :rvalue,
   :arity => -2,
-:doc => <<-DOC
-Finds an existing file from a module and returns its path.
-
-The argument to this function should be a String as a `<MODULE NAME>/<FILE>`
-reference, which will search for `<FILE>` relative to a module's `files`
-directory. (For example, the reference `mysql/mysqltuner.pl` will search for the
-file `<MODULES DIRECTORY>/mysql/files/mysqltuner.pl`.)
-
-This function can also accept:
-
-* An absolute String path, which will check for the existence of a file from anywhere on disk.
-* Multiple String arguments, which will return the path of the **first** file
-  found, skipping non existing files.
-* An array of string paths, which will return the path of the **first** file
-  found from the given paths in the array, skipping non existing files.
-
-The function returns `undef` if none of the given paths were found
-
-- since 4.8.0
-DOC
-) do |args|
+  :doc => <<~DOC
+    Finds an existing file from a module and returns its path.
+    
+    The argument to this function should be a String as a `<MODULE NAME>/<FILE>`
+    reference, which will search for `<FILE>` relative to a module's `files`
+    directory. (For example, the reference `mysql/mysqltuner.pl` will search for the
+    file `<MODULES DIRECTORY>/mysql/files/mysqltuner.pl`.)
+    
+    This function can also accept:
+    
+    * An absolute String path, which will check for the existence of a file from anywhere on disk.
+    * Multiple String arguments, which will return the path of the **first** file
+      found, skipping non existing files.
+    * An array of string paths, which will return the path of the **first** file
+      found from the given paths in the array, skipping non existing files.
+    
+    The function returns `undef` if none of the given paths were found
+    
+    - since 4.8.0
+  DOC
+) do |_args|
   Puppet::Parser::Functions::Error.is4x('find_file')
 end
 

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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require 'digest/md5'
 require 'digest/sha2'
 
@@ -20,26 +21,26 @@ Puppet::Parser::Functions::newfunction(:fqdn_rand, :arity => -2, :type => :rvalu
   have more than one such task and need several unrelated random numbers per
   node. (For example, `fqdn_rand(30)`, `fqdn_rand(30, 'expensive job 1')`, and
   `fqdn_rand(30, 'expensive job 2')` will produce totally different numbers.)") do |args|
-    max = args.shift.to_i
-    initial_seed = args.shift
-    downcase = !!args.shift
-
-    fqdn = self['facts'].dig('networking', 'fqdn')
-    fqdn = fqdn.downcase if downcase
-
-    # Puppet 5.4's fqdn_rand function produces a different value than earlier versions
-    # for the same set of inputs.
-    # This causes problems because the values are often written into service configuration files.
-    # When they change, services get notified and restart.
-
-    # Restoring previous fqdn_rand behavior of calculating its seed value using MD5
-    # when running on a non-FIPS enabled platform and only using SHA256 on FIPS enabled
-    # platforms.
-    if Puppet::Util::Platform.fips_enabled?
-      seed = Digest::SHA256.hexdigest([fqdn,max,initial_seed].join(':')).hex
-    else
-      seed = Digest::MD5.hexdigest([fqdn,max,initial_seed].join(':')).hex
-    end
-
-    Puppet::Util.deterministic_rand_int(seed,max)
+  max = args.shift.to_i
+  initial_seed = args.shift
+  downcase = !!args.shift
+
+  fqdn = self['facts'].dig('networking', 'fqdn')
+  fqdn = fqdn.downcase if downcase
+
+  # Puppet 5.4's fqdn_rand function produces a different value than earlier versions
+  # for the same set of inputs.
+  # This causes problems because the values are often written into service configuration files.
+  # When they change, services get notified and restart.
+
+  # Restoring previous fqdn_rand behavior of calculating its seed value using MD5
+  # when running on a non-FIPS enabled platform and only using SHA256 on FIPS enabled
+  # platforms.
+  if Puppet::Util::Platform.fips_enabled?
+    seed = Digest::SHA256.hexdigest([fqdn,max,initial_seed].join(':')).hex
+  else
+    seed = Digest::MD5.hexdigest([fqdn,max,initial_seed].join(':')).hex
+  end
+
+  Puppet::Util.deterministic_rand_int(seed,max)
 end

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

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
+
 # Runs an external command and returns the results
 Puppet::Parser::Functions::newfunction(:generate, :arity => -2, :type => :rvalue,
-    :doc => "Calls an external command on the Puppet master and returns
+                                                  :doc => "Calls an external command on the Puppet master and returns
     the results of the command. Any arguments are passed to the external command as
     arguments. If the generator does not exit with return code of 0,
     the generator is considered to have failed and a parse error is
@@ -12,27 +13,26 @@ Puppet::Parser::Functions::newfunction(:generate, :arity => -2, :type => :rvalue
     generators, so all shell metacharacters are passed directly to
     the generator, and all metacharacters are returned by the function.
     Consider cleaning white space from any string generated.") do |args|
+  # TRANSLATORS "fully qualified" refers to a fully qualified file system path
+  raise Puppet::ParseError, _("Generators must be fully qualified") unless Puppet::Util.absolute_path?(args[0])
 
-      #TRANSLATORS "fully qualified" refers to a fully qualified file system path
-      raise Puppet::ParseError, _("Generators must be fully qualified") unless Puppet::Util.absolute_path?(args[0])
-
-      if Puppet::Util::Platform.windows?
-        valid = args[0] =~ /^[a-z]:(?:[\/\\][-.~\w]+)+$/i
-      else
-        valid = args[0] =~ /^[-\/\w.+]+$/
-      end
+  if Puppet::Util::Platform.windows?
+    valid = args[0] =~ /^[a-z]:(?:[\/\\][-.~\w]+)+$/i
+  else
+    valid = args[0] =~ /^[-\/\w.+]+$/
+  end
 
-      unless valid
-        raise Puppet::ParseError, _("Generators can only contain alphanumerics, file separators, and dashes")
-      end
+  unless valid
+    raise Puppet::ParseError, _("Generators can only contain alphanumerics, file separators, and dashes")
+  end
 
-      if args[0] =~ /\.\./
-        raise Puppet::ParseError, _("Can not use generators with '..' in them.")
-      end
+  if args[0] =~ /\.\./
+    raise Puppet::ParseError, _("Can not use generators with '..' in them.")
+  end
 
-      begin
-        Dir.chdir(File.dirname(args[0])) { Puppet::Util::Execution.execute(args).to_str }
-      rescue Puppet::ExecutionFailure => detail
-        raise Puppet::ParseError, _("Failed to execute generator %{generator}: %{detail}") % { generator: args[0], detail: detail }, detail.backtrace
-      end
+  begin
+    Dir.chdir(File.dirname(args[0])) { Puppet::Util::Execution.execute(args).to_str }
+  rescue Puppet::ExecutionFailure => detail
+    raise Puppet::ParseError, _("Failed to execute generator %{generator}: %{detail}") % { generator: args[0], detail: detail }, detail.backtrace
+  end
 end

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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require 'hiera_puppet'
 
 module Puppet::Parser::Functions
@@ -6,99 +7,99 @@ module Puppet::Parser::Functions
     :hiera,
     :type => :rvalue,
     :arity => -2,
-    :doc => <<DOC
-Performs a standard priority lookup of the hierarchy and returns the most specific value
-for a given key. The returned value can be any type of data.
-
-The function takes up to three arguments, in this order:
-
-1. A string key that Hiera searches for in the hierarchy. **Required**.
-2. An optional default value to return if Hiera doesn't find anything matching the key.
-    * If this argument isn't provided and this function results in a lookup failure, Puppet
-    fails with a compilation error.
-3. The optional name of an arbitrary
-[hierarchy level](https://puppet.com/docs/hiera/latest/hierarchy.html) to insert at the
-top of the hierarchy. This lets you temporarily modify the hierarchy for a single lookup.
-    * If Hiera doesn't find a matching key in the overriding hierarchy level, it continues
-    searching the rest of the hierarchy.
-
-The `hiera` function does **not** find all matches throughout a hierarchy, instead
-returining the first specific value starting at the top of the hierarchy. To search
-throughout a hierarchy, use the `hiera_array` or `hiera_hash` functions.
-
-**Example**: Using `hiera`
-
-~~~ yaml
-# Assuming hiera.yaml
-# :hierarchy:
-#   - web01.example.com
-#   - common
-
-# Assuming web01.example.com.yaml:
-# users:
-#   - "Amy Barry"
-#   - "Carrie Douglas"
-
-# Assuming common.yaml:
-users:
-  admins:
-    - "Edith Franklin"
-    - "Ginny Hamilton"
-  regular:
-    - "Iris Jackson"
-    - "Kelly Lambert"
-~~~
-
-~~~ puppet
-# Assuming we are not web01.example.com:
-
-$users = hiera('users', undef)
-
-# $users contains {admins  => ["Edith Franklin", "Ginny Hamilton"],
-#                  regular => ["Iris Jackson", "Kelly Lambert"]}
-~~~
-
-You can optionally generate the default value with a
-[lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html) that
-takes one parameter.
-
-**Example**: Using `hiera` with a lambda
-
-~~~ puppet
-# Assuming the same Hiera data as the previous example:
-
-$users = hiera('users') | $key | { "Key \'${key}\' not found" }
-
-# $users contains {admins  => ["Edith Franklin", "Ginny Hamilton"],
-#                  regular => ["Iris Jackson", "Kelly Lambert"]}
-# If hiera couldn't match its key, it would return the lambda result,
-# "Key 'users' not found".
-~~~
-
-The returned value's data type depends on the types of the results. In the example
-above, Hiera matches the 'users' key and returns it as a hash.
-
-The `hiera` function is deprecated in favor of using `lookup` and will be removed in 6.0.0.
-See https://puppet.com/docs/puppet/#{Puppet.minor_version}/deprecated_language.html.
-Replace the calls as follows:
-
-| from  | to |
-| ----  | ---|
-| hiera($key) | lookup($key) |
-| hiera($key, $default) | lookup($key, { 'default_value' => $default }) |
-| hiera($key, $default, $level) | override level not supported |
-
-Note that calls using the 'override level' option are not directly supported by 'lookup' and the produced
-result must be post processed to get exactly the same result, for example using simple hash/array `+` or
-with calls to stdlib's `deep_merge` function depending on kind of hiera call and setting of merge in hiera.yaml.
-
-See
-[the documentation](https://puppet.com/docs/hiera/latest/puppet.html#hiera-lookup-functions)
-for more information about Hiera lookup functions.
-
-- Since 4.0.0
-DOC
-  ) do |*args|
+    :doc => <<~DOC
+      Performs a standard priority lookup of the hierarchy and returns the most specific value
+      for a given key. The returned value can be any type of data.
+      
+      The function takes up to three arguments, in this order:
+      
+      1. A string key that Hiera searches for in the hierarchy. **Required**.
+      2. An optional default value to return if Hiera doesn't find anything matching the key.
+          * If this argument isn't provided and this function results in a lookup failure, Puppet
+          fails with a compilation error.
+      3. The optional name of an arbitrary
+      [hierarchy level](https://puppet.com/docs/hiera/latest/hierarchy.html) to insert at the
+      top of the hierarchy. This lets you temporarily modify the hierarchy for a single lookup.
+          * If Hiera doesn't find a matching key in the overriding hierarchy level, it continues
+          searching the rest of the hierarchy.
+      
+      The `hiera` function does **not** find all matches throughout a hierarchy, instead
+      returining the first specific value starting at the top of the hierarchy. To search
+      throughout a hierarchy, use the `hiera_array` or `hiera_hash` functions.
+      
+      **Example**: Using `hiera`
+      
+      ~~~ yaml
+      # Assuming hiera.yaml
+      # :hierarchy:
+      #   - web01.example.com
+      #   - common
+      
+      # Assuming web01.example.com.yaml:
+      # users:
+      #   - "Amy Barry"
+      #   - "Carrie Douglas"
+      
+      # Assuming common.yaml:
+      users:
+        admins:
+          - "Edith Franklin"
+          - "Ginny Hamilton"
+        regular:
+          - "Iris Jackson"
+          - "Kelly Lambert"
+      ~~~
+      
+      ~~~ puppet
+      # Assuming we are not web01.example.com:
+      
+      $users = hiera('users', undef)
+      
+      # $users contains {admins  => ["Edith Franklin", "Ginny Hamilton"],
+      #                  regular => ["Iris Jackson", "Kelly Lambert"]}
+      ~~~
+      
+      You can optionally generate the default value with a
+      [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html) that
+      takes one parameter.
+      
+      **Example**: Using `hiera` with a lambda
+      
+      ~~~ puppet
+      # Assuming the same Hiera data as the previous example:
+      
+      $users = hiera('users') | $key | { "Key \'${key}\' not found" }
+      
+      # $users contains {admins  => ["Edith Franklin", "Ginny Hamilton"],
+      #                  regular => ["Iris Jackson", "Kelly Lambert"]}
+      # If hiera couldn't match its key, it would return the lambda result,
+      # "Key 'users' not found".
+      ~~~
+      
+      The returned value's data type depends on the types of the results. In the example
+      above, Hiera matches the 'users' key and returns it as a hash.
+      
+      The `hiera` function is deprecated in favor of using `lookup` and will be removed in 6.0.0.
+      See https://puppet.com/docs/puppet/#{Puppet.minor_version}/deprecated_language.html.
+      Replace the calls as follows:
+      
+      | from  | to |
+      | ----  | ---|
+      | hiera($key) | lookup($key) |
+      | hiera($key, $default) | lookup($key, { 'default_value' => $default }) |
+      | hiera($key, $default, $level) | override level not supported |
+      
+      Note that calls using the 'override level' option are not directly supported by 'lookup' and the produced
+      result must be post processed to get exactly the same result, for example using simple hash/array `+` or
+      with calls to stdlib's `deep_merge` function depending on kind of hiera call and setting of merge in hiera.yaml.
+      
+      See
+      [the documentation](https://puppet.com/docs/hiera/latest/puppet.html#hiera-lookup-functions)
+      for more information about Hiera lookup functions.
+      
+      - Since 4.0.0
+    DOC
+  ) do |*_args|
     Error.is4x('hiera')
   end
 end