openvox 8.19.0

data/lib/puppet/pal/script_compiler.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Puppet
+module Pal
+  class ScriptCompiler < Compiler
+    # Returns the signature of the given plan name
+    # @param plan_name [String] the name of the plan to get the signature of
+    # @return [Puppet::Pal::PlanSignature, nil] returns a PlanSignature, or nil if plan is not found
+    #
+    def plan_signature(plan_name)
+      loader = internal_compiler.loaders.private_environment_loader
+      func = loader.load(:plan, plan_name)
+      if func
+        return PlanSignature.new(func)
+      end
+
+      # Could not find plan
+      nil
+    end
+
+    # Returns an array of TypedName objects for all plans, optionally filtered by a regular expression.
+    # The returned array has more information than just the leaf name - the typical thing is to just get
+    # the name as showing the following example.
+    #
+    # Errors that occur during plan 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.
+    #
+    # @example getting the names of all plans
+    #   compiler.list_plans.map {|tn| tn.name }
+    #
+    # @param filter_regex [Regexp] an optional regexp that filters based on name (matching names are included in the result)
+    # @param error_collector [Array<Puppet::DataTypes::Error>] an optional array that will receive errors during load
+    # @return [Array<Puppet::Pops::Loader::TypedName>] an array of typed names
+    #
+    def list_plans(filter_regex = nil, error_collector = nil)
+      list_loadable_kind(:plan, filter_regex, error_collector)
+    end
+
+    # Returns the signature callable of the given task (the arguments it accepts, and the data type it returns)
+    # @param task_name [String] the name of the task to get the signature of
+    # @return [Puppet::Pal::TaskSignature, nil] returns a TaskSignature, or nil if task is not found
+    #
+    def task_signature(task_name)
+      loader = internal_compiler.loaders.private_environment_loader
+      task = loader.load(:task, task_name)
+      if task
+        return TaskSignature.new(task)
+      end
+
+      # Could not find task
+      nil
+    end
+
+    # Returns an array of TypedName objects for all tasks, optionally filtered by a regular expression.
+    # The returned array has more information than just the leaf name - the typical thing is to just get
+    # the name as showing the following example.
+    #
+    # @example getting the names of all tasks
+    #   compiler.list_tasks.map {|tn| tn.name }
+    #
+    # Errors that occur during task 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 filter_regex [Regexp] an optional regexp that filters based on name (matching names are included in the result)
+    # @param error_collector [Array<Puppet::DataTypes::Error>] an optional array that will receive errors during load
+    # @return [Array<Puppet::Pops::Loader::TypedName>] an array of typed names
+    #
+    def list_tasks(filter_regex = nil, error_collector = nil)
+      list_loadable_kind(:task, filter_regex, error_collector)
+    end
+  end
+end
+end

data/lib/puppet/pal/task_signature.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Puppet
+module Pal
+  # A TaskSignature is returned from `task_signature`. Its purpose is to answer questions about the task's parameters
+  # and if it can be run/called with a hash of named parameters.
+  #
+  class TaskSignature
+    def initialize(task)
+      @task = task
+    end
+
+    # Returns whether or not the given arguments are acceptable when running the task.
+    # In addition to returning the boolean outcome, if a block is given, it is called with a string of formatted
+    # error messages that describes the difference between what was given and what is expected. The error message may
+    # have multiple lines of text, and each line is indented one space.
+    #
+    # @param args_hash [Hash] a hash mapping parameter names to argument values
+    # @yieldparam [String] a formatted error message if a type mismatch occurs that explains the mismatch
+    # @return [Boolean] if the given arguments are acceptable when running the task
+    #
+    def runnable_with?(args_hash)
+      params = @task.parameters
+      params_type = if params.nil?
+                      T_GENERIC_TASK_HASH
+                    else
+                      Puppet::Pops::Types::TypeFactory.struct(params)
+                    end
+      return true if params_type.instance?(args_hash)
+
+      if block_given?
+        tm = Puppet::Pops::Types::TypeMismatchDescriber.singleton
+        error = if params.nil?
+                  tm.describe_mismatch('', params_type,
+                                       Puppet::Pops::Types::TypeCalculator
+                                         .infer_set(args_hash))
+                else
+                  tm.describe_struct_signature(params_type, args_hash)
+                    .flatten
+                    .map(&:format)
+                    .join("\n")
+                end
+        yield "Task #{@task.name}:\n#{error}"
+      end
+      false
+    end
+
+    # Returns the Task instance as a hash
+    #
+    # @return [Hash{String=>Object}] the hash representation of the task
+    def task_hash
+      @task._pcore_init_hash
+    end
+
+    # Returns the Task instance which can be further explored. It contains all meta-data defined for
+    # the task such as the description, parameters, output, etc.
+    #
+    # @return [Puppet::Pops::Types::PuppetObject] An instance of a dynamically created Task class
+    def task
+      @task
+    end
+  end
+end
+end

