puppet 4.4.2-x86-mingw32 → 4.5.0-x86-mingw32

data/lib/puppet/functions.rb

@@ -290,6 +290,45 @@ module Puppet::Functions
         dispatch(meth_name, &block)
       end
     end
+
+    # Allows types local to the function to be defined to ease the use of complex types
+    # in a 4.x function. Within the given block, calls to `type` can be made with a string
+    # 'AliasType = ExistingType` can be made to define aliases. The defined aliases are
+    # available for further aliases, and in all dispatchers.
+    #
+    # @since 4.5.0
+    # @api public
+    #
+    def self.local_types(&block)
+      if loader.nil?
+        raise ArgumentError, "No loader present. Call create_loaded_function(:myname, loader,...), instead of 'create_function' if running tests"
+      end
+      aliases = LocalTypeAliasesBuilder.new(loader, name)
+      aliases.instance_eval(&block)
+      # Add the loaded types to the builder
+      aliases.local_types.each do |type_alias_expr|
+        # Bind the type alias to the local_loader using the alias
+        t = Puppet::Pops::Loader::TypeDefinitionInstantiator.create_from_model(type_alias_expr, aliases.loader)
+
+        # Also define a method for convenient access to the defined type alias.
+        # Since initial capital letter in Ruby means a Constant these names use a prefix of 
+        # `type`. As an example, the type 'MyType' is accessed by calling `type_MyType`.
+        define_method("type_#{t.name}") { t }
+      end
+      # Store the loader in the class
+      @loader = aliases.loader
+    end
+
+    # Creates a new function instance in the given closure scope (visibility to variables), and a loader
+    # (visibility to other definitions). The created function will either use the `given_loader` or
+    # (if it has local type aliases) a loader that was constructed from the loader used when loading
+    # the function's class.
+    #
+    # TODO: It would be of value to get rid of the second parameter here, but that would break API.
+    #
+    def self.new(closure_scope, given_loader)
+      super(closure_scope, @loader || given_loader)
+    end
   end
 
   # Base class for all functions implemented in the puppet language
@@ -497,6 +536,36 @@ module Puppet::Functions
     end
   end
 
+  # The LocalTypeAliasBuilder is used by the 'local_types' method to collect the individual
+  # type aliases given by the function's author.
+  # 
+  class LocalTypeAliasesBuilder
+    attr_reader :local_types, :parser, :loader
+
+    def initialize(loader, name)
+      @loader = Puppet::Pops::Loader::PredefinedLoader.new(loader, :"local_function_#{name}")
+      @local_types = []
+      # get the shared parser used by puppet's compiler
+      @parser = Puppet::Pops::Parser::EvaluatingParser.singleton()
+    end
+
+    # Defines a local type alias, the given string should be a Puppet Language type alias expression
+    # in string form without the leading 'type' keyword.
+    # Calls to local_type must be made before the first parameter definition or an error will
+    # be raised.
+    # 
+    # @param assignment_string [String] a string on the form 'AliasType = ExistingType'
+    # @api public
+    #
+    def type(assignment_string)
+      result = parser.parse_string("type #{assignment_string}", nil) # no file source :-(
+      unless result.body.kind_of?(Puppet::Pops::Model::TypeAlias)
+        raise ArgumentError, "Expected a type alias assignment on the form 'AliasType = T', got '#{assignment_string}'"
+      end
+      @local_types << result.body
+    end
+  end
+
   private
 
   # @note WARNING: This style of creating functions is not public. It is a system

data/lib/puppet/functions/dig.rb

@@ -0,0 +1,39 @@
+# Returns a value for a sequence of given keys/indexes into a structure.
+# 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.
+#
+# @since 4.5.0
+#
+Puppet::Functions.create_function(:dig) do
+  dispatch :dig do
+    param 'Optional[Collection]', :data
+    repeated_param 'Any', :arg
+  end
+
+  def dig(data, *args)
+    walked_path = []
+    args.reduce(data) do | d, k |
+      return nil if d.nil? || k.nil?
+      if !(d.is_a?(Array) || d.is_a?(Hash))
+        raise ArgumentError, "The given data does not contain a Collection at #{walked_path}, got '#{d.class}'"
+      end
+      walked_path << k
+      d[k]
+    end
+  end
+end

