puppet 4.2.0 → 4.3.0

data/lib/puppet/pops/lookup/explainer.rb

@@ -0,0 +1,402 @@
+module Puppet::Pops::Lookup
+
+# The ExplainNode contains information of a specific node in a tree traversed during
+# lookup. The tree can be traversed using the `parent` and `branches` attributes of
+# each node.
+#
+# Each leaf node contains information about what happened when the leaf of the branch
+# was traversed.
+  class ExplainNode
+    def branches
+      @branches ||= []
+    end
+
+    def to_hash
+      hash = {}
+      hash[:branches] = @branches.map {|b| b.to_hash} unless @branches.nil? || @branches.empty?
+      hash
+    end
+
+    def to_s
+      io = StringIO.new
+      dump_on(io, '', '')
+      io.string
+    end
+
+    def dump_on(io, indent, first_indent)
+    end
+  end
+
+  class ExplainTreeNode < ExplainNode
+    attr_reader :parent, :event, :key, :value
+
+    def initialize(parent)
+      @parent = parent
+      @event = nil
+    end
+
+    def found_in_overrides(key, value)
+      @key = key
+      @value = value
+      @event = :found_in_overrides
+    end
+
+    def found_in_defaults(key, value)
+      @key = key
+      @value = value
+      @event = :found_in_defaults
+    end
+
+    def found(key, value)
+      @key = key
+      @value = value
+      @event = :found
+    end
+
+    def result(value)
+      @value = value
+      @event = :result
+    end
+
+    def not_found(key)
+      @key = key
+      @event = :not_found
+    end
+
+    def path_not_found
+      @event = :path_not_found
+    end
+
+    def module_not_found
+      @event = :module_not_found
+    end
+
+    def increase_indent(indent)
+      indent + '  '
+    end
+
+    def to_hash
+      hash = super
+      hash[:key] = @key unless @key.nil?
+      hash[:value] = @value if [:found, :found_in_defaults, :found_in_overrides, :result].include?(@event)
+      hash[:event] = @event unless @event.nil?
+      hash[:type] = type
+      hash
+    end
+
+    def type
+      :root
+    end
+
+    def dump_outcome(io, indent)
+      io << indent << 'No such key: "' << @key << "\"\n" if @event == :not_found
+      if [:found, :found_in_overrides, :found_in_defaults].include?(@event)
+        io << indent << 'Found key: "' << @key << '" value: '
+        dump_value(io, indent, @value)
+        io << ' in overrides' if @event == :found_in_overrides
+        io << ' in defaults' if @event == :found_in_defaults
+        io << "\n"
+      end
+    end
+
+    def dump_value(io, indent, value)
+      case value
+      when Hash
+        io << '{'
+        unless value.empty?
+          inner_indent = increase_indent(indent)
+          value.reduce("\n") do |sep, (k, v)|
+            io << sep << inner_indent
+            dump_value(io, inner_indent, k)
+            io << ' => '
+            dump_value(io, inner_indent, v)
+            ",\n"
+          end
+          io << "\n" << indent
+        end
+        io << '}'
+      when Array
+        io << '['
+        unless value.empty?
+          inner_indent = increase_indent(indent)
+          value.reduce("\n") do |sep, v|
+            io << sep << inner_indent
+            dump_value(io, inner_indent, v)
+            ",\n"
+          end
+          io << "\n" << indent
+        end
+        io << ']'
+      else
+        io << value.inspect
+      end
+    end
+  end
+
+  class ExplainInterpolate < ExplainTreeNode
+    def initialize(parent, expression)
+      super(parent)
+      @expression = expression
+    end
+
+    def dump_on(io, indent, first_indent)
+      io << first_indent << 'Interpolation on "' << @expression << "\"\n"
+      indent = increase_indent(indent)
+      branches.each {|b| b.dump_on(io, indent, indent)}
+    end
+
+    def to_hash
+      hash = super
+      hash[:expression] = @expression
+      hash
+    end
+
+    def type
+      :interpolate
+    end
+  end
+
+  class ExplainMerge < ExplainTreeNode
+    def initialize(parent, merge)
+      super(parent)
+      @merge = merge
+    end
+
+    def dump_on(io, indent, first_indent)
+      # It's pointless to report a merge where there's only one branch
+      return branches[0].dump_on(io, indent, first_indent) if branches.size == 1
+
+      io << first_indent << 'Merge strategy ' << @merge.class.key << "\n"
+      indent = increase_indent(indent)
+      options = options_wo_strategy
+      unless options.nil?
+        io << indent << 'Options: '
+        dump_value(io, indent, options)
+        io << "\n"
+      end
+      branches.each {|b| b.dump_on(io, indent, indent)}
+      if @event == :result
+        io << indent << 'Merged result: '
+        dump_value(io, indent, @value)
+        io << "\n"
+      end
+    end
+
+    def to_hash
+      return branches[0].to_hash if branches.size == 1
+      hash = super
+      hash[:merge] = @merge.class.key
+      options = options_wo_strategy
+      hash[:options] = options unless options.nil?
+      hash
+    end
+
+    def type
+      :merge
+    end
+
+    def options_wo_strategy
+      options = @merge.options
+      if !options.nil? && options.include?('strategy')
+        options = options.dup
+        options.delete('strategy')
+      end
+      options.empty? ? nil : options
+    end
+  end
+
+  class ExplainModule < ExplainTreeNode
+    def initialize(parent, mod)
+      super(parent)
+      @module = mod
+    end
+
+    def dump_on(io, indent, first_indent)
+      io << indent << 'Module "' << @module << '"'
+      if branches.size == 1
+        branches[0].dump_on(io, indent, ' using ')
+      else
+        io << "\n"
+        indent = increase_indent(indent)
+        branches.each {|b| b.dump_on(io, indent, indent)}
+      end
+      io << indent << "Module not found\n" if @event == :module_not_found
+    end
+
+    def to_hash
+      if branches.size == 1
+        branches[0].to_hash.merge(:module => @module)
+      else
+        hash = super
+        hash[:module] = @module
+        hash
+      end
+    end
+
+    def type
+      :module
+    end
+  end
+
+  class ExplainGlobal < ExplainTreeNode
+    def initialize(parent, binding_terminus)
+      super(parent)
+      @binding_terminus = binding_terminus
+    end
+
+    def dump_on(io, indent, first_indent)
+      io << first_indent << 'Data Binding "' << @binding_terminus << "\"\n"
+      indent = increase_indent(indent)
+      branches.each {|b| b.dump_on(io, indent, indent)}
+      dump_outcome(io, indent)
+    end
+
+    def to_hash
+      hash = super
+      hash[:name] = @binding_terminus
+      hash
+    end
+
+    def type
+      :global
+    end
+  end
+
+  class ExplainDataProvider < ExplainTreeNode
+    def initialize(parent, provider)
+      super(parent)
+      @provider = provider
+    end
+
+    def dump_on(io, indent, first_indent)
+      io << first_indent << 'Data Provider "' << @provider.name << "\"\n"
+      indent = increase_indent(indent)
+      io << indent << 'ConfigurationPath "' << @provider.config_path << "\"\n" if @provider.respond_to?(:config_path)
+      branches.each {|b| b.dump_on(io, indent, indent)}
+      dump_outcome(io, indent)
+    end
+
+    def to_hash
+      hash = super
+      hash[:name] = @provider.name
+      hash[:configuration_path] = @provider.config_path.to_s if @provider.respond_to?(:config_path)
+      hash
+    end
+
+    def type
+      :data_provider
+    end
+  end
+
+  class ExplainPath < ExplainTreeNode
+    def initialize(parent, path)
+      super(parent)
+      @path = path
+    end
+
+    def dump_on(io, indent, first_indent)
+      io << indent << 'Path "' << @path.path << "\"\n"
+      indent = increase_indent(indent)
+      io << indent << 'Original path: ' << @path.original_path << "\n"
+      branches.each {|b| b.dump_on(io, indent, indent)}
+      io << indent << "Path not found\n" if @event == :path_not_found
+      dump_outcome(io, indent)
+    end
+
+    def to_hash
+      hash = super
+      hash[:original_path] = @path.original_path
+      hash[:path] = @path.path.to_s
+      hash
+    end
+
+    def type
+      :path
+    end
+  end
+
+  class ExplainScope < ExplainTreeNode
+    def initialize(parent)
+      super(parent)
+    end
+
+    def dump_on(io, indent, first_indent)
+      io << indent << 'Global Scope' << "\"\n"
+      indent = increase_indent(indent)
+      dump_outcome(io, indent)
+    end
+
+    def type
+      :scope
+    end
+  end
+
+  class Explainer < ExplainNode
+    def initialize
+      @current = self
+    end
+
+    def push(qualifier_type, qualifier)
+      node = case (qualifier_type)
+        when :global
+         ExplainGlobal.new(@current, qualifier)
+        when :path
+          ExplainPath.new(@current, qualifier)
+        when :module
+          ExplainModule.new(@current, qualifier)
+        when :interpolate
+          ExplainInterpolate.new(@current, qualifier)
+        when :data_provider
+          ExplainDataProvider.new(@current, qualifier)
+        when :merge
+          ExplainMerge.new(@current, qualifier)
+        when :scope
+          ExplainScope.new(@current)
+        else
+          raise ArgumentError, "Unknown Explain type #{qualifier_type}"
+        end
+      @current.branches << node
+      @current = node
+    end
+
+    def pop
+      @current = @current.parent unless @current.parent.nil?
+    end
+
+    def accept_found_in_overrides(key, value)
+      @current.found_in_overrides(key, value)
+    end
+
+    def accept_found_in_defaults(key, value)
+      @current.found_in_defaults(key, value)
+    end
+
+    def accept_found(key, value)
+      @current.found(key, value)
+    end
+
+    def accept_not_found(key)
+      @current.not_found(key)
+    end
+
+    def accept_path_not_found
+      @current.path_not_found
+    end
+
+    def accept_module_not_found
+      @current.module_not_found
+    end
+
+    def accept_result(result)
+      @current.result(result)
+    end
+
+    def dump_on(io, indent, first_indent)
+      branches.each { |b| b.dump_on(io, indent, first_indent) }
+    end
+
+    def to_hash
+      branches.size == 1 ? branches[0].to_hash : super
+    end
+  end
+end

