puppet-retrospec 1.5.0 → 1.6.0

data/vendor/pup410/lib/puppet/pops/label_provider.rb

@@ -0,0 +1,90 @@
+# Provides a label for an object.
+# This simple implementation calls #to_s on the given object, and handles articles 'a/an/the'.
+#
+module Puppet::Pops::LabelProvider
+  VOWELS = %w{a e i o u y}
+  SKIPPED_CHARACTERS = %w{" '}
+  A = "a"
+  AN = "an"
+
+  # Provides a label for the given object by calling `to_s` on the object.
+  # The intent is for this method to be overridden in concrete label providers.
+  def label o
+    o.to_s
+  end
+
+  # Produces a label for the given text with indefinite article (a/an)
+  def a_an o
+    text = label(o)
+    "#{article(text)} #{text}"
+  end
+
+  # Produces a label for the given text with indefinite article (A/An)
+  def a_an_uc o
+    text = label(o)
+    "#{article(text).capitalize} #{text}"
+  end
+
+  # Produces a label for the given text with *definite article* (the).
+  def the o
+    "the #{label(o)}"
+  end
+
+  # Produces a label for the given text with *definite article* (The).
+  def the_uc o
+    "The #{label(o)}"
+  end
+
+  # Appends 's' to (optional) text if count != 1 else an empty string
+  def plural_s(count, text = '')
+    count == 1 ? text : "#{text}s"
+  end
+
+  # Combines several strings using commas and a final conjunction
+  def combine_strings(strings, conjunction = 'or')
+    case strings.size
+    when 0
+      ''
+    when 1
+      strings[0]
+    when 2
+      "#{strings[0]} #{conjunction} #{strings[1]}"
+    else
+      "#{strings[0...-1].join(', ')}, #{conjunction} #{strings.last}"
+    end
+  end
+
+  # Produces an *indefinite article* (a/an) for the given text ('a' if
+  # it starts with a vowel) This is obviously flawed in the general
+  # sense as may labels have punctuation at the start and this method
+  # does not translate punctuation to English words. Also, if a vowel is
+  # pronounced as a consonant, the article should not be "an".
+  #
+  def article s
+    article_for_letter(first_letter_of(s))
+  end
+
+  private
+
+  def first_letter_of(string)
+    char = string[0,1]
+    if SKIPPED_CHARACTERS.include? char
+      char = string[1,1]
+    end
+
+    if char == ""
+      raise Puppet::DevError, "<#{string}> does not appear to contain a word"
+    end
+
+    char
+  end
+
+  def article_for_letter(letter)
+    downcased = letter.downcase
+    if VOWELS.include? downcased
+      AN
+    else
+      A
+    end
+  end
+end

data/vendor/pup410/lib/puppet/pops/loader/base_loader.rb

@@ -0,0 +1,156 @@
+module Puppet::Pops
+module Loader
+# BaseLoader
+# ===
+# An abstract implementation of Loader
+#
+# A derived class should implement `find(typed_name)` and set entries, and possible handle "miss caching".
+#
+# @api private
+#
+class BaseLoader < Loader
+
+  # The parent loader
+  attr_reader :parent
+
+  def initialize(parent_loader, loader_name)
+    super(loader_name)
+    @parent = parent_loader # the higher priority loader to consult
+    @named_values = {}      # hash name => NamedEntry
+    @last_result = nil      # the value of the last name (optimization)
+  end
+
+  # @api public
+  #
+  def load_typed(typed_name)
+    # The check for "last queried name" is an optimization when a module searches. First it checks up its parent
+    # chain, then itself, and then delegates to modules it depends on.
+    # These modules are typically parented by the same
+    # loader as the one initiating the search. It is inefficient to again try to search the same loader for
+    # the same name.
+    if @last_result.nil? || typed_name != @last_result.typed_name
+      @last_result = internal_load(typed_name)
+    else
+      @last_result
+    end
+  end
+
+  # @api public
+  #
+  def loaded_entry(typed_name, check_dependencies = false)
+    if @named_values.has_key?(typed_name)
+      @named_values[typed_name]
+    elsif parent
+      parent.loaded_entry(typed_name, check_dependencies)
+    else
+      nil
+    end
+  end
+
+  # This method is final (subclasses should not override it)
+  #
+  # @api private
+  #
+  def get_entry(typed_name)
+    @named_values[typed_name]
+  end
+
+  # @api private
+  #
+  def set_entry(typed_name, value, origin = nil)
+    # It is never ok to redefine in the very same loader unless redefining a 'not found'
+    if entry = @named_values[typed_name]
+      fail_redefine(entry) unless entry.value.nil?
+    end
+
+    # Check if new entry shadows existing entry and fail
+    # (unless special loader allows shadowing)
+    if typed_name.type == :type && !allow_shadowing?
+      entry = loaded_entry(typed_name)
+      if entry
+        fail_redefine(entry) unless entry.value.nil? #|| entry.value == value
+      end
+    end
+
+    @last_result = Loader::NamedEntry.new(typed_name, value, origin)
+    @named_values[typed_name] = @last_result
+  end
+
+  # @api private
+  #
+  def add_entry(type, name, value, origin)
+    set_entry(TypedName.new(type, name), value, origin)
+  end
+
+  # @api private
+  #
+  def remove_entry(typed_name)
+    unless @named_values.delete(typed_name).nil?
+      @last_result = nil unless @last_result.nil? || typed_name != @last_result.typed_name
+    end
+  end
+
+  # Promotes an already created entry (typically from another loader) to this loader
+  #
+  # @api private
+  #
+  def promote_entry(named_entry)
+    typed_name = named_entry.typed_name
+    if entry = @named_values[typed_name] then fail_redefine(entry); end
+    @named_values[typed_name] = named_entry
+  end
+
+  protected
+
+  def allow_shadowing?
+    false
+  end
+
+  private
+
+  def fail_redefine(entry)
+    origin_info = entry.origin ? "Originally set #{origin_label(entry.origin)}." : "Set at unknown location"
+    raise ArgumentError, "Attempt to redefine entity '#{entry.typed_name}'. #{origin_info}"
+  end
+
+  # TODO: Should not really be here?? - TODO: A Label provider ? semantics for the URI?
+  #
+  def origin_label(origin)
+    if origin && origin.is_a?(URI)
+      format_uri(origin)
+    elsif origin.respond_to?(:uri)
+      format_uri(origin.uri)
+    else
+      origin
+    end
+  end
+
+  def format_uri(uri)
+    (uri.scheme == 'puppet' ? 'by ' : 'at ') + uri.to_s.sub(/^puppet:/,'')
+  end
+
+  # loads in priority order:
+  # 1. already loaded here
+  # 2. load from parent
+  # 3. find it here
+  # 4. give up
+  #
+  def internal_load(typed_name)
+    # avoid calling get_entry by looking it up
+    te = @named_values[typed_name]
+    return te unless te.nil? || te.value.nil?
+
+    te = parent.load_typed(typed_name)
+    return te unless te.nil? || te.value.nil?
+
+    # Under some circumstances, the call to the parent loader will have resulted in files being
+    # parsed that in turn contained references to the requested entity and hence, caused a
+    # recursive call into this loader. This means that the entry might be present now, so a new
+    # check must be made.
+    te = @named_values[typed_name]
+    te.nil? || te.value.nil? ? find(typed_name) : te
+  end
+end
+end
+end
+

data/vendor/pup410/lib/puppet/pops/loader/loader.rb

@@ -0,0 +1,190 @@
+# Loader
+# ===
+# A Loader is responsible for loading "entities" ("instantiable and executable objects in the puppet language" which
+# are type, hostclass, definition, function, and bindings.
+#
+# The main method for users of a Loader is the `load` or `load_typed methods`, which returns a previously loaded entity
+# of a given type/name, and searches and loads the entity if not already loaded.
+#
+# private entities
+# ---
+# TODO: handle loading of entities that are private. Suggest that all calls pass an origin_loader (the loader
+# where request originated (or symbol :public). A module loader has one (or possibly a list) of what is
+# considered to represent private loader - i.e. the dependency loader for a module. If an entity is private
+# it should be stored with this status, and an error should be raised if the origin_loader is not on the list
+# of accepted "private" loaders.
+# The private loaders can not be given at creation time (they are parented by the loader in question). Another
+# alternative is to check if the origin_loader is a child loader, but this requires bidirectional links
+# between loaders or a search if loader with private entity is a parent of the origin_loader).
+#
+# @api public
+#
+module Puppet::Pops
+module Loader
+
+ENVIRONMENT = 'environment'.freeze
+ENVIRONMENT_PRIVATE = 'environment private'.freeze
+
+class Loader
+  attr_reader :loader_name
+
+  # Describes the kinds of things that loaders can load
+  LOADABLE_KINDS = [:func_4x, :func_4xpp, :type_pp, :resource_type_pp].freeze
+
+  # @param [String] name the name of the loader. Must be unique among all loaders maintained by a {Loader} instance
+  def initialize(loader_name)
+    @loader_name = loader_name.freeze
+  end
+
+  # Produces the value associated with the given name if already loaded, or available for loading
+  # by this loader, one of its parents, or other loaders visible to this loader.
+  # This is the method an external party should use to "get" the named element.
+  #
+  # An implementor of this method should first check if the given name is already loaded by self, or a parent
+  # loader, and if so return that result. If not, it should call `find` to perform the loading.
+  #
+  # @param type [:Symbol] the type to load
+  # @param name [String, Symbol]  the name of the entity to load
+  # @return [Object, nil] the value or nil if not found
+  #
+  # @api public
+  #
+  def load(type, name)
+    if result = load_typed(TypedName.new(type, name.to_s))
+      result.value
+    end
+  end
+
+  # Loads the given typed name, and returns a NamedEntry if found, else returns nil.
+  # This the same a `load`, but returns a NamedEntry with origin/value information.
+  #
+  # @param typed_name [TypedName] - the type, name combination to lookup
+  # @return [NamedEntry, nil] the entry containing the loaded value, or nil if not found
+  #
+  # @api public
+  #
+  def load_typed(typed_name)
+    raise NotImplementedError, "Class #{self.class.name} must implement method #load_typed"
+  end
+
+  # Returns an already loaded entry if one exists, or nil. This does not trigger loading
+  # of the given type/name.
+  #
+  # @param typed_name [TypedName] - the type, name combination to lookup
+  # @param check_dependencies [Boolean] - if dependencies should be checked in additiona to here and parent
+  # @return [NamedEntry, nil] the entry containing the loaded value, or nil if not found
+  # @api public
+  #
+  def loaded_entry(typed_name, check_dependencies = false)
+    raise NotImplementedError, "Class #{self.class.name} must implement method #loaded_entry"
+  end
+
+  # Produces the value associated with the given name if defined **in this loader**, or nil if not defined.
+  # This lookup does not trigger any loading, or search of the given name.
+  # An implementor of this method may not search or look up in any other loader, and it may not
+  # define the name.
+  #
+  # @param typed_name [TypedName] - the type, name combination to lookup
+  #
+  # @api private
+  #
+  def [] (typed_name)
+    if found = get_entry(typed_name)
+      found.value
+    else
+      nil
+    end
+  end
+
+  # Searches for the given name in this loader's context (parents should already have searched their context(s) without
+  # producing a result when this method is called).
+  # An implementation of find typically caches the result.
+  #
+  # @param typed_name [TypedName] the type, name combination to lookup
+  # @return [NamedEntry, nil] the entry for the loaded entry, or nil if not found
+  #
+  # @api private
+  #
+  def find(typed_name)
+    raise NotImplementedError, "Class #{self.class.name} must implement method #find"
+  end
+
+  # Returns the parent of the loader, or nil, if this is the top most loader. This implementation returns nil.
+  def parent
+    nil
+  end
+
+  # Produces the private loader for loaders that have a one (the visibility given to loaded entities).
+  # For loaders that does not provide a private loader, self is returned.
+  #
+  # @api private
+  def private_loader
+    self
+  end
+
+  # Binds a value to a name. The name should not start with '::', but may contain multiple segments.
+  #
+  # @param type [:Symbol] the type of the entity being set
+  # @param name [String, Symbol] the name of the entity being set
+  # @param origin [URI, #uri, String] the origin of the set entity, a URI, or provider of URI, or URI in string form
+  # @return [NamedEntry, nil] the created entry
+  #
+  # @api private
+  #
+  def set_entry(type, name, value, origin = nil)
+    raise NotImplementedError.new
+  end
+
+  # Produces a NamedEntry if a value is bound to the given name, or nil if nothing is bound.
+  #
+  # @param typed_name [TypedName] the type, name combination to lookup
+  # @return [NamedEntry, nil] the value bound in an entry
+  #
+  # @api private
+  #
+  def get_entry(typed_name)
+    raise NotImplementedError.new
+  end
+
+  # A loader is by default a loader for all kinds of loadables. An implementation may override
+  # if it cannot load all kinds.
+  #
+  # @api private
+  def loadables
+    LOADABLE_KINDS
+  end
+
+  # A loader may want to implement its own version with more detailed information.
+  def to_s
+    loader_name
+  end
+
+  # Loaders may contain references to the environment they load items within.
+  # Consequently, calling Kernel#inspect may return strings that are large
+  # enough to cause OutOfMemoryErrors on some platforms.
+  #
+  # We do not call alias_method here as that would copy the content of to_s
+  # at this point to inspect (ie children would print out `loader_name`
+  # rather than their version of to_s if they chose to implement it).
+  def inspect
+    self.to_s
+  end
+
+
+  # An entry for one entity loaded by the loader.
+  #
+  class NamedEntry
+    attr_reader :typed_name
+    attr_reader :value
+    attr_reader :origin
+
+    def initialize(typed_name, value, origin)
+      @typed_name = typed_name
+      @value = value
+      @origin = origin
+      freeze()
+    end
+  end
+end
+end
+end

data/vendor/pup410/lib/puppet/pops/loader/loader_paths.rb

@@ -0,0 +1,225 @@
+
+# LoaderPaths
+# ===
+# The central loader knowledge about paths, what they represent and how to instantiate from them.
+# Contains helpers (*smart paths*) to deal with lazy resolution of paths.
+#
+# TODO: Currently only supports loading of functions (2 kinds)
+#
+module Puppet::Pops::Loader::LoaderPaths
+  # Returns an array of SmartPath, each instantiated with a reference to the given loader (for root path resolution
+  # and existence checks). The smart paths in the array appear in precedence order. The returned array may be
+  # mutated.
+  #
+  def self.relative_paths_for_type(type, loader)
+    result = []
+    case type
+    when :function
+        # Only include support for the loadable items the loader states it can contain
+        if loader.loadables.include?(:func_4x)
+          result << FunctionPath4x.new(loader)
+        end
+        if loader.loadables.include?(:func_4xpp)
+          result << FunctionPathPP.new(loader)
+        end
+        # When wanted also add FunctionPath3x to load 3x functions
+    when :type
+      result << TypePathPP.new(loader) if loader.loadables.include?(:type_pp)
+    when :resource_type_pp
+      result << ResourceTypeImplPP.new(loader) if loader.loadables.include?(:resource_type_pp)
+    else
+      # unknown types, simply produce an empty result; no paths to check, nothing to find... move along...
+      []
+    end
+    result
+  end
+
+#  # DO NOT REMOVE YET. needed later? when there is the need to decamel a classname
+#  def de_camel(fq_name)
+#    fq_name.to_s.gsub(/::/, '/').
+#    gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+#    gsub(/([a-z\d])([A-Z])/,'\1_\2').
+#    tr("-", "_").
+#    downcase
+#  end
+
+  class SmartPath
+    # Generic path, in the sense of "if there are any entities of this kind to load, where are they?"
+    attr_reader :generic_path
+
+    # Creates SmartPath for the given loader (loader knows how to check for existence etc.)
+    def initialize(loader)
+      @loader = loader
+    end
+
+    def generic_path()
+      return @generic_path unless @generic_path.nil?
+
+      the_root_path = root_path() # @loader.path
+      @generic_path = (the_root_path.nil? ? relative_path : File.join(the_root_path, relative_path))
+    end
+
+    def root_path
+      @loader.path
+    end
+
+    # Effective path is the generic path + the name part(s) + extension.
+    #
+    def effective_path(typed_name, start_index_in_name)
+      "#{File.join(generic_path, typed_name.name_parts)}#{extension}"
+    end
+
+    def relative_path()
+      raise NotImplementedError.new
+    end
+
+    def instantiator()
+      raise NotImplementedError.new
+    end
+  end
+
+  class RubySmartPath < SmartPath
+    EXTENSION = '.rb'.freeze
+
+    def extension
+      EXTENSION
+    end
+
+    # Duplication of extension information, but avoids one call
+    def effective_path(typed_name, start_index_in_name)
+      "#{File.join(generic_path, typed_name.name_parts)}.rb"
+    end
+  end
+
+  # A PuppetSmartPath is rooted at the loader's directory one level up from what the loader specifies as it
+  # path (which is a reference to its 'lib' directory.
+  #
+  class PuppetSmartPath < SmartPath
+    EXTENSION = '.pp'.freeze
+
+    def extension
+      EXTENSION
+    end
+
+    def root_path
+      Puppet::FileSystem.dir_string(@loader.path)
+    end
+
+    # Duplication of extension information, but avoids one call
+    def effective_path(typed_name, start_index_in_name)
+      # Puppet name to path always skips the name-space as that is part of the generic path
+      # i.e. <module>/mymodule/functions/foo.pp is the function mymodule::foo
+      parts = typed_name.name_parts
+      if start_index_in_name > 0
+        return nil if start_index_in_name >= parts.size
+        parts = parts[start_index_in_name..-1]
+      end
+      "#{File.join(generic_path, parts)}.pp"
+    end
+  end
+
+  class FunctionPath4x < RubySmartPath
+    FUNCTION_PATH_4X = File.join('puppet', 'functions')
+
+    def relative_path
+      FUNCTION_PATH_4X
+    end
+
+    def instantiator()
+      Puppet::Pops::Loader::RubyFunctionInstantiator
+    end
+  end
+
+  class FunctionPath3x < RubySmartPath
+    FUNCTION_PATH_3X = File.join('puppet', 'parser', 'functions')
+
+    def relative_path
+      FUNCTION_PATH_3X
+    end
+
+    def instantiator()
+      Puppet::Pops::Loader::RubyLegacyFunctionInstantiator
+    end
+  end
+
+  class FunctionPathPP < PuppetSmartPath
+    # Navigate to directory where 'lib' is, then down again
+    FUNCTION_PATH_PP = File.join('functions')
+
+    def relative_path
+      FUNCTION_PATH_PP
+    end
+
+    def instantiator()
+      Puppet::Pops::Loader::PuppetFunctionInstantiator
+    end
+  end
+
+  class TypePathPP < PuppetSmartPath
+    TYPE_PATH_PP = File.join('types')
+
+    def relative_path
+      TYPE_PATH_PP
+    end
+
+    def instantiator()
+      Puppet::Pops::Loader::TypeDefinitionInstantiator
+    end
+  end
+
+  class ResourceTypeImplPP < PuppetSmartPath
+    RESOURCE_TYPES_PATH_PP = File.join('.resource_types')
+
+    def relative_path
+      RESOURCE_TYPES_PATH_PP
+    end
+
+    def root_path
+      @loader.path
+    end
+
+    def instantiator()
+      Puppet::Pops::Loader::PuppetResourceTypeImplInstantiator
+    end
+
+    # The effect paths for resource type impl is the full name
+    # since resource types are not name spaced.
+    # This overrides the default PuppetSmartPath.
+    #
+    def effective_path(typed_name, start_index_in_name)
+      # Resource type to name does not skip the name-space
+      # i.e. <module>/mymodule/resource_types/foo.pp is the reource type foo
+      "#{File.join(generic_path, typed_name.name_parts)}.pp"
+    end
+  end
+
+  # SmartPaths
+  # ===
+  # Holds effective SmartPath instances per type
+  #
+  class SmartPaths
+    def initialize(path_based_loader)
+      @loader = path_based_loader
+      @smart_paths = {}
+    end
+
+    # Ensures that the paths for the type have been probed and pruned to what is existing relative to
+    # the given root.
+    #
+    # @param type [Symbol] the entity type to load
+    # @return [Array<SmartPath>] array of effective paths for type (may be empty)
+    #
+    def effective_paths(type)
+      smart_paths = @smart_paths
+      loader = @loader
+      unless effective_paths = smart_paths[type]
+        # type not yet processed, does the various directories for the type exist ?
+        # Get the relative dirs for the type
+        paths_for_type = Puppet::Pops::Loader::LoaderPaths.relative_paths_for_type(type, loader)
+        # Check which directories exist in the loader's content/index
+        effective_paths = smart_paths[type] = paths_for_type.select { |sp| loader.meaningful_to_search?(sp) }
+      end
+      effective_paths
+    end
+  end
+end