puppet 4.7.1-universal-darwin → 4.8.0-universal-darwin

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

@@ -0,0 +1,38 @@
+Puppet::Parser::Functions::newfunction(
+  :next,
+  :arity => -2,
+  :doc => <<-DOC
+Immediately returns the given optional value from a block (lambda), function, class body or user defined type body.
+If a value is not given, an `undef` value is returned. This function does not return to the immediate caller.
+
+The signal produced to return a value bubbles up through
+the call stack until reaching a code block (lambda), function, class definition or
+definition of a user defined type at which point the value given to the function will
+be produced as the result of that body of code. An error is raised
+if the signal to return a value reaches the end of the call stack.
+
+**Example:** Using `next` in `each`
+
+```puppet
+$data = [1,2,3]
+$data.each |$x| { if $x == 2 { next() } notice $x }
+```
+
+Would notice the values `1` and `3`
+
+**Example:** Using `next` to produce a value
+
+If logic consists of deeply nested conditionals it may be complicated to get out of the innermost conditional.
+A call to `next` can then simplify the logic. This example however, only shows the principle.
+```puppet
+$data = [1,2,3]
+notice $data.map |$x| { if $x == 2 { next($x*100) }; $x*10 }
+```
+Would notice the value `[10, 200, 30]`
+
+* Also see functions `return` and `break`
+* Since 4.8.0
+DOC
+) do |args|
+  Error.is4x('next')
+end

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

@@ -102,5 +102,5 @@ $combine = $data.reduce( [d, 4] ) |$memo, $value| {
 - Since 4.0.0
 DOC
 ) do |args|
-  function_fail(["reduce() is only available when parser/evaluator future is in effect"])
+  Error.is4x('reduce')
 end

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

@@ -24,7 +24,8 @@
 # other dealings in this Software without prior written authorization
 # from Thomas Bellman.
 
-Puppet::Parser::Functions::newfunction(
+module Puppet::Parser::Functions
+  newfunction(
   :regsubst, :type => :rvalue,
   :arity => -4,
 
@@ -56,5 +57,6 @@ Put angle brackets around each octet in the node's IP address:
 
     $x = regsubst($ipaddress, '([0-9]+)', '<\\1>', 'G')
 ") do |args|
-    function_fail(['regsubst() has been converted to 4x API'])
+    Error.is4x('regsubst')
+end
 end

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

@@ -33,31 +33,8 @@ you may also directly use Class and Resource Type values that are produced when
 resource and relationship expressions.
 
 - Since 4.0.0 Class and Resource types, absolute names
-") do |vals|
-  # Make call patterns uniform and protected against nested arrays, also make
-  # names absolute if so desired.
-  vals = transform_and_assert_classnames(vals.is_a?(Array) ? vals.flatten : [vals])
-
-  # This is the same as calling the include function (but faster) since it again
-  # would otherwise need to perform the optional absolute name transformation
-  # (for no reason since they are already made absolute here).
-  #
-  compiler.evaluate_classes(vals, self, false)
-
-  vals.each do |klass|
-    # lookup the class in the scopes
-    if classobj = environment.known_resource_types.find_hostclass(klass)
-      klass = classobj.name
-    else
-      raise Puppet::ParseError, "Could not find class #{klass}"
-    end
-
-    # This is a bit hackish, in some ways, but it's the only way
-    # to configure a dependency that will make it to the client.
-    # The 'obvious' way is just to add an edge in the catalog,
-    # but that is considered a containment edge, not a dependency
-    # edge, so it usually gets lost on the client.
-    ref = Puppet::Resource.new(:class, klass)
-    resource.set_parameter(:require, [resource[:require]].flatten.compact << ref)
-  end
+- Since 4.7.0 Returns an Array[Type[Class]] with references to the required classes
+") do |classes|
+  Puppet.warn_once(:deprecation, '3xfunction#require', "Calling function_require via the Scope class is deprecated. Use Scope#call_function instead")
+  call_function('require', classes)
 end

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

@@ -0,0 +1,71 @@
+Puppet::Parser::Functions::newfunction(
+  :return,
+  :arity => -2,
+  :doc => <<-DOC
+Immediately returns the given optional value from a function, class body or user defined type body.
+If a value is not given, an `undef` value is returned. This function does not return to the immediate caller.
+If called from within a lambda the return will return from the function evaluating the lambda.
+
+The signal produced to return a value bubbles up through
+the call stack until reaching a function, class definition or
+definition of a user defined type at which point the value given to the function will
+be produced as the result of that body of code. An error is raised
+if the signal to return a value reaches the end of the call stack.
+
+**Example:** Using `return`
+
+```puppet
+function example($x) {
+  # handle trivial cases first for better readability of
+  # what follows
+  if $x == undef or $x == [] or $x == '' {
+    return false
+  }
+  # complex logic to determine if value is true
+  true 
+}
+notice example([]) # would notice false
+notice example(42) # would notice true
+```
+
+**Example:** Using `return` in a class
+
+```puppet
+class example($x) {
+  # handle trivial cases first for better readability of
+  # what follows
+  if $x == undef or $x == [] or $x == '' {
+    # Do some default configuration of this class
+    notice 'foo'
+    return()
+  }
+  # complex logic configuring the class if something more interesting
+  # was given in $x
+  notice 'bar'
+}
+```
+
+When used like this:
+
+```puppet
+class { example: x => [] }
+```
+
+The code would notice `'foo'`, but not `'bar'`.
+
+When used like this:
+
+```puppet
+class { example: x => [some_value] }
+```
+
+The code would notice `'bar'` but not `'foo'`
+
+Note that the returned value is ignored if used in a class or user defined type.
+
+* Also see functions `return` and `break`
+* Since 4.8.0
+DOC
+) do |args|
+  Error.is4x('return')
+end

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

@@ -79,5 +79,5 @@ $transformed_data = map(reverse_each($data)) |$item| { $item * 10 }
 
 DOC
 ) do |args|
-  function_fail(["reverse_each() is only available when parser/evaluator future is in effect"])
+  Error.is4x('reverse_each')
 end

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

@@ -14,17 +14,22 @@ the format string. The result of the scan is an array, with each successfully sc
 The scanning stops if a scan is unsuccessful, and the scanned result up to that point is returned. If there
 was no successful scan, the result is an empty array.
 
-   "42".scanf("%i")
+```puppet
+"42".scanf("%i")
+```
 
 You can also optionally pass a lambda to scanf, to do additional validation or processing.
 
-    "42".scanf("%i") |$x| {
-      unless $x[0] =~ Integer {
-        fail "Expected a well formed integer value, got '$x[0]'"
-      }
-      $x[0]
-    }
-- since 4.0.0
+```puppet
+"42".scanf("%i") |$x| {
+  unless $x[0] =~ Integer {
+    fail "Expected a well formed integer value, got '$x[0]'"
+  }
+  $x[0]
+}
+```
+
+- Since 4.0.0
 DOC
 ) do |args|
   data = args[0]

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

