puppet 3.4.3 → 3.5.0.rc1

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

@@ -0,0 +1,41 @@
+Puppet::Parser::Functions::newfunction(:epp, :type => :rvalue, :arity => -2, :doc =>
+"Evaluates an Embedded Puppet Template (EPP) file and returns the rendered text result as a String.
+
+EPP support the following tags:
+
+* `<%= puppet expression %>` - This tag renders the value of the expression it contains.
+* `<% puppet expression(s) %>` - This tag will execute the expression(s) it contains, but renders nothing.
+* `<%# comment %>` - The tag and its content renders nothing.
+* `<%%` or `%%>` - Renders a literal `<%` or `%>` respectively.
+* `<%-` - Same as `<%` but suppresses any leading whitespace.
+* `-%>` - Same as `%>` but suppresses any trailing whitespace on the same line (including line break).
+* `<%-( parameters )-%>` - When placed as the first tag declares the template's parameters.
+
+File based EPP supports the following visibilities of variables in scope:
+
+* Global scope (i.e. top + node scopes) - global scope is always visible
+* Global + all given arguments - if the EPP template does not declare parameters, and arguments are given
+* Global + declared parameters - if the EPP declares parameters, given argument names must match
+
+EPP supports parameters by placing an optional parameter list as the very first element in the EPP. As an example,
+`<%- ($x, $y, $z='unicorn') -%>` when placed first in the EPP text declares that the parameters `x` and `y` must be
+given as template arguments when calling `inline_epp`, and that `z` if not given as a template argument
+defaults to `'unicorn'`. Template parameters are available as variables, e.g.arguments `$x`, `$y` and `$z` in the example.
+Note that `<%-` must be used or any leading whitespace will be interpreted as text
+
+Arguments are passed to the template by calling `epp` with a Hash as the last argument, where parameters
+are bound to values, e.g. `epp('...', {'x'=>10, 'y'=>20})`. Excess arguments may be given
+(i.e. undeclared parameters) only if the EPP templates does not declare any parameters at all.
+Template parameters shadow variables in outer scopes. File based epp does never have access to variables in the
+scope where the `epp` function is called from.
+
+- See function inline_epp for examples of EPP
+- Since 3.5
+- Requires Future Parser") do |arguments|
+  # Requires future parser
+  unless Puppet[:parser] == "future"
+    raise ArgumentError, "epp(): function is only available when --parser future is in effect"
+  end
+  Puppet::Pops::Evaluator::EppEvaluator.epp(self, arguments[0], self.compiler.environment.to_s, arguments[1])
+
+end

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

@@ -100,7 +100,7 @@ This is for back compatibility to interpolate variables with %. % interpolation
 
   # if we got a custom data file, put it first in the array of search files
   if datafile != ""
-    datafiles << extlookup_datadir + "/#{datafile}.csv" if Puppet::FileSystem::File.exist?(extlookup_datadir + "/#{datafile}.csv")
+    datafiles << extlookup_datadir + "/#{datafile}.csv" if Puppet::FileSystem.exist?(extlookup_datadir + "/#{datafile}.csv")
   end
 
   extlookup_precedence.each do |d|
@@ -111,7 +111,7 @@ This is for back compatibility to interpolate variables with %. % interpolation
 
   datafiles.each do |file|
     if desired.nil?
-      if Puppet::FileSystem::File.exist?(file)
+      if Puppet::FileSystem.exist?(file)
         result = CSV.read(file).find_all do |r|
           r[0] == key
         end

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

@@ -10,7 +10,7 @@ Puppet::Parser::Functions::newfunction(
       unless Puppet::Util.absolute_path?(file)
         raise Puppet::ParseError, "Files must be fully qualified"
       end
-      if Puppet::FileSystem::File.exist?(file)
+      if Puppet::FileSystem.exist?(file)
         ret = File.read(file)
         break
       end

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

@@ -6,43 +6,95 @@ Puppet::Parser::Functions::newfunction(
 :arity => 2,
 :doc => <<-'ENDHEREDOC') do |args|
   Applies a parameterized block to each element in a sequence of entries from the first
-  argument and returns an array or hash (same type as left operand)
-  with the entries for which the block evaluates to true.
+  argument and returns an array or hash (same type as left operand for array/hash, and array for
+  other enumerable types) with the entries for which the block evaluates to `true`.
 
-  This function takes two mandatory arguments: the first should be an Array or a Hash, and the second
-  a parameterized block as produced by the puppet syntax:
+  This function takes two mandatory arguments: the first should be an Array, a Hash, or an
+  Enumerable object (integer, Integer range, or String),
+  and the second a parameterized block as produced by the puppet syntax:
 
         $a.filter |$x| { ... }
+        filter($a) |$x| { ... }
 
-  When the first argument is an Array, the block is called with each entry in turn. When the first argument
-  is a Hash the entry is an array with `[key, value]`.
-
-  The returned filtered object is of the same type as the receiver.
+  When the first argument is something other than a Hash, the block is called with each entry in turn.
+  When the first argument is a Hash the entry is an array with `[key, value]`.
 
   *Examples*
 
         # selects all that end with berry
         $a = ["raspberry", "blueberry", "orange"]
-        $a.filter |$x| { $x =~ /berry$/ }
+        $a.filter |$x| { $x =~ /berry$/ }          # rasberry, blueberry
+
+  If the block defines two parameters, they will be set to `index, value` (with index starting at 0) for all
+  enumerables except Hash, and to `key, value` for a Hash.
+
+  *Examples*
+
+        # selects all that end with 'berry' at an even numbered index
+        $a = ["raspberry", "blueberry", "orange"]
+        $a.filter |$index, $x| { $index % 2 == 0 and $x =~ /berry$/ } # raspberry
 
-  - Since 3.4
-  - requires `parser = future`.
+        # selects all that end with 'berry' and value >= 1
+        $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
+  - requires `parser = future`
   ENDHEREDOC
 
+  def filter_Enumerator(enumerator, scope, pblock, serving_size)
+    result = []
+    index = 0
+    if serving_size == 1
+      begin
+        loop { pblock.call(scope, it = enumerator.next) == true ? result << it : nil }
+      rescue StopIteration
+      end
+    else
+      begin
+        loop do
+          pblock.call(scope, index, it = enumerator.next) == true ? result << it : nil
+          index = index +1
+        end
+      rescue StopIteration
+      end
+    end
+    result
+  end
+
   receiver = args[0]
   pblock = args[1]
 
-  raise ArgumentError, ("filter(): wrong argument type (#{pblock.class}; must be a parameterized block.") unless pblock.is_a? Puppet::Parser::AST::Lambda
+  raise ArgumentError, ("filter(): wrong argument type (#{pblock.class}; must be a parameterized block.") unless pblock.respond_to?(:puppet_lambda)
+  serving_size = pblock.parameter_count
+  if serving_size == 0
+    raise ArgumentError, "filter(): block must define at least one parameter; value. Block has 0."
+  end
 
   case receiver
-  when Array
-    receiver.select {|x| pblock.call(self, x) }
   when Hash
-    result = receiver.select {|x, y| pblock.call(self, [x, y]) }
+    if serving_size > 2
+      raise ArgumentError, "filter(): block must define at most two parameters; key, value. Block has #{serving_size}; "+
+      pblock.parameter_names.join(', ')
+    end
+    if serving_size == 1
+      result = receiver.select {|x, y| pblock.call(self, [x, y]) }
+    else
+      result = receiver.select {|x, y| pblock.call(self, x, y) }
+    end
     # Ruby 1.8.7 returns Array
     result = Hash[result] unless result.is_a? Hash
     result
   else
-    raise ArgumentError, ("filter(): wrong argument type (#{receiver.class}; must be an Array or a Hash.")
+    if serving_size > 2
+      raise ArgumentError, "filter(): block must define at most two parameters; index, value. Block has #{serving_size}; "+
+      pblock.parameter_names.join(', ')
+    end
+    enum = Puppet::Pops::Types::Enumeration.enumerator(receiver)
+    unless enum
+      raise ArgumentError, ("filter(): wrong argument type (#{receiver.class}; must be something enumerable.")
+    end
+    filter_Enumerator(enum, self, pblock, serving_size)
   end
 end

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

@@ -32,6 +32,6 @@ Puppet::Parser::Functions::newfunction(:generate, :arity => -2, :type => :rvalue
       begin
         Dir.chdir(File.dirname(args[0])) { Puppet::Util::Execution.execute(args) }
       rescue Puppet::ExecutionFailure => detail
-        raise Puppet::ParseError, "Failed to execute generator #{args[0]}: #{detail}"
+        raise Puppet::ParseError, "Failed to execute generator #{args[0]}: #{detail}", detail.backtrace
       end
 end

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

@@ -1,5 +1,6 @@
 # Include the specified classes
-Puppet::Parser::Functions::newfunction(:include, :arity => -2, :doc => "Declares one or more classes, causing the resources in them to be
+Puppet::Parser::Functions::newfunction(:include, :arity => -2, :doc =>
+"Declares one or more classes, causing the resources in them to be
 evaluated and added to the catalog. Accepts a class name, an array of class
 names, or a comma-separated list of class names.
 
@@ -15,7 +16,7 @@ and resource-like declarations with the same class.
 
 The `include` function does not cause classes to be contained in the class
 where they are declared. For that, see the `contain` function. It also
-does not create a dependency relationship between the declared class and th
+does not create a dependency relationship between the declared class and the
 surrounding class; for that, see the `require` function.") do |vals|
     if vals.is_a?(Array)
       # Protect against array inside array

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

@@ -0,0 +1,79 @@
+Puppet::Parser::Functions::newfunction(:inline_epp, :type => :rvalue, :arity => -2, :doc =>
+"Evaluates an Embedded Puppet Template (EPP) string and returns the rendered text result as a String.
+
+EPP support the following tags:
+
+* `<%= puppet expression %>` - This tag renders the value of the expression it contains.
+* `<% puppet expression(s) %>` - This tag will execute the expression(s) it contains, but renders nothing.
+* `<%# comment %>` - The tag and its content renders nothing.
+* `<%%` or `%%>` - Renders a literal `<%` or `%>` respectively.
+* `<%-` - Same as `<%` but suppresses any leading whitespace.
+* `-%>` - Same as `%>` but suppresses any trailing whitespace on the same line (including line break).
+* `<%-( parameters )-%>` - When placed as the first tag declares the template's parameters.
+
+Inline EPP supports the following visibilities of variables in scope which depends on how EPP parameters
+are used - see further below:
+
+* Global scope (i.e. top + node scopes) - global scope is always visible
+* Global + Enclosing scope - if the EPP template does not declare parameters, and no arguments are given
+* Global + all given arguments - if the EPP template does not declare parameters, and arguments are given
+* Global + declared parameters - if the EPP declares parameters, given argument names must match
+
+EPP supports parameters by placing an optional parameter list as the very first element in the EPP. As an example,
+`<%-( $x, $y, $z='unicorn' )-%>` when placed first in the EPP text declares that the parameters `x` and `y` must be
+given as template arguments when calling `inline_epp`, and that `z` if not given as a template argument
+defaults to `'unicorn'`. Template parameters are available as variables, e.g.arguments `$x`, `$y` and `$z` in the example.
+Note that `<%-` must be used or any leading whitespace will be interpreted as text
+
+Arguments are passed to the template by calling `inline_epp` with a Hash as the last argument, where parameters
+are bound to values, e.g. `inline_epp('...', {'x'=>10, 'y'=>20})`. Excess arguments may be given
+(i.e. undeclared parameters) only if the EPP templates does not declare any parameters at all.
+Template parameters shadow variables in outer scopes.
+
+Note: An inline template is best stated using a single-quoted string, or a heredoc since a double-quoted string
+is subject to expression interpolation before the string is parsed as an EPP template. Here are examples
+(using heredoc to define the EPP text):
+
+    # produces 'Hello local variable world!'
+    $x ='local variable'
+    inline_epptemplate(@(END:epp))
+    <%-( $x )-%>
+    Hello <%= $x %> world!
+    END
+
+    # produces 'Hello given argument world!'
+    $x ='local variable world'
+    inline_epptemplate(@(END:epp), { x =>'given argument'})
+    <%-( $x )-%>
+    Hello <%= $x %> world!
+    END
+
+    # produces 'Hello given argument world!'
+    $x ='local variable world'
+    inline_epptemplate(@(END:epp), { x =>'given argument'})
+    <%-( $x )-%>
+    Hello <%= $x %>!
+    END
+
+    # results in error, missing value for y
+    $x ='local variable world'
+    inline_epptemplate(@(END:epp), { x =>'given argument'})
+    <%-( $x, $y )-%>
+    Hello <%= $x %>!
+    END
+
+    # Produces 'Hello given argument planet'
+    $x ='local variable world'
+    inline_epptemplate(@(END:epp), { x =>'given argument'})
+    <%-( $x, $y=planet)-%>
+    Hello <%= $x %> <%= $y %>!
+    END
+
+- Since 3.5
+- Requires Future Parser") do |arguments|
+  # Requires future parser
+  unless Puppet[:parser] == "future"
+    raise ArgumentError, "inline_epp(): function is only available when --parser future is in effect"
+  end
+  Puppet::Pops::Evaluator::EppEvaluator.inline_epp(self, arguments[0], arguments[1])
+end

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

@@ -15,7 +15,7 @@ Puppet::Parser::Functions::newfunction(:inline_template, :type => :rvalue, :arit
         wrapper.result(string)
       rescue => detail
         raise Puppet::ParseError,
-          "Failed to parse inline template: #{detail}"
+          "Failed to parse inline template: #{detail}", detail.backtrace
       end
     end.join("")
 end

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

@@ -1,44 +1,144 @@
 Puppet::Parser::Functions.newfunction(:lookup, :type => :rvalue, :arity => -2, :doc => <<-'ENDHEREDOC') do |args|
-Looks up data defined using Puppet Bindings.
-The function is callable with one or two arguments and optionally with a lambda to process the result.
-The second argument can be a type specification; a String that describes the type of the produced result.
-If a value is found, an assert is made that the value is compliant with the specified type.
+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.
 
-When called with one argument; the name:
+The lookup function can be called in one of these ways:
 
-    lookup('the_name')
+    lookup(name)
+    lookup(name, type)
+    lookup(name, type, default)
+    lookup(options_hash)
+    lookup(name, options_hash)
+
+The function may optionally be called with a code block / lambda with the following signatures:
+
+    lookup(...) |$result| { ... }
+    lookup(...) |$name, $result| { ... }
+    lookup(...) |$name, $result, $default| { ... }
+
+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 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.
 
-When called with two arguments; the name, and the expected type:
+The content of the options hash is:
 
-    lookup('the_name', 'String')
+* `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`.
+* `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.
 
-Using a lambda to process the looked up result.
+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']`.
 
-    lookup('the_name') |$result| { if $result == undef { 'Jane Doe' } else { $result }}
+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:
 
-* the basic types; 'Integer', 'String', 'Float', 'Boolean', or 'Pattern' (regular expression)
-* an Array with an optional element type given in '[]', that when not given defaults to '[Data]'
-* a Hash with optional key and value types given in '[]', where key type defaults to 'Literal' and value to 'Data', if
-  only one type is given, the key defaults to 'Literal'
-* the abstract type 'Literal' which is one of the basic types
-* the abstract type 'Data' which is 'Literal', or type compatible with Array[Data], or Hash[Literal, Data]
-* the abstract type 'Collection' which is Array or Hash of any element type.
-* the abstract type 'Object' which is any kind of type
+  * 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:
+
+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`:
+
+    lookup('the_name')
+
+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
+
+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):
+
+    lookup('the_name', 'String', 'Fred') # 3x
+    lookup('the_name', String, 'Fred')   # parser future
+
+Using a lambda to process the looked up result - asserting that it starts with an upper case letter:
+
+    # 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
+    }
+
+Including the name in the error
+
+    # 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
+    }
+
+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`.
+
+All options work as the corresponding (direct) argument. The `first_found` option and
+`accept_undef` are however only available as options.
+
+Using first_found semantics option to return the first name that has a bound 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 }
 
 ENDHEREDOC
 
   unless Puppet[:binder] || Puppet[:parser] == 'future'
     raise Puppet::ParseError, "The lookup function is only available with settings --binder true, or --parser future" 
   end
-  type_parser = Puppet::Pops::Types::TypeParser.new
-  pblock    = args[-1] if args[-1].is_a?(Puppet::Parser::AST::Lambda)
-  type_name = args[1] unless args[1].is_a?(Puppet::Parser::AST::Lambda)
-  type = type_parser.parse( type_name || "Data")
-  result = compiler.injector.lookup(self, type, args[0])
-  if pblock
-    result = pblock.call(self, result.nil? ? :undef : result)
-  end
-  result.nil? ? :undef : result
+  Puppet::Pops::Binder::Lookup.lookup(self, args)
 end