data/lib/puppet/parameter/boolean.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative '../../puppet/coercion'
+
+# This specialized {Puppet::Parameter} handles Boolean options, accepting lots
+# of strings and symbols for both truth and falsehood.
+#
+class Puppet::Parameter::Boolean < Puppet::Parameter
+  def unsafe_munge(value)
+    Puppet::Coercion.boolean(value)
+  end
+
+  def self.initvars
+    super
+    @value_collection.newvalues(*Puppet::Coercion.boolean_values)
+  end
+end

data/lib/puppet/parameter/package_options.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative '../../puppet/parameter'
+
+# This specialized {Puppet::Parameter} handles munging of package options.
+# Package options are passed as an array of key value pairs. Special munging is
+# required as the keys and values needs to be quoted in a safe way.
+#
+class Puppet::Parameter::PackageOptions < Puppet::Parameter
+  def unsafe_munge(values)
+    values = [values] unless values.is_a? Array
+
+    values.collect do |val|
+      case val
+      when Hash
+        safe_hash = {}
+        val.each_pair do |k, v|
+          safe_hash[quote(k)] = quote(v)
+        end
+        safe_hash
+      when String
+        quote(val)
+      else
+        fail(_("Expected either a string or hash of options"))
+      end
+    end
+  end
+
+  # @api private
+  def quote(value)
+    value.include?(' ') ? %Q("#{value.gsub(/"/, '\"')}") : value
+  end
+end

data/lib/puppet/parameter/path.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative '../../puppet/parameter'
+
+# This specialized {Puppet::Parameter} handles validation and munging of paths.
+# By default, a single path is accepted, and by calling {accept_arrays} it is possible to
+# allow an array of paths.
+#
+class Puppet::Parameter::Path < Puppet::Parameter
+  # Specifies whether multiple paths are accepted or not.
+  # @dsl type
+  #
+  def self.accept_arrays(bool = true)
+    @accept_arrays = !!bool
+  end
+
+  def self.arrays?
+    @accept_arrays
+  end
+
+  # Performs validation of the given paths.
+  # If the concrete parameter defines a validation method, it may call this method to perform
+  # path validation.
+  # @raise [Puppet::Error] if this property is configured for single paths and an array is given
+  # @raise [Puppet::Error] if a path is not an absolute path
+  # @return [Array<String>] the given paths
+  #
+  def validate_path(paths)
+    if paths.is_a?(Array) and !self.class.arrays? then
+      fail _("%{name} only accepts a single path, not an array of paths") % { name: name }
+    end
+
+    fail(_("%{name} must be a fully qualified path") % { name: name }) unless Array(paths).all? { |path| absolute_path?(path) }
+
+    paths
+  end
+
+  # This is the default implementation of the `validate` method.
+  # It will be overridden if the validate option is used when defining the parameter.
+  # @return [void]
+  #
+  def unsafe_validate(paths)
+    validate_path(paths)
+  end
+
+  # This is the default implementation  of `munge`.
+  # If the concrete parameter defines a `munge` method, this default implementation will be overridden.
+  # This default implementation does not perform any munging, it just checks the one/many paths
+  # constraints. A derived implementation can perform this check as:
+  # `paths.is_a?(Array) and ! self.class.arrays?` and raise a {Puppet::Error}.
+  # @param paths [String, Array<String>] one of multiple paths
+  # @return [String, Array<String>] the given paths
+  # @raise [Puppet::Error] if the given paths does not comply with the on/many paths rule.
+  def unsafe_munge(paths)
+    if paths.is_a?(Array) and !self.class.arrays? then
+      fail _("%{name} only accepts a single path, not an array of paths") % { name: name }
+    end
+
+    paths
+  end
+end

