puppet-retrospec 0.7.0 → 0.7.2

data/vendor/gems/puppet-3.7.3/lib/puppet/pops/adapters.rb

@@ -0,0 +1,109 @@
+# The Adapters module contains adapters for Documentation, Origin, SourcePosition, and Loader.
+#
+module Puppet::Pops::Adapters
+  # A documentation adapter adapts an object with a documentation string.
+  # (The intended use is for a source text parser to extract documentation and store this
+  # in DocumentationAdapter instances).
+  #
+  class DocumentationAdapter < Puppet::Pops::Adaptable::Adapter
+    # @return [String] The documentation associated with an object
+    attr_accessor :documentation
+  end
+
+  # A SourcePosAdapter holds a reference to  a *Positioned* object (object that has offset and length).
+  # This somewhat complex structure makes it possible to correctly refer to a source position
+  # in source that is embedded in some resource; a parser only sees the embedded snippet of source text
+  # and does not know where it was embedded. It also enables lazy evaluation of source positions (they are
+  # rarely needed - typically just when there is an error to report.
+  #
+  # @note It is relatively expensive to compute line and position on line - it is not something that
+  #   should be done for every token or model object.
+  #
+  # @see Puppet::Pops::Utils#find_adapter, Puppet::Pops::Utils#find_closest_positioned
+  #
+  class SourcePosAdapter < Puppet::Pops::Adaptable::Adapter
+    attr_accessor :locator
+
+    def self.create_adapter(o)
+      new(o)
+    end
+
+    def initialize(o)
+      @adapted = o
+    end
+
+    def locator
+      # The locator is always the parent locator, all positioned objects are positioned within their
+      # parent. If a positioned object also has a locator that locator is for its children!
+      #
+      @locator ||= find_locator(@adapted.eContainer)
+    end
+
+    def find_locator(o)
+      if o.nil?
+        raise ArgumentError, "InternalError: SourcePosAdapter for something that has no locator among parents"
+      end
+      case
+      when o.is_a?(Puppet::Pops::Model::Program)
+        return o.locator
+      # TODO_HEREDOC use case of SubLocator instead
+      when o.is_a?(Puppet::Pops::Model::SubLocatedExpression) && !(found_locator = o.locator).nil?
+        return found_locator
+      when adapter = self.class.get(o)
+        return adapter.locator
+      else
+        find_locator(o.eContainer)
+      end
+    end
+    private :find_locator
+
+    def offset
+      @adapted.offset
+    end
+
+    def length
+      @adapted.length
+    end
+
+    # Produces the line number for the given offset.
+    # @note This is an expensive operation
+    #
+    def line
+      # Optimization: manual inlining of locator accessor since this method is frequently called
+      (@locator ||= find_locator(@adapted.eContainer)).line_for_offset(offset)
+    end
+
+    # Produces the position on the line of the given offset.
+    # @note This is an expensive operation
+    #
+    def pos
+      locator.pos_on_line(offset)
+    end
+
+    # Extracts the text represented by this source position (the string is obtained from the locator)
+    def extract_text
+      locator.string.slice(offset, length)
+    end
+
+    # Produces an URI with path?line=n&pos=n. If origin is unknown the URI is string:?line=n&pos=n
+    def to_uri
+      f = locator.file
+      f = 'string:' if f.nil? || f.empty?
+      URI("#{f}?line=#{line.to_s}&pos=#{pos.to_s}")
+    end
+  end
+
+  # A LoaderAdapter adapts an object with a {Puppet::Pops::Loader}. This is used to make further loading from the
+  # perspective of the adapted object take place in the perspective of this Loader.
+  #
+  # It is typically enough to adapt the root of a model as a search is made towards the root of the model
+  # until a loader is found, but there is no harm in duplicating this information provided a contained
+  # object is adapted with the correct loader.
+  #
+  # @see Puppet::Pops::Utils#find_adapter
+  #
+  class LoaderAdapter < Puppet::Pops::Adaptable::Adapter
+    # @return [Puppet::Pops::Loader::Loader] the loader
+    attr_accessor :loader
+  end
+end

data/vendor/gems/puppet-3.7.3/lib/puppet/pops/binder/binder.rb

