class Puppet::Pal::Compiler

A configured compiler as obtained in the callback from `Puppet::Pal.with_script_compiler`. (Later, there may also be a catalog compiler available.)

Attributes

internal_compiler[R]
internal_evaluator[R]

Public Class Methods

new(internal_compiler) click to toggle source
   # File lib/puppet/pal/compiler.rb
14 def initialize(internal_compiler)
15   @internal_compiler = internal_compiler
16   @internal_evaluator = Puppet::Pops::Parser::EvaluatingParser.new
17 end

Public Instance Methods

call_function(function_name, *args, &block) click to toggle source

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

   # File lib/puppet/pal/compiler.rb
25 def call_function(function_name, *args, &block)
26   # TRANSLATORS: do not translate variable name strings in these assertions
27   Pal::assert_non_empty_string(function_name, 'function_name', false)
28   Pal::assert_type(Pal::T_ANY_ARRAY, args, 'args', false)
29   internal_evaluator.evaluator.external_call_function(function_name, args, topscope, &block)
30 end
create(data_type, *arguments) click to toggle source

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.
    # File lib/puppet/pal/compiler.rb
188 def create(data_type, *arguments)
189   t = data_type.is_a?(String) ? type(data_type) : data_type
190   unless t.is_a?(Puppet::Pops::Types::PAnyType)
191     raise ArgumentError, _("Given data_type value is not a data type, got '%{type}'") % {type: t.class}
192   end
193   call_function('new', t, *arguments)
194 end
evaluate(ast) click to toggle source

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

    # File lib/puppet/pal/compiler.rb
109 def evaluate(ast)
110   if ast.is_a?(Puppet::Pops::Model::Program)
111     loaders = Puppet.lookup(:loaders)
112     loaders.instantiate_definitions(ast, loaders.public_environment_loader)
113   end
114   internal_evaluator.evaluate(topscope, ast)
115 end
evaluate_file(file) click to toggle source

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

    # File lib/puppet/pal/compiler.rb
 98 def evaluate_file(file)
 99   evaluate(parse_file(file))
100 end
evaluate_literal(ast) click to toggle source

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

    # File lib/puppet/pal/compiler.rb
124 def evaluate_literal(ast)
125   catch :not_literal do
126     return Puppet::Pops::Evaluator::LiteralEvaluator.new().literal(ast)
127   end
128   # TRANSLATORS, the 'ast' is the name of a parameter, do not translate
129   raise ArgumentError, _("The given 'ast' does not represent a literal value")
130 end
evaluate_string(puppet_code, source_file = nil) click to toggle source

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

   # File lib/puppet/pal/compiler.rb
84 def evaluate_string(puppet_code, source_file = nil)
85   return nil if puppet_code.nil? || puppet_code == ''
86   unless puppet_code.is_a?(String)
87     raise ArgumentError, _("The argument 'puppet_code' must be a String, got %{type}") % { type: puppet_code.class }
88   end
89   evaluate(parse_string(puppet_code, source_file))
90 end
function_signature(function_name) click to toggle source

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

   # File lib/puppet/pal/compiler.rb
42 def function_signature(function_name)
43   loader = internal_compiler.loaders.private_environment_loader
44   func = loader.load(:function, function_name)
45   if func
46     return FunctionSignature.new(func.class)
47   end
48   # Could not find function
49   nil
50 end
has_catalog?() click to toggle source

Returns true if this is a compiler that compiles a catalog. This implementation returns `false` @return Boolan false

    # File lib/puppet/pal/compiler.rb
199 def has_catalog?
200   false
201 end
list_functions(filter_regex = nil, error_collector = nil) click to toggle source

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

   # File lib/puppet/pal/compiler.rb
67 def list_functions(filter_regex = nil, error_collector = nil)
68   list_loadable_kind(:function, filter_regex, error_collector)
69 end
parse_file(file) click to toggle source

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

    # File lib/puppet/pal/compiler.rb
152 def parse_file(file)
153   unless file.is_a?(String)
154     raise ArgumentError, _("The argument 'file' must be a String, got %{type}") % { type: file.class }
155   end
156   internal_evaluator.parse_file(file)
157 end
parse_string(code_string, source_file = nil) click to toggle source

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

    # File lib/puppet/pal/compiler.rb
139 def parse_string(code_string, source_file = nil)
140   unless code_string.is_a?(String)
141     raise ArgumentError, _("The argument 'code_string' must be a String, got %{type}") % { type: code_string.class }
142   end
143   internal_evaluator.parse_string(code_string, source_file)
144 end
type(type_string) click to toggle source

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

    # File lib/puppet/pal/compiler.rb
178 def type(type_string)
179   Puppet::Pops::Types::TypeParser.singleton.parse(type_string)
180 end

Protected Instance Methods

list_loadable_kind(kind, filter_regex = nil, error_collector = nil) click to toggle source
    # File lib/puppet/pal/compiler.rb
205 def list_loadable_kind(kind, filter_regex = nil, error_collector = nil)
206   loader = internal_compiler.loaders.private_environment_loader
207   if filter_regex.nil?
208     loader.discover(kind, error_collector)
209   else
210     loader.discover(kind, error_collector) {|f| f.name =~ filter_regex }
211   end
212 end

Private Instance Methods

topscope() click to toggle source
    # File lib/puppet/pal/compiler.rb
216 def topscope
217   internal_compiler.topscope
218 end