Class: Puppet::Pal::Compiler

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

Overview

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 


14
15
16
17
 
# File 'lib/puppet/pal/compiler.rb', line 14

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

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


25
26
27
28
29
30
 
# File 'lib/puppet/pal/compiler.rb', line 25

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

Creates a new instance of a given data type.


188
189
190
191
192
193
194
 
# File 'lib/puppet/pal/compiler.rb', line 188

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

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


109
110
111
112
113
114
115
 
# File 'lib/puppet/pal/compiler.rb', line 109

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

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


98
99
100
 
# File 'lib/puppet/pal/compiler.rb', line 98

def evaluate_file(file)
  evaluate(parse_file(file))
end

#evaluate_literal(ast) ⇒ Object

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.

Raises:

  • (ArgumentError) 

124
125
126
127
128
129
130
 
# File 'lib/puppet/pal/compiler.rb', line 124

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

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.


84
85
86
87
88
89
90
 
# File 'lib/puppet/pal/compiler.rb', line 84

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

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


42
43
44
45
46
47
48
49
50
 
# File 'lib/puppet/pal/compiler.rb', line 42

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

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


199
200
201
 
# File 'lib/puppet/pal/compiler.rb', line 199

def has_catalog?
  false
end

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

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 }


67
68
69
 
# File 'lib/puppet/pal/compiler.rb', line 67

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

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.


152
153
154
155
156
157
 
# File 'lib/puppet/pal/compiler.rb', line 152

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

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.


139
140
141
142
143
144
 
# File 'lib/puppet/pal/compiler.rb', line 139

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

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


178
179
180
 
# File 'lib/puppet/pal/compiler.rb', line 178

def type(type_string)
  Puppet::Pops::Types::TypeParser.singleton.parse(type_string)
end