data/lib/puppet/functions/lest.rb

@@ -0,0 +1,53 @@
+# Call a [lambda](https://docs.puppet.com/puppet/latest/reference/lang_lambdas.html)
+# (which should accept no arguments) if the argument given to the function is `undef`.
+# Returns the result of calling the lambda if the argument is `undef`, otherwwise the
+# given argument.
+#
+# The `lest` function is useful in a chain of `then` calls, or in general
+# as a guard against `undef` values. The function can be used to call `fail`, or to
+# return a default value.
+#
+# These two expressions are equivalent:
+# ~~~puppet
+# if $x == undef { do_things() }
+# lest($x) || { do_things() }
+# ~~
+#
+# @example Using `lest`
+#
+# ~~~ puppet
+# $data = {a => [ b, c ] }
+# notice $data.dig(a, b, c)
+#  .then |$x| { $x * 2 }
+#  .lest || { fail("no value for $data[a][b][c]" }
+# ~~~
+#
+# Would fail the operation because $data[a][b][c] results in `undef`
+#
+# In contrast - this example:
+#
+# ~~~ puppet
+# $data = {a => { b => { c => 10 } } }
+# notice $data.dig(a, b, c)
+#  .then |$x| { $x * 2 }
+#  .lest || { fail("no value for $data[a][b][c]" }
+# ~~~
+#
+# Would notice the value 20
+#
+# @since 4.5.0
+#
+Puppet::Functions.create_function(:lest) do
+  dispatch :lest do
+    param 'Any', :arg
+    block_param 'Callable[0,0]', :block
+  end
+
+  def lest(arg)
+    if arg.nil?
+      yield()
+    else
+      arg
+    end
+  end
+end

data/lib/puppet/functions/lookup.rb

@@ -122,54 +122,67 @@
 #
 # @since 4.0.0
 Puppet::Functions.create_function(:lookup, Puppet::Functions::InternalFunction) do
-  name_t = 'Variant[String,Array[String]]'
-  value_type_t = 'Type'
-  default_value_t = 'Any'
-  merge_t = 'Variant[String[1],Hash[String,Scalar]]'
-  block_t = "Callable[#{name_t}]"
-  option_pairs =
-      "value_type=>Optional[#{value_type_t}],"\
-      "default_value=>Optional[#{default_value_t}],"\
-      "override=>Optional[Hash[String,Any]],"\
-      "default_values_hash=>Optional[Hash[String,Any]],"\
-      "merge=>Optional[#{merge_t}]"
+
+  local_types do
+    type 'NameType         = Variant[String, Array[String]]'
+    type 'ValueType        = Type'
+    type 'DefaultValueType = Any'
+    type 'MergeType        = Variant[String[1], Hash[String, Scalar]]'
+    type 'BlockType        = Callable[NameType]'
+    type "OptionsWithName  = Struct[{\
+      name                => NameType,\
+      value_type          => Optional[ValueType],\
+      default_value       => Optional[DefaultValueType],\
+      override            => Optional[Hash[String,Any]],\
+      default_values_hash => Optional[Hash[String,Any]],\
+      merge               => Optional[MergeType]\
+    }]"
+    type "OptionsWithoutName = Struct[{\
+      value_type          => Optional[ValueType],\
+      default_value       => Optional[DefaultValueType],\
+      override            => Optional[Hash[String,Any]],\
+      default_values_hash => Optional[Hash[String,Any]],\
+      merge               => Optional[MergeType]\
+    }]"
+
+  end
 
   dispatch :lookup_1 do
     scope_param
-    param           name_t,       :name
-    optional_param  value_type_t, :value_type
-    optional_param  merge_t,      :merge
+    param           'NameType',       :name
+    optional_param  'ValueType',      :value_type
+    optional_param  'MergeType',      :merge
   end
 
   dispatch :lookup_2 do
     scope_param
-    param name_t,                     :name
-    param "Optional[#{value_type_t}]", :value_type
-    param "Optional[#{merge_t}]",      :merge
-    param default_value_t,            :default_value
+    param 'NameType',                 :name
+    param 'Optional[ValueType]',      :value_type
+    param 'Optional[MergeType]',      :merge
+    param 'DefaultValueType',         :default_value
   end
 
   dispatch :lookup_3 do
     scope_param
