puppet 8.3.1 → 8.4.0

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

@@ -1,40 +1,41 @@
 # frozen_string_literal: true
+
 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|
+  :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/lib/puppet/parser/functions/contain.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 # Called within a class definition, establishes a containment
 # relationship with another class
 

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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 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.
     
@@ -51,7 +52,7 @@ Puppet::Parser::Functions::newfunction(:create_resources, :arity => -3, :doc =>
     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
+ENDHEREDOC
   if Puppet[:tasks]
     raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
       Puppet::Pops::Issues::CATALOG_OPERATION_NOT_SUPPORTED_WHEN_SCRIPTING,
@@ -60,6 +61,7 @@ Puppet::Parser::Functions::newfunction(:create_resources, :arity => -3, :doc =>
 
   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
@@ -90,7 +92,7 @@ Puppet::Parser::Functions::newfunction(:create_resources, :arity => -3, :doc =>
 
   instances.map do |title, params|
     # Add support for iteration if title is an array
-    resource_titles = title.is_a?(Array) ? title  : [title]
+    resource_titles = title.is_a?(Array) ? title : [title]
     Puppet::Pops::Evaluator::Runtime3ResourceSupport.create_resources(
       file, line,
       self,
@@ -100,12 +102,12 @@ Puppet::Parser::Functions::newfunction(:create_resources, :arity => -3, :doc =>
       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
+          :name => name,
+          :value => value, # wide open to various data types, must be correct
           :source => self.source, # TODO: support :line => line, :file => file,
-          :add    => false
+          :add => false
         )
       end.compact
-      )
+    )
   end.flatten.compact
 end

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

@@ -1,108 +1,109 @@
 # frozen_string_literal: true
+
 Puppet::Parser::Functions::newfunction(
   :defined,
   :type => :rvalue,
   :arity => -2,
-  :doc => <<DOC
-Determines whether a given class or resource type is defined and returns a Boolean
-value. You can also use `defined` to determine whether a specific resource is defined,
-or whether a variable has a value (including `undef`, as opposed to the variable never
-being declared or assigned).
-
-This function takes at least one string argument, which can be a class name, type name,
-resource reference, or variable reference of the form `'$name'`.
-
-The `defined` function checks both native and defined types, including types
-provided by modules. Types and classes are matched by their names. The function matches
-resource declarations by using resource references.
-
-**Examples**: Different types of `defined` function matches
-
-~~~ puppet
-# Matching resource types
-defined("file")
-defined("customtype")
-
-# Matching defines and classes
-defined("foo")
-defined("foo::bar")
-
-# Matching variables
-defined('$name')
-
-# Matching declared resources
-defined(File['/tmp/file'])
-~~~
-
-Puppet depends on the configuration's evaluation order when checking whether a resource
-is declared.
-
-**Example**: Importance of evaluation order when using `defined`
-
-~~~ puppet
-# Assign values to $is_defined_before and $is_defined_after using identical `defined`
-# functions.
-
-$is_defined_before = defined(File['/tmp/file'])
-
-file { "/tmp/file":
-  ensure => present,
-}
-
-$is_defined_after = defined(File['/tmp/file'])
-
-# $is_defined_before returns false, but $is_defined_after returns true.
-~~~
-
-This order requirement only refers to evaluation order. The order of resources in the
-configuration graph (e.g. with `before` or `require`) does not affect the `defined`
-function's behavior.
-
-> **Warning:** Avoid relying on the result of the `defined` function in modules, as you
-> might not be able to guarantee the evaluation order well enough to produce consistent
-> results. This can cause other code that relies on the function's result to behave
-> inconsistently or fail.
-
-If you pass more than one argument to `defined`, the function returns `true` if _any_
-of the arguments are defined. You can also match resources by type, allowing you to
-match conditions of different levels of specificity, such as whether a specific resource
-is of a specific data type.
-
-**Example**: Matching multiple resources and resources by different types with `defined`
-
-~~~ puppet
-file { "/tmp/file1":
-  ensure => file,
-}
-
-$tmp_file = file { "/tmp/file2":
-  ensure => file,
-}
-
-# Each of these statements return `true` ...
-defined(File['/tmp/file1'])
-defined(File['/tmp/file1'],File['/tmp/file2'])
-defined(File['/tmp/file1'],File['/tmp/file2'],File['/tmp/file3'])
-# ... but this returns `false`.
-defined(File['/tmp/file3'])
-
-# Each of these statements returns `true` ...
-defined(Type[Resource['file','/tmp/file2']])
-defined(Resource['file','/tmp/file2'])
-defined(File['/tmp/file2'])
-defined('$tmp_file')
-# ... but each of these returns `false`.
-defined(Type[Resource['exec','/tmp/file2']])
-defined(Resource['exec','/tmp/file2'])
-defined(File['/tmp/file3'])
-defined('$tmp_file2')
-~~~
-
-- Since 2.7.0
-- Since 3.6.0 variable reference and future parser types
-- Since 3.8.1 type specific requests with future parser
-- Since 4.0.0 includes all future parser features
-DOC
-) do |vals|
+  :doc => <<~DOC
+    Determines whether a given class or resource type is defined and returns a Boolean
+    value. You can also use `defined` to determine whether a specific resource is defined,
+    or whether a variable has a value (including `undef`, as opposed to the variable never
+    being declared or assigned).
+    
+    This function takes at least one string argument, which can be a class name, type name,
+    resource reference, or variable reference of the form `'$name'`.
+    
+    The `defined` function checks both native and defined types, including types
+    provided by modules. Types and classes are matched by their names. The function matches
+    resource declarations by using resource references.
+    
+    **Examples**: Different types of `defined` function matches
+    
+    ~~~ puppet
+    # Matching resource types
+    defined("file")
+    defined("customtype")
+    
+    # Matching defines and classes
+    defined("foo")
+    defined("foo::bar")
+    
+    # Matching variables
+    defined('$name')
+    
+    # Matching declared resources
+    defined(File['/tmp/file'])
+    ~~~
+    
+    Puppet depends on the configuration's evaluation order when checking whether a resource
+    is declared.
+    
+    **Example**: Importance of evaluation order when using `defined`
+    
+    ~~~ puppet
+    # Assign values to $is_defined_before and $is_defined_after using identical `defined`
+    # functions.
+    
+    $is_defined_before = defined(File['/tmp/file'])
+    
+    file { "/tmp/file":
+      ensure => present,
+    }
+    
+    $is_defined_after = defined(File['/tmp/file'])
+    
+    # $is_defined_before returns false, but $is_defined_after returns true.
+    ~~~
+    
+    This order requirement only refers to evaluation order. The order of resources in the
+    configuration graph (e.g. with `before` or `require`) does not affect the `defined`
+    function's behavior.
+    
+    > **Warning:** Avoid relying on the result of the `defined` function in modules, as you
+    > might not be able to guarantee the evaluation order well enough to produce consistent
+    > results. This can cause other code that relies on the function's result to behave
+    > inconsistently or fail.
+    
+    If you pass more than one argument to `defined`, the function returns `true` if _any_
+    of the arguments are defined. You can also match resources by type, allowing you to
+    match conditions of different levels of specificity, such as whether a specific resource
+    is of a specific data type.
+    
+    **Example**: Matching multiple resources and resources by different types with `defined`
+    
+    ~~~ puppet
+    file { "/tmp/file1":
+      ensure => file,
+    }
+    
+    $tmp_file = file { "/tmp/file2":
+      ensure => file,
+    }
+    
+    # Each of these statements return `true` ...
+    defined(File['/tmp/file1'])
+    defined(File['/tmp/file1'],File['/tmp/file2'])
+    defined(File['/tmp/file1'],File['/tmp/file2'],File['/tmp/file3'])
+    # ... but this returns `false`.
+    defined(File['/tmp/file3'])
+    
+    # Each of these statements returns `true` ...
+    defined(Type[Resource['file','/tmp/file2']])
+    defined(Resource['file','/tmp/file2'])
+    defined(File['/tmp/file2'])
+    defined('$tmp_file')
+    # ... but each of these returns `false`.
+    defined(Type[Resource['exec','/tmp/file2']])
+    defined(Resource['exec','/tmp/file2'])
+    defined(File['/tmp/file3'])
+    defined('$tmp_file2')
+    ~~~
+    
+    - Since 2.7.0
+    - Since 3.6.0 variable reference and future parser types
+    - Since 3.8.1 type specific requests with future parser
+    - Since 4.0.0 includes all future parser features
+  DOC
+) do |_vals|
   Puppet::Parser::Functions::Error.is4x('defined')
 end

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

@@ -1,39 +1,40 @@
 # frozen_string_literal: true
+
 Puppet::Parser::Functions::newfunction(
   :dig,
   :type => :rvalue,
   :arity => -1,
-  :doc => <<-DOC
-Returns a value for a sequence of given keys/indexes into a structure, such as
-an array or hash.
-This function is used to "dig into" a complex data structure by
-using a sequence of keys / indexes to access a value from which
-the next key/index is accessed recursively.
-
-The first encountered `undef` value or key stops the "dig" and `undef` is returned.
-
-An error is raised if an attempt is made to "dig" into
-something other than an `undef` (which immediately returns `undef`), an `Array` or a `Hash`.
-
-
-
-**Example:** Using `dig`
-
-```puppet
-$data = {a => { b => [{x => 10, y => 20}, {x => 100, y => 200}]}}
-notice $data.dig('a', 'b', 1, 'x')
-```
-
-Would notice the value 100.
-
-This is roughly equivalent to `$data['a']['b'][1]['x']`. However, a standard
-index will return an error and cause catalog compilation failure if any parent
-of the final key (`'x'`) is `undef`. The `dig` function will return undef,
-rather than failing catalog compilation. This allows you to check if data
-exists in a structure without mandating that it always exists.
-
-* Since 4.5.0
-DOC
-) do |args|
+  :doc => <<~DOC
+    Returns a value for a sequence of given keys/indexes into a structure, such as
+    an array or hash.
+    This function is used to "dig into" a complex data structure by
+    using a sequence of keys / indexes to access a value from which
+    the next key/index is accessed recursively.
+    
+    The first encountered `undef` value or key stops the "dig" and `undef` is returned.
+    
+    An error is raised if an attempt is made to "dig" into
+    something other than an `undef` (which immediately returns `undef`), an `Array` or a `Hash`.
+    
+    
+    
+    **Example:** Using `dig`
+    
+    ```puppet
+    $data = {a => { b => [{x => 10, y => 20}, {x => 100, y => 200}]}}
+    notice $data.dig('a', 'b', 1, 'x')
+    ```
+    
+    Would notice the value 100.
+    
+    This is roughly equivalent to `$data['a']['b'][1]['x']`. However, a standard
+    index will return an error and cause catalog compilation failure if any parent
+    of the final key (`'x'`) is `undef`. The `dig` function will return undef,
+    rather than failing catalog compilation. This allows you to check if data
+    exists in a structure without mandating that it always exists.
+    
+    * Since 4.5.0
+  DOC
+) do |_args|
   Puppet::Parser::Functions::Error.is4x('dig')
 end

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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require_relative '../../../puppet/util/checksums'
 Puppet::Parser::Functions::newfunction(:digest, :type => :rvalue, :arity => 1, :doc => "Returns a hash value from a provided string using the digest_algorithm setting from the Puppet config file.") do |args|
   algo = Puppet[:digest_algorithm]

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

