puppet 4.5.3-x64-mingw32 → 4.6.1-x64-mingw32

data/lib/puppet/parser/ast/resource_instance.rb

@@ -2,5 +2,9 @@
 # title and a set of parameters.
 #
 class Puppet::Parser::AST::ResourceInstance < Puppet::Parser::AST::Branch
-    attr_accessor :title, :parameters
+  attr_accessor :title, :parameters
+  def initialize(argshash)
+    Puppet.warn_once('deprecation', 'AST::ResourceInstance', 'Use of Puppet::Parser::AST::ResourceInstance is deprecated')
+    super(argshash)
+  end
 end

data/lib/puppet/parser/ast/resourceparam.rb

@@ -3,6 +3,11 @@
 class Puppet::Parser::AST::ResourceParam < Puppet::Parser::AST::Branch
   attr_accessor :value, :param, :add
 
+  def initialize(argshash)
+    Puppet.warn_once('deprecation', 'AST::ResourceParam', 'Use of Puppet::Parser::AST::ResourceParam is deprecated and not fully functional')
+    super(argshash)
+  end
+
   def each
     [@param, @value].each { |child| yield child }
   end

data/lib/puppet/parser/compiler.rb

@@ -4,7 +4,6 @@ require 'puppet/node'
 require 'puppet/resource/catalog'
 require 'puppet/util/errors'
 
-require 'puppet/resource/type_collection_helper'
 require 'puppet/loaders'
 require 'puppet/pops'
 
@@ -16,7 +15,6 @@ class Puppet::Parser::Compiler
   include Puppet::Util
   include Puppet::Util::Errors
   include Puppet::Util::MethodHelper
-  include Puppet::Resource::TypeCollectionHelper
   include Puppet::Pops::Evaluator::Runtime3Support
 
   def self.compile(node, code_id = nil)
@@ -139,9 +137,6 @@ class Puppet::Parser::Compiler
     end
   end
 
-  # Do we use nodes found in the code, vs. the external node sources?
-  def_delegator :known_resource_types, :nodes?, :ast_nodes?
-
   # Store the fact that we've evaluated a class
   def add_class(name)
     @catalog.add_class(name) unless name == ""
@@ -267,7 +262,7 @@ class Puppet::Parser::Compiler
   def evaluate_site
     # Has a site been defined? If not, do nothing but issue a warning.
     #
-    site = known_resource_types.find_site()
+    site = environment.known_resource_types.find_site()
     unless site
       on_empty_site()
       return
@@ -384,7 +379,7 @@ class Puppet::Parser::Compiler
     end
 
     hostclasses = classes.collect do |name|
-      scope.find_hostclass(name) or raise Puppet::Error, "Could not find class #{name} for #{node.name}"
+      environment.known_resource_types.find_hostclass(name) or raise Puppet::Error, "Could not find class #{name} for #{node.name}"
     end
 
     if class_parameters
@@ -507,7 +502,7 @@ class Puppet::Parser::Compiler
   end
 
   def evaluate_capability_mappings
-    krt = known_resource_types
+    krt = environment.known_resource_types
     krt.capability_mappings.each_value do |capability_mapping|
       args = capability_mapping.arguments
       component_ref = args['component']
@@ -540,15 +535,16 @@ class Puppet::Parser::Compiler
 
   # If ast nodes are enabled, then see if we can find and evaluate one.
   def evaluate_ast_node
-    return unless ast_nodes?
+    krt = environment.known_resource_types
+    return unless krt.nodes? #ast_nodes?
 
     # Now see if we can find the node.
     astnode = nil
     @node.names.each do |name|
-      break if astnode = known_resource_types.node(name.to_s.downcase)
+      break if astnode = krt.node(name.to_s.downcase)
     end
 
-    unless (astnode ||= known_resource_types.node("default"))
+    unless (astnode ||= krt.node("default"))
       raise Puppet::ParseError, "Could not find node statement with name 'default' or '#{node.names.join(", ")}'"
     end
 
@@ -627,9 +623,10 @@ class Puppet::Parser::Compiler
 
   # Find and evaluate our main object, if possible.
   def evaluate_main
