puppet 4.10.12 → 5.0.0

data/lib/puppet/functions/annotate.rb

@@ -0,0 +1,108 @@
+# Handles annotations on objects. The function can be used in four different ways.
+#
+# With two arguments, an `Annotation` type and an object, the function returns the annotation
+# for the object of the given type, or `undef` if no such annotation exists.
+#
+# @example Using `annotate` with two arguments
+#
+# ~~~ puppet
+# $annotation = Mod::NickNameAdapter.annotate(o)
+#
+# $annotation = annotate(Mod::NickNameAdapter.annotate, o)
+# ~~~
+#
+# With three arguments, an `Annotation` type, an object, and a block, the function returns the
+# annotation for the object of the given type, or annotates it with a new annotation initialized
+# from the hash returned by the given block when no such annotation exists. The block will not
+# be called when an annotation of the given type is already present.
+#
+# @example Using `annotate` with two arguments and a block
+#
+# ~~~ puppet
+# $annotation = Mod::NickNameAdapter.annotate(o) || { { 'nick_name' => 'Buddy' } }
+#
+# $annotation = annotate(Mod::NickNameAdapter.annotate, o) || { { 'nick_name' => 'Buddy' } }
+# ~~~
+#
+# With three arguments, an `Annotation` type, an object, and an `Hash`, the function will annotate
+# the given object with a new annotation of the given type that is initialized from the given hash.
+# An existing annotation of the given type is discarded.
+#
+# @example Using `annotate` with three arguments where third argument is a Hash
+#
+# ~~~ puppet
+# $annotation = Mod::NickNameAdapter.annotate(o, { 'nick_name' => 'Buddy' })
+#
+# $annotation = annotate(Mod::NickNameAdapter.annotate, o, { 'nick_name' => 'Buddy' })
+# ~~~
+#
+# With three arguments, an `Annotation` type, an object, and an the string `clear`, the function will
+# clear the annotatation of the given type in the given object. The old annotation is returned if
+# it existed.
+#
+# @example Using `annotate` with three arguments where third argument is the string 'clear'
+#
+# ~~~ puppet
+# $annotation = Mod::NickNameAdapter.annotate(o, clear)
+#
+# $annotation = annotate(Mod::NickNameAdapter.annotate, o, clear)
+# ~~~
+#
+# With three arguments, the type `Pcore`, an object, and a Hash of hashes keyed by `Annotation` types,
+# the function will annotate the given object with all types used as keys in the given hash. Each annotation
+# is initialized with the nested hash for the respective type. The annotated object is returned.
+#
+# @example Add multiple annotations to a new instance of `Mod::Person` using the `Pcore` type.
+#
+# ~~~ puppet
+#   $person = Pcore.annotate(Mod::Person({'name' => 'William'}), {
+#     Mod::NickNameAdapter >= { 'nick_name' => 'Bill' },
+#     Mod::HobbiesAdapter => { 'hobbies' => ['Ham Radio', 'Philatelist'] }
+#   })
+# ~~~
+#
+# @since 5.0.0
+#
+Puppet::Functions.create_function(:annotate) do
+  dispatch :annotate do
+    param 'Type[Annotation]', :type
+    param 'Any', :value
+    optional_block_param 'Callable[0, 0]', :block
+  end
+
+  dispatch :annotate_new do
+    param 'Type[Annotation]', :type
+    param 'Any', :value
+    param 'Variant[Enum[clear],Hash[Pcore::MemberName,Any]]', :annotation_hash
+  end
+
+  dispatch :annotate_multi do
+    param 'Type[Pcore]', :type
+    param 'Any', :value
+    param 'Hash[Type[Annotation], Hash[Pcore::MemberName,Any]]', :annotations
+  end
+
+  # @param type [Annotation] the annotation type
+  # @param value [Object] the value to annotate
+  # @param block [Proc] optional block to produce the annotation hash
+  #
+  def annotate(type, value, &block)
+    type.implementation_class.annotate(value, &block)
+  end
+
+  # @param type [Annotation] the annotation type
+  # @param value [Object] the value to annotate
+  # @param annotation_hash [Hash{String => Object}] the annotation hash
+  #
+  def annotate_new(type, value, annotation_hash)
+    type.implementation_class.annotate_new(value, annotation_hash)
+  end
+
+  # @param type [Type] the Pcore type
+  # @param value [Object] the value to annotate
+  # @param annotations [Hash{Annotation => Hash{String => Object}}] hash of annotation hashes
+  #
+  def annotate_multi(type, value, annotations)
+    type.implementation_class.annotate(value, annotations)
+  end
+end