data/lib/puppet/pops/lookup/invocation.rb

@@ -0,0 +1,117 @@
+module Puppet::Pops::Lookup
+  class Invocation
+    attr_reader :scope, :override_values, :default_values, :explainer, :module_name
+
+    # Creates a context object for a lookup invocation. The object contains the current scope, overrides, and default
+    # values and may optionally contain an {ExplanationAcceptor} instance that will receive book-keeping information
+    # about the progress of the lookup.
+    #
+    # If the _explain_ argument is a boolean, then _false_ means that no explanation is needed and _true_ means that
+    # the default explanation acceptor should be used. The _explain_ argument may also be an instance of the
+    # `ExplanationAcceptor` class.
+    #
+    # @param scope [Puppet::Parser::Scope] The scope to use for the lookup
+    # @param override_values [Hash<String,Object>|nil] A map to use as override. Values found here are returned immediately (no merge)
+    # @param default_values [Hash<String,Object>] A map to use as the last resort (but before default)
+    # @param explainer [boolean,Explanainer] An boolean true to use the default explanation acceptor or an explainer instance that will receive information about the lookup
+    def initialize(scope, override_values = {}, default_values = {}, explainer = nil)
+      @name_stack = []
+      @scope = scope
+      @override_values = override_values
+      @default_values = default_values
+      unless explainer.is_a?(Explainer)
+        explainer = explainer == true ? Explainer.new : nil
+      end
+      @explainer = explainer
+    end
+
+    def check(name)
+      if @name_stack.include?(name)
+        raise Puppet::DataBinding::RecursiveLookupError, "Recursive lookup detected in [#{@name_stack.join(', ')}]"
+      end
+      return unless block_given?
+
+      @name_stack.push(name)
+      begin
+        yield
+      rescue Puppet::DataBinding::LookupError
+        raise
+      rescue Puppet::Error => detail
+        raise Puppet::DataBinding::LookupError.new(detail.message, detail)
+      ensure
+        @name_stack.pop
+      end
+    end
+
+    # The qualifier_type can be one of:
+    # :global - qualifier is the data binding terminus name
+    # :data_provider - qualifier a DataProvider instance
+    # :path - qualifier is a ResolvedPath instance
+    # :merge - qualifier is a MergeStrategy instance
+    # :module - qualifier is the name of a module
+    # :interpolation - qualifier is the unresolved interpolation expression
+    # :meta - qualifier is the name of a module or nil if that's not applicable
+    #
+    # @param qualifier [Object] A branch, a provider, or a path
+    def with(qualifier_type, qualifier)
+      is_meta = qualifier_type == :meta
+      @module_name = qualifier if is_meta
+      if @explainer.nil?
+        yield
+      else
+        if is_meta
+          save_explainer = @explainer
+          @explainer = nil
+          begin
+            yield
+          ensure
+            @explainer = save_explainer
+          end
+        else
+          @explainer.push(qualifier_type, qualifier)
+          begin
+            yield
+          ensure
+            @explainer.pop
+          end
+        end
+      end
+    end
+
+    def report_found_in_overrides(key, value)
+      @explainer.accept_found_in_overrides(key, value) unless @explainer.nil?
+      value
+    end
+
+    def report_found_in_defaults(key, value)
+      @explainer.accept_found_in_defaults(key, value) unless @explainer.nil?
+      value
+    end
+
+    def report_found(key, value)
+      @explainer.accept_found(key, value) unless @explainer.nil?
+      value
+    end
+
+    # Report the result of a merge or fully resolved interpolated string
+    # @param value [Object] The result to report
+    # @return [Object] the given value
+    def report_result(value)
+      @explainer.accept_result(value) unless @explainer.nil?
+      value
+    end
+
+    def report_not_found(key)
+      @explainer.accept_not_found(key) unless @explainer.nil?
+    end
+
+    def report_path_not_found
+      @explainer.accept_path_not_found unless @explainer.nil?
+    end
+
+    def report_module_not_found
+      @explainer.accept_module_not_found unless @explainer.nil?
+    end
+  end
+end
+

