puppet-retrospec 0.12.2 → 1.0.0

data/vendor/gems/puppet-4.5.2/lib/puppet/functions/match.rb

@@ -0,0 +1,120 @@
+# Matches a regular expression against a string and returns an array containing the match
+# and any matched capturing groups.
+#
+# The first argument is a string or array of strings. The second argument is either a
+# regular expression, regular expression represented as a string, or Regex or Pattern
+# data type that the function matches against the first argument.
+#
+# The returned array contains the entire match at index 0, and each captured group at
+# subsequent index values. If the value or expression being matched is an array, the
+# function returns an array with mapped match results.
+#
+# If the function doesn't find a match, it returns 'undef'.
+#
+# @example Matching a regular expression in a string
+#
+# ~~~ ruby
+# $matches = "abc123".match(/[a-z]+[1-9]+/)
+# # $matches contains [abc123]
+# ~~~
+#
+# @example Matching a regular expressions with grouping captures in a string
+#
+# ~~~ ruby
+# $matches = "abc123".match(/([a-z]+)([1-9]+)/)
+# # $matches contains [abc123, abc, 123]
+# ~~~
+#
+# @example Matching a regular expression with grouping captures in an array of strings
+#
+# ~~~ ruby
+# $matches = ["abc123","def456"].match(/([a-z]+)([1-9]+)/)
+# # $matches contains [[abc123, abc, 123], [def456, def, 456]]
+# ~~~
+#
+# @since 4.0.0
+#
+Puppet::Functions.create_function(:match) do
+  dispatch :match do
+    param 'String', :string
+    param 'Variant[Any, Type]', :pattern
+  end
+
+  dispatch :enumerable_match do
+    param 'Array[String]', :string
+    param 'Variant[Any, Type]', :pattern
+  end
+
+  def initialize(closure_scope, loader)
+    super
+
+    # Make this visitor shared among all instantiations of this function since it is faster.
+    # This can be used because it is not possible to replace
+    # a puppet runtime (where this function is) without a reboot. If you model a function in a module after
+    # this class, use a regular instance variable instead to enable reloading of the module without reboot
+    #
+    @@match_visitor   ||= Puppet::Pops::Visitor.new(self, "match", 1, 1)
+  end
+
+  # Matches given string against given pattern and returns an Array with matches.
+  # @param string [String] the string to match
+  # @param pattern [String, Regexp, Puppet::Pops::Types::PPatternType, Puppet::Pops::PRegexpType, Array] the pattern
+  # @return [Array<String>] matches where first match is the entire match, and index 1-n are captures from left to right
+  #
+  def match(string, pattern)
+    @@match_visitor.visit_this_1(self, pattern, string)
+  end
+
+  # Matches given Array[String] against given pattern and returns an Array with mapped match results.
+  #
+  # @param array [Array<String>] the array of strings to match
+  # @param pattern [String, Regexp, Puppet::Pops::Types::PPatternType, Puppet::Pops::PRegexpType, Array] the pattern
+  # @return [Array<Array<String, nil>>] Array with matches (see {#match}), non matching entries produce a nil entry
+  #
+  def enumerable_match(array, pattern)
+    array.map {|s| match(s, pattern) }
+  end
+
+  protected
+
+  def match_Object(obj, s)
+    msg = "match() expects pattern of T, where T is String, Regexp, Regexp[r], Pattern[p], or Array[T]. Got #{obj.class}"
+    raise ArgumentError, msg
+  end
+
+  def match_String(pattern_string, s)
+    do_match(s, Regexp.new(pattern_string))
+  end
+
+  def match_Regexp(regexp, s)
+    do_match(s, regexp)
+  end
+
+  def match_PRegexpType(regexp_t, s)
+    raise ArgumentError, "Given Regexp Type has no regular expression" unless regexp_t.pattern
+    do_match(s, regexp_t.regexp)
+  end
+
+  def match_PPatternType(pattern_t, s)
+    # Since we want the actual match result (not just a boolean), an iteration over
+    # Pattern's regular expressions is needed. (They are of PRegexpType)
+    result = nil
+    pattern_t.patterns.find {|pattern| result = match(s, pattern) }
+    result
+  end
+
+  # Returns the first matching entry
+  def match_Array(array, s)
+    result = nil
+    array.flatten.find {|entry| result = match(s, entry) }
+    result
+  end
+
+  private
+
+  def do_match(s, regexp)
+    if result = regexp.match(s)
+      result.to_a
+    end
+  end
+end

data/vendor/gems/puppet-4.5.2/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