puppet 5.4.0-universal-darwin → 5.5.0-universal-darwin

data/lib/puppet/functions/assert_type.rb

@@ -10,7 +10,7 @@
 #
 # @example Using `assert_type`
 #
-# ~~~ puppet
+# ```puppet
 # $raw_username = 'Amy Berry'
 #
 # # Assert that $raw_username is a non-empty string and assign it to $valid_username.
@@ -19,7 +19,7 @@
 # # $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:
@@ -29,7 +29,7 @@
 #
 # @example Using `assert_type` with a warning and default value
 #
-# ~~~ puppet
+# ```puppet
 # $raw_username = 'Amy Berry'
 #
 # # Assert that $raw_username is a non-empty string and assign it to $valid_username.
@@ -43,7 +43,7 @@
 # # 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://docs.puppetlabs.com/puppet/latest/reference/lang_data.html).

data/lib/puppet/functions/binary_file.rb

@@ -1,5 +1,17 @@
-# Loads a binary file from a module or file system and returns its contents as a Binary.
-# (Documented in 3.x stub)
+# 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
 #
 # @since 4.8.0
 #

data/lib/puppet/functions/break.rb

@@ -1,6 +1,35 @@
-# Make iteration break as if there were no more values to process
+# Breaks an innermost iteration as if it encountered an end of input.
+# This function does not return to the caller.
 #
-# @since 4.7.0
+# 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
 #
 Puppet::Functions.create_function(:break) do
   dispatch :break_impl do

data/lib/puppet/functions/call.rb

@@ -8,20 +8,20 @@
 #
 # @example Using the `call` function
 #
-# ~~~ puppet
+# ```puppet
 # $a = 'notice'
 # call($a, 'message')
-# ~~~
+# ```
 #
 # @example Using the `call` function with a lambda
 #
-# ~~~ puppet
+# ```puppet
 # $a = 'each'
 # $b = [1,2,3]
 # call($a, $b) |$item| {
 #  notify { $item: }
 # }
-# ~~~
+# ```
 #
 # The `call` function can be used to call either Ruby functions or Puppet language
 # functions.

data/lib/puppet/functions/contain.rb

@@ -1,6 +1,22 @@
-# Called within a class definition, establishes a containment
-# relationship with another class
-# For documentation, see the 3.x stub
+# Makes one or more classes be contained inside the current class.
+# If any of these classes are undeclared, they will be declared as if
+# there were declared 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 a value of type `Array[Type[Class[n]]]` is returned with all the contained classes
 #
 Puppet::Functions.create_function(:contain, Puppet::Functions::InternalFunction) do
   dispatch :contain do

data/lib/puppet/functions/convert_to.rb

@@ -1,4 +1,4 @@
-# The `convert_to(value, type)` is a convenience function does the same as `new(type, value)`.
+# The `convert_to(value, type)` is a convenience function that does the same as `new(type, value)`.
 # The difference in the argument ordering allows it to be used in chained style for
 # improved readability "left to right".
 #
@@ -7,14 +7,15 @@
 #
 # @example 'convert_to' instead of 'new'
 #
-# ~~~ puppet
-#   # using new operator - that is "calling the type" with operator ()
+# ```puppet
+#   # The harder to read variant:
+#   # Using new operator - that is "calling the type" with operator ()
 #   Hash(Array("abc").map |$i,$v| { [$i, $v] })
 #
+#   # The easier to read variant:
 #   # using 'convert_to'
 #   "abc".convert_to(Array).map |$i,$v| { [$i, $v] }.convert_to(Hash)
-#
-# ~~~
+# ```
 #
 # @since 5.4.0
 #

data/lib/puppet/functions/crit.rb

@@ -1,4 +1,4 @@
-# Log a message on the server at level crit.
+# Logs a message on the server at level `crit`.
 Puppet::Functions.create_function(:crit, Puppet::Functions::InternalFunction) do
   # @param values The values to log.
   # @return [Undef]

data/lib/puppet/functions/debug.rb

@@ -1,4 +1,4 @@
-# Log a message on the server at level debug.
+# Logs a message on the server at level `debug`.
 Puppet::Functions.create_function(:debug, Puppet::Functions::InternalFunction) do
   # @param values The values to log.
   # @return [Undef]

data/lib/puppet/functions/defined.rb

@@ -4,15 +4,17 @@
 # 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'`.
+# resource reference, or variable reference of the form `'$name'`. (Note that the `$` sign
+# is included in the string which must be in single quotes to prevent the `$` character
+# to be interpreted as interpolation.
 #
 # 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