data/lib/puppet/pops/lookup.rb

@@ -1,43 +1,45 @@
 # This class is the backing implementation of the Puppet function 'lookup'.
 # See puppet/functions/lookup.rb for documentation.
 #
-class Puppet::Pops::Lookup
+module Puppet::Pops::Lookup
   # Performs a lookup in the configured scopes and optionally merges the default.
   #
   # This is a backing function and all parameters are assumed to have been type checked.
   # See puppet/functions/lookup.rb for full documentation and all parameter combinations.
   #
-  # @param scope [Puppet::Parser::Scope] The scope to use for the lookup
   # @param name [String|Array<String>] The name or names to lookup
   # @param type [Puppet::Pops::Types::PAnyType|nil] The expected type of the found value
   # @param default_value [Object] The value to use as default when no value is found
   # @param has_default [Boolean] Set to _true_ if _default_value_ is included (_nil_ is a valid _default_value_)
-  # @param override [Hash<String,Object>|nil] A map to use as override. Values found here are returned immediately (no merge)
-  # @param default_values_hash [Hash<String,Object>] A map to use as the last resort (but before default)
-  # @param merge [String|Hash<String,Object>|nil] Merge strategy or hash with strategy and options
+  # @param merge [Puppet::Pops::MergeStrategy,String,Hash<String,Object>,nil] Merge strategy or hash with strategy and options
+  # @param lookup_invocation [Puppet::Pops::Lookup::Invocation] Invocation data containing scope, overrides, and defaults
   # @return [Object] The found value
   #