data/lib/puppet/parameter/value.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative '../../puppet/parameter/value_collection'
+
+# Describes an acceptable value for a parameter or property.
+# An acceptable value is either specified as a literal value or a regular expression.
+# @note this class should be used via the api methods in {Puppet::Parameter} and {Puppet::Property}
+# @api private
+#
+class Puppet::Parameter::Value
+  attr_reader :name, :options, :event
+  attr_accessor :block, :method, :required_features, :invalidate_refreshes
+
+  # Adds an alias for this value.
+  # Makes the given _name_ be an alias for this acceptable value.
+  # @param name [Symbol] the additional alias this value should be known as
+  # @api private
+  #
+  def alias(name)
+    @aliases << convert(name)
+  end
+
+  # @return [Array<Symbol>] Returns all aliases (or an empty array).
+  # @api private
+  #
+  def aliases
+    @aliases.dup
+  end
+
+  # Stores the event that our value generates, if it does so.
+  # @api private
+  #
+  def event=(value)
+    @event = convert(value)
+  end
+
+  # Initializes the instance with a literal accepted value, or a regular expression.
+  # If anything else is passed, it is turned into a String, and then made into a Symbol.
+  # @param name [Symbol, Regexp, Object] the value to accept, Symbol, a regular expression, or object to convert.
+  # @api private
+  #
+  def initialize(name)
+    if name.is_a?(Regexp)
+      @name = name
+    else
+      # Convert to a string and then a symbol, so things like true/false
+      # still show up as symbols.
+      @name = convert(name)
+    end
+
+    @aliases = []
+  end
+
+  # Checks if the given value matches the acceptance rules (literal value, regular expression, or one
+  # of the aliases.
+  # @api private
+  #
+  def match?(value)
+    if regex?
+      true if name =~ value.to_s
+    else
+      (name == convert(value) ? true : @aliases.include?(convert(value)))
+    end
+  end
+
+  # @return [Boolean] whether the accepted value is a regular expression or not.
+  # @api private
+  #
+  def regex?
+    @name.is_a?(Regexp)
+  end
+
+  private
+
+  # A standard way of converting all of our values, so we're always
+  # comparing apples to apples.
+  # @api private
+  #
+  def convert(value)
+    case value
+    when Symbol, '' # can't intern an empty string
+      value
+    when String
+      value.intern
+    when true
+      :true
+    when false
+      :false
+    else
+      value.to_s.intern
+    end
+  end
+end