-    param           name_t,       :name
-    optional_param  value_type_t, :value_type
-    optional_param  merge_t,      :merge
-    required_block_param block_t, :block
+    param                'NameType',   :name
+    optional_param       'ValueType',  :value_type
+    optional_param       'MergeType',  :merge
+    required_block_param 'BlockType',  :block
   end
 
   # Lookup without name. Name then becomes a required entry in the options hash
   dispatch :lookup_4 do
     scope_param
-    param "Struct[{name=>#{name_t},#{option_pairs}}]", :options_hash
-    optional_block_param block_t, :block
+    param                'OptionsWithName', :options_hash
+    optional_block_param 'BlockType',       :block
   end
 
   # Lookup using name and options hash.
   dispatch :lookup_5 do
     scope_param
-    param 'Variant[String,Array[String]]', :name
-    param "Struct[{#{option_pairs}}]", :options_hash
-    optional_block_param block_t, :block
+    param                'Variant[String,Array[String]]', :name
+    param                'OptionsWithoutName',            :options_hash
+    optional_block_param 'BlockType',                     :block
   end
 
   def lookup_1(scope, name, value_type=nil, merge=nil)

data/lib/puppet/functions/new.rb

@@ -0,0 +1,502 @@
+# Creates a new instance/object of a given type.
+#
+# This functions makes it possible to create new instances of
+# concrete types. If a block is given it is called with the
+# just created instance as an argument.
+#
+# Calling this function is equivalent to directly
+# calling the type:
+#
+# @ example new and calling type directly are equivalent
+#
+# ~~~ puppet
+# $a = Integer.new("42")
+# $b = Integer("42")
+# ~~~
+#
+# This would convert the string "42" to the decimal value 42.
+#
+# @ example arguments by position or by name
+#
+# ~~~ puppet
+# $a = Integer.new("42", 8)
+# $b = Integer({from => "42", radix => 8})
+# ~~~
+#
+# This would convert the octal (radix 8) number "42" in string form
+# to the decimal value 34.
+#
+# The new function supports two ways of giving the arguments:
+#
+# * by name (using a hash with property to value mapping)
+# * by position (as regular arguments)
+#
+# Note that it is not possible to create new instances of
+# some abstract classes (e.g. `Variant`). The type Optional[T] is an
+# exception as it will create an instance of T or `undef` if the
+# value to convert is `undef`.
+#
+# The arguments that can be given to each type is
+# determined by the type.
+#
+# An assertion is always made that
+# the produced value complies with the given type constraints.
+#
+# @example type constraints are checked:
+#
+# ~~~ puppet
+#  Integer[0].new("-100")
+# ~~~
+# 
+# Would fail with an assertion error.
+#
+# The following sections show the arguments and conversion rules
+# per type built into the Puppet Type System.
+#
+# Conversion to Optional[T] and NotUndef[T]
+# -----------------------------------------
+# Conversion to these types is the same as a conversion to the type argument `T`. In the case of `Optional[T]`
+# it accepted that the result may be `undef` (i.e. not possible to convert).
+#
+# Conversion to Integer
+# ---------------------
+#
+# A new `Integer` can be created from `Integer`, `Float`, `Boolean`, and `String` values.
+# For conversion `from` String it is possible to specify the radix. 
+#
+# ~~~ puppet
+# type Radix = Variant[Default, Integer[2,2], Integer[8,8], Integer[10,10], Integer[16,16]]
+# Callable[String, Radix, 1, 2]
+# Callable[Variant[Numeric, Boolean]]
+# ~~~
+# 
+# * When converting from String the default radix is 10
+# * If radix is not specified an attempt is made to detect the radix from the start of the string:
+#   * `0b` or `0B` is taken as radix 2, 
+#   * `0x` or `0X` is taken as radix 16, 
+#   * `0` as radix 8,
+#   * all other are decimal 
+# * Conversion from String accepts an optional sign in the string.
+# * For hexadecimal (radix 16) conversion an optional leading "0x", or "0X" is accepted
+# * for octal (radix 8) an optional leading "0" is accepted
+# * for binary (radix 2) an optional leading "0b" or "0B" is accepted
+# * When `radix` is set to `default`, the conversion is based on the leading
+#   characters in the string. A leading "0" for radix 8, a leading "0x", or "0X" for
+#   radix 16, and leading "0b" or "0B" for binary.
+# * Conversion from Boolean results in 0 for `false` and 1 for `true`.
+# * Conversion from Integer, Float, and Boolean ignores the radix.
+# * Float value fractions are truncated (no rounding)
+#
+# @example Converting to Integer
+#
+# ~~~ puppet
+# $a_number = Integer("0xFF", 16)  # results in 255
+# $a_number = Numeric("010")       # results in 8
+# $a_number = Numeric("010", 10)   # results in 10
+# $a_number = Integer("true")      # results in 1
+# ~~~
+#
+# Conversion to Float
+# -------------------
+#
+# A new `Float` can be created from `Integer`, `Float`, `Boolean`, and `String` values.
+# For conversion `from` String both float and integer formats are supported.
+#
+# * For an integer, the floating point fraction of .0 is added to the value.
+# * A Boolean true is converted to 1.0, and a false to 0.0
+# * In String format, integer prefixes for hex and binary are understood (but not octal since
+#   floating point in string format may start with a '0'). 
+#
+# Conversion to Numeric
+# ---------------------
+#
+# A new Integer or Float can be created from Integer, Float, Boolean and
+# String values.
+#
+# ~~~ puppet
+# Callable[Variant[Numeric, Boolean, String]]
+# ~~~
+#
+# * If the value has a decimal period, or if given in scientific notation
+#   (e/E), the result is a `Float`, otherwise the value is an `Integer`. The
+#   conversion from `String` always uses a radix based on the prefix of the string.
+# * Conversion from Boolean results in 0 for `false` and 1 for `true`.
+#
+# @example Converting to Numeric
+#
+# ~~~ puppet
+# $a_number = Numeric("true")  # results in 1
+# $a_number = Numeric("0xFF")  # results in 255
+# $a_number = Numeric("010")   # results in 8
+# $a_number = Numeric("3.14")  # results in 3.14 (a float)
+# ~~~
+# 
+# Conversion to String
+# --------------------
+#
+# Conversion to String is the most comprehensive conversion as there are many
+# use cases where a String representation is wanted. The defaults for the many options
+# have been chosen with care to be the most basic "value in textual form" representation.
+#
+# A new String can be created from all other data types. The process is performed in
+# several steps - first the type of the given value is inferred, then the resulting type
+# is used to find the most significant format specified for that type. And finally,
+# the found format is used to convert the given value.
+#
+# The mapping from type to format is referred to as the format map. This map
+# allows different formatting depending on type.
+#
+# @example Positive Integers in Hexadecimal prefixed with '0x', negative in Decimal
+#
+# ~~~ puppet
+# $format_map = { Integer[default, 0] => "%d",
+#   Integer[1, default] => "%#x"
+# }
+# String("-1", $format_map)  # produces '-1'
+# String("10", $format_map)  # produces '0xa'
+# ~~~
+#
+# A format is specified on the form:
+#
+# ~~~
+# %[Flags][Width][.Precision]Format
+# ~~~
+#
+# `Width` is the number of characters into which the value should be fitted. This allocated space is
+# padded if value is shorter. By default it is space padded, and the flag 0 will cause padding with 0
+# for numerical formats.
+#
+# `Precision` is the number of fractional digits to show for floating point, and the maximum characters
+# included in a string format.
+#
+# Note that all data type supports the formats `s` and `p` with the meaning "default to string" and
+# "default programmatic string representation" (which for example means that a String is quoted in 'p' format).
+#
+# ### Signatures of String conversion
+#
+# ~~~ puppet
+# type Format = Pattern[/^%([\s\+\-#0\[\{<\(\|]*)([1-9][0-9]*)?(?:\.([0-9]+))?([a-zA-Z])/]
+# type ContainerFormat = Struct[{
+#   format         => Optional[String],
+#   separator      => Optional[String],
+#   separator2     => Optional[String],
+#   string_formats => Hash[Type, Format]
+#   }]
+# type TypeMap = Hash[Type, Variant[Format, ContainerFormat]]
+# type Formats = Variant[Default, String[1], TypeMap]
+#
+# Callable[Any, Formats]
+# ~~~
+#
+# Where:
+# * `separator` is the string used to separate entries in an array, or hash (extra space should not be included at
+#   then end), defaults to `","`
+# * `separator2` is the separator between key and value in a hash entry (space padding should be included as
+#   wanted), defaults to `" => ".
+# * `string_formats` is a type to format map for values contained in arrays and hashes - defaults to `{Any => "%p"}`. Note that
+#   these nested formats are not applicable to containers which are always formatted as per the top level format specification.
+#
+# @example Simple Conversion to String (using defaults)
+#
+# ~~~ puppet
+# $str = String(10)      # produces '10'
+# $str = String([10])    # produces '["10"]'
+# ~~~
+#
+# @example Simple Conversion to String specifying the format for the given value directly
+#
+# ~~~ puppet
+# $str = String(10, "%#x")    # produces '0x10'
+# $str = String([10], "%(a")  # produces '("10")'
+# ~~~
+#
+# @example Specifying type for values contained in an array
+#
+# ~~~ puppet
+# $formats = { Array => {format => '%(a', string_formats => { Integer => '%#x' } }
+# $str = String([1,2,3], $formats) # produces '(0x1, 0x2, 0x3)'
+# ~~~
+#
+# Given formats are merged with the default formats, and matching of values to convert against format is based on
+# the specificity of the mapped type; for example, different formats can be used for short and long arrays.
+#
+# ### Integer to String
+#
+# | Format  | Integer Formats
+# | ------  | ---------------
+# | d       | Decimal, negative values produces leading '-'
+# | x X     | Hexadecimal in lower or upper case. Uses ..f/..F for negative values unless # is also used
+# | o       | Octal. Uses ..0 for negative values unless # is also used
+# | b B     | Binary with prefix 'b' or 'B'. Uses ..1/..1 for negative values unless # is also used
+# | c       | numeric value representing a Unicode value, result is a one unicode character string, quoted if alternative flag # is used
+# | s       | same as d, or d in quotes if alternative flag # is used
+# | p       | same as d
+# | eEfgGaA | converts integer to float and formats using the floating point rules
+#
+# Defaults to `d`
+#
+# ### Float to String
+#
+# | Format  | Float formats
+# | ------  | -------------
+# | f       | floating point in non exponential notation
+# | e E     | exponential notation with 'e' or 'E'
+# | g G     | conditional exponential with 'e' or 'E' if exponent < -4 or >= the precision
+# | a A     | hexadecimal exponential form, using 'x'/'X' as prefix and 'p'/'P' before exponent
+# | s       | converted to string using format p, then applying string formatting rule, alternate form # quotes result
+# | p       | f format with minimum significant number of fractional digits, prec has no effect
+# | dxXobBc | converts float to integer and formats using the integer rules
+#
+# Defaults to `p`
+#
+# ### String to String
+#
+# | Format | String
+# | ------ | ------
+# | s      | unquoted string, verbatim output of control chars
+# | p      | programmatic representation - strings are quoted, interior quotes and control chars are escaped
+# | C      | each :: name segment capitalized, quoted if alternative flag # is used
+# | c      | capitalized string, quoted if alternative flag # is used
+# | d      | downcased string, quoted if alternative flag # is used
+# | u      | upcased string, quoted if alternative flag # is used
+# | t      | trims leading and trailing whitespace from the string, quoted if alternative flag # is used
+#
+# Defaults to `s` at top level and `p` inside array or hash.
+#
+# ### Boolean to String
+# 
+# | Format    | Boolean Formats
+# | ----      | -------------------   
+# | t T       | 'true'/'false' or 'True'/'False' , first char if alternate form is used (i.e. 't'/'f' or 'T'/'F').
+# | y Y       | 'yes'/'no', 'Yes'/'No', 'y'/'n' or 'Y'/'N' if alternative flag # is used
+# | dxXobB    | numeric value 0/1 in accordance with the given format which must be valid integer format
+# | eEfgGaA   | numeric value 0.0/1.0 in accordance with the given float format and flags
+# | s         | 'true' / 'false'
+# | p         | 'true' / 'false'
+#
+# ### Regexp to String
+#
+# | Format    | Regexp Formats (%/)
+# | ----      | ------------------
+# | s         | / / delimiters, alternate flag replaces / delimiters with quotes
+# | p         | / / delimiters
+#
+# ### Undef to String
+#
+# | Format    | Undef formats
+# | ------    | -------------
+# | s         | empty string, or quoted empty string if alternative flag # is used
+# | p         | 'undef', or quoted '"undef"' if alternative flag # is used
+# | n         | 'nil', or 'null' if alternative flag # is used
+# | dxXobB    | 'NaN'
+# | eEfgGaA   | 'NaN'
+# | v         | 'n/a'
+# | V         | 'N/A'
+# | u         | 'undef', or 'undefined' if alternative # flag is used
+#
+# ### Default value to String
+# 
+# | Format    | Default formats
+# | ------    | ---------------
+# | d D       | 'default' or 'Default', alternative form # causes value to be quoted
+# | s         | same as d
+# | p         | same as d
+#
+# ### Array & Tuple to String
+#
+# | Format    | Array/Tuple Formats
+# | ------    | -------------
+# | a         | formats with `[ ]` delimiters and `,`, alternate form `#` indents nested arrays/hashes
+# | s         | same as a
+# | p         | same as a
+#
+# See "Flags" `<[({\|` for formatting of delimiters, and "Additional parameters for containers; Array and Hash" for
+# more information about options.
+#
+# The alternate form flag `#` will cause indentation of nested array or hash containers. If width is also set
+# it is taken as the maximum allowed length of a sequence of elements (not including delimiters). If this max length
+# is exceeded, each element will be indented.
+#
+# ### Hash & Struct to String
+#
+# | Format    | Hash/Struct Formats
+# | ------    | -------------
+# | h         | formats with `{ }` delimiters, `,` element separator and ` => ` inner element separator unless overridden by flags 
+# | s         | same as h
+# | p         | same as h
+# | a         | converts the hash to an array of [k,v] tuples and formats it using array rule(s)
+# 
+# See "Flags" `<[({\|` for formatting of delimiters, and "Additional parameters for containers; Array and Hash" for
+# more information about options.
+#
+# The alternate form flag `#` will format each hash key/value entry indented on a separate line.
+#
+# ### Type to String
+# 
+# | Format    | Array/Tuple Formats
+# | ------    | -------------
+# | s         | The same as p, quoted if alternative flag # is used
+# | p         | Outputs the type in string form as specified by the Puppet Language
+#
+# ### Flags
+#
+# | Flag     | Effect 
+# | ------   | ------
+# | (space)  | space instead of + for numeric output (- is shown), for containers skips delimiters
+# | #        | alternate format; prefix 0x/0x, 0 (octal) and 0b/0B for binary, Floats force decimal '.'. For g/G keep trailing 0.
+# | +        | show sign +/- depending on value's sign, changes x,X, o,b, B format to not use 2's complement form
+# | -        | left justify the value in the given width
+# | 0        | pad with 0 instead of space for widths larger than value
+# | <[({\|   | defines an enclosing pair <> [] () {} or \| \| when used with a container type
+#
+# Conversion to Boolean
+# ---
+#
+# Accepts a single value as argument:
+# * Float 0.0 is `false`, all other float values are `true`
+# * Integer 0 is `false`, all other integer values are `true`
+# * Strings
+#   * `true` if 'true', 'yes', 'y' (case independent compare)
+#   * `false` if 'false', 'no', 'n' (case independent compare)
+# * Boolean is already boolean and is simply returned
+#
+# Conversion to Array and Tuple
+# ---
+#
+# When given a single value as argument:
+#
+# * A non empty `Hash` is converted to an array matching `Array[Tuple[Any,Any], 1]`
+# * An empty `Hash` becomes an empty array
+# * An `Array` is simply returned
+# * An `Iterable[T]` is turned into an array of `T` instances
+#
+# When given a second Boolean argument
+# * if `true`, a value that is not already an array is returned as a one element array
+# * if `false`, (the default), converts the first argument as shown above.
+#
+# @example ensuring value is array
+#
+# ~~~ puppet
+# $arr = Array($value, true)
+# ~~~
+#
+# Conversion to a `Tuple` works exactly as conversion to an `Array`, only that the constructed array is
+# asserted against the given tuple type.
+#
+# Conversion to Hash and Struct
+# ---
+# Accepts a single value as argument:
+#
+# * An empty `Array` becomes an empty hash
+# * An `Array` matching `Array[Tuple[Any,Any], 1]` is converted to a hash where each tuple describes a key/value entry
+# * An `Array` with an even number of entries is interpreted as `[key1, val1, key2, val2, ...]`
+# * An `Iterable` is turned into an `Array` and then converted to hash as per the array rules
+# * A `Hash` is simply returned
+#
+# Conversion to a `Struct` works exactly as conversion to a `Hash`, only that the constructed hash is
+# asserted against the given struct type.
+#
+# Creating a SemVer
+# ---
+# A SemVer object represents a single [Semantic Version](http://semver.org/).
+# It can be created from a String, individual values for its parts, or a hash specifying the value per part.
+# See the specification at [semver.org](http://semver.org/) for the meaning of the SemVer's parts.
+#
+# The signatures are:
+#
+# ~~~ puppet
+#
+# type PositiveInteger = Integer[0,default]
+# type SemVerQualifier = Pattern[/\A(?<part>[0-9A-Za-z-]+)(?:\.\g<part>)*\Z/]
+# type SemVerString = String[1]
+# type SemVerHash =Struct[{
+#   major                => PositiveInteger,
+#   minor                => PositiveInteger,
+#   patch                => PositiveInteger,
+#   Optional[prerelease] => SemVerQualifier,
+#   Optional[build]      => SemVerQualifier
+# }]
+# 
+# function SemVer.new(SemVerString $str)
+# function SemVer.new(
+#         PositiveInteger           $major
+#         PositiveInteger           $minor
+#         PositiveInteger           $patch
+#         Optional[SemVerQualifier] $prerelease = undef
+#         Optional[SemVerQualifier] $build = undef
+#         )
+# function SemVer.new(SemVerHash $hash_args)
+#
+# ~~~
+#
+# Examples of SemVer and SemVerRange usage:
+#
+# ~~~ puppet
+#
+# # As a type, SemVer can describe disjunct ranges which versions can be matched
+# # against - here the type is constructed with two SemVerRange objects.
+# $t = SemVer[SemVerRange('>=1.0.0 <2.0.0'), SemVerRange('>=3.0.0 <4.0.0')]
+# notice(SemVer('1.2.3') =~ $t) # true
+# notice(SemVer('2.3.4') =~ $t) # false
+# notice(SemVer('3.4.5') =~ $t) # true
+#
+# ~~~
+#
+# Creating a SemVerRange
+# ---
+# A SemVerRange object represents a range of SemVer. It can be created from
+# a String, from two SemVer instances, where either end can be given as
+# a literal `default` to indicate infinity. The string format of a SemVerRange is specified by
+# the [Semantic Version Range Grammar](https://github.com/npm/node-semver#ranges).
+# Use of the comparator sets described in the grammar (joining with `||`) is not supported.
+#
+# The signatures are:
+#
+# ~~~ puppet
+# type SemVerRangeString = String[1]
+# type SemVerRangeHash = Struct[{
+#   min                   => Variant[default, SemVer],
+#   Optional[max]         => Variant[default, SemVer],
+#   Optional[exclude_max] => Boolean
+# }]
+# 
+# function SemVerRange.new( SemVerRangeString $semver_range_string)
+# 
+# function SemVerRange.new(
+#               Variant[default,SemVer] $min
+#               Variant[default,SemVer] $max
+#               Optional[Boolean]       $exclude_max = undef
+#             }
+# function SemVerRange.new(SemVerRangeHash $semver_range_hash)
+# ~~~
+#
+# For examples, see `SemVer.new`.
+#
+# @since 4.5.0
+#
+Puppet::Functions.create_function(:new, Puppet::Functions::InternalFunction) do
+
+  dispatch :new_instance do
+    scope_param
+    param          'Type', :type
+    repeated_param 'Any',  :args
+    optional_block_param
+  end
+
+  def new_instance(scope, t, *args)
+    result = catch :undefined_value do
+      new_function_for_type(t, scope).call(scope, *args)
+    end
+    assert_type(t, result)
+    return block_given? ? yield(result) : result
+  end
+
+  def new_function_for_type(t, scope)
+    @new_function_cache ||= Hash.new() {|hsh, key| hsh[key] = key.new_function(loader).new(scope, loader) }
+    @new_function_cache[t]
+  end
+
+  def assert_type(type, value)
+    Puppet::Pops::Types::TypeAsserter.assert_instance_of('new():', type, value)
+  end
+end