puppet 3.5.1-x86-mingw32 → 3.6.0.rc1-x86-mingw32

data/lib/puppet/pops/loader/gem_support.rb

@@ -0,0 +1,49 @@
+# GemSupport offers methods to find a gem's location by name or gem://gemname URI.
+#
+# TODO: The Puppet 3x, uses Puppet::Util::RubyGems to do this, and obtain paths, and avoids using ::Gems
+# when ::Bundler is in effect. A quick check what happens on Ruby 1.8.7 and Ruby 1.9.3 with current
+# version of bundler seems to work just fine without jumping through any hoops. Hopefully the Puppet::Utils::RubyGems is
+# just dealing with arcane things prior to RubyGems 1.8 that are not needed any more. To verify there is
+# the need to set up a scenario where additional bundles than what Bundler allows for a given configuration are available
+# and then trying to access those.
+#
+module Puppet::Pops::Loader::GemSupport
+
+  # Produces the root directory of a gem given as an URI (gem://gemname/optional/path), or just the
+  # gemname as a string.
+  #
+  def gem_dir(uri_or_string)
+    case uri_or_string
+    when URI
+      gem_dir_from_uri(uri_or_string)
+    when String
+      gem_dir_from_name(uri_or_string)
+    end
+  end
+
+  # Produces the root directory of a gem given as an uri, where hostname is the gemname, and an optional
+  # path is appended to the root of the gem (i.e. if the reference is given to a sub-location within a gem.
+  # TODO: FIND by name raises exception Gem::LoadError with list of all gems on the path
+  #
+  def gem_dir_from_uri(uri)
+    unless spec = Gem::Specification.find_by_name(uri.hostname)
+      raise ArgumentError, "Gem not found #{uri}"
+    end
+    # if path given append that, else append given subdir
+    if uri.path.empty?
+      spec.gem_dir
+    else
+      File.join(spec.full_gem_path, uri.path)
+    end
+  end
+
+  # Produces the root directory of a gem given as a string with the gem's name.
+  # TODO: FIND by name raises exception Gem::LoadError with list of all gems on the path
+  #
+  def gem_dir_from_name(gem_name)
+    unless spec = Gem::Specification.find_by_name(gem_name)
+      raise ArgumentError, "Gem not found '#{gem_name}'"
+    end
+    spec.full_gem_path
+  end
+end

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

@@ -0,0 +1,180 @@
+# 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
+#
+class Puppet::Pops::Loader::Loader
+
+  # 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.new
+  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.new
+  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
+
+  # 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)
+      @name = typed_name
+      @value = value
+      @origin = origin
+      freeze()
+    end
+  end
+
+  # A name/type combination that can be used as a compound hash key
+  #
+  class TypedName
+    attr_reader :type
+    attr_reader :name
+    attr_reader :name_parts
+
+    # True if name is qualified (more than a single segment)
+    attr_reader :qualified
+
+    def initialize(type, name)
+      @type = type
+      # relativize the name (get rid of leading ::), and make the split string available
+      @name_parts = name.to_s.split(/::/)
+      @name_parts.shift if name_parts[0].empty?
+      @name = name_parts.join('::')
+      @qualified = name_parts.size > 1
+      # precompute hash - the name is frozen, so this is safe to do
+      @hash = [self.class, type, @name].hash
+
+      # Not allowed to have numeric names - 0, 010, 0x10, 1.2 etc
+      if Puppet::Pops::Utils.is_numeric?(@name)
+        raise ArgumentError, "Illegal attempt to use a numeric name '#{name}' at #{origin_label(origin)}."
+      end
+
+      freeze()
+    end
+
+    def hash
+      @hash
+    end
+
+    def ==(o)
+      o.class == self.class && type == o.type && name == o.name
+    end
+
+    alias eql? ==
+
+    def to_s
+      "#{type}/#{name}"
+    end
+  end
+end
+

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

