openvox 8.19.0

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2009 Thomas Bellman
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# IN NO EVENT SHALL THOMAS BELLMAN BE LIABLE FOR ANY CLAIM, DAMAGES OR
+# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE.
+#
+# Except as contained in this notice, the name of Thomas Bellman shall
+# not be used in advertising or otherwise to promote the sale, use or
+# other dealings in this Software without prior written authorization
+# from Thomas Bellman.
+
+Puppet::Parser::Functions.newfunction(
+  :sprintf, :type => :rvalue,
+            :arity => -2,
+            :doc => "Perform printf-style formatting of text.
+
+  The first parameter is format string describing how the rest of the parameters should be formatted.
+  See the documentation for the [`Kernel::sprintf` function](https://ruby-doc.org/core/Kernel.html)
+  in Ruby for details.
+
+  To use [named format](https://idiosyncratic-ruby.com/49-what-the-format.html) arguments, provide a
+  hash containing the target string values as the argument to be formatted. For example:
+
+  ```puppet
+  notice sprintf(\"%<x>s : %<y>d\", { 'x' => 'value is', 'y' => 42 })
+  ```
+
+  This statement produces a notice of `value is : 42`."
+) do |args|
+  fmt = args[0]
+  args = args[1..]
+  begin
+    return sprintf(fmt, *args)
+  rescue KeyError => e
+    if args.size == 1 && args[0].is_a?(Hash)
+      # map the single hash argument such that all top level string keys are symbols
+      # as that allows named arguments to be used in the format string.
+      #
+      result = {}
+      args[0].each_pair { |k, v| result[k.is_a?(String) ? k.to_sym : k] = v }
+      return sprintf(fmt, result)
+    end
+    raise e
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+Puppet::Parser::Functions.newfunction(
+  :step,
+  :type => :rvalue,
+  :arity => -1,
+  :doc => <<~DOC
+    Provides stepping with given interval over elements in an iterable and optionally runs a
+    [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html) for each
+    element.
+
+    This function takes two to three arguments:
+
+    1. An 'Iterable' that the function will iterate over.
+    2. An `Integer` step factor. This must be a positive integer.
+    3. An optional lambda, which the function calls for each element in the interval. It must
+       request one parameter.
+
+    **Example:** Using the `step` function
+
+    ```puppet
+    $data.step(<n>) |$parameter| { <PUPPET CODE BLOCK> }
+    ```
+
+    or
+
+    ```puppet
+    $stepped_data = $data.step(<n>)
+    ```
+
+    or
+    ```puppet
+    step($data, <n>) |$parameter| { <PUPPET CODE BLOCK> }
+    ```
+
+    or
+
+    ```puppet
+    $stepped_data = step($data, <n>)
+    ```
+
+    When no block is given, Puppet returns an `Iterable` that yields the first element and every nth successor
+    element, from its first argument. This allows functions on iterables to be chained.
+    When a block is given, Puppet iterates and calls the block with the first element and then with
+    every nth successor element. It then returns `undef`.
+
+    **Example:** Using the `step` function with an array, a step factor, and a one-parameter block
+
+    ```puppet
+    # For the array $data, call a block with the first element and then with each 3rd successor element
+    $data = [1,2,3,4,5,6,7,8]
+    $data.step(3) |$item| {
+     notice($item)
+    }
+    # Puppet notices the values '1', '4', '7'.
+    ```
+
+    When no block is given, Puppet returns a new `Iterable` which allows it to be directly chained into
+    another function that takes an `Iterable` as an argument.
+
+    **Example:** Using the `step` function chained with a `map` function.
+
+    ```puppet
+    # For the array $data, return an array, set to the first element and each 5th successor element, in reverse
+    # order multiplied by 10
+    $data = Integer[0,20]
+    $transformed_data = $data.step(5).map |$item| { $item * 10 }
+    $transformed_data contains [0,50,100,150,200]
+    ```
+
+    **Example:** The same example using `step` function chained with a `map` in alternative syntax
+
+    ```puppet
+    # For the array $data, return an array, set to the first and each 5th
+    # successor, in reverse order, multiplied by 10
+    $data = Integer[0,20]
+    $transformed_data = map(step($data, 5)) |$item| { $item * 10 }
+    $transformed_data contains [0,50,100,150,200]
+    ```
+
+    * Since 4.4.0
+
+  DOC
+) do |_args|
+  Puppet::Parser::Functions::Error.is4x('step')
+end

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

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+Puppet::Parser::Functions.newfunction(
+  :strftime,
+  :type => :rvalue,
+  :arity => -3,
+  :doc => <<~DOC
+    Formats timestamp or timespan according to the directives in the given format string. The directives begins with a percent (%) character.
+    Any text not listed as a directive will be passed through to the output string.
+
+    A third optional timezone argument can be provided. The first argument will then be formatted to represent a local time in that
+    timezone. The timezone can be any timezone that is recognized when using the '%z' or '%Z' formats, or the word 'current', in which
+    case the current timezone of the evaluating process will be used. The timezone argument is case insensitive.
+
+    The default timezone, when no argument is provided, or when using the keyword `default`, is 'UTC'.
+
+    The directive consists of a percent (%) character, zero or more flags, optional minimum field width and
+    a conversion specifier as follows:
+    ```
+    %[Flags][Width]Conversion
+    ```
+
+    ### Flags that controls padding
+
+    | Flag  | Meaning
+    | ----  | ---------------
+    | -     | Don't pad numerical output
+    | _     | Use spaces for padding
+    | 0     | Use zeros for padding
+
+    ### `Timestamp` specific flags
+
+    | Flag  | Meaning
+    | ----  | ---------------
+    | #     | Change case
+    | ^     | Use uppercase
+    | :     | Use colons for %z
+
+    ### Format directives applicable to `Timestamp` (names and padding can be altered using flags):
+
+    **Date (Year, Month, Day):**
+
+    | Format | Meaning |
+    | ------ | ------- |
+    | Y | Year with century, zero-padded to at least 4 digits |
+    | C | year / 100 (rounded down such as 20 in 2009) |
+    | y | year % 100 (00..99) |
+    | m | Month of the year, zero-padded (01..12) |
+    | B | The full month name ("January") |
+    | b | The abbreviated month name ("Jan") |
+    | h | Equivalent to %b |
+    | d | Day of the month, zero-padded (01..31) |
+    | e | Day of the month, blank-padded ( 1..31) |
+    | j | Day of the year (001..366) |
+
+    **Time (Hour, Minute, Second, Subsecond):**
+
+    | Format | Meaning |
+    | ------ | ------- |
+    | H | Hour of the day, 24-hour clock, zero-padded (00..23) |
+    | k | Hour of the day, 24-hour clock, blank-padded ( 0..23) |
+    | I | Hour of the day, 12-hour clock, zero-padded (01..12) |
+    | l | Hour of the day, 12-hour clock, blank-padded ( 1..12) |
+    | P | Meridian indicator, lowercase ("am" or "pm") |
+    | p | Meridian indicator, uppercase ("AM" or "PM") |
+    | M | Minute of the hour (00..59) |
+    | S | Second of the minute (00..60) |
+    | L | Millisecond of the second (000..999). Digits under millisecond are truncated to not produce 1000 |
+    | N | Fractional seconds digits, default is 9 digits (nanosecond). Digits under a specified width are truncated to avoid carry up |
+
+    **Time (Hour, Minute, Second, Subsecond):**
+
+    | Format | Meaning |
+    | ------ | ------- |
+    | z   | Time zone as hour and minute offset from UTC (e.g. +0900) |
+    | :z  | hour and minute offset from UTC with a colon (e.g. +09:00) |
+    | ::z | hour, minute and second offset from UTC (e.g. +09:00:00) |
+    | Z   | Abbreviated time zone name or similar information.  (OS dependent) |
+
+    **Weekday:**
+
+    | Format | Meaning |
+    | ------ | ------- |
+    | A | The full weekday name ("Sunday") |
+    | a | The abbreviated name ("Sun") |
+    | u | Day of the week (Monday is 1, 1..7) |
+    | w | Day of the week (Sunday is 0, 0..6) |
+
+    **ISO 8601 week-based year and week number:**
+
+    The first week of YYYY starts with a Monday and includes YYYY-01-04.
+    The days in the year before the first week are in the last week of
+    the previous year.
+
+    | Format | Meaning |
+    | ------ | ------- |
+    | G | The week-based year |
+    | g | The last 2 digits of the week-based year (00..99) |
+    | V | Week number of the week-based year (01..53) |
+
+    **Week number:**
+
+    The first week of YYYY that starts with a Sunday or Monday (according to %U
+    or %W). The days in the year before the first week are in week 0.
+
+    | Format | Meaning |
+    | ------ | ------- |
+    | U | Week number of the year. The week starts with Sunday. (00..53) |
+    | W | Week number of the year. The week starts with Monday. (00..53) |
+
+    **Seconds since the Epoch:**
+
+    | Format | Meaning |
+    | s | Number of seconds since 1970-01-01 00:00:00 UTC. |
+
+    **Literal string:**
+
+    | Format | Meaning |
+    | ------ | ------- |
+    | n | Newline character (\n) |
+    | t | Tab character (\t) |
+    | % | Literal "%" character |
+
+    **Combination:**
+
+    | Format | Meaning |
+    | ------ | ------- |
+    | c | date and time (%a %b %e %T %Y) |
+    | D | Date (%m/%d/%y) |
+    | F | The ISO 8601 date format (%Y-%m-%d) |
+    | v | VMS date (%e-%^b-%4Y) |
+    | x | Same as %D |
+    | X | Same as %T |
+    | r | 12-hour time (%I:%M:%S %p) |
+    | R | 24-hour time (%H:%M) |
+    | T | 24-hour time (%H:%M:%S) |
+
+    **Example**: Using `strftime` with a `Timestamp`:
+
+    ~~~ puppet
+    $timestamp = Timestamp('2016-08-24T12:13:14')
+
+    # Notice the timestamp using a format that notices the ISO 8601 date format
+    notice($timestamp.strftime('%F')) # outputs '2016-08-24'
+
+    # Notice the timestamp using a format that notices weekday, month, day, time (as UTC), and year
+    notice($timestamp.strftime('%c')) # outputs 'Wed Aug 24 12:13:14 2016'
+
+    # Notice the timestamp using a specific timezone
+    notice($timestamp.strftime('%F %T %z', 'PST')) # outputs '2016-08-24 04:13:14 -0800'
+
+    # Notice the timestamp using timezone that is current for the evaluating process
+    notice($timestamp.strftime('%F %T', 'current')) # outputs the timestamp using the timezone for the current process
+    ~~~
+
+    ### Format directives applicable to `Timespan`:
+
+    | Format | Meaning |
+    | ------ | ------- |
+    | D | Number of Days |
+    | H | Hour of the day, 24-hour clock |
+    | M | Minute of the hour (00..59) |
+    | S | Second of the minute (00..59) |
+    | L | Millisecond of the second (000..999). Digits under millisecond are truncated to not produce 1000. |
+    | N | Fractional seconds digits, default is 9 digits (nanosecond). Digits under a specified length are truncated to avoid carry up |
+
+    The format directive that represents the highest magnitude in the format will be allowed to overflow.
+    I.e. if no "%D" is used but a "%H" is present, then the hours will be more than 23 in case the
+    timespan reflects more than a day.
+
+    **Example**: Using `strftime` with a Timespan and a format
+
+    ~~~ puppet
+    $duration = Timespan({ hours => 3, minutes => 20, seconds => 30 })
+
+    # Notice the duration using a format that outputs <hours>:<minutes>:<seconds>
+    notice($duration.strftime('%H:%M:%S')) # outputs '03:20:30'
+
+    # Notice the duration using a format that outputs <minutes>:<seconds>
+    notice($duration.strftime('%M:%S')) # outputs '200:30'
+    ~~~
+
+    - Since 4.8.0
+  DOC
+) do |_args|
+  Puppet::Parser::Functions::Error.is4x('strftime')
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Tag the current scope with each passed name
+Puppet::Parser::Functions.newfunction(:tag, :arity => -2, :doc => "Add the specified tags to the containing class
+  or definition.  All contained objects will then acquire that tag, also.
+  ") do |vals|
+  if Puppet[:tasks]
+    raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+      Puppet::Pops::Issues::CATALOG_OPERATION_NOT_SUPPORTED_WHEN_SCRIPTING,
+      { :operation => 'tag' }
+    )
+  end
+
+  resource.tag(*vals)
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Test whether a given tag is set.  This functions as a big OR -- if any of the specified tags are unset, we return false.
+Puppet::Parser::Functions.newfunction(:tagged, :type => :rvalue, :arity => -2, :doc => "A boolean function that
+  tells you whether the current container is tagged with the specified tags.
+  The tags are ANDed, so that all of the specified tags must be included for
+  the function to return true.") do |vals|
+  if Puppet[:tasks]
+    raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+      Puppet::Pops::Issues::CATALOG_OPERATION_NOT_SUPPORTED_WHEN_SCRIPTING,
+      { :operation => 'tagged' }
+    )
+  end
+
+  retval = true
+  vals.each do |val|
+    unless compiler.catalog.tagged?(val) or resource.tagged?(val)
+      retval = false
+      break
+    end
+  end
+
+  return retval
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+Puppet::Parser::Functions.newfunction(:template, :type => :rvalue, :arity => -2, :doc =>
+  "Loads an ERB template from a module, evaluates it, and returns the resulting
+  value as a string.
+
+  The argument to this function should be a `<MODULE NAME>/<TEMPLATE FILE>`
+  reference, which will load `<TEMPLATE FILE>` from a module's `templates`
+  directory. (For example, the reference `apache/vhost.conf.erb` will load the
+  file `<MODULES DIRECTORY>/apache/templates/vhost.conf.erb`.)
+
+  This function can also accept:
+
+  * An absolute path, which can load a template file from anywhere on disk.
+  * Multiple arguments, which will evaluate all of the specified templates and
+  return their outputs concatenated into a single string.") do |vals|
+  if Puppet[:tasks]
+    raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+      Puppet::Pops::Issues::FEATURE_NOT_SUPPORTED_WHEN_SCRIPTING,
+      { :feature => 'ERB template' }
+    )
+  end
+  vals.collect do |file|
+    # Use a wrapper, so the template can't get access to the full
+    # Scope object.
+    debug "Retrieving template #{file}"
+
+    wrapper = Puppet::Parser::TemplateWrapper.new(self)
+    wrapper.file = file
+    begin
+      wrapper.result
+    rescue => detail
+      info = detail.backtrace.first.split(':')
+      message = []
+      message << _("Failed to parse template %{file}:") % { file: file }
+      message << _("  Filepath: %{file_path}") % { file_path: info[0] }
+      message << _("  Line: %{line}") % { line: info[1] }
+      message << _("  Detail: %{detail}") % { detail: detail }
+      raise Puppet::ParseError, message.join("\n") + "\n"
+    end
+  end.join("")
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+Puppet::Parser::Functions.newfunction(
+  :then,
+  :type => :rvalue,
+  :arity => -2,
+  :doc => <<~DOC
+    Call a [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html)
+    with the given argument unless the argument is undef. Return `undef` if argument is
+    `undef`, and otherwise the result of giving the argument to the lambda.
+
+    This is useful to process a sequence of operations where an intermediate
+    result may be `undef` (which makes the entire sequence `undef`).
+    The `then` function is especially useful with the function `dig` which
+    performs in a similar way "digging out" a value in a complex structure.
+
+    **Example:** Using `dig` and `then`
+
+    ```puppet
+    $data = {a => { b => [{x => 10, y => 20}, {x => 100, y => 200}]}}
+    notice $data.dig(a, b, 1, x).then |$x| { $x * 2 }
+    ```
+
+    Would notice the value 200
+
+    Contrast this with:
+
+    ```puppet
+    $data = {a => { b => [{x => 10, y => 20}, {ex => 100, why => 200}]}}
+    notice $data.dig(a, b, 1, x).then |$x| { $x * 2 }
+    ```
+
+    Which would notice `undef` since the last lookup of 'x' results in `undef` which
+    is returned (without calling the lambda given to the `then` function).
+
+    As a result there is no need for conditional logic or a temporary (non local)
+    variable as the result is now either the wanted value (`x`) multiplied
+    by 2 or `undef`.
+
+    Calls to `then` can be chained. In the next example, a structure is using an offset based on
+    using 1 as the index to the first element (instead of 0 which is used in the language).
+    We are not sure if user input actually contains an index at all, or if it is
+    outside the range of available names.args.
+
+    **Example:** Chaining calls to the `then` function
+
+    ```puppet
+    # Names to choose from
+    $names = ['Ringo', 'Paul', 'George', 'John']
+
+    # Structure where 'beatle 2' is wanted (but where the number refers
+    # to 'Paul' because input comes from a source using 1 for the first
+    # element).
+
+    $data = ['singer', { beatle => 2 }]
+    $picked = assert_type(String,
+      # the data we are interested in is the second in the array,
+      # a hash, where we want the value of the key 'beatle'
+      $data.dig(1, 'beatle')
+        # and we want the index in $names before the given index
+        .then |$x| { $names[$x-1] }
+        # so we can construct a string with that beatle's name
+        .then |$x| { "Picked Beatle '${x}'" }
+    )
+    ```
+
+    Would notice "Picked Beatle 'Paul'", and would raise an error if the result
+    was not a String.
+
+    * Since 4.5.0
+
+  DOC
+) do |_args|
+  Puppet::Parser::Functions::Error.is4x('then')
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+Puppet::Parser::Functions.newfunction(
+  :type,
+  :type => :rvalue,
+  :arity => -1,
+  :doc => <<~DOC
+    Returns the data type of a given value with a given degree of generality.
+
+    ```puppet
+    type InferenceFidelity = Enum[generalized, reduced, detailed]
+
+    function type(Any $value, InferenceFidelity $fidelity = 'detailed') # returns Type
+    ```
+
+     **Example:** Using `type`
+
+     ``` puppet
+     notice type(42) =~ Type[Integer]
+     ```
+
+     Would notice `true`.
+
+     By default, the best possible inference is made where all details are retained.
+     This is good when the type is used for further type calculations but is overwhelmingly
+     rich in information if it is used in a error message.
+
+     The optional argument `$fidelity` may be given as (from lowest to highest fidelity):
+
+     * `generalized` - reduces to common type and drops size constraints
+     * `reduced` - reduces to common type in collections
+     * `detailed` - (default) all details about inferred types is retained
+
+     **Example:** Using `type()` with different inference fidelity:
+
+     ``` puppet
+     notice type([3.14, 42], 'generalized')
+     notice type([3.14, 42], 'reduced'')
+     notice type([3.14, 42], 'detailed')
+     notice type([3.14, 42])
+     ```
+
+     Would notice the four values:
+
+     1. 'Array[Numeric]'
+     2. 'Array[Numeric, 2, 2]'
+     3. 'Tuple[Float[3.14], Integer[42,42]]]'
+     4. 'Tuple[Float[3.14], Integer[42,42]]]'
+
+     * Since 4.4.0
+
+  DOC
+) do |_args|
+  Puppet::Parser::Functions::Error.is4x('type')
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative '../../../puppet/util/package'
+
+Puppet::Parser::Functions.newfunction(:versioncmp, :type => :rvalue, :arity => 2, :doc =>
+"Compares two version numbers.
+
+Prototype:
+
+    \$result = versioncmp(a, b)
+
+Where a and b are arbitrary version strings.
+
+This function returns:
+
+* `1` if version a is greater than version b
+* `0` if the versions are equal
+* `-1` if version a is less than version b
+
+Example:
+
+    if versioncmp('2.6-1', '2.4.5') > 0 {
+        notice('2.6-1 is > than 2.4.5')
+    }
+
+This function uses the same version comparison algorithm used by Puppet's
+`package` type.
+
+") do |args|
+  return Puppet::Util::Package.versioncmp(args[0], args[1])
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+Puppet::Parser::Functions.newfunction(
+  :with,
+  :type => :rvalue,
+  :arity => -1,
+  :doc => <<~DOC
+    Call a [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html)
+    with the given arguments and return the result. Since a lambda's scope is
+    local to the lambda, you can use the `with` function to create private blocks
+    of code within a class using variables whose values cannot be accessed outside
+    of the lambda.
+
+    **Example**: Using `with`
+
+    ~~~ puppet
+    # Concatenate three strings into a single string formatted as a list.
+    $fruit = with("apples", "oranges", "bananas") |$x, $y, $z| {
+      "${x}, ${y}, and ${z}"
+    }
+    $check_var = $x
+    # $fruit contains "apples, oranges, and bananas"
+    # $check_var is undefined, as the value of $x is local to the lambda.
+    ~~~
+
+    - Since 4.0.0
+  DOC
+) do |_args|
+  Puppet::Parser::Functions::Error.is4x('with')
+end