-  def self.lookup(scope, name, value_type, default_value, has_default, override, default_values_hash, merge)
-    value_type = Puppet::Pops::Types::PDataType.new if value_type.nil?
+  def self.lookup(name, value_type, default_value, has_default, merge, lookup_invocation)
+    value_type = Puppet::Pops::Types::PDataType::DEFAULT if value_type.nil?
     names = name.is_a?(Array) ? name : [name]
 
     # find first name that yields a non-nil result and wrap it in a two element array
     # with name and value.
-    not_found = Object.new
-    result_with_name = names.reduce([nil,not_found]) do |memo, key|
-      value = override.include?(key) ? assert_type('override', value_type, override[key]) : not_found
-      value = search_and_merge(key, scope, merge, not_found) if value.equal?(not_found)
+    not_found = Puppet::Pops::MergeStrategy::NOT_FOUND
+    override_values = lookup_invocation.override_values
+    result_with_name = names.reduce([nil, not_found]) do |memo, key|
+      value = override_values.include?(key) ? assert_type('override', value_type, override_values[key]) : not_found
+      catch(:no_such_key) { value = search_and_merge(key, lookup_invocation, merge) } if value.equal?(not_found)
       break [key, assert_type('found', value_type, value)] unless value.equal?(not_found)
       memo
     end
 
