puppet 5.3.4 → 6.29.0

data/lib/puppet/functions/split.rb

@@ -1,19 +1,21 @@
-# Split a string variable into an array using the specified pattern.
+# Splits a string into an array using a given pattern.
 # The pattern can be a string, regexp or regexp type.
 #
-# @example
+# @example Splitting a String value
 #
-#     $string     = 'v1.v2:v3.v4'
-#     $array_var1 = split($string, /:/)
-#     $array_var2 = split($string, '[.]')
-#     $array_var3 = split($string, Regexp['[.:]'])
+# ```puppet
+# $string     = 'v1.v2:v3.v4'
+# $array_var1 = split($string, /:/)
+# $array_var2 = split($string, '[.]')
+# $array_var3 = split($string, Regexp['[.:]'])
 #
-# `$array_var1` now holds the result `['v1.v2', 'v3.v4']`,
-# while `$array_var2` holds `['v1', 'v2:v3', 'v4']`, and
-# `$array_var3` holds `['v1', 'v2', 'v3', 'v4']`.
+# #`$array_var1` now holds the result `['v1.v2', 'v3.v4']`,
+# # while `$array_var2` holds `['v1', 'v2:v3', 'v4']`, and
+# # `$array_var3` holds `['v1', 'v2', 'v3', 'v4']`.
+# ```
 #
 # Note that in the second example, we split on a literal string that contains
-# a regexp meta-character (.), which must be escaped.  A simple
+# 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.
 #

data/lib/puppet/functions/step.rb

@@ -1,4 +1,76 @@
-# (Documentation in 3.x stub)
+# 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
 #
@@ -16,7 +88,7 @@ Puppet::Functions.create_function(:step) do
 
   def step(iterable, step)
     # produces an Iterable
-    Puppet::Pops::Types::Iterable.asserted_iterable(self, iterable).step(step)
+    Puppet::Pops::Types::Iterable.asserted_iterable(self, iterable, true).step(step)
   end
 
   def step_block(iterable, step, &block)

data/lib/puppet/functions/strftime.rb

@@ -1,7 +1,182 @@
-# (Documentation in 3.x stub)
+# 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.
 #
-# @since 4.8.0
+# 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
+# 
 Puppet::Functions.create_function(:strftime) do
   dispatch :format_timespan do
     param 'Timespan', :time_object
@@ -28,15 +203,9 @@ Puppet::Functions.create_function(:strftime) do
   end
 
   def legacy_strftime(format, timezone = nil)
-    stacktrace = Puppet::Pops::PuppetStack.stacktrace()
-    if stacktrace.size > 0
-      file, line = stacktrace[0]
-    else
-      file = nil
-      line = nil
-    end
+    file, line = Puppet::Pops::PuppetStack.top_of_stack
     Puppet.warn_once('deprecations', 'legacy#strftime',
-      _('The argument signature (String format, [String timezone]) is deprecated for #strfime. See #strftime documentation and Timespan type for more info'),
+      _('The argument signature (String format, [String timezone]) is deprecated for #strftime. See #strftime documentation and Timespan type for more info'),
       file, line)
     Puppet::Pops::Time::Timestamp.format_time(format, Time.now.utc, timezone)
   end

data/lib/puppet/functions/strip.rb