-    @main = known_resource_types.find_hostclass("") || known_resource_types.add(Puppet::Resource::Type.new(:hostclass, ""))
+    krt = environment.known_resource_types
+    @main = krt.find_hostclass('') || krt.add(Puppet::Resource::Type.new(:hostclass, ''))
     @topscope.source = @main
-    @main_resource = Puppet::Parser::Resource.new("class", :main, :scope => @topscope, :source => @main)
+    @main_resource = Puppet::Parser::Resource.new('class', :main, :scope => @topscope, :source => @main)
     @topscope.resource = @main_resource
 
     add_resource(@topscope, @main_resource)
@@ -762,7 +759,7 @@ class Puppet::Parser::Compiler
     #
     Puppet.override( @context_overrides , "For initializing compiler") do
       # THE MAGIC STARTS HERE ! This triggers parsing, loading etc.
-      @catalog.version = known_resource_types.version
+      @catalog.version = environment.known_resource_types.version
     end
 
     @catalog.add_resource(Puppet::Parser::Resource.new("stage", :main, :scope => @topscope))
@@ -795,7 +792,7 @@ class Puppet::Parser::Compiler
     # 2.2.2 some other terminus having stored a fact called "trusted" (most likely that would have failed earlier, but could
     #       be spoofed).
     #
-    # For the reasons above, the resurection of trusted node data with authenticated => true is only performed
+    # For the reasons above, the resurrection of trusted node data with authenticated => true is only performed
     # if user is running as root, else it is resurrected as unauthenticated.
     #
     trusted_param = node.parameters['trusted']
@@ -807,7 +804,7 @@ class Puppet::Parser::Compiler
         trusted_param = nil
       end
     else
-      # trusted may be boolean false if set as a fact by someone
+      # trusted may be Boolean false if set as a fact by someone
       trusted_param = nil
     end
 
@@ -872,7 +869,7 @@ class Puppet::Parser::Compiler
   # Return an array of all of the unevaluated resources.  These will be definitions,
   # which need to get evaluated into native resources.
   def unevaluated_resources
-    # The order of these is significant for speed due to short-circuting
+    # The order of these is significant for speed due to short-circuiting
     resources.reject { |resource| resource.evaluated? or resource.virtual? or resource.builtin_type? }
   end
 

data/lib/puppet/parser/compiler/catalog_validator/relationship_validator.rb

@@ -30,7 +30,7 @@ class Puppet::Parser::Compiler
         # all other relationships requires the referenced resource to exist when mode is strict
         refs = param.value.is_a?(Array) ? param.value.flatten : [param.value]
         refs.each do |r|
-          next if r.nil?
+          next if r.nil? || r == :undef
           unless catalog.resource(r.to_s)
             msg = "Could not find resource '#{r.to_s}' in parameter '#{param.name.to_s}'"
             if Puppet[:strict] == :error

data/lib/puppet/parser/environment_compiler.rb

@@ -15,6 +15,16 @@ class Puppet::Parser::EnvironmentCompiler < Puppet::Parser::Compiler
     end
   end
 
+  def initialize(node, options = {})
+    super
+    add_function_overrides
+  end
+
+  def add_function_overrides
+    hiera_include = proc { Puppet.debug "Ignoring hiera_include() during environment catalog compilation" }
+    loaders.puppet_system_loader.add_entry(:function, 'hiera_include', hiera_include, nil)
+  end
+
   def add_catalog_validators
     super
     add_catalog_validator(CatalogValidator::SiteValidator)

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