-    # Use the 'default_values_hash' map as a last resort if nothing is found
-    if result_with_name[1].equal?(not_found) && !default_values_hash.empty?
-      result_with_name = names.reduce(result_with_name) do |memo, key|
-        value = default_values_hash.include?(key) ? assert_type('default_values_hash', value_type, default_values_hash[key]) : not_found
-        memo = [ key, value ]
-        break memo unless value.equal?(not_found)
-        memo
+    # Use the 'default_values' hash as a last resort if nothing is found
+    if result_with_name[1].equal?(not_found)
+      default_values = lookup_invocation.default_values
+      unless default_values.empty?
+        result_with_name = names.reduce(result_with_name) do |memo, key|
+          value = default_values.include?(key) ? assert_type('default_values_hash', value_type, default_values[key]) : not_found
+          memo = [key, value]
+          break memo unless value.equal?(not_found)
+          memo
+        end
       end
     end
 
@@ -54,34 +56,10 @@ class Puppet::Pops::Lookup
     answer
   end
 
-  def self.search_and_merge(name, scope, merge, not_found)
-    in_global = lambda { lookup_with_databinding(name, scope, merge) }
-    in_env = lambda { Puppet::DataProviders.lookup_in_environment(name, scope, merge) }
-    in_module = lambda { Puppet::DataProviders.lookup_in_module(name, scope, merge) }
-
-    [in_global, in_env, in_module].reduce(not_found) do |memo, f|
-      found = false # can't trust catch return value since nil is valid
-      value = catch (:no_such_key) do
-        answer = f.call
-        found = true
-        answer
-      end
-      next memo unless found
-      break value if merge.nil? # value found and no merge
-      strategy = Puppet::Pops::MergeStrategy.strategy(merge)
-      memo.equal?(not_found) ? strategy.convert_value(value) : strategy.merge(memo, value)
-    end
-  end
-  private_class_method :search_and_merge
-
-  def self.lookup_with_databinding(key, scope, merge)
-    begin
-      Puppet::DataBinding.indirection.find(key, { :environment => scope.environment.to_s, :variables => scope, :merge => merge })
-    rescue Puppet::DataBinding::LookupError => e
-      raise Puppet::Error, "Error from DataBinding '#{Puppet[:data_binding_terminus]}' while looking up '#{name}': #{e.message}", e
-    end
+  # @api private
+  def self.search_and_merge(name, lookup_invocation, merge)
+    return Puppet::DataProviders.lookup_adapter(lookup_invocation).lookup(name, lookup_invocation, merge)
   end
-  private_class_method :lookup_with_databinding
 
   def self.assert_type(subject, type, value)
     Puppet::Pops::Types::TypeAsserter.assert_instance_of(subject, type, value)
@@ -89,8 +67,8 @@ class Puppet::Pops::Lookup
   private_class_method :assert_type
 
   def self.fail_lookup(names)
-    name_part = names.size == 1 ? "the name '#{names[0]}'" : 'any of the names [' + names.map {|n| "'#{n}'"} .join(', ') + ']'
-    raise Puppet::Error, "Function lookup() did not find a value for #{name_part}"
+    name_part = names.size == 1 ? "the name '#{names[0]}'" : 'any of the names [' + names.map { |n| "'#{n}'" }.join(', ') + ']'
+    raise Puppet::DataBinding::LookupError, "Function lookup() did not find a value for #{name_part}"
   end
   private_class_method :fail_lookup
 end