puppet-retrospec 0.12.2 → 1.0.0

data/vendor/gems/puppet-4.5.2/lib/puppet/pops/loaders.rb

@@ -0,0 +1,352 @@
+module Puppet::Pops
+class Loaders
+  class LoaderError < Puppet::Error; end
+
+  attr_reader :static_loader
+  attr_reader :puppet_system_loader
+  attr_reader :public_environment_loader
+  attr_reader :private_environment_loader
+  attr_reader :implementation_registry
+
+  def initialize(environment)
+
+    # Create the set of loaders
+    # 1. Puppet, loads from the "running" puppet - i.e. bundled functions, types, extension points and extensions
+    #    These cannot be cached since a  loaded instance will be bound to its closure scope which holds on to
+    #    a compiler and all loaded types. Subsequent request would find remains of the environment that loaded
+    #    the content. PUP-4461.
+    #
+    @puppet_system_loader = create_puppet_system_loader()
+
+    # 2. Environment loader - i.e. what is bound across the environment, may change for each setup
+    #    TODO: loaders need to work when also running in an agent doing catalog application. There is no
+    #    concept of environment the same way as when running as a master (except when doing apply).
+    #    The creation mechanisms should probably differ between the two.
+    #
+    @private_environment_loader = create_environment_loader(environment)
+
+    # 3. The implementation registry maintains mappings between Puppet types and Runtime types for
+    #    the current environment
+    @implementation_registry = Types::ImplementationRegistry.new(@private_environment_loader)
+    Pcore.init(@puppet_system_loader, @implementation_registry)
+
+    # 4. module loaders are set up from the create_environment_loader, they register themselves
+  end
+
+  # Clears the cached static and puppet_system loaders (to enable testing)
+  #
+  def self.clear
+    @@static_loader = nil
+  end
+
+  # Calls {#loaders} to obtain the {{Loaders}} instance and then uses it to find the appropriate loader
+  # for the given `module_name`, or for the environment in case `module_name` is `nil` or empty.
+  #
+  # @param module_name [String,nil] the name of the module
+  # @return [Loader::Loader] the found loader
+  # @raise [Puppet::ParseError] if no loader can be found
+  # @api private
+  def self.find_loader(module_name)
+    loaders.find_loader(module_name)
+  end
+
+  def self.static_loader
+    # The static loader can only be changed after a reboot
+    @@static_loader ||= Loader::StaticLoader.new()
+  end
+
+  def self.implementation_registry
+    loaders = Puppet.lookup(:loaders) { nil }
+    loaders.nil? ? nil : loaders.implementation_registry
+  end
+
+  def register_implementations(*obj_classes)
+    loader = @private_environment_loader
+    types = obj_classes.map do |obj_class|
+      type = obj_class._ptype
+      typed_name = Loader::Loader::TypedName.new(:type, type.name.downcase)
+      entry = loader.loaded_entry(typed_name)
+      loader.set_entry(typed_name, type, obj_class._plocation) if entry.nil? || entry.value.nil?
+      type
+    end
+    # Resolve lazy so that all types can cross reference eachother
+    parser = Types::TypeParser.new
+    types.each { |type| type.resolve(parser, loader) }
+  end
+
+  # Register the given type with the Runtime3TypeLoader. The registration will not happen unless
+  # the type system has been initialized.
+  #
+  # @param name [String,Symbol] the name of the entity being set
+  # @param origin [URI] the origin or the source where the type is defined
+  # @api private
+  def self.register_runtime3_type(name, origin)
+    loaders = Puppet.lookup(:loaders) { nil }
+    unless loaders.nil?
+      name = name.to_s
+      caps_name = Types::TypeFormatter.singleton.capitalize_segments(name)
+      typed_name = Loader::Loader::TypedName.new(:type, name.downcase)
+      loaders.runtime3_type_loader.set_entry(typed_name, Types::PResourceType.new(caps_name), origin)
+    end
+    nil
+  end
+
+  # Finds the `Loaders` instance by looking up the :loaders in the global Puppet context
+  #
+  # @return [Loaders] the loaders instance
+  # @raise [Puppet::ParseError] if loader has been bound to the global context
+  # @api private
+  def self.loaders
+    loaders = Puppet.lookup(:loaders) { nil }
+    raise Puppet::ParseError, "Internal Error: Puppet Context ':loaders' missing" if loaders.nil?
+    loaders
+  end
+
+  # Finds the appropriate loader for the given `module_name`, or for the environment in case `module_name`
+  # is `nil` or empty.
+  #
+  # @param module_name [String,nil] the name of the module
+  # @return [Loader::Loader] the found loader
+  # @raise [Puppet::ParseError] if no loader can be found
+  # @api private
+  def find_loader(module_name)
+    if module_name.nil? || module_name == ''
+      # TODO : Later when fdefinition can be private, a decision is needed regarding what that means.
+      #        A private environment loader could be used for logic outside of modules, then only that logic
+      #        would see the definition.
+      #
+      # Use the private loader, this definition may see the environment's dependencies (currently, all modules)
+      loader = private_environment_loader()
+      raise Puppet::ParseError, 'Internal Error: did not find public loader' if loader.nil?
+      loader
+    else
+      # TODO : Later check if definition is private, and then add it to private_loader_for_module
+      #
+      loader = public_loader_for_module(module_name)
+      raise Puppet::ParseError, "Internal Error: did not find public loader for module: '#{module_name}'" if loader.nil?
+      loader
+    end
+  end
+
+  def static_loader
+    self.class.static_loader
+  end
+
+  def puppet_system_loader
+    @puppet_system_loader
+  end
+
+  def runtime3_type_loader
+    @runtime3_type_loader
+  end
+
+  def public_loader_for_module(module_name)
+    md = @module_resolver[module_name] || (return nil)
+    # Note, this loader is not resolved until there is interest in the visibility of entities from the
+    # perspective of something contained in the module. (Many request may pass through a module loader
+    # without it loading anything.
+    # See {#private_loader_for_module}, and not in {#configure_loaders_for_modules}
+    md.public_loader
+  end
+
+  def private_loader_for_module(module_name)
+    md = @module_resolver[module_name] || (return nil)
+    # Since there is interest in the visibility from the perspective of entities contained in the
+    # module, it must be resolved (to provide this visibility).
+    # See {#configure_loaders_for_modules}
+    unless md.resolved?
+      @module_resolver.resolve(md)
+    end
+    md.private_loader
+  end
+
+  private
+
+  def create_puppet_system_loader()
+    Loader::ModuleLoaders.system_loader_from(static_loader, self)
+  end
+
+  def create_environment_loader(environment)
+    # This defines where to start parsing/evaluating - the "initial import" (to use 3x terminology)
+    # Is either a reference to a single .pp file, or a directory of manifests. If the environment becomes
+    # a module and can hold functions, types etc. then these are available across all other modules without
+    # them declaring this dependency - it is however valuable to be able to treat it the same way
+    # bindings and other such system related configuration.
+
+    # This is further complicated by the many options available:
+    # - The environment may not have a directory, the code comes from one appointed 'manifest' (site.pp)
+    # - The environment may have a directory and also point to a 'manifest'
+    # - The code to run may be set in settings (code)
+
+    # Further complication is that there is nothing specifying what the visibility is into
+    # available modules. (3x is everyone sees everything).
+    # Puppet binder currently reads confdir/bindings - that is bad, it should be using the new environment support.
+
+    # The environment is not a namespace, so give it a nil "module_name"
+    module_name = nil
+    loader_name = "environment:#{environment.name}"
+    env_conf = Puppet.lookup(:environments).get_conf(environment.name)
+
+    # Create the 3.x resource type loader
+    @runtime3_type_loader = Loader::Runtime3TypeLoader.new(puppet_system_loader, environment)
+
+    if env_conf.nil? || !env_conf.is_a?(Puppet::Settings::EnvironmentConf)
+      # Not a real directory environment, cannot work as a module TODO: Drop when legacy env are dropped?
+      loader = Loader::SimpleEnvironmentLoader.new(@runtime3_type_loader, loader_name)
+    else
+      # View the environment as a module to allow loading from it - this module is always called 'environment'
+      loader = Loader::ModuleLoaders.module_loader_from(@runtime3_type_loader, self, 'environment', env_conf.path_to_env)
+    end
+
+    # An environment has a module path even if it has a null loader
+    configure_loaders_for_modules(loader, environment)
+    # modules should see this loader
+    @public_environment_loader = loader
+
+    # Code in the environment gets to see all modules (since there is no metadata for the environment)
+    # but since this is not given to the module loaders, they can not load global code (since they can not
+    # have prior knowledge about this
+    loader = Loader::DependencyLoader.new(loader, "environment", @module_resolver.all_module_loaders())
+
+    # The module loader gets the private loader via a lazy operation to look up the module's private loader.
+    # This does not work for an environment since it is not resolved the same way.
+    # TODO: The EnvironmentLoader could be a specialized loader instead of using a ModuleLoader to do the work.
+    #       This is subject to future design - an Environment may move more in the direction of a Module.
+    @public_environment_loader.private_loader = loader
+    loader
+  end
+
+  def configure_loaders_for_modules(parent_loader, environment)
+    @module_resolver = mr = ModuleResolver.new()
+    environment.modules.each do |puppet_module|
+      # Create data about this module
+      md = LoaderModuleData.new(puppet_module)
+      mr[puppet_module.name] = md
+      md.public_loader = Loader::ModuleLoaders.module_loader_from(parent_loader, self, md.name, md.path)
+    end
+    # NOTE: Do not resolve all modules here - this is wasteful if only a subset of modules / functions are used
+    #       The resolution is triggered by asking for a module's private loader, since this means there is interest
+    #       in the visibility from that perspective.
+    #       If later, it is wanted that all resolutions should be made up-front (to capture errors eagerly, this
+    #       can be introduced (better for production), but may be irritating in development mode.
+  end
+
+  # =LoaderModuleData
+  # Information about a Module and its loaders.
+  # TODO: should have reference to real model element containing all module data; this is faking it
+  # TODO: Should use Puppet::Module to get the metadata (as a hash) - a somewhat blunt instrument, but that is
+  #       what is available with a reasonable API.
+  #
+  class LoaderModuleData
+
+    attr_accessor :state
+    attr_accessor :public_loader
+    attr_accessor :private_loader
+    attr_accessor :resolutions
+
+    # The Puppet::Module this LoaderModuleData represents in the loader configuration
+    attr_reader :puppet_module
+
+    # @param puppet_module [Puppet::Module] the module instance for the module being represented
+    #
+    def initialize(puppet_module)
+      @state = :initial
+      @puppet_module = puppet_module
+      @resolutions = []
+      @public_loader = nil
+      @private_loader = nil
+    end
+
+    def name
+      @puppet_module.name
+    end
+
+    def version
+      @puppet_module.version
+    end
+
+    def path
+      @puppet_module.path
+    end
+
+    def resolved?
+      @state == :resolved
+    end
+
+    def restrict_to_dependencies?
+      @puppet_module.has_metadata?
+    end
+
+    def unmet_dependencies?
+      @puppet_module.unmet_dependencies.any?
+    end
+
+    def dependency_names
+      @puppet_module.dependencies_as_modules.collect(&:name)
+    end
+  end
+
+  # Resolves module loaders - resolution of model dependencies is done by Puppet::Module
+  #
+  class ModuleResolver
+
+    def initialize()
+      @index = {}
+      @all_module_loaders = nil
+    end
+
+    def [](name)
+      @index[name]
+    end
+
+    def []=(name, module_data)
+      @index[name] = module_data
+    end
+
+    def all_module_loaders
+      @all_module_loaders ||= @index.values.map {|md| md.public_loader }
+    end
+
+    def resolve(module_data)
+      if module_data.resolved?
+        return
+      else
+        module_data.private_loader =
+          if module_data.restrict_to_dependencies?
+            create_loader_with_only_dependencies_visible(module_data)
+          else
+            create_loader_with_all_modules_visible(module_data)
+          end
+      end
+    end
+
+    private
+
+    def create_loader_with_all_modules_visible(from_module_data)
+      Puppet.debug{"ModuleLoader: module '#{from_module_data.name}' has unknown dependencies - it will have all other modules visible"}
+
+      Loader::DependencyLoader.new(from_module_data.public_loader, from_module_data.name, all_module_loaders())
+    end
+
+    def create_loader_with_only_dependencies_visible(from_module_data)
+      if from_module_data.unmet_dependencies?
+        if Puppet[:strict] != :off
+          msg = "ModuleLoader: module '#{from_module_data.name}' has unresolved dependencies" \
+              " - it will only see those that are resolved." \
+              " Use 'puppet module list --tree' to see information about modules"
+          case Puppet[:strict]
+          when :error
+              raise LoaderError.new(msg)
+          when :warning
+            Puppet.warn_once(:unresolved_module_dependencies,
+                             "unresolved_dependencies_for_module_#{from_module_data.name}",
+                             msg)
+          end
+        end
+      end
+      dependency_loaders = from_module_data.dependency_names.collect { |name| @index[name].public_loader }
+      Loader::DependencyLoader.new(from_module_data.public_loader, from_module_data.name, dependency_loaders)
+    end
+  end
+end
+end

