openvox 8.19.0

data/lib/puppet/pal/compiler.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module Puppet
+module Pal
+  # A configured compiler as obtained in the callback from `Puppet::Pal.with_script_compiler`.
+  # (Later, there may also be a catalog compiler available.)
+  #
+  class Compiler
+    attr_reader :internal_compiler
+    protected :internal_compiler
+
+    attr_reader :internal_evaluator
+    protected :internal_evaluator
+
+    def initialize(internal_compiler)
+      @internal_compiler = internal_compiler
+      @internal_evaluator = Puppet::Pops::Parser::EvaluatingParser.new
+    end
+
+    # Calls a function given by name with arguments specified in an `Array`, and optionally accepts a code block.
+    # @param function_name [String] the name of the function to call
+    # @param args [Object] the arguments to the function
+    # @param block [Proc] an optional callable block that is given to the called function
+    # @return [Object] what the called function returns
+    #
+    def call_function(function_name, *args, &block)
+      # TRANSLATORS: do not translate variable name strings in these assertions
+      Pal.assert_non_empty_string(function_name, 'function_name', false)
+      Pal.assert_type(Pal::T_ANY_ARRAY, args, 'args', false)
+      internal_evaluator.evaluator.external_call_function(function_name, args, topscope, &block)
+    end
+
+    # Returns a Puppet::Pal::FunctionSignature object or nil if function is not found
+    # The returned FunctionSignature has information about all overloaded signatures of the function
+    #
+    # @example using function_signature
+    #   # returns true if 'myfunc' is callable with three integer arguments 1, 2, 3
+    #   compiler.function_signature('myfunc').callable_with?([1,2,3])
+    #
+    # @param function_name [String] the name of the function to get a signature for
+    # @return [Puppet::Pal::FunctionSignature] a function signature, or nil if function not found
+    #
+    def function_signature(function_name)
+      loader = internal_compiler.loaders.private_environment_loader
+      func = loader.load(:function, function_name)
+      if func
+        return FunctionSignature.new(func.class)
+      end
+
+      # Could not find function
+      nil
+    end
+
+    # Returns an array of TypedName objects for all functions, 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 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.
+    #
+    # @example getting the names of all functions
+    #   compiler.list_functions.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_functions(filter_regex = nil, error_collector = nil)
+      list_loadable_kind(:function, filter_regex, error_collector)
+    end
+
+    # Evaluates a string of puppet language code in top scope.
+    # A "source_file" reference to a source can be given - if not an actual file name, by convention the name should
+    # be bracketed with < > to indicate it is something symbolic; for example `<commandline>` if the string was given on the
+    # command line.
+    #
+    # If the given `puppet_code` is `nil` or an empty string, `nil` is returned, otherwise the result of evaluating the
+    # puppet language string. The given string must form a complete and valid expression/statement as an error is raised
+    # otherwise. That is, it is not possible to divide a compound expression by line and evaluate each line individually.
+    #
+    # @param puppet_code [String, nil] the puppet language code to evaluate, must be a complete expression/statement
+    # @param source_file [String, nil] an optional reference to a source (a file or symbolic name/location)
+    # @return [Object] what the `puppet_code` evaluates to
+    #
+    def evaluate_string(puppet_code, source_file = nil)
+      return nil if puppet_code.nil? || puppet_code == ''
+      unless puppet_code.is_a?(String)
+        raise ArgumentError, _("The argument 'puppet_code' must be a String, got %{type}") % { type: puppet_code.class }
+      end
+
+      evaluate(parse_string(puppet_code, source_file))
+    end
+
+    # Evaluates a puppet language file in top scope.
+    # The file must exist and contain valid puppet language code or an error is raised.
+    #
+    # @param file [Path, String] an absolute path to a file with puppet language code, must exist
+    # @return [Object] what the last evaluated expression in the file evaluated to
+    #
+    def evaluate_file(file)
+      evaluate(parse_file(file))
+    end
+
+    # Evaluates an AST obtained from `parse_string` or `parse_file` in topscope.
+    # If the ast is a `Puppet::Pops::Model::Program` (what is returned from the `parse` methods, any definitions
+    # in the program (that is, any function, plan, etc. that is defined will be made available for use).
+    #
+    # @param ast [Puppet::Pops::Model::PopsObject] typically the returned `Program` from the parse methods, but can be any `Expression`
+    # @returns [Object] whatever the ast evaluates to
+    #
+    def evaluate(ast)
+      if ast.is_a?(Puppet::Pops::Model::Program)
+        loaders = Puppet.lookup(:loaders)
+        loaders.instantiate_definitions(ast, loaders.public_environment_loader)
+      end
+      internal_evaluator.evaluate(topscope, ast)
+    end
+
+    # Produces a literal value if the AST obtained from `parse_string` or `parse_file` does not require any actual evaluation.
+    # This method is useful if obtaining an AST that represents literal values; string, integer, float, boolean, regexp, array, hash;
+    # for example from having read this from the command line or as values in some file.
+    #
+    # @param ast [Puppet::Pops::Model::PopsObject] typically the returned `Program` from the parse methods, but can be any `Expression`
+    # @returns [Object] whatever the literal value the ast evaluates to
+    #
+    def evaluate_literal(ast)
+      catch :not_literal do
+        return Puppet::Pops::Evaluator::LiteralEvaluator.new().literal(ast)
+      end
+      # TRANSLATORS, the 'ast' is the name of a parameter, do not translate
+      raise ArgumentError, _("The given 'ast' does not represent a literal value")
+    end
+
+    # Parses and validates a puppet language string and returns an instance of Puppet::Pops::Model::Program on success.
+    # If the content is not valid an error is raised.
+    #
+    # @param code_string [String] a puppet language string to parse and validate
+    # @param source_file [String] an optional reference to a file or other location in angled brackets
+    # @return [Puppet::Pops::Model::Program] returns a `Program` instance on success
+    #
+    def parse_string(code_string, source_file = nil)
+      unless code_string.is_a?(String)
+        raise ArgumentError, _("The argument 'code_string' must be a String, got %{type}") % { type: code_string.class }
+      end
+
+      internal_evaluator.parse_string(code_string, source_file)
+    end
+
+    # Parses and validates a puppet language file and returns an instance of Puppet::Pops::Model::Program on success.
+    # If the content is not valid an error is raised.
+    #
+    # @param file [String] a file with puppet language content to parse and validate
+    # @return [Puppet::Pops::Model::Program] returns a `Program` instance on success
+    #
+    def parse_file(file)
+      unless file.is_a?(String)
+        raise ArgumentError, _("The argument 'file' must be a String, got %{type}") % { type: file.class }
+      end
+
+      internal_evaluator.parse_file(file)
+    end
+
+    # Parses a puppet data type given in String format and returns that type, or raises an error.
+    # A type is needed in calls to `new` to create an instance of the data type, or to perform type checking
+    # of values - typically using `type.instance?(obj)` to check if `obj` is an instance of the type.
+    #
+    # @example Verify if obj is an instance of a data type
+    #   # evaluates to true
+    #   pal.type('Enum[red, blue]').instance?("blue")
+    #
+    # @example Create an instance of a data type
+    #   # using an already create type
+    #   t = pal.type('Car')
+    #   pal.create(t, 'color' => 'black', 'make' => 't-ford')
+    #
+    #   # letting 'new_object' parse the type from a string
+    #   pal.create('Car', 'color' => 'black', 'make' => 't-ford')
+    #
+    # @param type_string [String] a puppet language data type
+    # @return [Puppet::Pops::Types::PAnyType] the data type
+    #
+    def type(type_string)
+      Puppet::Pops::Types::TypeParser.singleton.parse(type_string)
+    end
+
+    # Creates a new instance of a given data type.
+    # @param data_type [String, Puppet::Pops::Types::PAnyType] the data type as a data type or in String form.
+    # @param arguments [Object] one or more arguments to the called `new` function
+    # @return [Object] an instance of the given data type,
+    #   or raises an error if it was not possible to parse data type or create an instance.
+    #
+    def create(data_type, *arguments)
+      t = data_type.is_a?(String) ? type(data_type) : data_type
+      unless t.is_a?(Puppet::Pops::Types::PAnyType)
+        raise ArgumentError, _("Given data_type value is not a data type, got '%{type}'") % { type: t.class }
+      end
+
+      call_function('new', t, *arguments)
+    end
+
+    # Returns true if this is a compiler that compiles a catalog.
+    # This implementation returns `false`
+    # @return Boolan false
+    def has_catalog?
+      false
+    end
+
+    protected
+
+    def list_loadable_kind(kind, filter_regex = nil, error_collector = nil)
+      loader = internal_compiler.loaders.private_environment_loader
+      if filter_regex.nil?
+        loader.discover(kind, error_collector)
+      else
+        loader.discover(kind, error_collector) { |f| f.name =~ filter_regex }
+      end
+    end
+
+    private
+
+    def topscope
+      internal_compiler.topscope
+    end
+  end
+end
+end