@@ -0,0 +1,393 @@
+# The Binder is responsible for processing layered bindings that can be used to setup an Injector.
+#
+# An instance should be created and a call to {#define_layers} should be made which will process the layered bindings
+# (handle overrides, abstract entries etc.).
+# The constructed hash with `key => InjectorEntry` mappings is obtained as {#injector_entries}, and is used to initialize an
+# {Puppet::Pops::Binder::Injector Injector}.
+#
+# @api public
+#
+class Puppet::Pops::Binder::Binder
+
+  # @api private
+  attr_reader :injector_entries
+
+  # @api private
+  attr :id_index
+
+  # @api private
+  attr_reader :key_factory
+
+  # A parent Binder or nil
+  # @api private
+  attr_reader :parent
+
+  # The next anonymous key to use
+  # @api private
+  attr_reader :anonymous_key
+
+  # This binder's precedence
+  # @api private
+  attr_reader :binder_precedence
+
+  # @api public
+  def initialize(layered_bindings, parent_binder=nil)
+    @parent = parent_binder
+    @id_index = Hash.new() { |k, v| [] }
+
+    @key_factory = Puppet::Pops::Binder::KeyFactory.new()
+
+    # Resulting hash of all key -> binding
+    @injector_entries = {}
+
+    if @parent.nil?
+      @anonymous_key = 0
+      @binder_precedence = 0
+    else
+      # First anonymous key is the parent's next (non incremented key). (The parent can not change, it is
+      # the final, free key).
+      @anonymous_key = @parent.anonymous_key
+      @binder_precedence = @parent.binder_precedence + 1
+    end
+    define_layers(layered_bindings)
+  end
+
+  # Binds layers from highest to lowest as defined by the given LayeredBindings.
+  # @note
+  #   The model should have been
+  #   validated to get better error messages if the model is invalid. This implementation expects the model
+  #   to be valid, and any errors raised will be more technical runtime errors.
+  #
+  # @param layered_bindings [Puppet::Pops::Binder::Bindings::LayeredBindings] the named and ordered layers
+  # @raise ArgumentError if this binder is already configured
+  # @raise ArgumentError if bindings with unresolved 'override' surfaces as an effective binding
+  # @raise ArgumentError if the given argument has the wrong type, or if model is invalid in some way
+  # @return [Puppet::Pops::Binder::Binder] self
+  # @api public
+  #
+  def define_layers(layered_bindings)
+
+    LayerProcessor.new(self, key_factory).bind(layered_bindings)
+    contribution_keys = []
+    # make one pass over entries to collect contributions, and check overrides
+    injector_entries.each do |k,v|
+      if key_factory.is_contributions_key?(k)
+        contribution_keys << [k,v]
+      elsif !v.is_resolved?()
+        raise ArgumentError, "Binding with unresolved 'override' detected: #{self.class.format_binding(v.binding)}}"
+      else
+        # if binding has an id, add it to the index
+        add_id_to_index(v.binding)
+      end
+    end
+
+    # If a lower level binder has contributions for a key also contributed to in this binder
+    # they must included in the higher shadowing contribution.
+    # If a contribution is made to an id that is defined in a parent
+    # contribute to an id that is defined in a lower binder, it must be promoted to this binder (copied) or
+    # there is risk of making the lower level injector dirty.
+    #
+    contribution_keys.each do |kv|
+      parent_contribution = lookup_in_parent(kv[0])
+      next unless parent_contribution
+      injector_entries[kv[0]] = kv[1] + parent_contributions
+
+      # key the multibind_id from the contribution key
+      multibind_id = key_factory.multibind_contribution_key_to_id(kv[0])
+      promote_matching_bindings(self, @parent, multibind_id)
+    end
+  end
+  private :define_layers
+
+  # @api private
+  def next_anonymous_key
+    tmp = @anonymous_key
+    @anonymous_key += 1
+    tmp
+  end
+
+  def add_id_to_index(binding)
+    return unless binding.is_a?(Puppet::Pops::Binder::Bindings::Multibinding) && !(id = binding.id).nil?
+    @id_index[id] = @id_index[id] << binding
+  end
+
+  def promote_matching_bindings(to_binder, from_binder, multibind_id)
+    return if from_binder.nil?
+    from_binder.id_index[ multibind_id ].each do |binding|
+      key = key_factory.binding_key(binding)
+      entry = lookup(key)
+      unless entry.precedence == @binder_precedence
+        # it is from a lower layer it must be promoted
+        injector_entries[ key ] = Puppet::Pops::Binder::InjectorEntry.new(binding, binder_precedence)
+      end
+    end
+    # recursive "up the parent chain" to promote all
+    promote_matching_bindings(to_binder, from_binder.parent, multibind_id)
+  end
+
+  def lookup_in_parent(key)
+    @parent.nil? ? nil : @parent.lookup(key)
+  end
+
+  def lookup(key)
+    if x = injector_entries[key]
+      return x
+    end
+    @parent ?  @parent.lookup(key) :  nil
+  end
+
+  # @api private
+  def self.format_binding(b)
+    type_name = Puppet::Pops::Types::TypeCalculator.new().string(b.type)
+    layer_name, bindings_name = get_named_binding_layer_and_name(b)
+    "binding: '#{type_name}/#{b.name}' in: '#{bindings_name}' in layer: '#{layer_name}'"
+  end
+
+  # @api private
+  def self.format_contribution_source(b) 
+    layer_name, bindings_name = get_named_binding_layer_and_name(b)
+    "(layer: #{layer_name}, bindings: #{bindings_name})"
+  end
+
+  # @api private
+  def self.get_named_binding_layer_and_name(b)
+    return ['<unknown>', '<unknown>'] if b.nil?
+    return [get_named_layer(b), b.name] if b.is_a?(Puppet::Pops::Binder::Bindings::NamedBindings)
+    get_named_binding_layer_and_name(b.eContainer)
+  end
+
+  # @api private
+  def self.get_named_layer(b)
+    return '<unknown>' if b.nil?
+    return b.name if b.is_a?(Puppet::Pops::Binder::Bindings::NamedLayer)
+    get_named_layer(b.eContainer)
+  end
+
+  # Processes the information in a layer, aggregating it to the injector_entries hash in its parent binder.
+  # A LayerProcessor holds the intermediate state required while processing one layer.
+  #
+  # @api private
+  #
+  class LayerProcessor
+    attr :bindings
+    attr :binder
+    attr :key_factory
+    attr :contributions
+    attr :binder_precedence
+
+    def initialize(binder, key_factory)
+      @binder = binder
+      @binder_precedence = binder.binder_precedence
+      @key_factory = key_factory
+      @bindings = []
+      @contributions = []
+      @@bind_visitor ||= Puppet::Pops::Visitor.new(nil,"bind",0,0)
+    end
+
+    # Add the binding to the list of potentially effective bindings from this layer
+    # @api private
+    #
+    def add(b)
+      bindings << Puppet::Pops::Binder::InjectorEntry.new(b, binder_precedence)
+    end
+
+    # Add a multibind contribution
+    # @api private
+    #
+    def add_contribution(b)
+      contributions << Puppet::Pops::Binder::InjectorEntry.new(b, binder_precedence)
+    end
+
+    # Bind given abstract binding
+    # @api private
+    #
+    def bind(binding)
+      @@bind_visitor.visit_this(self, binding)
+    end
+
+    # @return [Puppet::Pops::Binder::InjectorEntry] the entry with the highest precedence
+    # @api private
+    def highest(b1, b2)
+      if b1.is_abstract? != b2.is_abstract?
+        # if one is abstract and the other is not, the non abstract wins
+        b1.is_abstract? ? b2 : b1
+      else
+        case b1.precedence <=> b2.precedence
+        when 1
+          b1
+        when -1
+          b2
+        when 0
+          raise_conflicting_binding(b1, b2)
+        end
+      end
+    end
+
+    # Raises a conflicting bindings error given two InjectorEntry's with same precedence in the same layer
+    # (if they are in different layers, something is seriously wrong)
+    def raise_conflicting_binding(b1, b2)
+      b1_layer_name, b1_bindings_name = binder.class.get_named_binding_layer_and_name(b1.binding)
+      b2_layer_name, b2_bindings_name = binder.class.get_named_binding_layer_and_name(b2.binding)
+
+      finality_msg = (b1.is_final? || b2.is_final?) ? ". Override of final binding not allowed" : ''
+
+      # TODO: Use of layer_name is not very good, it is not guaranteed to be unique
+      unless b1_layer_name == b2_layer_name
+        raise ArgumentError, [
+          'Conflicting binding for',
+          "'#{b1.binding.name}'",
+          'being resolved across layers',
+          "'#{b1_layer_name}' and",
+          "'#{b2_layer_name}'"
+          ].join(' ')+finality_msg
+      end
+
+      # Conflicting bindings made from the same source
+      if b1_bindings_name == b2_bindings_name
+        raise ArgumentError, [
+          'Conflicting binding for name:',
+          "'#{b1.binding.name}'",
+          'in layer:',
+          "'#{b1_layer_name}', ",
+          'both from:',
+          "'#{b1_bindings_name}'"
+          ].join(' ')+finality_msg
+      end
+
+      # Conflicting bindings from different sources
+      raise ArgumentError, [
+        'Conflicting binding for name:',
+        "'#{b1.binding.name}'",
+        'in layer:',
+        "'#{b1_layer_name}',",
+        'from:',
+        "'#{b1_bindings_name}', and",
+        "'#{b2_bindings_name}'"
+        ].join(' ')+finality_msg
+    end
+
+
+    # Produces the key for the given Binding.
+    # @param binding [Puppet::Pops::Binder::Bindings::Binding] the binding to get a key for
+    # @return [Object] an opaque key
+    # @api private
+    #
+    def key(binding)
+      k = if is_contribution?(binding)
+        # contributions get a unique (sequential) key
+        binder.next_anonymous_key()
+      else
+        key_factory.binding_key(binding)
+      end
+    end
+
+    # @api private
+    def is_contribution?(binding)
+      ! binding.multibind_id.nil?
+    end
+
+    # @api private
+    def bind_Binding(o)
+      if is_contribution?(o)
+        add_contribution(o)
+      else
+        add(o)
+      end
+    end
+
+    # @api private
+    def bind_Bindings(o)
+      o.bindings.each {|b| bind(b) }
+    end
+
+    # @api private
+    def bind_NamedBindings(o)
+      # Name is ignored here, it should be introspected when needed (in case of errors)
+      o.bindings.each {|b| bind(b) }
+    end
+
+    # Process layered bindings from highest to lowest layer
+    # @api private
+    #
+    def bind_LayeredBindings(o)
+      o.layers.each do |layer|
+        processor = LayerProcessor.new(binder, key_factory)
+        # All except abstract (==error) are transfered to injector_entries
+
+        processor.bind(layer).each do |k, v|
+          entry = binder.injector_entries[k]
+          unless key_factory.is_contributions_key?(k)
+            if v.is_abstract?()
+              layer_name, bindings_name = Puppet::Pops::Binder::Binder.get_named_binding_layer_and_name(v.binding)
+              type_name = key_factory.type_calculator.string(v.binding.type)
+              raise ArgumentError, "The abstract binding '#{type_name}/#{v.binding.name}' in '#{bindings_name}' in layer '#{layer_name}' was not overridden"
+            end
+            raise ArgumentError, "Internal Error - redefinition of key: #{k}, (should never happen)" if entry
+            binder.injector_entries[k] = v
+          else
+            entry ? entry << v : binder.injector_entries[k] = v
+          end
+        end
+      end
+    end
+
+    # Processes one named ("top level") layer consisting of a list of NamedBindings
+    # @api private
+    #
+    def bind_NamedLayer(o)
+      o.bindings.each {|b| bind(b) }
+      this_layer = {}
+
+      # process regular bindings
+      bindings.each do |b|
+        bkey = key(b.binding)
+
+        # ignore if a higher layer defined it (unless the lower is final), but ensure override gets resolved
+        # (override is not resolved across binders)
+        if x = binder.injector_entries[bkey]
+          if b.is_final?
+            raise_conflicting_binding(x, b)
+          end
+          x.mark_override_resolved()
+          next
+        end
+
+        # If a lower (parent) binder exposes a final binding it may not be overridden
+        #
+        if (x = binder.lookup_in_parent(bkey)) && x.is_final?
+          raise_conflicting_binding(x, b)
+        end
+
+        # if already found in this layer, one wins (and resolves override), or it is an error
+        existing = this_layer[bkey]
+        winner = existing ? highest(existing, b) : b
+        this_layer[bkey] = winner
+        if existing
+          winner.mark_override_resolved()
+        end
+      end
+
+      # Process contributions
+      # - organize map multibind_id to bindings with this id
+      # - for each id, create an array with the unique anonymous keys to the contributed bindings
+      # - bind the index to a special multibind contributions key (these are aggregated)
+      #
+      c_hash = Hash.new {|hash, key| hash[ key ] = [] }
+      contributions.each {|b| c_hash[ b.binding.multibind_id ] << b }
+      # - for each id
+      c_hash.each do |k, v|
+        index = v.collect do |b|
+          bkey = key(b.binding)
+          this_layer[bkey] = b
+          bkey
+        end
+        contributions_key = key_factory.multibind_contributions(k)
+        unless this_layer[contributions_key]
+          this_layer[contributions_key] = []
+        end
+        this_layer[contributions_key] += index
+      end
+      this_layer
+    end
+  end
+end