module Puppet::Pops::Evaluator::Runtime3Support
A module with bindings between the new evaluator and the 3x runtime. The intention is to separate all calls into scope, compiler, resource, etc. in this module to make it easier to later refactor the evaluator for better implementations of the 3x classes.
@api private
Constants
- NAME_SPACE_SEPARATOR
Public Instance Methods
Adds a relationship between the given `source` and `target` of the given `relationship_type` @param source [Puppet:Pops::Types::PCatalogEntryType] the source end of the relationship (from) @param target [Puppet:Pops::Types::PCatalogEntryType] the target end of the relationship (to) @param relationship_type [:relationship, :subscription] the type of the relationship
# File lib/puppet/pops/evaluator/runtime3_support.rb 172 def add_relationship(source, target, relationship_type, scope) 173 # The 3x way is to record a Puppet::Parser::Relationship that is evaluated at the end of the compilation. 174 # This means it is not possible to detect any duplicates at this point (and signal where an attempt is made to 175 # add a duplicate. There is also no location information to signal the original place in the logic. The user will have 176 # to go fish. 177 # The 3.x implementation is based on Strings :-o, so the source and target must be transformed. The resolution is 178 # done by Catalog#resource(type, title). To do that, it creates a Puppet::Resource since it is responsible for 179 # translating the name/type/title and create index-keys used by the catalog. The Puppet::Resource has bizarre parsing of 180 # the type and title (scan for [] that is interpreted as type/title (but it gets it wrong). 181 # Moreover if the type is "" or "component", the type is Class, and if the type is :main, it is :main, all other cases 182 # undergo capitalization of name-segments (foo::bar becomes Foo::Bar). (This was earlier done in the reverse by the parser). 183 # Further, the title undergoes the same munging !!! 184 # 185 # That bug infested nest of messy logic needs serious Exorcism! 186 # 187 # Unfortunately it is not easy to simply call more intelligent methods at a lower level as the compiler evaluates the recorded 188 # Relationship object at a much later point, and it is responsible for invoking all the messy logic. 189 # 190 # TODO: Revisit the below logic when there is a sane implementation of the catalog, compiler and resource. For now 191 # concentrate on transforming the type references to what is expected by the wacky logic. 192 # 193 # HOWEVER, the Compiler only records the Relationships, and the only method it calls is @relationships.each{|x| x.evaluate(catalog) } 194 # Which means a smarter Relationship class could do this right. Instead of obtaining the resource from the catalog using 195 # the borked resource(type, title) which creates a resource for the purpose of looking it up, it needs to instead 196 # scan the catalog's resources 197 # 198 # GAAAH, it is even worse! 199 # It starts in the parser, which parses "File['foo']" into an AST::ResourceReference with type = File, and title = foo 200 # This AST is evaluated by looking up the type/title in the scope - causing it to be loaded if it exists, and if not, the given 201 # type name/title is used. It does not search for resource instances, only classes and types. It returns symbolic information 202 # [type, [title, title]]. From this, instances of Puppet::Resource are created and returned. These only have type/title information 203 # filled out. One or an array of resources are returned. 204 # This set of evaluated (empty reference) Resource instances are then passed to the relationship operator. It creates a 205 # Puppet::Parser::Relationship giving it a source and a target that are (empty reference) Resource instances. These are then remembered 206 # until the relationship is evaluated by the compiler (at the end). When evaluation takes place, the (empty reference) Resource instances 207 # are converted to String (!?! WTF) on the simple format "#{type}[#{title}]", and the catalog is told to find a resource, by giving 208 # it this string. If it cannot find the resource it fails, else the before/notify parameter is appended with the target. 209 # The search for the resource begin with (you guessed it) again creating an (empty reference) resource from type and title (WTF?!?!). 210 # The catalog now uses the reference resource to compute a key [r.type, r.title.to_s] and also gets a uniqueness key from the 211 # resource (This is only a reference type created from title and type). If it cannot find it with the first key, it uses the 212 # uniqueness key to lookup. 213 # 214 # This is probably done to allow a resource type to munge/translate the title in some way (but it is quite unclear from the long 215 # and convoluted path of evaluation. 216 # In order to do this in a way that is similar to 3.x two resources are created to be used as keys. 217 # 218 # And if that is not enough, a source/target may be a Collector (a baked query that will be evaluated by the 219 # compiler - it is simply passed through here for processing by the compiler at the right time). 220 # 221 if source.is_a?(Collectors::AbstractCollector) 222 # use verbatim - behavior defined by 3x 223 source_resource = source 224 else 225 # transform into the wonderful String representation in 3x 226 type, title = Runtime3Converter.instance.catalog_type_to_split_type_title(source) 227 type = Runtime3ResourceSupport.find_resource_type(scope, type) unless type == 'class' || type == 'node' 228 source_resource = Puppet::Resource.new(type, title) 229 end 230 if target.is_a?(Collectors::AbstractCollector) 231 # use verbatim - behavior defined by 3x 232 target_resource = target 233 else 234 # transform into the wonderful String representation in 3x 235 type, title = Runtime3Converter.instance.catalog_type_to_split_type_title(target) 236 type = Runtime3ResourceSupport.find_resource_type(scope, type) unless type == 'class' || type == 'node' 237 target_resource = Puppet::Resource.new(type, title) 238 end 239 # Add the relationship to the compiler for later evaluation. 240 scope.compiler.add_relationship(Puppet::Parser::Relationship.new(source_resource, target_resource, relationship_type)) 241 end
# File lib/puppet/pops/evaluator/runtime3_support.rb 298 def call_function(name, args, o, scope, &block) 299 file, line = extract_file_line(o) 300 loader = Adapters::LoaderAdapter.loader_for_model_object(o, file) 301 func = loader.load(:function, name) if loader 302 if func 303 Puppet::Util::Profiler.profile(name, [:functions, name]) do 304 # Add stack frame when calling. 305 return Puppet::Pops::PuppetStack.stack(file || '', line, func, :call, [scope, *args], &block) 306 end 307 end 308 # Call via 3x API if function exists there without having been autoloaded 309 fail(Issues::UNKNOWN_FUNCTION, o, {:name => name}) unless Puppet::Parser::Functions.function(name) 310 311 # Arguments must be mapped since functions are unaware of the new and magical creatures in 4x. 312 # NOTE: Passing an empty string last converts nil/:undef to empty string 313 mapped_args = Runtime3FunctionArgumentConverter.map_args(args, scope, '') 314 # The 3x function performs return value mapping and returns nil if it is not of rvalue type 315 Puppet::Pops::PuppetStack.stack(file, line, scope, "function_#{name}", [mapped_args], &block) 316 end
Capitalizes each segment of a qualified name
# File lib/puppet/pops/evaluator/runtime3_support.rb 356 def capitalize_qualified_name(name) 357 name.split(/::/).map(&:capitalize).join(NAME_SPACE_SEPARATOR) 358 end
Coerce value `v` to numeric or fails. The given value `v` is coerced to Numeric, and if that fails the operation calls {#fail}. @param v [Object] the value to convert @param o [Object] originating instruction @param scope [Object] the (runtime specific) scope where evaluation of o takes place @return [Numeric] value `v` converted to Numeric.
# File lib/puppet/pops/evaluator/runtime3_support.rb 251 def coerce_numeric(v, o, scope) 252 if v.is_a?(Numeric) 253 return v 254 end 255 n = Utils.to_n(v) 256 unless n 257 fail(Issues::NOT_NUMERIC, o, {:value => v}) 258 end 259 # this point is reached if there was a conversion 260 optionally_fail(Issues::NUMERIC_COERCION, o, {:before => v, :after => n}) 261 n 262 end
# File lib/puppet/pops/evaluator/runtime3_support.rb 329 def convert(value, scope, undef_value) 330 Runtime3Converter.instance.convert(value, scope, undef_value) 331 end
Creates a local scope with vairalbes set from a hash of variable name to value
# File lib/puppet/pops/evaluator/runtime3_support.rb 143 def create_local_scope_from(hash, scope) 144 # two dummy values are needed since the scope tries to give an error message (can not happen in this 145 # case - it is just wrong, the error should be reported by the caller who knows in more detail where it 146 # is in the source. 147 # 148 raise ArgumentError, _("Internal error - attempt to create a local scope without a hash") unless hash.is_a?(Hash) 149 scope.ephemeral_from(hash) 150 end
Creates a nested match scope
# File lib/puppet/pops/evaluator/runtime3_support.rb 153 def create_match_scope_from(scope) 154 # Create a transparent match scope (for future matches) 155 scope.new_match_scope(nil) 156 end
Defines default parameters for a type with the given name.
# File lib/puppet/pops/evaluator/runtime3_support.rb 345 def create_resource_defaults(o, scope, type_name, evaluated_parameters) 346 # Note that name must be capitalized in this 3x call 347 # The 3x impl creates a Resource instance with a bogus title and then asks the created resource 348 # for the type of the name. 349 # Note, locations are available per parameter. 350 # 351 scope.define_settings(capitalize_qualified_name(type_name), evaluated_parameters.flatten) 352 end
Creates resource overrides for all resource type objects in evaluated_resources. The same set of evaluated parameters are applied to all.
# File lib/puppet/pops/evaluator/runtime3_support.rb 363 def create_resource_overrides(o, scope, evaluated_resources, evaluated_parameters) 364 # Not 100% accurate as this is the resource expression location and each title is processed separately 365 # The titles are however the result of evaluation and they have no location at this point (an array 366 # of positions for the source expressions are required for this to work. 367 # TODO: Revisit and possible improve the accuracy. 368 # 369 file, line = extract_file_line(o) 370 # A *=> results in an array of arrays 371 evaluated_parameters = evaluated_parameters.flatten 372 evaluated_resources.each do |r| 373 unless r.is_a?(Types::PResourceType) && r.type_name != 'class' 374 fail(Issues::ILLEGAL_OVERRIDDEN_TYPE, o, {:actual => r} ) 375 end 376 t = Runtime3ResourceSupport.find_resource_type(scope, r.type_name) 377 resource = Puppet::Parser::Resource.new( 378 t, r.title, { 379 :parameters => evaluated_parameters, 380 :file => file, 381 :line => line, 382 # WTF is this? Which source is this? The file? The name of the context ? 383 :source => scope.source, 384 :scope => scope 385 }, false # defaults should not override 386 ) 387 388 scope.compiler.add_override(resource) 389 end 390 end
The o is used for source reference
# File lib/puppet/pops/evaluator/runtime3_support.rb 319 def create_resource_parameter(o, scope, name, value, operator) 320 file, line = extract_file_line(o) 321 Puppet::Parser::Resource::Param.new( 322 :name => name, 323 :value => convert(value, scope, nil), # converted to 3x since 4x supports additional objects / types 324 :source => scope.source, :line => line, :file => file, 325 :add => operator == '+>' 326 ) 327 end
# File lib/puppet/pops/evaluator/runtime3_support.rb 333 def create_resources(o, scope, virtual, exported, type_name, resource_titles, evaluated_parameters) 334 # Not 100% accurate as this is the resource expression location and each title is processed separately 335 # The titles are however the result of evaluation and they have no location at this point (an array 336 # of positions for the source expressions are required for this to work). 337 # TODO: Revisit and possible improve the accuracy. 338 # 339 file, line = extract_file_line(o) 340 Runtime3ResourceSupport.create_resources(file, line, scope, virtual, exported, type_name, resource_titles, evaluated_parameters) 341 end
Creates a diagnostic producer
# File lib/puppet/pops/evaluator/runtime3_support.rb 473 def diagnostic_producer 474 Validation::DiagnosticProducer.new( 475 ExceptionRaisingAcceptor.new(), # Raises exception on all issues 476 SeverityProducer.new(), # All issues are errors 477 Model::ModelLabelProvider.new()) 478 end
Provides the ability to call a 3.x or 4.x function from the perspective of a 3.x function or ERB template. The arguments to the function must be an Array containing values compliant with the 4.x calling convention. If the targeted function is a 3.x function, the values will be transformed. @param name [String] the name of the function (without the 'function_' prefix used by scope) @param args [Array] arguments, may be empty @param scope [Object] the (runtime specific) scope where evaluation takes place @raise [ArgumentError] 'unknown function' if the function does not exist
# File lib/puppet/pops/evaluator/runtime3_support.rb 272 def external_call_function(name, args, scope, &block) 273 # Call via 4x API if the function exists there 274 loaders = scope.compiler.loaders 275 # Since this is a call from non puppet code, it is not possible to relate it to a module loader 276 # It is known where the call originates by using the scope associated module - but this is the calling scope 277 # and it does not defined the visibility of functions from a ruby function's perspective. Instead, 278 # this is done from the perspective of the environment. 279 loader = loaders.private_environment_loader 280 func = loader.load(:function, name) if loader 281 if func 282 Puppet::Util::Profiler.profile(name, [:functions, name]) do 283 return func.call(scope, *args, &block) 284 end 285 end 286 287 # Call via 3x API if function exists there 288 raise ArgumentError, _("Unknown function '%{name}'") % { name: name } unless Puppet::Parser::Functions.function(name) 289 290 # Arguments must be mapped since functions are unaware of the new and magical creatures in 4x. 291 # NOTE: Passing an empty string last converts nil/:undef to empty string 292 mapped_args = Runtime3FunctionArgumentConverter.map_args(args, scope, '') 293 result = scope.send("function_#{name}", mapped_args, &block) 294 # Prevent non r-value functions from leaking their result (they are not written to care about this) 295 Puppet::Parser::Functions.rvalue?(name) ? result : nil 296 end
# File lib/puppet/pops/evaluator/runtime3_support.rb 468 def extract_file_line(o) 469 o.is_a?(Model::Positioned) ? [o.file, o.line] : [nil, -1] 470 end
Fails the evaluation of semantic with a given issue.
@param issue [Issue] the issue to report @param semantic [ModelPopsObject] the object for which evaluation failed in some way. Used to determine origin. @param options [Hash] hash of optional named data elements for the given issue @return [!] this method does not return @raise [Puppet::ParseError] an evaluation error initialized from the arguments (TODO: Change to EvaluationError
?)
# File lib/puppet/pops/evaluator/runtime3_support.rb 20 def fail(issue, semantic, options={}, except=nil) 21 optionally_fail(issue, semantic, options, except) 22 # an error should have been raised since fail always fails 23 raise ArgumentError, _("Internal Error: Configuration of runtime error handling wrong: should have raised exception") 24 end
Finds a resource given a type and a title.
# File lib/puppet/pops/evaluator/runtime3_support.rb 394 def find_resource(scope, type_name, title) 395 scope.compiler.findresource(type_name, title) 396 end
Returns the value of a resource's parameter by first looking up the parameter in the resource and then in the defaults for the resource. Since the resource exists (it must in order to look up its parameters, any overrides have already been applied). Defaults are not applied to a resource until it has been finished (which typically has not taken place when this is evaluated; hence the dual lookup).
# File lib/puppet/pops/evaluator/runtime3_support.rb 403 def get_resource_parameter_value(scope, resource, parameter_name) 404 # This gets the parameter value, or nil (for both valid parameters and parameters that do not exist). 405 val = resource[parameter_name] 406 407 # Sometimes the resource is a Puppet::Parser::Resource and sometimes it is 408 # a Puppet::Resource. The Puppet::Resource case occurs when puppet language 409 # is evaluated against an already completed catalog (where all instances of 410 # Puppet::Parser::Resource are converted to Puppet::Resource instances). 411 # Evaluating against an already completed catalog is really only found in 412 # the language specification tests, where the puppet language is used to 413 # test itself. 414 if resource.is_a?(Puppet::Parser::Resource) 415 # The defaults must be looked up in the scope where the resource was created (not in the given 416 # scope where the lookup takes place. 417 resource_scope = resource.scope 418 defaults = resource_scope.lookupdefaults(resource.type) if val.nil? && resource_scope 419 if defaults 420 # NOTE: 3x resource keeps defaults as hash using symbol for name as key to Parameter which (again) holds 421 # name and value. 422 # NOTE: meta parameters that are unset ends up here, and there are no defaults for those encoded 423 # in the defaults, they may receive hardcoded defaults later (e.g. 'tag'). 424 param = defaults[parameter_name.to_sym] 425 # Some parameters (meta parameters like 'tag') does not return a param from which the value can be obtained 426 # at all times. Instead, they return a nil param until a value has been set. 427 val = param.nil? ? nil : param.value 428 end 429 end 430 val 431 end
# File lib/puppet/pops/evaluator/runtime3_support.rb 158 def get_scope_nesting_level(scope) 159 scope.ephemeral_level 160 end
Returns the value of the variable (nil is returned if variable has no value, or if variable does not exist)
# File lib/puppet/pops/evaluator/runtime3_support.rb 97 def get_variable_value(name, o, scope) 98 # Puppet 3x stores all variables as strings (then converts them back to numeric with a regexp... to see if it is a match variable) 99 # Not ideal, scope should support numeric lookup directly instead. 100 # TODO: consider fixing scope 101 catch(:undefined_variable) { 102 x = scope.lookupvar(name.to_s) 103 # Must convert :undef back to nil - this can happen when an undefined variable is used in a 104 # parameter's default value expression - there nil must be :undef to work with the rest of 3x. 105 # Now that the value comes back to 4x it is changed to nil. 106 return :undef.equal?(x) ? nil : x 107 } 108 # It is always ok to reference numeric variables even if they are not assigned. They are always undef 109 # if not set by a match expression. 110 # 111 unless name =~ Puppet::Pops::Patterns::NUMERIC_VAR_NAME 112 optionally_fail(Puppet::Pops::Issues::UNKNOWN_VARIABLE, o, {:name => name}) 113 end 114 nil # in case unknown variable is configured as a warning or ignore 115 end
Utility method for TrueClass || FalseClass @param x [Object] the object to test if it is instance of TrueClass or FalseClass
# File lib/puppet/pops/evaluator/runtime3_support.rb 464 def is_boolean? x 465 x.is_a?(TrueClass) || x.is_a?(FalseClass) 466 end
Returns true, if the given name is the name of a resource parameter.
# File lib/puppet/pops/evaluator/runtime3_support.rb 435 def is_parameter_of_resource?(scope, resource, name) 436 return false unless name.is_a?(String) 437 resource.valid_parameter?(name) 438 end
This is the same type of “truth” as used in the current Puppet
DSL.
# File lib/puppet/pops/evaluator/runtime3_support.rb 448 def is_true?(value, o) 449 # Is the value true? This allows us to control the definition of truth 450 # in one place. 451 case value 452 # Support :undef since it may come from a 3x structure 453 when :undef 454 false 455 when String 456 true 457 else 458 !!value 459 end 460 end
Optionally (based on severity) Fails the evaluation of semantic with a given issue If the given issue is configured to be of severity < :error it is only reported, and the function returns.
@param issue [Issue] the issue to report @param semantic [ModelPopsObject] the object for which evaluation failed in some way. Used to determine origin. @param options [Hash] hash of optional named data elements for the given issue @return [!] this method does not return @raise [Puppet::ParseError] an evaluation error initialized from the arguments (TODO: Change to EvaluationError
?)
# File lib/puppet/pops/evaluator/runtime3_support.rb 35 def optionally_fail(issue, semantic, options={}, except=nil) 36 if except.nil? && diagnostic_producer.severity_producer[issue] == :error 37 # Want a stacktrace, and it must be passed as an exception 38 begin 39 raise EvaluationError.new() 40 rescue EvaluationError => e 41 except = e 42 end 43 end 44 diagnostic_producer.accept(issue, semantic, options, except) 45 end
# File lib/puppet/pops/evaluator/runtime3_support.rb 440 def resource_to_ptype(resource) 441 nil if resource.nil? 442 # inference returns the meta type since the 3x Resource is an alternate way to describe a type 443 type_calculator.infer(resource).type 444 end
Optionally (based on severity) Fails the evaluation with a given issue If the given issue is configured to be of severity < :error it is only reported, and the function returns. The location the issue is reported against is found is based on the top file/line in the puppet call stack
@param issue [Issue] the issue to report @param options [Hash] hash of optional named data elements for the given issue @return [!] this method may not return, nil if it does @raise [Puppet::ParseError] an evaluation error initialized from the arguments
# File lib/puppet/pops/evaluator/runtime3_support.rb 56 def runtime_issue(issue, options={}) 57 # Get position from puppet runtime stack 58 file, line = Puppet::Pops::PuppetStack.top_of_stack 59 60 # Use a SemanticError as the sourcepos 61 semantic = Puppet::Pops::SemanticError.new(issue, nil, options.merge({:file => file, :line => line})) 62 optionally_fail(issue, semantic) 63 nil 64 end
# File lib/puppet/pops/evaluator/runtime3_support.rb 130 def set_match_data(match_data, scope) 131 # See set_variable for rationale for not passing file and line to ephemeral_from. 132 # NOTE: The 3x scope adds one ephemeral(match) to its internal stack per match that succeeds ! It never 133 # clears anything. Thus a context that performs many matches will get very deep (there simply is no way to 134 # clear the match variables without rolling back the ephemeral stack.) 135 # This implementation does not attempt to fix this, it behaves the same bad way. 136 unless match_data.nil? 137 scope.ephemeral_from(match_data) 138 end 139 end
# File lib/puppet/pops/evaluator/runtime3_support.rb 162 def set_scope_nesting_level(scope, level) 163 # 3x uses this method to reset the level, 164 scope.pop_ephemerals(level) 165 end
Binds the given variable name to the given value in the given scope. The reference object `o` is intended to be used for origin information - the 3x scope implementation only makes use of location when there is an error. This is now handled by other mechanisms; first a check is made if a variable exists and an error is raised if attempting to change an immutable value. Errors in name, numeric variable assignment etc. have also been validated prior to this call. In the event the scope.setvar still raises an error, the general exception handling for evaluation of the assignment expression knows about its location. Because of this, there is no need to extract the location for each setting (extraction is somewhat expensive since 3x requires line instead of offset).
# File lib/puppet/pops/evaluator/runtime3_support.rb 75 def set_variable(name, value, o, scope) 76 # Scope also checks this but requires that location information are passed as options. 77 # Those are expensive to calculate and a test is instead made here to enable failing with better information. 78 # The error is not specific enough to allow catching it - need to check the actual message text. 79 # TODO: Improve the messy implementation in Scope. 80 # 81 if name == "server_facts" 82 fail(Issues::ILLEGAL_RESERVED_ASSIGNMENT, o, {:name => name} ) 83 end 84 85 if scope.bound?(name) 86 if Puppet::Parser::Scope::RESERVED_VARIABLE_NAMES.include?(name) 87 fail(Issues::ILLEGAL_RESERVED_ASSIGNMENT, o, {:name => name} ) 88 else 89 fail(Issues::ILLEGAL_REASSIGNMENT, o, {:name => name} ) 90 end 91 end 92 scope.setvar(name, value) 93 end
Returns true if the variable of the given name is set in the given most nested scope. True is returned even if variable is bound to nil.
# File lib/puppet/pops/evaluator/runtime3_support.rb 120 def variable_bound?(name, scope) 121 scope.bound?(name.to_s) 122 end
Returns true if the variable is bound to a value or nil, in the scope or it's parent scopes.
# File lib/puppet/pops/evaluator/runtime3_support.rb 126 def variable_exists?(name, scope) 127 scope.exist?(name.to_s) 128 end