openvox 7.37.1

data/lib/puppet/parser/files.rb

@@ -0,0 +1,93 @@
+module Puppet::Parser::Files
+
+  module_function
+
+  # Return a list of manifests as absolute filenames matching the given
+  # pattern.
+  #
+  # @param pattern [String] A reference for a file in a module. It is the
+  #   format "<modulename>/<file glob>"
+  # @param environment [Puppet::Node::Environment] the environment of modules
+  #
+  # @return [Array(String, Array<String>)] the module name and the list of files found
+  # @api private
+  def find_manifests_in_modules(pattern, environment)
+    module_name, file_pattern = split_file_path(pattern)
+
+    mod = environment.module(module_name)
+    if mod
+      [mod.name, mod.match_manifests(file_pattern)]
+    else
+      [nil, []]
+    end
+  end
+
+  # Find the path to the given file selector. Files can be selected in
+  # one of two ways:
+  #   * absolute path: the path is simply returned
+  #   * modulename/filename selector: a file is found in the file directory
+  #     of the named module.
+  #
+  # In the second case a nil is returned if there isn't a file found. In the
+  # first case (absolute path), there is no existence check done and so the
+  # path will be returned even if there isn't a file available.
+  #
+  # @param template [String] the file selector
+  # @param environment [Puppet::Node::Environment] the environment in which to search
+  # @return [String, nil] the absolute path to the file or nil if there is no file found
+  #
+  # @api private
+  def find_file(file, environment)
+    find_in_module(file, environment) do |mod,module_file|
+      mod.file(module_file)
+    end
+  end
+
+  # Find the path to the given template selector. Templates can be selected in
+  # a couple of ways:
+  #   * absolute path: the path is simply returned
+  #   * modulename/filename selector: a file is found in the template directory
+  #     of the named module.
+  #
+  # In the last two cases a nil is returned if there isn't a file found. In the
+  # first case (absolute path), there is no existence check done and so the
+  # path will be returned even if there isn't a file available.
+  #
+  # @param template [String] the template selector
+  # @param environment [Puppet::Node::Environment] the environment in which to search
+  # @return [String, nil] the absolute path to the template file or nil if there is no file found
+  #
+  # @api private
+  def find_template(template, environment)
+    find_in_module(template, environment) do |mod,template_file|
+      mod.template(template_file)
+    end
+  end
+
+  # @api private
+  def find_in_module(reference, environment)
+    if Puppet::Util.absolute_path?(reference)
+      reference
+    else
+      path, file = split_file_path(reference)
+      mod = environment.module(path)
+
+      if file && mod
+        yield(mod, file)
+      else
+        nil
+      end
+    end
+  end
+
+  # Split the path into the module and the rest of the path, or return
+  # nil if the path is empty or absolute (starts with a /).
+  # @api private
+  def split_file_path(path)
+    if path == "" || Puppet::Util.absolute_path?(path)
+      nil
+    else
+      path.split(File::SEPARATOR, 2)
+    end
+  end
+end

data/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://puppet.com/docs/puppet/latest/lang_data.html), or
+otherwise either raises an error or executes an optional two-parameter
+[lambda](https://puppet.com/docs/puppet/latest/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://puppet.com/docs/puppet/latest/lang_data.html).
+
+- Since 4.0.0
+DOC
+) do |args|
+  Puppet::Parser::Functions::Error.is4x('assert_type')
+end

data/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/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/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/lib/puppet/parser/functions/create_resources.rb

@@ -0,0 +1,110 @@
+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.
+    
+    **Note**: Use this function selectively. It's generally better to write resources in
+     [Puppet](https://puppet.com/docs/puppet/latest/lang_resources.html), as
+     resources created with `create_resource` are difficult to read and troubleshoot.
+
+    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` filters 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.
+  #
+  file, line = Puppet::Pops::PuppetStack.top_of_stack
+
+  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

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

@@ -0,0 +1,107 @@
+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|
+  Puppet::Parser::Functions::Error.is4x('defined')
+end

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

@@ -0,0 +1,38 @@
+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|
+  Puppet::Parser::Functions::Error.is4x('dig')
+end

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

@@ -0,0 +1,5 @@
+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]
+  Puppet::Util::Checksums.method(algo.intern).call args[0]
+end

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

@@ -0,0 +1,104 @@
+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|
+  Puppet::Parser::Functions::Error.is4x('each')
+end

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

@@ -0,0 +1,39 @@
+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.
+
+`epp('<MODULE NAME>/<TEMPLATE FILE>', <PARAMETER HASH>)`
+
+The first argument to this function should be a `<MODULE NAME>/<TEMPLATE FILE>`
+reference, which loads `<TEMPLATE FILE>` from `<MODULE NAME>`'s `templates`
+directory. In most cases, the last argument is optional; if used, it should be a
+[hash](https://puppet.com/docs/puppet/latest/lang_data_hash.html) that contains parameters to
+pass to the template.
+
+- See the [template](https://puppet.com/docs/puppet/latest/lang_template.html) documentation
+for general template usage information.
+- See the [EPP syntax](https://puppet.com/docs/puppet/latest/lang_template_epp.html)
+documentation for examples of EPP.
+
+For example, to call the apache module's `templates/vhost/_docroot.epp`
+template and pass the `docroot` and `virtual_docroot` parameters, call the `epp`
+function like this:
+
+`epp('apache/vhost/_docroot.epp', { 'docroot' => '/var/www/html',
+'virtual_docroot' => '/var/www/example' })`
+
+This function can also accept an absolute path, which can load a template file
+from anywhere on disk.
+
+Puppet produces a syntax error if you pass more parameters than are declared in
+the template's parameter tag. When passing parameters to a template that
+contains a parameter tag, use the same names as the tag's declared parameters.
+
+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|
+
+  Puppet::Parser::Functions::Error.is4x('epp')
+end

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

@@ -0,0 +1,11 @@
+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
+) do |vals|
+    vals = vals.collect { |s| s.to_s }.join(" ") if vals.is_a? Array
+    raise Puppet::ParseError, vals.to_s
+end