@@ -35,5 +35,5 @@ to empty arrays for a hash.
 - Since 4.0.0
 DOC
 ) do |args|
-  function_fail(["slice() is only available when parser/evaluator future is in effect"])
+  Error.is4x('slice')
 end

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

@@ -23,6 +23,6 @@ a regexp meta-character (.), which must be escaped.  A simple
 way to do that for a single character is to enclose it in square
 brackets; a backslash will also escape a single character.") do |args|
 
-    function_fail(['split() has been converted to 4x API'])
+    Error.is4x('split')
   end
 end

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

@@ -80,5 +80,5 @@ $transformed_data contains [0,50,100,150,200]
 
 DOC
 ) do |args|
-  function_fail(["step() is only available when parser/evaluator future is in effect"])
+  Error.is4x('step')
 end

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

@@ -69,5 +69,5 @@ was not a String.
 
 DOC
 ) do |args|
-  function_fail(["then() is only available when parser/evaluator future is in effect"])
+  Error.is4x('then')
 end

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

@@ -49,5 +49,5 @@ function type(Any $value, InferenceFidelity $fidelity = 'detailed') # returns Ty
 
 DOC
 ) do |args|
-  function_fail(["type() is only available when parser/evaluator future is in effect"])
+  Error.is4x('type')
 end

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

@@ -13,8 +13,8 @@ class using variables whose values cannot be accessed outside of the lambda.
 
 ~~~ puppet
 # Concatenate three strings into a single string formatted as a list.
-$fruit = with("apples", "oranges", "bananas") |$x, $y, $z| { 
-  "${x}, ${y}, and ${z}" 
+$fruit = with("apples", "oranges", "bananas") |$x, $y, $z| {
+  "${x}, ${y}, and ${z}"
 }
 $check_var = $x
 # $fruit contains "apples, oranges, and bananas"
@@ -24,5 +24,5 @@ $check_var = $x
 - Since 4.0.0
 DOC
 ) do |args|
-  function_fail(["with() is only available when parser/evaluator future is in effect"])
+  Error.is4x('with')
 end