data/lib/puppet/functions/binary_file.rb

@@ -12,7 +12,7 @@ Puppet::Functions.create_function(:binary_file, Puppet::Functions::InternalFunct
   def binary_file(scope, unresolved_path)
     path = Puppet::Parser::Files.find_file(unresolved_path, scope.compiler.environment)
     unless path && Puppet::FileSystem.exist?(path)
-      raise Puppet::ParseError, "binary_file(): The given file '#{unresolved_path}' does not exist"
+      raise Puppet::ParseError, _("binary_file(): The given file '%{unresolved_path}' does not exist") % { unresolved_path: unresolved_path }
     end
     Puppet::Pops::Types::PBinaryType::Binary.from_binary_string(Puppet::FileSystem.binread(path))
   end

data/lib/puppet/functions/call.rb

@@ -0,0 +1,42 @@
+# Calls an arbitrary Puppet function by name.
+#
+# This function takes one mandatory argument and one or more optional arguments:
+#
+# 1. A string corresponding to a function name.
+# 2. Any number of arguments to be passed to the called function.
+# 3. An optional lambda, if the function being called supports it.
+#
+# @example Using the `call` function
+#
+# ~~~ puppet
+# $a = 'notice'
+# call($a, 'message')
+# ~~~
+#
+# @example Using the `call` function with a lambda
+#
+# ~~~ puppet
+# $a = 'each'
+# $b = [1,2,3]
+# call($a, $b) |$item| {
+#  notify { $item: }
+# }
+# ~~~
+#
+# The `call` function can be used to call either Ruby functions or Puppet language
+# functions.
+#
+# @since 5.0.0
+#
+Puppet::Functions.create_function(:call, Puppet::Functions::InternalFunction) do
+  dispatch :call_impl_block do
+    scope_param
+    param 'String', :function_name
+    repeated_param 'Any', :arguments
+    optional_block_param
+  end
+
+  def call_impl_block(scope, function_name, *args, &block)
+    call_function_with_scope(scope, function_name, *args, &block)
+  end
+end

data/lib/puppet/functions/defined.rb

@@ -129,12 +129,12 @@ Puppet::Functions.create_function(:'defined', Puppet::Functions::InternalFunctio
         scope.compiler.findresource(val.resource_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?
+        raise ArgumentError, _('The given resource type is a reference to all kind of types') if val.type_name.nil?
         type = Puppet::Pops::Evaluator::Runtime3ResourceSupport.find_resource_type(scope, val.type_name)
         val.title.nil? ? type : scope.compiler.findresource(type, val.title)
 
       when Puppet::Pops::Types::PHostClassType
-        raise  ArgumentError, 'The given class type is a reference to all classes' if val.class_name.nil?
+        raise  ArgumentError, _('The given class type is a reference to all classes') if val.class_name.nil?
         scope.compiler.findresource(:class, val.class_name)
 
       when Puppet::Pops::Types::PType
@@ -148,12 +148,12 @@ Puppet::Functions.create_function(:'defined', Puppet::Functions::InternalFunctio
           # Interpreted as asking if a class (and nothing else) is defined without having to be included in the catalog
           # (this is the same as asking for just the class' name, but with the added certainty that it cannot be a defined type.
           #
-          raise  ArgumentError, 'The given class type is a reference to all classes' if val.type.class_name.nil?
+          raise  ArgumentError, _('The given class type is a reference to all classes') if val.type.class_name.nil?
           Puppet::Pops::Evaluator::Runtime3ResourceSupport.find_hostclass(scope, val.type.class_name)
           #scope.environment.known_resource_types.find_hostclass(val.type.class_name)
         end
       else
-        raise ArgumentError, "Invalid argument of type '#{val.class}' to 'defined'"
+        raise ArgumentError, _("Invalid argument of type '%{value_class}' to 'defined'") % { value_class: val.class }
       end
     end
   end

data/lib/puppet/functions/dig.rb

@@ -14,7 +14,7 @@ Puppet::Functions.create_function(:dig) do
     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}'"
+        raise ArgumentError, _("The given data does not contain a Collection at %{walked_path}, got '%{klass}'") % { walked_path: walked_path, klass: d.class }
       end
       walked_path << k
       d[k]

data/lib/puppet/functions/each.rb

@@ -117,11 +117,8 @@ Puppet::Functions.create_function(:each) do
 
   def foreach_Hash_1(hash)
     enumerator = hash.each_pair
-    begin
-      hash.size.times do
-        yield(enumerator.next)
-      end
-    rescue StopIteration
+    hash.size.times do
+      yield(enumerator.next)
     end
     # produces the receiver
     hash
@@ -129,11 +126,8 @@ Puppet::Functions.create_function(:each) do
 
   def foreach_Hash_2(hash)
     enumerator = hash.each_pair
-    begin
-      hash.size.times do
-        yield(*enumerator.next)
-      end
-    rescue StopIteration
+    hash.size.times do
+      yield(*enumerator.next)
     end
     # produces the receiver
     hash

data/lib/puppet/functions/epp.rb

@@ -21,9 +21,6 @@
 # `epp('apache/vhost/_docroot.epp', { 'docroot' => '/var/www/html',
 # 'virtual_docroot' => '/var/www/example' })`
 #
-# This function can also accept an absolute path, which can load a template file
-# from anywhere on disk.
-#
 # Puppet produces a syntax error if you pass more parameters than are declared in
 # the template's parameter tag. When passing parameters to a template that
 # contains a parameter tag, use the same names as the tag's declared parameters.

data/lib/puppet/functions/hiera_include.rb

@@ -98,7 +98,7 @@ Puppet::Functions.create_function(:hiera_include, Hiera::PuppetFunction) do
   end
 
   def post_lookup(scope, key, value)
-    raise Puppet::ParseError, "Could not find data item #{key}" if value.nil?
+    raise Puppet::ParseError, _("Could not find data item %{key}") % { key: key } if value.nil?
     call_function_with_scope(scope, 'include', value) unless value.empty?
   end
 end

data/lib/puppet/functions/hocon_data.rb

@@ -8,7 +8,7 @@
 #
 Puppet::Functions.create_function(:hocon_data) do
   unless Puppet.features.hocon?
-    raise Puppet::DataBinding::LookupError, 'Lookup using Hocon data_hash function is not supported without hocon library'
+    raise Puppet::DataBinding::LookupError, _('Lookup using Hocon data_hash function is not supported without hocon library')
   end
 
   require 'hocon'
@@ -30,7 +30,7 @@ Puppet::Functions.create_function(:hocon_data) do
       begin
         Hocon.parse(content)
       rescue Hocon::ConfigError => ex
-        raise Puppet::DataBinding::LookupError, "Unable to parse (#{path}): #{ex.message}"
+        raise Puppet::DataBinding::LookupError, _("Unable to parse (%{path}): %{message}") % { path: path, message: ex.message }
       end
     end
   end

data/lib/puppet/functions/json_data.rb

@@ -22,7 +22,7 @@ Puppet::Functions.create_function(:json_data) do
         JSON.parse(content)
       rescue JSON::ParserError => ex
         # Filename not included in message, so we add it here.
-        raise Puppet::DataBinding::LookupError, "Unable to parse (#{path}): #{ex.message}"
+        raise Puppet::DataBinding::LookupError, "Unable to parse (%{path}): %{message}" % { path: path, message: ex.message }
       end
     end
   end

data/lib/puppet/functions/lookup.rb

@@ -91,8 +91,8 @@
 # merged hash. If the same key exists in multiple source hashes, Puppet will
 # recursively merge hash or array values (with duplicate values removed from
 # arrays). For conflicting scalar values, the highest-priority value will win.
-# * `{'strategy' => 'first'}`, `{'strategy' => 'unique'}`,
-# or `{'strategy' => 'hash'}` --- Same as the string versions of these merge behaviors.
+# * `{'strategy' => 'first|unique|hash'}` --- Same as the string versions of these
+# merge behaviors.
 # * `{'strategy' => 'deep', <DEEP OPTION> => <VALUE>, ...}` --- Same as `'deep'`,
 # but can adjust the merge with additional options. The available options are:
 #     * `'knockout_prefix'` (string or undef) --- A string prefix to indicate a

data/lib/puppet/functions/map.rb

@@ -88,21 +88,11 @@ Puppet::Functions.create_function(:map) do
   end
 
   def map_Hash_1(hash)
-    result = []
-    begin
-      hash.map {|x, y| result << yield([x, y]) }
-    rescue StopIteration
-    end
-    result
+    hash.map {|x, y| yield([x, y]) }
   end
 
   def map_Hash_2(hash)
-    result = []
-    begin
-      hash.map {|x, y| result << yield(x, y) }
-    rescue StopIteration
-    end
-    result
+    hash.map {|x, y| yield(x, y) }
   end
 
   def map_Enumerable_1(enumerable)
@@ -123,7 +113,7 @@ Puppet::Functions.create_function(:map) do
     begin
       loop do
         result << yield(index, enum.next)
-        index = index + 1
+        index = index +1
       end
     rescue StopIteration
     end

data/lib/puppet/functions/match.rb

@@ -78,7 +78,7 @@ Puppet::Functions.create_function(:match) do
   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}"
+    msg = _("match() expects pattern of T, where T is String, Regexp, Regexp[r], Pattern[p], or Array[T]. Got %{klass}") % { klass: obj.class }
     raise ArgumentError, msg
   end
 
@@ -91,7 +91,7 @@ Puppet::Functions.create_function(:match) do
   end
 
   def match_PRegexpType(regexp_t, s)
-    raise ArgumentError, "Given Regexp Type has no regular expression" unless regexp_t.pattern
+    raise ArgumentError, _("Given Regexp Type has no regular expression") unless regexp_t.pattern
     do_match(s, regexp_t.regexp)
   end
 

data/lib/puppet/functions/reduce.rb

@@ -94,37 +94,6 @@
 # # $combine contains [dabc, 10]
 # ~~~
 #
-# @example Using the `reduce` function to reduce a hash of hashes
-#
-# ~~~ puppet
-# # Reduce a hash of hashes $data, merging defaults into the inner hashes.
-# $data = {
-#   'connection1' => {
-#     'username' => 'user1',
-#     'password' => 'pass1',
-#   },
-#   'connection_name2' => {
-#     'username' => 'user2',
-#     'password' => 'pass2',
-#   },
-# }
-#
-# $defaults = {
-#   'maxActive' => '20',
-#   'maxWait'   => '10000',
-#   'username'  => 'defaultuser',
-#   'password'  => 'defaultpass',
-# }
-#
-# $merged = $data.reduce( {} ) |$memo, $x| {
-#   $memo + { $x[0] => $defaults + $data[$x[0]] }
-# }
-# # At the start of the lambda's first iteration, $memo is set to {}, and $x is set to
-# # the first [key, value] tuple. The key in $data is, therefore, given by $x[0]. In
-# # subsequent rounds, $memo retains the value returned by the expression, i.e.
-# # $memo + { $x[0] => $defaults + $data[$x[0]] }.
-# ~~~
-#
 # @since 4.0.0
 #
 Puppet::Functions.create_function(:reduce) do

data/lib/puppet/functions/require.rb

@@ -27,7 +27,7 @@ Puppet::Functions.create_function(:require, Puppet::Functions::InternalFunction)
     classes.each do |klass|
       # lookup the class in the scopes
       klass = (classobj = krt.find_hostclass(klass)) ? classobj.name : nil
-      raise Puppet::ParseError.new("Could not find class #{klass}") unless klass
+      raise Puppet::ParseError.new(_("Could not find class %{klass}") % { klass: klass }) unless klass
       ref = Puppet::Resource.new(:class, klass)
       resource = scope.resource
       resource.set_parameter(:require, [resource[:require]].flatten.compact << ref)

data/lib/puppet/functions/slice.rb

@@ -99,11 +99,11 @@ Puppet::Functions.create_function(:slice) do
       serving_size = 1
     end
     if serving_size == 0
-      raise ArgumentError, "slice(): block must define at least one parameter. Block has 0."
+      raise ArgumentError, _("slice(): block must define at least one parameter. Block has 0.")
     end
     unless serving_size == 1 || serving_size == slice_size
-      raise ArgumentError, "slice(): block must define one parameter, or " +
-        "the same number of parameters as the given size of the slice (#{slice_size}). Block has #{serving_size}; "+
+      raise ArgumentError, _("slice(): block must define one parameter, or ") +
+        _("the same number of parameters as the given size of the slice (%{slice_size}). Block has %{serving_size}; ") % { slice_size: slice_size, serving_size: serving_size }+
       pblock.parameter_names.join(', ')
     end
     serving_size

data/lib/puppet/functions/strftime.rb

@@ -28,8 +28,16 @@ Puppet::Functions.create_function(:strftime) do
   end
 
   def legacy_strftime(format, timezone = nil)
-    Puppet.warn_once('deprecation', 'legacy#strftime',
-      'The argument signature (String format, [String timezone]) is deprecated for #strfime. See #strftime documentation and Timespan type for more info')
+    stacktrace = Puppet::Pops::PuppetStack.stacktrace()
+    if stacktrace.size > 0
+      file, line = stacktrace[0]
+    else
+      file = nil
+      line = nil
+    end
+    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'),
+      file, line)
     Puppet::Pops::Time::Timestamp.format_time(format, Time.now.utc, timezone)
   end
 end

data/lib/puppet/functions/unique.rb

@@ -0,0 +1,132 @@
+# The `unique` function returns a unique set of values from an `Iterable` argument.
+#
+# * If the argument is a `String`, the unique set of characters are returned as a new `String`.
+# * If the argument is a `Hash`, the resulting hash associates a set of keys with a set of unique values.
+# * For all other types of `Iterable` (`Array`, `Iterator`) the result is an `Array` with
+#   a unique set of entries.
+# * Comparison of all `String` values are case sensitive.
+# * An optional code block can be given - if present it is given each candidate value and its return is used instead of the given value. This
+#   enables transformation of the value before comparison. The result of the lambda is only used for comparison.
+# * The optional code block when used with a hash is given each value (not the keys).
+#
+# @example Using unique with a String
+#
+# ~~~puppet
+# # will produce 'abc'
+# "abcaabb".unique
+# ~~~
+#
+# @example Using unique with an Array
+#
+# ~~~puppet
+# # will produce ['a', 'b', 'c']
+# ['a', 'b', 'c', 'a', 'a', 'b'].unique
+# ~~~
+#
+# @example Using unique with a Hash
+#
+# ~~~puppet
+# # will produce { ['a', 'b'] => [10], ['c'] => [20]}
+# {'a' => 10, 'b' => 10, 'c' => 20}.unique
+#
+# # will produce { 'a' => 10, 'c' => 20 } (use first key with first value)
+# Hash.new({'a' => 10, 'b' => 10, 'c' => 20}.unique.map |$k, $v| { [ $k[0] , $v[0]] })
+#
+# # will produce { 'b' => 10, 'c' => 20 } (use last key with first value)
+# Hash.new({'a' => 10, 'b' => 10, 'c' => 20}.unique.map |$k, $v| { [ $k[-1] , $v[0]] })
+# ~~~
+#
+# @example Using unique with an Iterable
+#
+# ~~~
+# # will produce [3, 2, 1]
+# [1,2,2,3,3].reverse_each.unique
+# ~~~
+#
+# @example Using unique with a lambda
+#
+# ~~~puppet
+# # will produce [['sam', 'smith'], ['sue', 'smith']]
+# [['sam', 'smith'], ['sam', 'brown'], ['sue', 'smith']].unique |$x| { $x[0] }
+#
+# # will produce [['sam', 'smith'], ['sam', 'brown']]
+# [['sam', 'smith'], ['sam', 'brown'], ['sue', 'smith']].unique |$x| { $x[1] }
+#
+# # will produce ['aBc', 'bbb'] (using a lambda to make comparison using downcased (%d) strings)
+# ['aBc', 'AbC', 'bbb'].unique |$x| { String($x,'%d') }
+#
+# # will produce {[a] => [10], [b, c, d, e] => [11, 12, 100]}
+# {a => 10, b => 11, c => 12, d => 100, e => 11}.unique |$v| { if $v > 10 { big } else { $v } } 
+# ~~~
+#
+# Note that for `Hash` the result is slightly different than for the other data types. For those the result contains the
+# *first-found* unique value, but for `Hash` it contains associations from a set of keys to the set of values clustered by the
+# equality lambda (or the default value equality if no lambda was given). This makes the `unique` function more versatile for hashes
+# in general, while requiring that the simple computation of "hash's unique set of values" is performed as `$hsh.map |$k, $v| { $v }.unique`.
+# (A unique set of hash keys is in general meaningless (since they are unique by definition) - although if processed with a different
+# lambda for equality that would be different. First map the hash to an array of its keys if such a unique computation is wanted). 
+# If the more advanced clustering is wanted for one of the other data types, simply transform it into a `Hash` as shown in the
+# following example.
+#
+# @example turning a string or array into a hash with index keys
+#
+# ~~puppet
+# # Array ['a', 'b', 'c'] to Hash with index results in
+# # {0 => 'a', 1 => 'b', 2 => 'c'}
+# Hash(['a', 'b', 'c'].map |$i, $v| { [$i, $v]})
+#
+# # String "abc" to Hash with index results in
+# # {0 => 'a', 1 => 'b', 2 => 'c'}
+# Hash(Array("abc").map |$i,$v| { [$i, $v]})
+# "abc".to(Array).map |$i,$v| { [$i, $v]}.to(Hash)
+# ~~~
+#
+# @since Puppet 5.0.0
+#
+Puppet::Functions.create_function(:unique) do
+  dispatch :unique_string do
+    param 'String', :string
+    optional_block_param 'Callable[String]', :block
+  end
+
+  dispatch :unique_hash do
+    param 'Hash', :hash
+    optional_block_param 'Callable[Any]', :block
+  end
+
+  dispatch :unique_array do
+    param 'Array', :array
+    optional_block_param 'Callable[Any]', :block
+  end
+
+  dispatch :unique_iterable do
+    param 'Iterable', :iterable
+    optional_block_param 'Callable[Any]', :block
+  end
+
+  def unique_string(string, &block)
+    string.split('').uniq(&block).join('')
+  end
+
+  def unique_hash(hash, &block)
+    block = lambda {|v| v } unless block_given?
+    result = Hash.new {|h, k| h[k] = {:keys =>[], :values =>[]} }
+    hash.each_pair do |k,v|
+      rc = result[ block.call(v) ]
+      rc[:keys] << k
+      rc[:values] << v
+    end
+    # reduce the set of possibly duplicated value entries
+    inverted = {}
+    result.each_pair {|k,v| inverted[v[:keys]] = v[:values].uniq }
+    inverted
+  end
+
+  def unique_array(array,&block)
+    array.uniq(&block)
+  end
+
+  def unique_iterable(iterable, &block)
+    Puppet::Pops::Types::Iterable.on(iterable).uniq(&block)
+  end
+end