data/lib/puppet/pal/function_signature.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Puppet
+module Pal
+  # A FunctionSignature is returned from `function_signature`. Its purpose is to answer questions about the function's parameters
+  # and if it can be called with a set of parameters.
+  #
+  # It is also possible to get an array of puppet Callable data type where each callable describes one possible way
+  # the function can be called.
+  #
+  # @api public
+  #
+  class FunctionSignature
+    # @api private
+    def initialize(function_class)
+      @func = function_class
+    end
+
+    # Returns true if the function can be called with the given arguments and false otherwise.
+    # If the function is not callable, and a code block is given, it is given a formatted error message that describes
+    # the type mismatch. That error message can be quite complex if the function has multiple dispatch depending on
+    # given types.
+    #
+    # @param args [Array] The arguments as given to the function call
+    # @param callable [Proc, nil] An optional ruby Proc or puppet lambda given to the function
+    # @yield [String] a formatted error message describing a type mismatch if the function is not callable with given args + block
+    # @return [Boolean] true if the function can be called with given args + block, and false otherwise
+    # @api public
+    #
+    def callable_with?(args, callable = nil)
+      signatures = @func.dispatcher.to_type
+      callables = signatures.is_a?(Puppet::Pops::Types::PVariantType) ? signatures.types : [signatures]
+
+      return true if callables.any? { |t| t.callable_with?(args) }
+      return false unless block_given?
+
+      args_type = Puppet::Pops::Types::TypeCalculator.singleton.infer_set(callable.nil? ? args : args + [callable])
+      error_message = Puppet::Pops::Types::TypeMismatchDescriber.describe_signatures(@func.name, @func.signatures, args_type)
+      yield error_message
+      false
+    end
+
+    # Returns an array of Callable puppet data type
+    # @return [Array<Puppet::Pops::Types::PCallableType] one callable per way the function can be called
+    #
+    # @api public
+    #
+    def callables
+      signatures = @func.dispatcher.to_type
+      signatures.is_a?(Puppet::Pops::Types::PVariantType) ? signatures.types : [signatures]
+    end
+  end
+end
+end