@@ -0,0 +1,58 @@
+# Strips leading and trailing spaces from a String
+#
+# This function is compatible with the stdlib function with the same name.
+#
+# The function does the following:
+# * For a `String` the conversion removes all leading and trailing ASCII white space characters such as space, tab, newline, and return.
+#   It does not remove other space-like characters like hard space (Unicode U+00A0). (Tip, `/^[[:space:]]/` regular expression
+#   matches all space-like characters).
+# * For an `Iterable[Variant[String, Numeric]]` (for example an `Array`) each value is processed and the conversion is not recursive.
+# * If the value is `Numeric` it is simply returned (this is for backwards compatibility).
+# * An error is raised for all other data types.
+#
+# @example Removing leading and trailing space from a String
+# ```puppet
+# " hello\n\t".strip()
+# strip(" hello\n\t")
+# ```
+# Would both result in `"hello"`
+#
+# @example Removing trailing space from strings in an Array
+# ```puppet
+# [" hello\n\t", " hi\n\t"].strip()
+# strip([" hello\n\t", " hi\n\t"])
+# ```
+# Would both result in `['hello', 'hi']`
+#
+Puppet::Functions.create_function(:strip) do
+
+  dispatch :on_numeric do
+    param 'Numeric', :arg
+  end
+
+  dispatch :on_string do
+    param 'String', :arg
+  end
+
+  dispatch :on_iterable do
+    param 'Iterable[Variant[String, Numeric]]', :arg
+  end
+
+  # unit function - since the old implementation skipped Numeric values
+  def on_numeric(n)
+    n
+  end
+
+  def on_string(s)
+    s.strip
+  end
+
+  def on_iterable(a)
+    a.map {|x| do_strip(x) }
+  end
+
+  def do_strip(x)
+    # x can only be a String or Numeric because type constraints have been automatically applied
+    x.is_a?(String) ? x.strip : x
+  end
+end

data/lib/puppet/functions/then.rb

@@ -1,5 +1,68 @@
-# (Documented in 3.x stub)
-# @since 4.5.0
+# Calls a [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html)
+# with the given argument unless the argument is `undef`.
+# Returns `undef` if the 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}, {not_x => 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}'" }
+# )
+# notice $picked
+# ```
+#
+# Would notice "Picked Beatle 'Paul'", and would raise an error if the result
+# was not a String.
+#
+# * Since 4.5.0
 #
 Puppet::Functions.create_function(:then) do
   dispatch :then do

data/lib/puppet/functions/tree_each.rb

@@ -1,4 +1,4 @@
-# Runs a [lambda](http://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html)
+# Runs a [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html)
 # recursively and repeatedly using values from a data structure, then returns the unchanged data structure, or if
 # a lambda is not given, returns an `Iterator` for the tree.
 #
@@ -6,13 +6,13 @@
 #
 # 1. An `Array`, `Hash`, `Iterator`, or `Object` that the function will iterate over.
 # 2. An optional hash with the options:
-#    * `include_containers` => `Optional[Boolean]` # default true - if containers should be given to the lambda
-#    * `include_values` => `Optional[Boolean]` # default true - if non containers should be given to the lambda
-#    * `include_root` => `Optional[Boolean]` # default true - if the root container should be given to the lambda
+#    * `include_containers` => `Optional[Boolean]` # default `true` - if containers should be given to the lambda
+#    * `include_values` => `Optional[Boolean]` # default `true` - if non containers should be given to the lambda
+#    * `include_root` => `Optional[Boolean]` # default `true` - if the root container should be given to the lambda
 #    * `container_type` => `Optional[Type[Variant[Array, Hash, Object]]]` # a type that determines what a container is - can only
 #       be set to a type that matches the default `Variant[Array, Hash, Object]`.
 #    * `order` => `Enum[depth_first, breadth_first]` # default ´depth_first`, the order in which elements are visited
-#    * `include_refs` => Optional[Boolean] # default `false`, if attributes in objects marked as bing of `reference` kind
+#    * `include_refs` => `Optional[Boolean]` # default `false`, if attributes in objects marked as bing of `reference` kind
 #       should be included.
 # 3. An optional lambda, which the function calls for each element in the first argument. It must
 #    accept one or two arguments; either `$path`, and `$value`, or just `$value`.
@@ -42,21 +42,19 @@
 #
 # @example depth- or breadth-first order
 #
-# ~~~ puppet
+# ```puppet
 # [1, [2, 3], 4]
-# ~~~
-# 
-# Results in:
-# 
-# If containers are skipped:
+# ```
 #
-# * `depth_first` order `1`, `2`, `3`, `4` 
-# * `breadth_first` order `1`, `4`,`2`, `3` 
+# If containers are skipped, results in:
 #
-# If containers and root, are included:
+# * `depth_first` order `1`, `2`, `3`, `4`
+# * `breadth_first` order `1`, `4`,`2`, `3`
 #