@@ -42,6 +42,10 @@ Puppet::Parser::Functions::newfunction(:create_resources, :arity => -3, :doc =>
 
         create_resources("@user", $myusers)
 
+    Note that `create_resources` will filter out parameter values that are `undef` so that normal
+    data binding and puppet default value expressions are considered (in that order) for the
+    final value of a parameter (just as when setting a parameter to `undef` in a puppet language
+    resource declaration).
   ENDHEREDOC
   raise ArgumentError, ("create_resources(): wrong number of arguments (#{args.length}; must be 2 or 3)") if args.length > 3
   raise ArgumentError, ('create_resources(): second argument must be a hash') unless args[1].is_a?(Hash)
@@ -49,35 +53,46 @@ Puppet::Parser::Functions::newfunction(:create_resources, :arity => -3, :doc =>
     raise ArgumentError, ('create_resources(): third argument, if provided, must be a hash') unless args[2].is_a?(Hash)
   end
 
-
   type, instances, defaults = args
   defaults ||= {}
-
-  resource = Puppet::Parser::AST::Resource.new(:type => type.sub(/^@{1,2}/, '').downcase, :instances =>
-    instances.collect do |title, params|
-      Puppet::Parser::AST::ResourceInstance.new(
-        :title => Puppet::Parser::AST::Leaf.new(:value => title),
-        :parameters => defaults.merge(params).collect do |name, value|
-          next if (value == :undef || value.nil?)
-          Puppet::Parser::AST::ResourceParam.new(
-            :param => name,
-            :value => Puppet::Parser::AST::Leaf.new(:value => value))
-        end.compact)
-    end)
+  type_name = type.sub(/^@{1,2}/, '').downcase
+
+  # Get file/line information from the puppet stack (where call comes from in puppet source)
+  # If relayed via other puppet functions in ruby that do not nest their calls, the source position
+  # will be in the original puppet source.
+  #
+  stacktrace = Puppet::Pops::PuppetStack.stacktrace()
+  if stacktrace.size > 0
+    file, line = stacktrace[0]
+  else
+    file = nil
+    line = nil
+  end
 
   if type.start_with? '@@'
-    resource.exported = true
+    exported = true
   elsif type.start_with? '@'
-    resource.virtual = true
+    virtual = true
   end
 
-  begin
-    resource.safeevaluate(self)
-  rescue Puppet::ParseError => internal_error
-    if internal_error.original.nil?
-      raise internal_error
-    else
-      raise internal_error.original
-    end
-  end
+  instances.map do |title, params|
+    # Add support for iteration if title is an array
+    resource_titles = title.is_a?(Array) ? title  : [title]
+    Puppet::Pops::Evaluator::Runtime3ResourceSupport.create_resources(
+      file, line,
+      self,
+      virtual, exported,
+      type_name,
+      resource_titles,
+      defaults.merge(params).map do |name, value|
+        value = nil if value == :undef
+        Puppet::Parser::Resource::Param.new(
+          :name   => name,
+          :value  => value, # wide open to various data types, must be correct
+          :source => self.source, # TODO: support :line => line, :file => file,
+          :add    => false
+        )
+      end.compact
+      )
+  end.flatten.compact
 end

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

@@ -100,32 +100,8 @@ defined('$tmp_file2')
 - Since 2.7.0
 - Since 3.6.0 variable reference and future parser types
 - Since 3.8.1 type specific requests with future parser
-- Since 4.0.0
+- Since 4.0.0 includes all future parser features
 DOC
 ) do |vals|
-  vals = [vals] unless vals.is_a?(Array)
-  vals.any? do |val|
-    case val
-    when String
-      if m = /^\$(.+)$/.match(val)
-        exist?(m[1])
-      else
-        find_resource_type(val) || find_definition(val) || find_hostclass(val)
-      end
-    when Puppet::Resource
-      compiler.findresource(val.type, val.title)
-    when Puppet::Pops::Types::PResourceType
-      raise ArgumentError, "The given resource type is a reference to all kind of types" if val.type_name.nil?
-      if val.title.nil?
-        find_builtin_resource_type(val.type_name) || find_definition(val.type_name)
-      else
-        compiler.findresource(val.type_name, val.title)
-      end
-    when Puppet::Pops::Types::PHostClassType
-      raise  ArgumentError, "The given class type is a reference to all classes" if val.class_name.nil?
-      find_hostclass(val.class_name)
-    else
-      raise ArgumentError, "Invalid argument of type '#{val.class}' to 'defined'"
-    end
-  end
+  function_fail(["defined() is a 4.x function - an illegal call was made to this function using old API"])
 end

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

@@ -0,0 +1,29 @@
+Puppet::Parser::Functions::newfunction(
+  :dig,
+  :type => :rvalue,
+  :arity => -1,
+  :doc => <<-DOC
+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
+DOC
+) do |args|
+  function_fail(["dig() is only available when parser/evaluator future is in effect"])
+end

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

@@ -0,0 +1,49 @@
+Puppet::Parser::Functions::newfunction(
+  :lest,
+  :type => :rvalue,
+  :arity => -2,
+  :doc => <<-DOC
+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`, otherwise 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 the `lest` function
+
+```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`
+(there is no `b` key in `a`).
+
+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
+DOC
+) do |args|
+  function_fail(["lest() is only available when parser/evaluator future is in effect"])
+end

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

@@ -0,0 +1,530 @@
+Puppet::Parser::Functions::newfunction(
+  :new,
+  :type => :rvalue,
+  :arity => -1,
+  :doc => <<-DOC
+Creates a new instance/object of a given data type.
+
+This function makes it possible to create new instances of
+concrete data 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 data type:
+
+**Example:** `new` and calling type directly are equivalent
+
+```puppet
+$a = Integer.new("42")
+$b = Integer("42")
+```
+
+These would both 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 data types (for example `Variant`). The data 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 is determined by the data type.
+
+> An assertion is always made that the produced value complies with the given type constraints.
+
+**Example:** data type constraints are checked
+
+```puppet
+Integer[0].new("-100")
+```
+
+Would fail with an assertion error (since value is less than 0).
+
+The following sections show the arguments and conversion rules
+per data type built into the Puppet Type System.
+
+Conversion to Optional[T] and NotUndef[T]
+-----------------------------------------
+
+Conversion to these data types is the same as a conversion to the type argument `T`.
+In the case of `Optional[T]` it is accepted that the argument to convert may be `undef`.
+It is however not acceptable to give other arguments (than `undef`) that cannot be
+converted to `T`.
+
+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 (base).
+
+```puppet
+type Radix = Variant[Default, Integer[2,2], Integer[8,8], Integer[10,10], Integer[16,16]]
+
+function Integer.new(
+  String $value,
+  Radix $radix = 10
+)
+
+function Integer.new(
+  Variant[Numeric, Boolean] $value
+)
+```
+
+* 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 others 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).
+
+Examples - 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.
+
+```puppet
+function Float.new(
+  Variant[Numeric, Boolean, String] $value
+)
+```
+
+
+* 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
+function Numeric.new(
+  Variant[Numeric, Boolean, String] $value
+)
+```
+
+* 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`.
+
+Examples - 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.
+The more advanced forms of formatting are intended to enable writing special purposes formatting
+functions in the Puppet language.
+
+A new string can be created from all other data types. The process is performed in
+several steps - first the data type of the given value is inferred, then the resulting data type
+is used to find the most significant format specified for that data type. And finally,
+the found format is used to convert the given value.
+
+The mapping from data 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 string representation" 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]
+
+function String.new(
+  Any $value,
+  Formats $string_formats
+)
+```
+
+Where:
+
+* `separator` is the string used to separate entries in an array, or hash (extra space should not be included at
+  the 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 data type to format map for values contained in arrays and hashes - defaults to `{Any => "%p"}`. Note that
+  these nested formats are not applicable to data types that are containers; they 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)'
+```
+
+The 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. A `#` adds prefix 0x/0X.
+| o       | Octal. Uses ..0 for negative values unless `+` is also used. A `#` adds prefix 0.
+| 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       | Same as 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       | String 'true'/'false' or 'True'/'False', first char if alternate form is used (i.e. 't'/'f' or 'T'/'F').
+| y Y       | String '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         | String 'true' / 'false'.
+| p         | String '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         | String 'undef', or quoted '"undef"' if alternative flag `#` is used.
+| n         | String 'nil', or 'null' if alternative flag `#` is used.
+| dxXobB    | String 'NaN'.
+| eEfgGaA   | String 'NaN'.
+| v         | String 'n/a'.
+| V         | String 'N/A'.
+| u         | String 'undef', or 'undefined' if alternative `#` flag is used.
+
+### Default value to String
+
+| Format    | Default formats
+| ------    | ---------------
+| d D       | String '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)  | A 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 an 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:** 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`, or 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 of `SemVerRange` use see "Creating a SemVer"
+
+* Since 4.5.0
+
+DOC
+) do |args|
+  function_fail(["new() is only available when parser/evaluator future is in effect"])
+end
+