+# @example Different types of `defined` function matches
 #
-# ~~~ puppet
+# ```puppet
 # # Matching resource types
 # defined("file")
 # defined("customtype")
@@ -21,19 +23,19 @@
 # defined("foo")
 # defined("foo::bar")
 #
-# # Matching variables
+# # Matching variables (note the single quotes)
 # 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
+# ```puppet
 # # Assign values to $is_defined_before and $is_defined_after using identical `defined`
 # # functions.
 #
@@ -46,7 +48,7 @@
 # $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`
@@ -64,7 +66,7 @@
 #
 # @example Matching multiple resources and resources by different types with `defined`
 #
-# ~~~ puppet
+# ```puppet
 # file { "/tmp/file1":
 #   ensure => file,
 # }
@@ -90,7 +92,7 @@
 # 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

data/lib/puppet/functions/dig.rb

@@ -1,5 +1,29 @@
-# Digs into a data structure.
-# (Documented in 3.x stub)
+# 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
 #

data/lib/puppet/functions/each.rb

@@ -20,7 +20,7 @@
 #
 # @example Using the `each` function with an array and a one-parameter lambda
 #
-# ~~~ puppet
+# ```puppet
 # # For the array $data, run a lambda that creates a resource for each item.
 # $data = ["routers", "servers", "workstations"]
 # $data.each |$item| {
@@ -30,14 +30,14 @@
 # }
 # # 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
+# ```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"}
@@ -48,7 +48,7 @@
 # }
 # # 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
@@ -56,7 +56,7 @@
 #
 # @example Using the `each` function with an array and a two-parameter lambda
 #
-# ~~~ puppet
+# ```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"]
@@ -67,14 +67,14 @@
 # }
 # # 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
+# ```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"}
@@ -85,7 +85,7 @@
 # }
 # # 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

data/lib/puppet/functions/emerg.rb

@@ -1,4 +1,4 @@
-# Log a message on the server at level emerg.
+# Logs a message on the server at level `emerg`.
 Puppet::Functions.create_function(:emerg, Puppet::Functions::InternalFunction) do
   # @param values The values to log.
   # @return [Undef]

data/lib/puppet/functions/empty.rb

@@ -0,0 +1,79 @@
+# Returns `true` if the given argument is an empty collection of values.
+#
+# This function can answer if one of the following is empty:
+# * `Array`, `Hash` - having zero entries
+# * `String`, `Binary` - having zero length
+#
+# For backwards compatibility with the stdlib function with the same name the
+# following data types are also accepted by the function instead of raising an error.
+# Using these is deprecated and will raise a warning:
+#
+# * `Numeric` - `false` is returned for all `Numeric` values.
+# * `Undef` - `true` is returned for all `Undef` values.
+#
+# @example Using `empty`
+#
+# ```puppet
+# notice([].empty)
+# notice(empty([]))
+# # would both notice 'true'
+# ```
+#
+# @since Puppet 5.5.0 - support for Binary
+#
+Puppet::Functions.create_function(:empty) do
+  dispatch :collection_empty do
+    param 'Collection', :coll
+  end
+
+  dispatch :string_empty do
+    param 'String', :str
+  end
+
+  dispatch :numeric_empty do
+    param 'Numeric', :num
+  end
+
+  dispatch :binary_empty do
+    param 'Binary', :bin
+  end
+
+  dispatch :undef_empty do
+    param 'Undef', :x
+  end
+
+  def collection_empty(coll)
+    coll.empty?
+  end
+
+  def string_empty(str)
+    str.empty?
+  end
+
+  # For compatibility reasons - return false rather than error on floats and integers
+  # (Yes, it is strange)
+  #
+  def numeric_empty(num)
+    deprecation_warning_for('Numeric')
+    false
+  end
+
+  def binary_empty(bin)
+    bin.length == 0
+  end
+
+  # For compatibility reasons - return true rather than error on undef
+  # (Yes, it is strange, but undef was passed as empty string in 3.x API)
+  #
+  def undef_empty(x)
+    deprecation_warning_for('Undef')
+    true
+  end
+
+  def deprecation_warning_for(arg_type)
+    stacktrace = Puppet::Pops::PuppetStack.stacktrace()
+    file, line = stacktrace[0] # defaults to nil
+    msg = _("Calling function empty() with %{arg_type} value is deprecated.") % { arg_type: arg_type }
+    Puppet.warn_once('deprecations', "empty-from-#{file}-#{line}", msg, file, line)
+  end
+end