data/vendor/gems/puppet-4.5.2/lib/puppet/pops/lookup.rb

@@ -0,0 +1,79 @@
+# This class is the backing implementation of the Puppet function 'lookup'.
+# See puppet/functions/lookup.rb for documentation.
+#
+module Puppet::Pops
+module Lookup
+  LOOKUP_OPTIONS = 'lookup_options'.freeze
+  GLOBAL = '__global__'.freeze
+
+  # 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 name [String|Array<String>] The name or names to lookup
+  # @param type [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 merge [MergeStrategy,String,Hash<String,Object>,nil] Merge strategy or hash with strategy and options
+  # @param lookup_invocation [Invocation] Invocation data containing scope, overrides, and defaults
+  # @return [Object] The found value
+  #
+  def self.lookup(name, value_type, default_value, has_default, merge, lookup_invocation)
+    value_type = 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 = 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(["Value found for key '%s' in override hash", key], 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', value_type, value)] unless value.equal?(not_found)
+      memo
+    end
+
+    # 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(["Value found for key '%s' in default values hash", key], value_type, default_values[key]) : not_found
+          memo = [key, value]
+          break memo unless value.equal?(not_found)
+          memo
+        end
+      end
+    end
+
+    answer = result_with_name[1]
+    if answer.equal?(not_found)
+      if block_given?
+        answer = assert_type('Value returned from default block', value_type, yield(name))
+      elsif has_default
+        answer = assert_type('Default value', value_type, default_value)
+      else
+        fail_lookup(names)
+      end
+    end
+    answer
+  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
+
+  def self.assert_type(subject, type, value)
+    Types::TypeAsserter.assert_instance_of(subject, type, value)
+  end
+  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::DataBinding::LookupError, "Function lookup() did not find a value for #{name_part}"
+  end
+  private_class_method :fail_lookup
+end
+end

data/vendor/gems/puppet-4.5.2/lib/puppet/pops/lookup/explainer.rb

@@ -0,0 +1,509 @@
+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, :value
+    attr_accessor :key
+
+    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 ExplainTop < ExplainTreeNode
+    def initialize(parent, type, key)
+      super(parent)
+      @type = type
+      self.key = key
+    end
+
+    def dump_on(io, indent, first_indent)
+      io << first_indent << 'Searching for "' << key << "\"\n"
+      indent = increase_indent(indent)
+      branches.each {|b| b.dump_on(io, indent, indent)}
+    end
+  end
+
+  class ExplainInvalidKey < ExplainTreeNode
+    def initialize(parent, key)
+      super(parent)
+      @key = key
+    end
+
+    def dump_on(io, indent, first_indent)
+      io << first_indent << "Invalid key \"" << @key << "\"\n"
+    end
+
+    def type
+      :invalid_key
+    end
+  end
+
+  class ExplainMergeSource < ExplainNode
+    attr_reader :merge_source
+
+    def initialize(merge_source)
+      @merge_source = merge_source
+    end
+
+    def dump_on(io, indent, first_indent)
+      io << first_indent << 'Using merge options from "' << merge_source << "\" hash\n"
+    end
+
+    def to_hash
+      { :type => type, :merge_source => merge_source }
+    end
+
+    def type
+      :merge_source
+    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)
+      return if branches.size == 0
+
+      # 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 ExplainSubLookup < ExplainTreeNode
+    def initialize(parent, sub_key)
+      super(parent)
+      @sub_key = sub_key
+    end
+
+    def dump_on(io, indent, first_indent)
+      io << indent << 'Sub key: "' << @sub_key.join('.') << "\"\n"
+      indent = increase_indent(indent)
+      branches.each {|b| b.dump_on(io, indent, indent)}
+      dump_outcome(io, indent)
+    end
+
+    def type
+      :sub_key
+    end
+  end
+
+  class ExplainKeySegment < ExplainTreeNode
+    def initialize(parent, segment)
+      super(parent)
+      @segment = segment
+    end
+
+    def dump_on(io, indent, first_indent)
+      dump_outcome(io, indent)
+    end
+
+    def type
+      :segment
+    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(explain_options = false, only_explain_options = false)
+      @current = self
+      @explain_options = explain_options
+      @only_explain_options = only_explain_options
+    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)
+        when :sub_lookup
+          ExplainSubLookup.new(@current, qualifier)
+        when :segment
+          ExplainKeySegment.new(@current, qualifier)
+        when :meta, :data
+          ExplainTop.new(@current, qualifier_type, qualifier)
+        when :invalid_key
+          ExplainInvalidKey.new(@current, qualifier)
+        else
+          raise ArgumentError, "Unknown Explain type #{qualifier_type}"
+        end
+      @current.branches << node
+      @current = node
+    end
+
+    def only_explain_options?
+      @only_explain_options
+    end
+
+    def explain_options?
+      @explain_options
+    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_merge_source(merge_source)
+      @current.branches << ExplainMergeSource.new(merge_source)
+    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