puppet 3.8.7 → 4.0.0.rc1

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

@@ -39,9 +39,7 @@ Example using each:
       "hello".each |$char| { ... }                      # 'h', 'e', 'l', 'l', 'o'
       3.each |$number| { ... }                          # 0, 1, 2
 
-- since 3.2 for Array and Hash
-- since 3.5 for other enumerables
-- note requires `parser = future`
+- Since 4.0.0
 DOC
 ) do |args|
   function_fail(["each() is only available when parser/evaluator future is in effect"])

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

@@ -38,8 +38,7 @@ Template parameters shadow variables in outer scopes. File based epp does never
 scope where the `epp` function is called from.
 
 - See function inline_epp for examples of EPP
-- Since 3.5
-- Requires Future Parser") do |args|
+- Since 4.0.0") do |args|
 
   function_fail(["epp() is only available when parser/evaluator future is in effect"])
 end

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

@@ -1,5 +1,3 @@
-require 'puppet/file_system'
-
 Puppet::Parser::Functions::newfunction(
   :file, :arity => -2, :type => :rvalue,
   :doc => "Loads a file from a module and returns its contents as a string.
@@ -26,7 +24,7 @@ Puppet::Parser::Functions::newfunction(
     end
 
     if path
-      Puppet::FileSystem.read_preserve_line_endings(path)
+      File.read(path)
     else
       raise Puppet::ParseError, "Could not find any files from #{vals.join(", ")}"
     end

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

@@ -35,9 +35,7 @@ Example Using filter with two parameters
      $a = {"raspberry"=>0, "blueberry"=>1, "orange"=>1}
      $a.filter |$key, $x| { $x =~ /berry$/ and $x >= 1 } # blueberry
 
-- since 3.4 for Array and Hash
-- since 3.5 for other enumerables
-- note requires `parser = future`
+- Since 4.0.0
 DOC
 ) do |args|
   function_fail(["filter() is only available when parser/evaluator future is in effect"])

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

@@ -3,7 +3,7 @@ require 'hiera_puppet'
 module Puppet::Parser::Functions
   newfunction(:hiera, :type => :rvalue, :arity => -2, :doc => "Performs a
   standard priority lookup and returns the most specific value for a given key.
-  The returned value can be data of any type (strings, arrays, or hashes)
+  The returned value can be data of any type (strings, arrays, or hashes). 
 
   The function can be called in one of three ways:
   1. Using 1 to 3 arguments where the arguments are:
@@ -20,16 +20,14 @@ module Puppet::Parser::Functions
 
   2. Using a 'key' and an optional 'override' parameter like in #1 but with a block to
      provide the default value. The block is called with one parameter (the key) and
-     should return the value. This option can only be used with the 3x future parser or
-     from 4.0.0.
+     should return the value.
 
   3. Like #1 but with all arguments passed in an array.
 
-  More thorough examples of `hiera` are available at:
+  More thorough examples of `hiera` are available at:  
   <http://docs.puppetlabs.com/hiera/1/puppet.html#hiera-lookup-functions>
   ") do |*args|
-    key, default, override = HieraPuppet.parse_args(args)
-    HieraPuppet.lookup(key, default, self, override, :priority)
+    function_fail(["hiera() has been converted to 4x API"])
   end
 end
 

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

@@ -1,7 +1,7 @@
 require 'hiera_puppet'
 
 module Puppet::Parser::Functions
-  newfunction(:hiera_array, :type => :rvalue, :arity => -2,:doc => "Returns all
+  newfunction(:hiera_array, :type => :rvalue, :arity => -2,:doc => "Returns all 
   matches throughout the hierarchy --- not just the first match --- as a flattened array of unique values.
   If any of the matched values are arrays, they're flattened and included in the results.
 
@@ -20,18 +20,16 @@ module Puppet::Parser::Functions
 
   2. Using a 'key' and an optional 'override' parameter like in #1 but with a block to
      provide the default value. The block is called with one parameter (the key) and
-     should return the value. This option can only be used with the 3x future parser or
-     from 4.0.0.
+     should return the value.
 
   3. Like #1 but with all arguments passed in an array.
 
   If any matched value is a hash, puppet will raise a type mismatch error.
 
-  More thorough examples of `hiera` are available at:
+  More thorough examples of `hiera` are available at:  
   <http://docs.puppetlabs.com/hiera/1/puppet.html#hiera-lookup-functions>
   ") do |*args|
-    key, default, override = HieraPuppet.parse_args(args)
-    HieraPuppet.lookup(key, default, self, override, :array)
+    function_fail(["hiera_array() has been converted to 4x API"])
   end
 end
 

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

@@ -1,9 +1,9 @@
 require 'hiera_puppet'
 
 module Puppet::Parser::Functions
-  newfunction(:hiera_hash, :type => :rvalue, :arity => -2, :doc =>
-  "Returns a merged hash of matches from throughout the hierarchy. In cases where two or
-  more hashes share keys, the hierarchy  order determines which key/value pair will be
+  newfunction(:hiera_hash, :type => :rvalue, :arity => -2, :doc => 
+  "Returns a merged hash of matches from throughout the hierarchy. In cases where two or 
+  more hashes share keys, the hierarchy  order determines which key/value pair will be 
   used in the returned hash, with the pair in the highest priority data source winning.
 
   The function can be called in one of three ways:
@@ -21,19 +21,17 @@ module Puppet::Parser::Functions
 
   2. Using a 'key' and an optional 'override' parameter like in #1 but with a block to
      provide the default value. The block is called with one parameter (the key) and
-     should return the value. This option can only be used with the 3x future parser or
-     from 4.0.0.
+     should return the value.
 
   3. Like #1 but with all arguments passed in an array.
 
   `hiera_hash` expects that all values returned will be hashes. If any of the values 
   found in the data sources are strings or arrays, puppet will raise a type mismatch error.
 
-  More thorough examples of `hiera_hash` are available at:
+  More thorough examples of `hiera_hash` are available at:  
   <http://docs.puppetlabs.com/hiera/1/puppet.html#hiera-lookup-functions>
   ") do |*args|
-    key, default, override = HieraPuppet.parse_args(args)
-    HieraPuppet.lookup(key, default, self, override, :hash)
+    function_fail(["hiera_hash() has been converted to 4x API"])
   end
 end
 

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

@@ -8,7 +8,7 @@ module Puppet::Parser::Functions
   To use `hiera_include`, the following configuration is required:
 
   - A key name to use for classes, e.g. `classes`.
-  - A line in the puppet `sites.pp` file (e.g. `/etc/puppet/manifests/sites.pp`)
+  - A line in the puppet `sites.pp` file (e.g. `/etc/puppetlabs/puppet/manifests/sites.pp`)
     reading `hiera_include('classes')`. Note that this line must be outside any node
     definition and below any top-scope variables in use for Hiera lookups.
   - Class keys in the appropriate data sources. In a data source keyed to a node's role,
@@ -35,21 +35,13 @@ module Puppet::Parser::Functions
   2. Using a 'key' and an optional 'override' parameter like in #1 but with a block to
      provide the default value. The block is called with one parameter (the key) and
      should return the array to be used in the subsequent call to include.
-     This option can only be used with the 3x future parser or
-     from 4.0.0.
 
   3. Like #1 but with all arguments passed in an array.
 
   More thorough examples of `hiera_include` are available at:
   <http://docs.puppetlabs.com/hiera/1/puppet.html#hiera-lookup-functions>
   ") do |*args|
-    key, default, override = HieraPuppet.parse_args(args)
-    if answer = HieraPuppet.lookup(key, default, self, override, :array)
-      method = Puppet::Parser::Functions.function(:include)
-      send(method, [answer])
-    else
-      raise Puppet::ParseError, "Could not find data item #{key}"
-    end
+    function_fail(["hiera_include() has been converted to 4x API"])
   end
 end
 

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

@@ -19,11 +19,13 @@ where they are declared. For that, see the `contain` function. It also
 does not create a dependency relationship between the declared class and the
 surrounding class; for that, see the `require` function.
 
-When the future parser is used, you must use the class's full name;
-relative names are no longer allowed. In addition to names in string form,
+You must use the class's full name;
+relative names are not allowed. In addition to names in string form,
 you may also directly use Class and Resource Type values that are produced by
 the future parser's resource and relationship expressions.
 
+- Since < 3.0.0
+- Since 4.0.0 support for class and resource type values, absolute names
 ") do |vals|
 
   # Unify call patterns (if called with nested arrays), make names absolute if

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

@@ -1,87 +1,113 @@
 Puppet::Parser::Functions.newfunction(:lookup, :type => :rvalue, :arity => -2, :doc => <<-'ENDHEREDOC') do |args|
-Looks up data defined using Puppet Bindings and Hiera.
-The function is callable with one to three arguments and optionally with a code block to further process the result.
+Looks up data defined using Data Binding, and Data Providers using different strategies. The lookup searches in
+Data Bindings first (if configured; typically Hiera), then in the environments data provider (if any), and last in
+the module's data provider (if any) of the module the call to lookup originates from. Thus, the global Data Binding
+has higher priority than data provided in the environment, which has higher priority than data provided in a module,
 
 The lookup function can be called in one of these ways:
 
     lookup(name)
-    lookup(name, type)
-    lookup(name, type, default)
+    lookup(name, value_type)
+    lookup(name, value_type, merge)
+    lookup(name, value_type, merge, default_value)
     lookup(options_hash)
     lookup(name, options_hash)
 
-The function may optionally be called with a code block / lambda with the following signatures:
+The function may optionally be called with a code block / lambda with the following signature:
 
-    lookup(...) |$result| { ... }
-    lookup(...) |$name, $result| { ... }
-    lookup(...) |$name, $result, $default| { ... }
+    lookup(...) |$name| { ... }
 
-The longer signatures are useful when the block needs to raise an error (it can report the name), or
-if it needs to know if the given default value was selected.
+The block, if present, is mutually exclusive to the `default_value` and will be called with the `name` used in the
+lookup when no value is found. The value produced by the block then becomes the value produced by the lookup.
 
-The code block receives the following three arguments:
-
-* The `$name` is the last name that was looked up (*the* name if only one name was looked up)
-* The `$result` is the looked up value (or the default value if not found).
-* The `$default` is the given default value (`undef` if not given).
-
-The block, if present, is called with the result from the lookup. The value produced by the block is also what is
-produced by the `lookup` function.
-When a block is used, it is the users responsibility to call `error` if the result does not meet additional
-criteria, or if an undef value is not acceptable. If a value is not found, and a default has been
-specified, the default value is given to the block.
-
-The content of the options hash is:
+The meaning of the parameters or content of the options hash is:
 
 * `name` - The name or array of names to lookup (first found is returned)
-* `type` - The type to assert (a Type or a type specification in string form)
-* `default` - The default value if there was no value found (must comply with the data type)
-* `accept_undef` - (default `false`) An `undef` result is accepted if this options is set to `true`.
+* `value_type` - The type to assert. Defaults to 'Data' See 'Type Specification' below.
+* `default_value` - The default value if there was no value found (must comply with the data type)
 * `override` - a hash with map from names to values that are used instead of the underlying bindings. If the name
   is found here it wins. Defaults to an empty hash.
-* `extra` - a hash with map from names to values that are used as a last resort to obtain a value. Defaults to an
-  empty hash.
-
-When the call is on the form `lookup(name, options_hash)`, or `lookup(name, type, options_hash)`, the given name
-argument wins over the `options_hash['name']`.
-
-The search order is `override` (if given), then `binder`, then `hiera` and finally `extra` (if given). The first to produce
-a value other than undef for a given name wins.
-
-The type specification is one of:
-
-  * A type in the Puppet Type System, e.g.:
-    * `Integer`, an integral value with optional range e.g.:
-      * `Integer[0, default]` - 0 or positive
-      * `Integer[default, -1]` - negative, 
-      * `Integer[1,100]` - value between 1 and 100 inclusive
-    * `String`- any string
-    * `Float` - floating point number (same signature as for Integer for `Integer` ranges)
-    * `Boolean` - true of false (strict)
-    * `Array` - an array (of Data by default), or parameterized as `Array[<element_type>]`, where
-      `<element_type>` is the expected type of elements
-    * `Hash`,  - a hash (of default `Literal` keys and `Data` values), or parameterized as
-      `Hash[<value_type>]`, `Hash[<key_type>, <value_type>]`, where `<key_type>`, and
-      `<value_type>` are the types of the keys and values respectively
-      (key is `Literal` by default).
-    * `Data` - abstract type representing any `Literal`, `Array[Data]`, or `Hash[Literal, Data]`
-    * `Pattern[<p1>, <p2>, ..., <pn>]` - an enumeration of valid patterns (one or more) where
-       a pattern is a regular expression string or regular expression,
-       e.g. `Pattern['.com$', '.net$']`, `Pattern[/[a-z]+[0-9]+/]` 
-    * `Enum[<s1>, <s2>, ..., <sn>]`, - an enumeration of exact string values (one or more)
-       e.g. `Enum[blue, red, green]`.
-    * `Variant[<t1>, <t2>,...<tn>]` - matches one of the listed types (at least one must be given)
-      e.g. `Variant[Integer[8000,8999], Integer[20000, 99999]]` to accept a value in either range
-    * `Regexp`- a regular expression (i.e. the result is a regular expression, not a string
-       matching a regular expression).
-  * A string containing a type description - one of the types as shown above but in string form.
-
-If the function is called without specifying a default value, and nothing is bound to the given name 
-an error is raised unless the option `accept_undef` is true. If a block is given it must produce an acceptable
-value (or call `error`). If the block does not produce an acceptable value an error is
-raised.
-
-Examples:
+* `default_values_hash` - a hash with map from names to values that are used as a last resort to obtain a value.
+  Defaults to an empty hash.
+* `merge` - A string of type Enum[unique, hash, merge] or a hash with the key 'strategy' set to that string. See
+  'Merge Strategies' below.
+
+It is not permitted to pass the `name` as both a parameter and in the options hash.
+
+The search will proceed as follows:
+1. For each name given in the `name` array (or once, if it's just one name):
+  - If a matching key is found in the `override` hash, it's value is immediately type checked and returned
+  - Search and optionally merge Data Binding, environment data providers, and module data providers
+  - Type check and return the value if a matching key is found
+2. For each name given in the `name` array (or once, if it's just one name):
+  - Type check and return the value if a matching key is found in the `default_values_hash`
+3. Type check and return either the given `default_value` or the result of calling the code block if either exist
+4. Raise an error indicating that no matching value was found
+
+*Merge Strategies*
+
+The default behavior of the lookup is to return the first value that is found for the given `name`. The optional
+`merge` parameter will change this so that a lookup makes an attempt to find values in all three sources (the Data
+Binder, the environment, and the module scope) and then merge these values according to the given strategy. This
+does not apply to values found in the 'override' hash. Such values are returned immediately without merging.
+Note that `merge` is passed on to allow the underlying provider to return a merged result
+
+The valid strategies are:
+- 'hash' Performs a simple hash-merge by overwriting keys of lower lookup priority. Merged values must be of Hash type
+- 'unique' Appends everything to an array containing no nested arrays and where all duplicates have been removed. Can
+   append values of Scalar or Array[Scalar] type
+- 'deep' Performs a deep merge on values of Array and Hash type. See documentation for the DeepMerge gem's deep_merge
+   operation for details and options.
+
+The 'deep' strategy can use additional options to control its behavior. Options can be passed as top level
+keys in the `merge` parameter when it is a given as a hash. Recognized options are:
+- 'knockout_prefix' Set to string value to signify prefix which deletes elements from existing element. Defaults is _undef_
+- 'sort_merged_arrays' Set to _true_ to sort all arrays that are merged together. Default is _false_
+- 'unpack_arrays' Set to string value used as a deliminator to join all array values and then split them again. Default is _undef_
+- 'merge_hash_arrays' Set to _true_ to merge hashes within arrays. Default is _false_
+
+*Type Specification*
+
+The type specification is a type in the Puppet Type System, e.g.:
+  * `Integer`, an integral value with optional range e.g.:
+    * `Integer[0, default]` - 0 or positive
+    * `Integer[default, -1]` - negative,
+    * `Integer[1,100]` - value between 1 and 100 inclusive
+  * `String`- any string
+  * `Float` - floating point number (same signature as for Integer for `Integer` ranges)
+  * `Boolean` - true of false (strict)
+  * `Array` - an array (of Data by default), or parameterized as `Array[<element_type>]`, where
+    `<element_type>` is the expected type of elements
+  * `Hash`,  - a hash (of default `Literal` keys and `Data` values), or parameterized as
+    `Hash[<value_type>]`, `Hash[<key_type>, <value_type>]`, where `<key_type>`, and
+    `<value_type>` are the types of the keys and values respectively
+    (key is `Literal` by default).
+  * `Data` - abstract type representing any `Literal` (including _undef_), `Array[Data]`, or `Hash[Literal, Data]`
+  * `Pattern[<p1>, <p2>, ..., <pn>]` - an enumeration of valid patterns (one or more) where
+     a pattern is a regular expression string or regular expression,
+     e.g. `Pattern['.com$', '.net$']`, `Pattern[/[a-z]+[0-9]+/]`
+  * `Enum[<s1>, <s2>, ..., <sn>]`, - an enumeration of exact string values (one or more)
+     e.g. `Enum[blue, red, green]`.
+  * `Variant[<t1>, <t2>,...<tn>]` - matches one of the listed types (at least one must be given)
+    e.g. `Variant[Integer[8000,8999], Integer[20000, 99999]]` to accept a value in either range
+  * `Regexp`- a regular expression (i.e. the result is a regular expression, not a string
+     matching a regular expression).
+
+For more options and details about types, see the Puppet Language Reference
+
+*Handling of undef*
+
+When no match is found for the given `name` when searching all sources, (including the `override`and
+`default_values_hash`), then the value used is either the `default_value` or the value produced by the given block.
+If neither is provided, then the lookup will always raise an error. Note that this only applies when there's no
+match for the given `name`. It does not happen when a value is found and that value happens to be _undef_.
+
+*Validation of returned value*
+
+The produced value is subject to type validation using the `value_type` (if given) and an error is raised unless
+the resulting value is of correct type.
+
+*Examples*
 
 When called with one argument; **the name**, it
 returns the bound value with the given name after having  asserted it has the default datatype `Data`:
@@ -92,53 +118,37 @@ When called with two arguments; **the name**, and **the expected type**, it
 returns the bound value with the given name after having asserted it has the given data
 type ('String' in the example):
 
-    lookup('the_name', 'String') # 3.x
-    lookup('the_name', String)   # parser future
+    lookup('the_name', String)
 
-When called with three arguments, **the name**, the **expected type**, and a **default**, it
-returns the bound value with the given name, or the default after having asserted the value
-has the given data type (`String` in the example above):
+When called with four arguments, **the name**, the **expected type**, the **merge** strategy, and a
+**default value**, it returns the bound value with the given name, or the default after having asserted the value
+has the given data type:
 
-    lookup('the_name', 'String', 'Fred') # 3x
-    lookup('the_name', String, 'Fred')   # parser future
+    lookup('the_name', String, undef, 'Fred')
+    lookup('the_name', Array[String], 'unique', [Fred])
 
-Using a lambda to process the looked up result - asserting that it starts with an upper case letter:
+Using a lambda to provide a default value by calling a function:
 
-    # only with parser future
-    lookup('the_size', Integer[1,100]) |$result| {
-      if $large_value_allowed and $result > 10
-        { error 'Values larger than 10 are not allowed'}
-      $result
+    lookup('the_size', Integer[1,100]) |$name| {
+      obtain_size_default()
     }
 
-Including the name in the error
+There are two ways to make lookup return undef when no matching key was found instead of raising an error.
+Either call it with four arguments (the `merge` argument must be present even when using the default strategy
+to ensure that the four argument variant is used):
 
-    # only with parser future
-    lookup('the_size', Integer[1,100]) |$name, $result| {
-      if $large_value_allowed and $result > 10
-        { error 'The bound value for '${name}' can not be larger than 10 in this configuration'}
-      $result
-    }
+     $are_you_there = lookup('peekaboo', Optional[String], undef, undef)
 
-When using a block, the value it produces is also asserted against the given type, and it may not be
-`undef` unless the option `'accept_undef'` is `true`.
+or call it using an options hash:
 
-All options work as the corresponding (direct) argument. The `first_found` option and
-`accept_undef` are however only available as options.
+     $are_you_there = lookup('peekaboo', { 'default_value' => undef })
+     $are_you_there = lookup({ 'name' => 'peekaboo', 'default_value' => undef })
 
-Using first_found semantics option to return the first name that has a bound value:
+or with a block that produces an undef value:
 
-    lookup(['apache::port', 'nginx::port'], 'Integer', 80)
-
-If you want to make lookup return undef when no value was found instead of raising an error:
-
-     $are_you_there = lookup('peekaboo', { accept_undef => true} )
-     $are_you_there = lookup('peekaboo', { accept_undef => true}) |$result| { $result }
+     $are_you_there = lookup('peekaboo', Optional[String]) |$name| { undef }
 
+- Since 4.0.0
 ENDHEREDOC
-
-  unless Puppet[:binder] || Puppet.future_parser?
-    raise Puppet::ParseError, "The lookup function is only available with settings --binder true, or --parser future"
-  end
-  Puppet::Pops::Binder::Lookup.lookup(self, args)
+  function_fail(["lookup() has been converted to 4x API"])
 end