puppet 4.0.0 → 4.9.1

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

@@ -0,0 +1,185 @@
+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|
+  Error.is4x('strftime')
+end

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

@@ -0,0 +1,73 @@
+Puppet::Parser::Functions::newfunction(
+  :then,
+  :type => :rvalue,
+  :arity => -2,
+  :doc => <<-DOC
+Call a [lambda](https://docs.puppet.com/puppet/latest/reference/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|
+  Error.is4x('then')
+end

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

@@ -0,0 +1,53 @@
+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|
+  Error.is4x('type')
+end

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

@@ -3,18 +3,26 @@ Puppet::Parser::Functions::newfunction(
   :type => :rvalue,
   :arity => -1,
   :doc => <<-DOC
-Call a lambda code block with the given arguments. Since the parameters of the lambda
-are local to the lambda's scope, this can be used to create private sections
-of logic in a class so that the variables are not visible outside of the
-class.
+Call a [lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html)
+with the given arguments and return the result. Since a lambda's scope is
+[local](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html#lambda-scope)
+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:
+**Example**: Using `with`
 
-     # notices the array [1, 2, 'foo']
-     with(1, 2, 'foo') |$x, $y, $z| { notice [$x, $y, $z] }
+~~~ 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
+- Since 4.0.0
 DOC
 ) do |args|
-  function_fail(["with() is only available when parser/evaluator future is in effect"])
+  Error.is4x('with')
 end

data/lib/puppet/parser/functions.rb

@@ -1,5 +1,6 @@
 require 'puppet/util/autoload'
 require 'puppet/parser/scope'
+require 'puppet/pops/adaptable'
 
 # A module for managing parser functions.  Each specified function
 # is added to a central module that then gets included into the Scope
@@ -17,12 +18,12 @@ module Puppet::Parser::Functions
   #
   # @api private
   def self.reset
-    @modules = {}
-
     # Runs a newfunction to create a function for each of the log levels
+    root_env = Puppet.lookup(:root_environment)
+    AnonymousModuleAdapter.clear(root_env)
     Puppet::Util::Log.levels.each do |level|
       newfunction(level,
-                  :environment => Puppet.lookup(:root_environment),
+                  :environment => root_env,
                   :doc => "Log a message on the server at level #{level.to_s}.") do |vals|
         send(level, vals.join(" "))
       end
@@ -36,26 +37,37 @@ module Puppet::Parser::Functions
     @autoloader ||= Puppet::Util::Autoload.new(self, "puppet/parser/functions")
   end
 
+  # An adapter that ties the anonymous module that acts as the container for all 3x functions to the environment
+  # where the functions are created. This adapter ensures that the life-cycle of those functions doesn't exceed
+  # the life-cycle of the environment.
+  #
+  # @api private
+  class AnonymousModuleAdapter < Puppet::Pops::Adaptable::Adapter
+    attr_accessor :module
+  end
+
   # Get the module that functions are mixed into corresponding to an
   # environment
   #
   # @api private
   def self.environment_module(env)
-    @modules[env.name] ||= Module.new do
-      @metadata = {}
+    AnonymousModuleAdapter.adapt(env) do |a|
+      a.module ||= Module.new do
+        @metadata = {}
 
-      def self.all_function_info
-        @metadata
-      end
+        def self.all_function_info
+          @metadata
+        end
 
-      def self.get_function_info(name)
-        @metadata[name]
-      end
+        def self.get_function_info(name)
+          @metadata[name]
+        end
 
-      def self.add_function_info(name, info)
-        @metadata[name] = info
+        def self.add_function_info(name, info)
+          @metadata[name] = info
+        end
       end
-    end
+    end.module
   end
 
   # Create a new Puppet DSL function.
@@ -70,7 +82,7 @@ module Puppet::Parser::Functions
   # extend the behavior and functionality of Puppet.
   #
   # See also [Docs: Custom
-  # Functions](http://docs.puppetlabs.com/guides/custom_functions.html)
+  # Functions](https://docs.puppetlabs.com/guides/custom_functions.html)
   #
   # @example Define a new Puppet DSL Function
   #     >> Puppet::Parser::Functions.newfunction(:double, :arity => 1,
@@ -113,7 +125,7 @@ module Puppet::Parser::Functions
   #   This string will be extracted by documentation generation tools.
   #
   # @option options [Integer] :arity (-1) the
-  #   [arity](http://en.wikipedia.org/wiki/Arity) of the function.  When
+  #   [arity](https://en.wikipedia.org/wiki/Arity) of the function.  When
   #   specified as a positive integer the function is expected to receive
   #   _exactly_ the specified number of arguments.  When specified as a
   #   negative number, the function is expected to receive _at least_ the
@@ -257,4 +269,10 @@ module Puppet::Parser::Functions
       environment_module(environment).get_function_info(name.intern) || environment_module(Puppet.lookup(:root_environment)).get_function_info(name.intern)
     end
   end
+
+  class Error
+    def self.is4x(name)
+      raise Puppet::ParseError, "#{name}() can only be called using the 4.x function API. See Scope#call_function"
+    end
+  end
 end