openvox 8.19.0

data/lib/puppet/pops/label_provider.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# 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") % { string: string }
+    end
+
+    char
+  end
+
+  def article_for_letter(letter)
+    downcased = letter.downcase
+    if VOWELS.include? downcased
+      AN
+    else
+      A
+    end
+  end
+end

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

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+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, environment)
+    super(loader_name, environment)
+    @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
+
+  def discover(type, error_collector = nil, name_authority = Pcore::RUNTIME_NAME_AUTHORITY, &block)
+    result = []
+    @named_values.each_pair do |key, entry|
+      result << key unless entry.nil? || entry.value.nil? || key.type != type || (block_given? && !yield(key))
+    end
+    result.concat(parent.discover(type, error_collector, name_authority, &block))
+    result.uniq!
+    result
+  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.
+    synchronize do
+      if @last_result.nil? || typed_name != @last_result.typed_name
+        @last_result = internal_load(typed_name)
+      else
+        @last_result
+      end
+    end
+  end
+
+  # @api public
+  #
+  def loaded_entry(typed_name, check_dependencies = false)
+    synchronize do
+      if @named_values.has_key?(typed_name)
+        @named_values[typed_name]
+      elsif parent
+        parent.loaded_entry(typed_name, check_dependencies)
+      else
+        nil
+      end
+    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)
+    synchronize do
+      # It is never ok to redefine in the very same loader unless redefining a 'not found'
+      entry = @named_values[typed_name]
+      if entry
+        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
+  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)
+    synchronize do
+      unless @named_values.delete(typed_name).nil?
+        @last_result = nil unless @last_result.nil? || typed_name != @last_result.typed_name
+      end
+    end
+  end
+
+  # Promotes an already created entry (typically from another loader) to this loader
+  #
+  # @api private
+  #
+  def promote_entry(named_entry)
+    synchronize do
+      typed_name = named_entry.typed_name
+      entry = @named_values[typed_name]
+      if entry then fail_redefine(entry); end
+      @named_values[typed_name] = named_entry
+    end
+  end
+
+  protected
+
+  def allow_shadowing?
+    false
+  end
+
+  private
+
+  def fail_redefine(entry)
+    origin_info = entry.origin ? _("Originally set %{original}.") % { original: origin_label(entry.origin) } : _("Set at unknown location")
+    raise ArgumentError, _("Attempt to redefine entity '%{name}'. %{origin_info}") % { name: entry.typed_name, origin_info: 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/lib/puppet/pops/loader/dependency_loader.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# =DependencyLoader
+# This loader provides visibility into a set of other loaders. It is used as a child of a ModuleLoader (or other
+# loader) to make its direct dependencies visible for loading from contexts that have access to this dependency loader.
+# Access is typically given to logic that resides inside of the module, but not to those that just depend on the module.
+#
+# It is instantiated with a name, and with a set of dependency_loaders.
+#
+# @api private
+#
+class Puppet::Pops::Loader::DependencyLoader < Puppet::Pops::Loader::BaseLoader
+  # Creates a DependencyLoader for one parent loader
+  #
+  # @param parent_loader [Puppet::Pops::Loader] typically a module loader for the root
+  # @param name [String] the name of the dependency-loader (used for debugging and tracing only)
+  # @param dependency_loaders [Array<Puppet::Pops::Loader>] array of loaders for modules this module depends on
+  #
+  def initialize(parent_loader, name, dependency_loaders, environment)
+    super(parent_loader, name, environment)
+    @dependency_loaders = dependency_loaders
+  end
+
+  def discover(type, error_collector = nil, name_authority = Puppet::Pops::Pcore::RUNTIME_NAME_AUTHORITY, &block)
+    result = []
+    @dependency_loaders.each { |loader| result.concat(loader.discover(type, error_collector, name_authority, &block)) }
+    result.concat(super)
+    result
+  end
+
+  # Finds name in a loader this loader depends on / can see
+  #
+  def find(typed_name)
+    if typed_name.qualified?
+      l = index()[typed_name.name_parts[0]]
+      if l
+        l.load_typed(typed_name)
+      else
+        # no module entered as dependency with name matching first segment of wanted name
+        nil
+      end
+    else
+      # a non name-spaced name, have to search since it can be anywhere.
+      # (Note: superclass caches the result in this loader as it would have to repeat this search for every
+      # lookup otherwise).
+      loaded = @dependency_loaders.reduce(nil) do |previous, loader|
+        break previous unless previous.nil?
+
+        loader.load_typed(typed_name)
+      end
+      if loaded
+        promote_entry(loaded)
+      end
+      loaded
+    end
+  end
+
+  # @api public
+  #
+  def loaded_entry(typed_name, check_dependencies = false)
+    super || (check_dependencies ? loaded_entry_in_dependency(typed_name, check_dependencies) : nil)
+  end
+
+  def to_s
+    "(DependencyLoader '#{@loader_name}' [" + @dependency_loaders.map(&:to_s).join(' ,') + "])"
+  end
+
+  private
+
+  def loaded_entry_in_dependency(typed_name, check_dependencies)
+    if typed_name.qualified?
+      l = index[typed_name.name_parts[0]]
+      if l
+        l.loaded_entry(typed_name)
+      else
+        # no module entered as dependency with name matching first segment of wanted name
+        nil
+      end
+    else
+      # a non name-spaced name, have to search since it can be anywhere.
+      # (Note: superclass caches the result in this loader as it would have to repeat this search for every
+      # lookup otherwise).
+      @dependency_loaders.reduce(nil) do |previous, loader|
+        break previous unless previous.nil?
+
+        loader.loaded_entry(typed_name, check_dependencies)
+      end
+    end
+  end
+
+  # An index of module_name to module loader used to speed up lookup of qualified names
+  def index
+    @index ||= @dependency_loaders.each_with_object({}) { |loader, index| index[loader.module_name] = loader; }
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# 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)
+    spec = Gem::Specification.find_by_name(uri.hostname)
+    unless spec
+      raise ArgumentError, _("Gem not found %{uri}") % { uri: 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)
+    spec = Gem::Specification.find_by_name(gem_name)
+    unless spec
+      raise ArgumentError, _("Gem not found '%{gem_name}'") % { gem_name: gem_name }
+    end
+
+    spec.full_gem_path
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Puppet::Pops
+module Loader
+# The GenericPlanInstantiator dispatches to either PuppetPlanInstantiator or a
+# yaml_plan_instantiator injected through the Puppet context, depending on
+# the type of the plan.
+#
+class GenericPlanInstantiator
+  def self.create(loader, typed_name, source_refs)
+    if source_refs.length > 1
+      raise ArgumentError, _("Found multiple files for plan '%{plan_name}' but only one is allowed") % { plan_name: typed_name.name }
+    end
+
+    source_ref = source_refs[0]
+    code_string = Puppet::FileSystem.read(source_ref, :encoding => 'utf-8')
+
+    instantiator = if source_ref.end_with?('.pp')
+                     Puppet::Pops::Loader::PuppetPlanInstantiator
+                   else
+                     Puppet.lookup(:yaml_plan_instantiator) do
+                       raise Puppet::DevError, _("No instantiator is available to load plan from %{source_ref}") % { source_ref: source_ref }
+                     end
+                   end
+
+    instantiator.create(loader, typed_name, source_ref, code_string)
+  end
+end
+end
+end

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

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+# 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'
+ENVIRONMENT_PRIVATE = 'environment private'
+
+class Loader
+  attr_reader :environment, :loader_name
+
+  # Describes the kinds of things that loaders can load
+  LOADABLE_KINDS = [:func_4x, :func_4xpp, :func_3x, :datatype, :type_pp, :resource_type_pp, :plan, :task].freeze
+
+  # @param [String] name the name of the loader. Must be unique among all loaders maintained by a {Loader} instance
+  def initialize(loader_name, environment)
+    @loader_name = loader_name.freeze
+    @environment = environment
+  end
+
+  # Search all places where this loader would find values of a given type and return a list the
+  # found values for which the given block returns true. All found entries will be returned if no
+  # block is given.
+  #
+  # Errors that occur function discovery will either be logged as warnings or collected by the optional
+  # `error_collector` array. When provided, it will receive {Puppet::DataTypes::Error} instances describing
+  # each error in detail and no warnings will be logged.
+  #
+  # @param type [Symbol] the type of values to search for
+  # @param error_collector [Array<Puppet::DataTypes::Error>] an optional array that will receive errors during load
+  # @param name_authority [String] the name authority, defaults to the pcore runtime
+  # @yield [typed_name] optional block to filter the results
+  # @yieldparam [TypedName] typed_name the typed name of a found entry
+  # @yieldreturn [Boolean] `true` to keep the entry, `false` to discard it.
+  # @return [Array<TypedName>] the list of names of discovered values
+  def discover(type, error_collector = nil, name_authority = Pcore::RUNTIME_NAME_AUTHORITY, &block)
+    EMPTY_ARRAY
+  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)
+    synchronize do
+      result = load_typed(TypedName.new(type, name.to_s))
+      if result
+        result.value
+      end
+    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 addition 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)
+    found = get_entry(typed_name)
+    if found
+      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
+
+  # Lock around a block
+  # This exists so some subclasses that are set up statically and don't actually
+  # load can override it
+  def synchronize(&block)
+    @environment.lock.synchronize(&block)
+  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
+  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
+  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
+    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