@@ -1,105 +1,106 @@
 # frozen_string_literal: true
+
 Puppet::Parser::Functions::newfunction(
   :each,
   :type => :rvalue,
   :arity => -3,
-  :doc => <<-DOC
-Runs a [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html)
-repeatedly using each value in a data structure, then returns the values unchanged.
-
-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 `each` function
-
-`$data.each |$parameter| { <PUPPET CODE BLOCK> }`
-
-or
-
-`each($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, then returns the original values.
-
-**Example**: Using the `each` function with an array and a one-parameter lambda
-
-~~~ puppet
-# For the array $data, run a lambda that creates a resource for each item.
-$data = ["routers", "servers", "workstations"]
-$data.each |$item| {
- notify { $item:
-   message => $item
- }
-}
-# Puppet creates one resource for each of the three items in $data. Each resource is
-# named after the item's value and uses the item's value in a parameter.
-~~~
-
-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 the original hash.
-
-**Example**: Using the `each` function with a hash and a one-parameter lambda
-
-~~~ puppet
-# For the hash $data, run a lambda using each item as a key-value array that creates a
-# resource for each item.
-$data = {"rtr" => "Router", "svr" => "Server", "wks" => "Workstation"}
-$data.each |$items| {
- notify { $items[0]:
-   message => $items[1]
- }
-}
-# Puppet creates one resource for each of the three items in $data, each named after the
-# item's key and containing a parameter using the item's value.
-~~~
-
-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 `each` function with an array and a two-parameter lambda
-
-~~~ puppet
-# For the array $data, run a lambda using each item's index and value that creates a
-# resource for each item.
-$data = ["routers", "servers", "workstations"]
-$data.each |$index, $value| {
- notify { $value:
-   message => $index
- }
-}
-# Puppet creates one resource for each of the three items in $data, each named after the
-# item's value and containing a parameter using the item's index.
-~~~
-
-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 `each` function with a hash and a two-parameter lambda
-
-~~~ puppet
-# For the hash $data, run a lambda using each item's key and value to create a resource
-# for each item.
-$data = {"rtr" => "Router", "svr" => "Server", "wks" => "Workstation"}
-$data.each |$key, $value| {
- notify { $key:
-   message => $value
- }
-}
-# Puppet creates one resource for each of the three items in $data, each named after the
-# item's key and containing a parameter using the item's value.
-~~~
-
-For an example that demonstrates how to create multiple `file` resources using `each`,
-see the Puppet
-[iteration](https://puppet.com/docs/puppet/latest/lang_iteration.html)
-documentation.
-
-- Since 4.0.0
-DOC
-) do |args|
+  :doc => <<~DOC
+    Runs a [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html)
+    repeatedly using each value in a data structure, then returns the values unchanged.
+    
+    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 `each` function
+    
+    `$data.each |$parameter| { <PUPPET CODE BLOCK> }`
+    
+    or
+    
+    `each($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, then returns the original values.
+    
+    **Example**: Using the `each` function with an array and a one-parameter lambda
+    
+    ~~~ puppet
+    # For the array $data, run a lambda that creates a resource for each item.
+    $data = ["routers", "servers", "workstations"]
+    $data.each |$item| {
+     notify { $item:
+       message => $item
+     }
+    }
+    # Puppet creates one resource for each of the three items in $data. Each resource is
+    # named after the item's value and uses the item's value in a parameter.
+    ~~~
+    
+    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 the original hash.
+    
+    **Example**: Using the `each` function with a hash and a one-parameter lambda
+    
+    ~~~ puppet
+    # For the hash $data, run a lambda using each item as a key-value array that creates a
+    # resource for each item.
+    $data = {"rtr" => "Router", "svr" => "Server", "wks" => "Workstation"}
+    $data.each |$items| {
+     notify { $items[0]:
+       message => $items[1]
+     }
+    }
+    # Puppet creates one resource for each of the three items in $data, each named after the
+    # item's key and containing a parameter using the item's value.
+    ~~~
+    
+    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 `each` function with an array and a two-parameter lambda
+    
+    ~~~ puppet
+    # For the array $data, run a lambda using each item's index and value that creates a
+    # resource for each item.
+    $data = ["routers", "servers", "workstations"]
+    $data.each |$index, $value| {
+     notify { $value:
+       message => $index
+     }
+    }
+    # Puppet creates one resource for each of the three items in $data, each named after the
+    # item's value and containing a parameter using the item's index.
+    ~~~
+    
+    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 `each` function with a hash and a two-parameter lambda
+    
+    ~~~ puppet
+    # For the hash $data, run a lambda using each item's key and value to create a resource
+    # for each item.
+    $data = {"rtr" => "Router", "svr" => "Server", "wks" => "Workstation"}
+    $data.each |$key, $value| {
+     notify { $key:
+       message => $value
+     }
+    }
+    # Puppet creates one resource for each of the three items in $data, each named after the
+    # item's key and containing a parameter using the item's value.
+    ~~~
+    
+    For an example that demonstrates how to create multiple `file` resources using `each`,
+    see the Puppet
+    [iteration](https://puppet.com/docs/puppet/latest/lang_iteration.html)
+    documentation.
+    
+    - Since 4.0.0
+  DOC
+) do |_args|
   Puppet::Parser::Functions::Error.is4x('each')
 end

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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 Puppet::Parser::Functions::newfunction(:epp, :type => :rvalue, :arity => -2, :doc =>
 "Evaluates an Embedded Puppet (EPP) template file and returns the rendered text
 result as a String.
@@ -34,7 +35,6 @@ Parameters are required only if they are declared in the called template's
 parameter tag without default values. Puppet produces an error if the `epp`
 function fails to pass any required parameter.
 
-- Since 4.0.0") do |args|
-
+- Since 4.0.0") do |_args|
   Puppet::Parser::Functions::Error.is4x('epp')
 end