data/lib/puppet/pal/json_catalog_encoder.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# The JsonCatalogEncoder is a wrapper around a catalog produced by the Pal::CatalogCompiler.with_json_encoding
+# method.
+# It allows encoding the entire catalog or an individual resource as Rich Data Json.
+#
+# @api public
+#
+module Puppet
+module Pal
+class JsonCatalogEncoder
+  # Is the resulting Json pretty printed or not.
+  attr_reader :pretty
+
+  # Should unrealized virtual resources be included in the result or not.
+  attr_reader :exclude_virtual
+
+  # The internal catalog being build - what this class wraps with a public API.
+  attr_reader :catalog
+  private :catalog
+
+  # Do not instantiate this class directly! Use the `Pal::CatalogCompiler#with_json_encoding` method
+  # instead.
+  #
+  # @param catalog [Puppet::Resource::Catalog] the internal catalog that this class wraps
+  # @param pretty [Boolean] (true), if the resulting JSON should be pretty printed or not
+  # @param exclude_virtual [Boolean] (true), if the resulting catalog should contain unrealzed virtual resources or not
+  #
+  # @api private
+  #
+  def initialize(catalog, pretty: true, exclude_virtual: true)
+    @catalog = catalog
+    @pretty = pretty
+    @exclude_virtual = exclude_virtual
+  end
+
+  # Encodes the entire catalog as a rich-data Json catalog.
+  # @return String The catalog in Json format using rich data format
+  # @api public
+  #
+  def encode
+    possibly_filtered_catalog.to_json(:pretty => pretty)
+  end
+
+  # Returns one particular resource as a Json string, or returns nil if resource was not found.
+  # @param type [String] the name of the puppet type (case independent)
+  # @param title [String] the title of the wanted resource
+  # @return [String] the resulting Json text
+  # @api public
+  #
+  def encode_resource(type, title)
+    # Ensure that both type and title are given since the underlying API will do mysterious things
+    # if 'title' is nil. (Other assertions are made by the catalog when looking up the resource).
+    #
+    # TRANSLATORS 'type' and 'title' are internal parameter names - do not translate
+    raise ArgumentError, _("Both type and title must be given") if type.nil? or title.nil?
+
+    r = possibly_filtered_catalog.resource(type, title)
+    return nil if r.nil?
+
+    r.to_data_hash.to_json(:pretty => pretty)
+  end
+
+  # Applies a filter for virtual resources and returns filtered catalog
+  # or the catalog itself if filtering was not needed.
+  # The result is cached.
+  # @api private
+  # rubocop:disable Naming/MemoizedInstanceVariableName
+  def possibly_filtered_catalog
+    @filtered ||= (exclude_virtual ? catalog.filter(&:virtual?) : catalog)
+  end
+  private :possibly_filtered_catalog
+  # rubocop:enable Naming/MemoizedInstanceVariableName
+end
+end
+end

data/lib/puppet/pal/pal_api.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Puppet
+  require_relative '../../puppet/parser/script_compiler'
+  require_relative '../../puppet/parser/catalog_compiler'
+
+  module Pal
+    require_relative '../../puppet/pal/json_catalog_encoder'
+    require_relative '../../puppet/pal/function_signature'
+    require_relative '../../puppet/pal/task_signature'
+    require_relative '../../puppet/pal/plan_signature'
+    require_relative '../../puppet/pal/compiler'
+    require_relative '../../puppet/pal/script_compiler'
+    require_relative '../../puppet/pal/catalog_compiler'
+    require_relative '../../puppet/pal/pal_impl'
+  end
+end