-# * `depth_first` order `[1, [2, 3], 4]`, `1`, `[2, 3]`, `2`, `3`, `4` 
-# * `breadth_first` order `[1, [2, 3], 4]`, `1`, `[2, 3]`, `4`, `2`, `3` 
+# If containers and root are included, results in:
+#
+# * `depth_first` order `[1, [2, 3], 4]`, `1`, `[2, 3]`, `2`, `3`, `4`
+# * `breadth_first` order `[1, [2, 3], 4]`, `1`, `[2, 3]`, `4`, `2`, `3`
 #
 # Typical use of the `tree_each` function include:
 # * a more efficient way to iterate over a tree than first using `flatten` on an array
@@ -67,60 +65,59 @@
 #
 # @example A flattened iteration over a tree excluding Collections
 #
-# ~~~ puppet
+# ```puppet
 # $data = [1, 2, [3, [4, 5]]]
 # $data.tree_each({include_containers => false}) |$v| { notice "$v" }
-# ~~~
+# ```
 #
 # This would call the lambda 5 times with with the following values in sequence: `1`, `2`, `3`, `4`, `5`
 #
 # @example A flattened iteration over a tree (including containers by default)
 #
-# ~~~ puppet
+# ```puppet
 # $data = [1, 2, [3, [4, 5]]]
 # $data.tree_each |$v| { notice "$v" }
-# ~~~
+# ```
 #
 # This would call the lambda 7 times with the following values in sequence:
 # `1`, `2`, `[3, [4, 5]]`, `3`, `[4, 5]`, `4`, `5`
 #
 # @example A flattened iteration over a tree (including only non root containers)
 #
-# ~~~ puppet
+# ```puppet
 # $data = [1, 2, [3, [4, 5]]]
 # $data.tree_each({include_values => false, include_root => false}) |$v| { notice "$v" }
-# ~~~
+# ```
 #
 # This would call the lambda 2 times with the following values in sequence:
 # `[3, [4, 5]]`, `[4, 5]`
-
+#
 # Any Puppet Type system data type can be used to filter what is
 # considered to be a container, but it must be a narrower type than one of
-# the default Array, Hash, Object types - for example it is not possible to make a
+# the default `Array`, `Hash`, `Object` types - for example it is not possible to make a
 # `String` be a container type.
 #
 # @example Only `Array` as container type
 #
-# ~~~ puppet
+# ```puppet
 # $data = [1, {a => 'hello', b => [100, 200]}, [3, [4, 5]]]
 # $data.tree_each({container_type => Array, include_containers => false} |$v| { notice "$v" }
-# ~~~
-# 
+# ```
+#
 # Would call the lambda 5 times with `1`, `{a => 'hello', b => [100, 200]}`, `3`, `4`, `5`
 #
 # **Chaining** When calling `tree_each` without a lambda the function produces an `Iterator`
 # that can be chained into another iteration. Thus it is easy to use one of:
-# 
-# * `reverse_each` - get "leaves before root" 
+#
+# * `reverse_each` - get "leaves before root"
 # * `filter` - prune the tree
 # * `map` - transform each element
-# * `reduce` - produce something else
 #
 # Note than when chaining, the value passed on is a `Tuple` with `[path, value]`.
 #
-# @example pruning a tree
-# 
-# ~~~ puppet
+# @example Pruning a tree
+#
+# ```puppet
 # # A tree of some complexity (here very simple for readability)
 # $tree = [
 #  { name => 'user1', status => 'inactive', id => '10'},
@@ -130,14 +127,14 @@
 #  $value = $v[1]
 #  $value =~ Hash and $value[status] == active
 # }
-# ~~~
+# ```
 #
 # Would notice `[[[1], {name => user2, status => active, id => 20}]]`, which can then be processed
 # further as each filtered result appears as a `Tuple` with `[path, value]`.
 #
 #
 # For general examples that demonstrates iteration see the Puppet
-# [iteration](https://docs.puppetlabs.com/puppet/latest/reference/lang_iteration.html)
+# [iteration](https://puppet.com/docs/puppet/latest/lang_iteration.html)
 # documentation.
 #
 # @since 5.0.0

data/lib/puppet/functions/type.rb

@@ -1,4 +1,45 @@
-# (Documentation in 3.x stub)
+# 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
 #
 Puppet::Functions.create_function(:type) do