@@ -0,0 +1,137 @@
+
+# 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 (3 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) #, start_index_in_name)
+    result =
+    case type # typed_name.type
+    when :function
+      if Puppet[:biff] == true
+        [FunctionPath4x.new(loader), FunctionPath3x.new(loader)]
+      else
+        [FunctionPath4x.new(loader)]
+      end
+
+    # when :xxx # TODO: Add all other types
+
+    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?
+
+      root_path = @loader.path
+      @generic_path = (root_path.nil? ? relative_path : File.join(root_path, relative_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
+    def extension
+      ".rb"
+    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
+
+  class FunctionPath4x < RubySmartPath
+    FUNCTION_PATH_4X = File.join('lib', '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('lib', 'puppet', 'parser', 'functions')
+
+    def relative_path
+      FUNCTION_PATH_3X
+    end
+
+    def instantiator()
+      Puppet::Pops::Loader::RubyLegacyFunctionInstantiator
+    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

data/lib/puppet/pops/loader/module_loaders.rb

@@ -0,0 +1,242 @@
+
+# =ModuleLoaders
+# A ModuleLoader loads items from a single module.
+# The ModuleLoaders (ruby) module contains various such loaders. There is currently one concrete
+# implementation, ModuleLoaders::FileBased that loads content from the file system.
+# Other implementations can be created - if they are based on name to path mapping where the path
+# is relative to a root path, they can derive the base behavior from the ModuleLoaders::AbstractPathBasedModuleLoader class.
+#
+# Examples of such extensions could be a zip/jar/compressed file base loader.
+#
+# Notably, a ModuleLoader does not configure itself - it is given the information it needs (the root, its name etc.)
+# Logic higher up in the loader hierarchy of things makes decisions based on the "shape of modules", and "available
+# modules" to determine which module loader to use for each individual module. (There could be differences in
+# internal layout etc.)
+#
+# A module loader is also not aware of the mapping of name to relative paths - this is performed by the
+# included module Puppet::Pops::Loader::PathBasedInstantatorConfig which knows about the map from type/name to
+# relative path, and the logic that can instantiate what is expected to be found in the content of that path.
+#
+# @api private
+#
+module Puppet::Pops::Loader::ModuleLoaders
+  class AbstractPathBasedModuleLoader < Puppet::Pops::Loader::BaseLoader
+
+    # The name of the module, or nil, if this is a global "component"
+    attr_reader :module_name
+
+    # The path to the location of the module/component - semantics determined by subclass
+    attr_reader :path
+
+    # A map of type to smart-paths that help with minimizing the number of paths to scan
+    attr_reader :smart_paths
+
+    # A Module Loader has a private loader, it is lazily obtained on request to provide the visibility
+    # for entities contained in the module. Since a ModuleLoader also represents an environment and it is
+    # created a different way, this loader can be set explicitly by the loaders bootstrap logic.
+    #
+    # @api private
+    attr_accessor :private_loader
+
+    # Initialize a kind of ModuleLoader for one module
+    # @param parent_loader [Puppet::Pops::Loader] loader with higher priority
+    # @param module_name [String] the name of the module (non qualified name), may be nil for a global "component"
+    # @param path [String] the path to the root of the module (semantics defined by subclass)
+    # @param loader_name [String] a name that is used for human identification (useful when module_name is nil)
+    #
+    def initialize(parent_loader, loaders, module_name, path, loader_name)
+      super parent_loader, loader_name
+
+      # Irrespective of the path referencing a directory or file, the path must exist.
+      unless Puppet::FileSystem.exist?(path)
+        raise ArgumentError, "The given path '#{path}' does not exist!"
+      end
+
+      @module_name = module_name
+      @path = path
+      @smart_paths = Puppet::Pops::Loader::LoaderPaths::SmartPaths.new(self)
+      @loaders = loaders
+    end
+
+    # Finds typed/named entity in this module
+    # @param typed_name [Puppet::Pops::Loader::TypedName] the type/name to find
+    # @return [Puppet::Pops::Loader::Loader::NamedEntry, nil found/created entry, or nil if not found
+    #
+    def find(typed_name)
+      # Assume it is a global name, and that all parts of the name should be used when looking up
+      name_part_index = 0
+      name_parts = typed_name.name_parts
+
+      # Certain types and names can be disqualified up front
+      if name_parts.size > 1
+        # The name is in a name space.
+
+        # Then entity cannot possible be in this module unless the name starts with the module name.
+        # Note: If "module" represents a "global component", the module_name is nil and cannot match which is
+        # ok since such a "module" cannot have namespaced content).
+        #
+        return nil unless name_parts[0] == module_name
+
+        # Skip the first part of the name when computing the path since the path already contains the name of the
+        # module
+        name_part_index = 1
+      else
+        # The name is in the global name space.
+
+        # The only globally name-spaced elements that may be loaded from modules are functions and resource types
+        case typed_name.type
+        when :function
+        when :resource_type
+        else
+          # anything else cannot possibly be in this module
+          # TODO: should not be allowed anyway... may have to revisit this decision
+          return nil
+        end
+      end
+
+      # Get the paths that actually exist in this module (they are lazily processed once and cached).
+      # The result is an array (that may be empty).
+      # Find the file to instantiate, and instantiate the entity if file is found
+      origin = nil
+      if (smart_path = smart_paths.effective_paths(typed_name.type).find do |sp|
+          origin = sp.effective_path(typed_name, name_part_index)
+          existing_path(origin)
+        end)
+        value = smart_path.instantiator.create(self, typed_name, origin, get_contents(origin))
+        # cache the entry and return it
+        set_entry(typed_name, value, origin)
+      else
+        nil
+      end
+    end
+
+    # Abstract method that subclasses override that checks if it is meaningful to search using a generic smart path.
+    # This optimization is performed to not be tricked into searching an empty directory over and over again.
+    # The implementation may perform a deep search for file content other than directories and cache this in
+    # and index. It is guaranteed that a call to meaningful_to_search? takes place before checking any other
+    # path with relative_path_exists?.
+    #
+    # This optimization exists because many modules have been created from a template and they have
+    # empty directories for functions, types, etc. (It is also the place to create a cached index of the content).
+    #
+    # @param smart_path [String] a path relative to the module's root
+    # @return [Boolean] true if there is content in the directory appointed by the relative path
+    #
+    def meaningful_to_search?(smart_path)
+      raise NotImplementedError.new
+    end
+
+    # Abstract method that subclasses override to answer if the given relative path exists, and if so returns that path
+    #
+    # @param resolved_path [String] a path resolved by a smart path against the loader's root (if it has one)
+    # @return [Boolean] true if the file exists
+    #
+    def existing_path(resolved_path)
+      raise NotImplementedError.new
+    end
+
+    # Abstract method that subclasses override to produce the content of the effective path.
+    # It should either succeed and return a String or fail with an exception.
+    #
+    # @param effective_path [String] a path as resolved by a smart path
+    # @return [String] the content of the file
+    #
+    def get_contents(effective_path)
+      raise NotImplementedError.new
+    end
+
+    # Abstract method that subclasses override to produce a source reference String used to identify the
+    # system resource (resource in the URI sense).
+    #
+    # @param relative_path [String] a path relative to the module's root
+    # @return [String] a reference to the source file (in file system, zip file, or elsewhere).
+    #
+    def get_source_ref(relative_path)
+      raise NotImplementedError.new
+    end
+
+    # Produces the private loader for the module. If this module is not already resolved, this will trigger resolution
+    #
+    def private_loader
+      @private_loader ||= @loaders.private_loader_for_module(module_name)
+    end
+  end
+
+  # @api private
+  #
+  class FileBased < AbstractPathBasedModuleLoader
+
+    attr_reader :smart_paths
+    attr_reader :path_index
+
+    # Create a kind of ModuleLoader for one module (Puppet Module, or module like)
+    #
+    # @param parent_loader [Puppet::Pops::Loader::Loader] typically the loader for the environment or root
+    # @param module_name [String] the name of the module (non qualified name), may be nil for "modules" only containing globals
+    # @param path [String] the path to the root of the module (semantics defined by subclass)
+    # @param loader_name [String] a name that identifies the loader
+    #
+    def initialize(parent_loader, loaders, module_name, path, loader_name)
+      super
+      unless Puppet::FileSystem.directory?(path)
+        raise ArgumentError, "The given module root path '#{path}' is not a directory (required for file system based module path entry)"
+      end
+      @path_index = Set.new()
+    end
+
+    def existing_path(effective_path)
+      # Optimized, checks index instead of visiting file system
+      @path_index.include?(effective_path) ? effective_path : nil
+    end
+
+    def meaningful_to_search?(smart_path)
+      ! add_to_index(smart_path).empty?
+    end
+
+    def to_s()
+      "(ModuleLoader::FileBased '#{loader_name()}' '#{module_name()}')"
+    end
+
+    def add_to_index(smart_path)
+      found = Dir.glob(File.join(smart_path.generic_path, '**', "*#{smart_path.extension}"))
+      @path_index.merge(found)
+      found
+    end
+
+    def get_contents(effective_path)
+      Puppet::FileSystem.read(effective_path)
+    end
+  end
+
+  # Loads from a gem specified as a URI, gem://gemname/optional/path/in/gem, or just a String gemname.
+  # The source reference (shown in errors etc.) is the expanded path of the gem as this is believed to be more
+  # helpful - given the location it should be quite obvious which gem it is, without the location, the user would
+  # need to go on a hunt for where the file actually is located.
+  #
+  # TODO: How does this get instantiated? Does the gemname refelect the name of the module (the namespace)
+  #   or is that specified a different way? Can a gem be the container of multiple modules?
+  #
+  # @api private
+  #
+  class GemBased < FileBased
+    include Puppet::Pops::Loader::GemSupport
+
+    attr_reader :gem_ref
+
+    # Create a kind of ModuleLoader for one module
+    # The parameters are:
+    # * parent_loader - typically the loader for the root
+    # * module_name - the name of the module (non qualified name)
+    # * gem_ref - [URI, String] gem reference to the root of the module (URI, gem://gemname/optional/path/in/gem), or
+    #     just the gem's name as a String.
+    #
+    def initialize(parent_loader, loaders, module_name, gem_ref, loader_name)
+      @gem_ref = gem_ref
+      super parent_loader, loaders, module_name, gem_dir(gem_ref), loader_name
+    end
+
+    def to_s()
+      "(ModuleLoader::GemBased '#{loader_name()}' '#{@gem_ref}' [#{module_name()}])"
+    end
+  end
+end