data/lib/puppet/parameter/value_collection.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require_relative '../../puppet/parameter/value'
+
+# A collection of values and regular expressions, used for specifying allowed values
+# in a given parameter.
+# @note This class is considered part of the internal implementation of {Puppet::Parameter}, and
+#   {Puppet::Property} and the functionality provided by this class should be used via their interfaces.
+# @comment This class probably have several problems when trying to use it with a combination of
+#   regular expressions and aliases as it finds an acceptable value holder vi "name" which may be
+#   a regular expression...
+#
+# @api private
+#
+class Puppet::Parameter::ValueCollection
+  # Aliases the given existing _other_ value with the additional given _name_.
+  # @return [void]
+  # @api private
+  #
+  def aliasvalue(name, other)
+    other = other.to_sym
+    value = match?(other)
+    raise Puppet::DevError, _("Cannot alias nonexistent value %{value}") % { value: other } unless value
+
+    value.alias(name)
+  end
+
+  # Returns a doc string (enumerating the acceptable values) for all of the values in this parameter/property.
+  # @return [String] a documentation string.
+  # @api private
+  #
+  def doc
+    unless defined?(@doc)
+      @doc = ''.dup
+      unless values.empty?
+        @doc << "Valid values are "
+        @doc << @strings.collect do |value|
+          aliases = value.aliases
+          if aliases && !aliases.empty?
+            "`#{value.name}` (also called `#{aliases.join(', ')}`)"
+          else
+            "`#{value.name}`"
+          end
+        end.join(", ") << ". "
+      end
+
+      unless regexes.empty?
+        @doc << "Values can match `#{regexes.join('`, `')}`."
+      end
+    end
+
+    @doc
+  end
+
+  # @return [Boolean] Returns whether the set of allowed values is empty or not.
+  # @api private
+  #
+  def empty?
+    @values.empty?
+  end
+
+  # @api private
+  #
+  def initialize
+    # We often look values up by name, so a hash makes more sense.
+    @values = {}
+
+    # However, we want to retain the ability to match values in order,
+    # but we always prefer directly equality (i.e., strings) over regex matches.
+    @regexes = []
+    @strings = []
+  end
+
+  # Checks if the given value is acceptable (matches one of the literal values or patterns) and returns
+  # the "matcher" that matched.
+  # Literal string matchers are tested first, if both a literal and a regexp match would match, the literal
+  # match wins.
+  #
+  # @param test_value [Object] the value to test if it complies with the configured rules
+  # @return [Puppet::Parameter::Value, nil] The instance of Puppet::Parameter::Value that matched the given value, or nil if there was no match.
+  # @api private
+  #
+  def match?(test_value)
+    # First look for normal values
+    value = @strings.find { |v| v.match?(test_value) }
+    return value if value
+
+    # Then look for a regex match
+    @regexes.find { |v| v.match?(test_value) }
+  end
+
+  # Munges the value if it is valid, else produces the same value.
+  # @param value [Object] the value to munge
+  # @return [Object] the munged value, or the given value
+  # @todo This method does not seem to do any munging. It just returns the value if it matches the
+  #   regexp, or the (most likely Symbolic) allowed value if it matches (which is more of a replacement
+  #   of one instance with an equal one. Is the intent that this method should be specialized?
+  # @api private
+  #
+  def munge(value)
+    return value if empty?
+
+    instance = match?(value)
+    if instance
+      if instance.regex?
+        value
+      else
+        instance.name
+      end
+    else
+      value
+    end
+  end
+
+  # Defines a new valid value for a {Puppet::Property}.
+  # A valid value is specified as a literal (typically a Symbol), but can also be
+  # specified with a regexp.
+  #
+  # @param name [Symbol, Regexp] a valid literal value, or a regexp that matches a value
+  # @param options [Hash] a hash with options
+  # @option options [Symbol] :event The event that should be emitted when this value is set.
+  # @todo Option :event original comment says "event should be returned...", is "returned" the correct word
+  #   to use?
+  # @option options [Symbol] :invalidate_refreshes True if a change on this property should invalidate and
+  #   remove any scheduled refreshes (from notify or subscribe) targeted at the same resource. For example, if
+  #   a change in this property takes into account any changes that a scheduled refresh would have performed,
+  #   then the scheduled refresh would be deleted.
+  # @option options [Object] _any_ Any other option is treated as a call to a setter having the given
+  #   option name (e.g. `:required_features` calls `required_features=` with the option's value as an
+  #   argument).
+  # @api private
+  #
+  def newvalue(name, options = {}, &block)
+    call_opt = options[:call]
+    unless call_opt.nil?
+      devfail "Cannot use obsolete :call value '#{call_opt}' for property '#{self.class.name}'" unless call_opt == :none || call_opt == :instead
+      # TRANSLATORS ':call' is a property and should not be translated
+      message = _("Property option :call is deprecated and no longer used.")
+      message += ' ' + _("Please remove it.")
+      Puppet.deprecation_warning(message)
+      options = options.reject { |k, _v| k == :call }
+    end
+
+    value = Puppet::Parameter::Value.new(name)
+    @values[value.name] = value
+    if value.regex?
+      @regexes << value
+    else
+      @strings << value
+    end
+
+    options.each { |opt, arg| value.send(opt.to_s + "=", arg) }
+    if block_given?
+      devfail "Cannot use :call value ':none' in combination with a block for property '#{self.class.name}'" if call_opt == :none
+      value.block = block
+      value.method ||= "set_#{value.name}" unless value.regex?
+    elsif call_opt == :instead
+      devfail "Cannot use :call value ':instead' without a block for property '#{self.class.name}'"
+    end
+    value
+  end
+
+  # Defines one or more valid values (literal or regexp) for a parameter or property.
+  # @return [void]
+  # @dsl type
+  # @api private
+  #
+  def newvalues(*names)
+    names.each { |name| newvalue(name) }
+  end
+
+  # @return [Array<String>] An array of the regular expressions in string form, configured as matching valid values.
+  # @api private
+  #
+  def regexes
+    @regexes.collect { |r| r.name.inspect }
+  end
+
+  # Validates the given value against the set of valid literal values and regular expressions.
+  # @raise [ArgumentError] if the value is not accepted
+  # @return [void]
+  # @api private
+  #
+  def validate(value)
+    return if empty?
+
+    unless @values.detect { |_name, v| v.match?(value) }
+      str = _("Invalid value %{value}.") % { value: value.inspect }
+      str += " " + _("Valid values are %{value_list}.") % { value_list: values.join(", ") } unless values.empty?
+      str += " " + _("Valid values match %{pattern}.") % { pattern: regexes.join(", ") } unless regexes.empty?
+      raise ArgumentError, str
+    end
+  end
+
+  # Returns a valid value matcher (a literal or regular expression)
+  # @todo This looks odd, asking for an instance that matches a symbol, or an instance that has
+  #   a regexp. What is the intention here? Marking as api private...
+  #
+  # @return [Puppet::Parameter::Value] a valid value matcher
+  # @api private
+  #
+  def value(name)
+    @values[name]
+  end
+
+  # @return [Array<Symbol>] Returns a list of valid literal values.
+  # @see regexes
+  # @api private
+  #
+  def values
+    @strings.collect(&:name)
+  end
+end