Class: Puppet::Pal::Compiler Private

Inherits:
Object
  • Object
show all
Defined in:
lib/puppet/pal/compiler.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

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

Direct Known Subclasses

CatalogCompiler, ScriptCompiler

Instance Method Summary collapse

Constructor Details

#initialize(internal_compiler) ⇒ Compiler

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Compiler.

 15 16 17 18
 
# File 'lib/puppet/pal/compiler.rb', line 15 def initialize(internal_compiler) @internal_compiler = internal_compiler @internal_evaluator = Puppet::Pops::Parser::EvaluatingParser.new end

Instance Method Details

#call_function(function_name, *args, &block) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Calls a function given by name with arguments specified in an ‘Array`, and optionally accepts a code block.

Parameters:

  • function_name (String) —

    the name of the function to call

  • args (Object) —

    the arguments to the function

  • block (Proc) —

    an optional callable block that is given to the called function

Returns:

  • (Object) —

    what the called function returns

 26 27 28 29 30 31
 
# File 'lib/puppet/pal/compiler.rb', line 26 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

#create(data_type, *arguments) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Creates a new instance of a given data type.

Parameters:

  • data_type (String, Puppet::Pops::Types::PAnyType) —

    the data type as a data type or in String form.

  • arguments (Object) —

    one or more arguments to the called ‘new` function

Returns:

  • (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.

 193 194 195 196 197 198 199 200
 
# File 'lib/puppet/pal/compiler.rb', line 193 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

#evaluate(ast) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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).

Parameters:

 112 113 114 115 116 117 118
 
# File 'lib/puppet/pal/compiler.rb', line 112 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

#evaluate_file(file) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Evaluates a puppet language file in top scope. The file must exist and contain valid puppet language code or an error is raised.

Parameters:

  • file (Path, String) —

    an absolute path to a file with puppet language code, must exist

Returns:

  • (Object) —

    what the last evaluated expression in the file evaluated to

 101 102 103
 
# File 'lib/puppet/pal/compiler.rb', line 101 def evaluate_file(file) evaluate(parse_file(file)) end

#evaluate_literal(ast) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.

Parameters:

Raises:

  • (ArgumentError) 
 127 128 129 130 131 132 133
 
# File 'lib/puppet/pal/compiler.rb', line 127 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

#evaluate_string(puppet_code, source_file = nil) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.

Parameters:

  • puppet_code (String, nil) —

    the puppet language code to evaluate, must be a complete expression/statement

  • source_file (String, nil) (defaults to: nil) —

    an optional reference to a source (a file or symbolic name/location)

Returns:

  • (Object) —

    what the ‘puppet_code` evaluates to

 86 87 88 89 90 91 92 93
 
# File 'lib/puppet/pal/compiler.rb', line 86 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

#function_signature(function_name) ⇒ Puppet::Pal::FunctionSignature

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Examples:

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])

Parameters:

  • function_name (String) —

    the name of the function to get a signature for

Returns:

 43 44 45 46 47 48 49 50 51 52
 
# File 'lib/puppet/pal/compiler.rb', line 43 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

#has_catalog? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Returns:

  • (Boolean) —

    Boolan false

 205 206 207
 
# File 'lib/puppet/pal/compiler.rb', line 205 def has_catalog? false end

#list_functions(filter_regex = nil, error_collector = nil) ⇒ Array<Puppet::Pops::Loader::TypedName>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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 DataTypes::Error instances describing each error in detail and no warnings will be logged.

Examples:

getting the names of all functions

compiler.list_functions.map {|tn| tn.name }

Parameters:

  • filter_regex (Regexp) (defaults to: nil) —

    an optional regexp that filters based on name (matching names are included in the result)

  • error_collector (Array<Puppet::DataTypes::Error>) (defaults to: nil) —

    an optional array that will receive errors during load

Returns:

 69 70 71
 
# File 'lib/puppet/pal/compiler.rb', line 69 def list_functions(filter_regex = nil, error_collector = nil) list_loadable_kind(:function, filter_regex, error_collector) end

#parse_file(file) ⇒ Puppet::Pops::Model::Program

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.

Parameters:

  • file (String) —

    a file with puppet language content to parse and validate

Returns:

 156 157 158 159 160 161 162
 
# File 'lib/puppet/pal/compiler.rb', line 156 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

#parse_string(code_string, source_file = nil) ⇒ Puppet::Pops::Model::Program

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.

Parameters:

  • code_string (String) —

    a puppet language string to parse and validate

  • source_file (String) (defaults to: nil) —

    an optional reference to a file or other location in angled brackets

Returns:

 142 143 144 145 146 147 148
 
# File 'lib/puppet/pal/compiler.rb', line 142 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

#type(type_string) ⇒ Puppet::Pops::Types::PAnyType

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.

Examples:

Verify if obj is an instance of a data type

# evaluates to true pal.type('Enum[red, blue]').instance?("blue")

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')

Parameters:

  • type_string (String) —

    a puppet language data type

Returns:

 183 184 185
 
# File 'lib/puppet/pal/compiler.rb', line 183 def type(type_string) Puppet::Pops::Types::TypeParser.singleton.parse(type_string) end