Class: Puppet::Parser::Scope

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Util::Errors
Defined in:
lib/puppet/parser/scope.rb

Overview

This class is part of the internal parser/evaluator/compiler functionality of Puppet. It is passed between the various classes that participate in evaluation. None of its methods are API except those that are clearly marked as such.

Defined Under Namespace

Classes: Ephemeral, LocalScope, MatchScope, ParameterScope

Constant Summary collapse

BUILT_IN_VARS =

Variables that always exist with nil value even if not set

['module_name'.freeze, 'caller_module_name'.freeze].freeze
EMPTY_HASH =
{}.freeze
UNDEFINED_VARIABLES_KIND =
'undefined_variables'.freeze
UNCAUGHT_THROW_EXCEPTION =

The exception raised when a throw is uncaught is different in different versions of ruby. In >=2.2.0 it is UncaughtThrowError (which did not exist prior to this)

defined?(UncaughtThrowError) ? UncaughtThrowError : ArgumentError
VARNAME_TRUSTED =
'trusted'.freeze
VARNAME_FACTS =
'facts'.freeze
VARNAME_SERVER_FACTS =
'server_facts'.freeze
RESERVED_VARIABLE_NAMES =
[VARNAME_TRUSTED, VARNAME_FACTS].freeze
TYPENAME_CLASS =
'Class'.freeze
TYPENAME_NODE =
'Node'.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Util::Errors

#adderrorcontext, #devfail, #error_context, error_location, error_location_with_space, error_location_with_unknowns, #exceptwrap, #fail

Constructor Details

#initialize(compiler, source: nil, resource: nil) ⇒ Scope

Initialize our new scope. Defaults to having no parent.


373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
# File 'lib/puppet/parser/scope.rb', line 373

def initialize(compiler, source: nil, resource: nil)
  if compiler.is_a? Puppet::Parser::AbstractCompiler
    @compiler = compiler
  else
    raise Puppet::DevError, _("you must pass a compiler instance to a new scope object")
  end

  @source = source
  @resource = resource

  extend_with_functions_module

  # The symbol table for this scope.  This is where we store variables.
  #    @symtable = Ephemeral.new(nil, true)
  @symtable = LocalScope.new(nil)

  @ephemeral = [ MatchScope.new(@symtable, nil) ]

  # All of the defaults set for types.  It's a hash of hashes,
  # with the first key being the type, then the second key being
  # the parameter.
  @defaults = Hash.new { |dhash,type|
    dhash[type] = {}
  }

  # The table for storing class singletons.  This will only actually
  # be used by top scopes and node scopes.
  @class_scopes = {}
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method, *args, &block) ⇒ Object


1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
# File 'lib/puppet/parser/scope.rb', line 1034

def method_missing(method, *args, &block)
  method.to_s =~ /^function_(.*)$/
  name = $1
  super unless name
  super unless Puppet::Parser::Functions.function(name)
  # In odd circumstances, this might not end up defined by the previous
  # method, so we might as well be certain.
  if respond_to? method
    send(method, *args)
  else
    raise Puppet::DevError, _("Function %{name} not defined despite being loaded!") % { name: name }
  end
end

Instance Attribute Details

#compilerObject (readonly)


25
26
27
# File 'lib/puppet/parser/scope.rb', line 25

def compiler
  @compiler
end

#defaultsObject (readonly)

Hash of hashes of default values per type name


29
30
31
# File 'lib/puppet/parser/scope.rb', line 29

def defaults
  @defaults
end

#parentObject


26
27
28
# File 'lib/puppet/parser/scope.rb', line 26

def parent
  @parent
end

#resourceObject


24
25
26
# File 'lib/puppet/parser/scope.rb', line 24

def resource
  @resource
end

#sourceObject


24
25
26
# File 'lib/puppet/parser/scope.rb', line 24

def source
  @source
end

Class Method Details

.number?(value) ⇒ Boolean

Coerce value to a number, or return `nil` if it isn't one.


327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
# File 'lib/puppet/parser/scope.rb', line 327

def self.number?(value)
  case value
  when Numeric
    value
  when /^-?\d+(:?\.\d+|(:?\.\d+)?e\d+)$/
    value.to_f
  when /^0x[0-9a-f]+$/i
    value.to_i(16)
  when /^0[0-7]+$/
    value.to_i(8)
  when /^-?\d+$/
    value.to_i
  else
    nil
  end
end

.true?(value) ⇒ Boolean

Is the value true? This allows us to control the definition of truth in one place.


315
316
317
318
319
320
321
322
323
324
# File 'lib/puppet/parser/scope.rb', line 315

def self.true?(value)
  case value
  when ''
    false
  when :undef
    false
  else
    !!value
  end
end

Instance Method Details

#[](varname, options = EMPTY_HASH) ⇒ Object

Retrieves the variable value assigned to the name given as an argument. The name must be a String, and namespace can be qualified with '::'. The value is looked up in this scope, its parent scopes, or in a specific visible named scope.

See Also:


553
554
555
# File 'lib/puppet/parser/scope.rb', line 553

def [](varname, options = EMPTY_HASH)
  lookupvar(varname, options)
end

#[]=(varname, value, _ = nil) ⇒ Object

Sets the variable value of the name given as an argument to the given value. The value is set in the current scope and may shadow a variable with the same name in a visible outer scope. It is illegal to re-assign a variable in the same scope. It is illegal to set a variable in some other scope/namespace than the scope passed to a method.


868
869
870
# File 'lib/puppet/parser/scope.rb', line 868

def []=(varname, value, _ = nil)
  setvar(varname, value)
end

#bound?(name) ⇒ Boolean

Returns true if the given name is bound in the current (most nested) scope for assignments.


308
309
310
311
# File 'lib/puppet/parser/scope.rb', line 308

def bound?(name)
  # Do not look in ephemeral (match scope), the semantics is to answer if an assignable variable is bound
  effective_symtable(false).bound?(name)
end

#call_function(func_name, args, &block) ⇒ Object

Calls a 3.x or 4.x function by name with arguments given in an array using the 4.x calling convention and returns the result. Note that it is the caller's responsibility to rescue the given ArgumentError and provide location information to aid the user find the problem. The problem is otherwise reported against the source location that invoked the function that ultimately called this method.

Raises:

  • ArgumentError if the function does not exist


1100
1101
1102
# File 'lib/puppet/parser/scope.rb', line 1100

def call_function(func_name, args, &block)
  Puppet::Pops::Parser::EvaluatingParser.new.evaluator.external_call_function(func_name, args, self, &block)
end

#catalogObject

Alias for `compiler.catalog`


37
38
39
# File 'lib/puppet/parser/scope.rb', line 37

def catalog
  @compiler.catalog
end

#class_scope(klass) ⇒ Object

Return the scope associated with a class. This is just here so that subclasses can set their parent scopes to be the scope of their parent class, and it's also used when looking up qualified variables.


417
418
419
420
421
# File 'lib/puppet/parser/scope.rb', line 417

def class_scope(klass)
  # They might pass in either the class or class name
  k = klass.respond_to?(:name) ? klass.name : klass
  @class_scopes[k] || (parent && parent.class_scope(k))
end

#class_set(name, scope) ⇒ Object

Store the fact that we've evaluated a class, and store a reference to the scope in which it was evaluated, so that we can look it up later.


405
406
407
408
409
410
411
# File 'lib/puppet/parser/scope.rb', line 405

def class_set(name, scope)
  if parent
    parent.class_set(name, scope)
  else
    @class_scopes[name] = scope
  end
end

#define_settings(type, params) ⇒ Object

Set defaults for a type. The typename should already be downcased, so that the syntax is isolated. We don't do any kind of type-checking here; instead we let the resource do it when the defaults are used.


695
696
697
698
699
700
701
702
703
704
705
706
707
# File 'lib/puppet/parser/scope.rb', line 695

def define_settings(type, params)
  table = @defaults[type]

  # if we got a single param, it'll be in its own array
  params = [params] unless params.is_a?(Array)

  params.each { |param|
    if table.include?(param.name)
      raise Puppet::ParseError.new(_("Default already defined for %{type} { %{param} }; cannot redefine") % { type: type, param: param.name }, param.file, param.line)
    end
    table[param.name] = param
  }
end

#effective_symtable(use_ephemeral) ⇒ Object

Return the effective “table” for setting variables. This method returns the first ephemeral “table” that acts as a local scope, or this scope's symtable. If the parameter `use_ephemeral` is true, the “top most” ephemeral “table” will be returned (irrespective of it being a match scope or a local scope).


847
848
849
850
851
852
853
854
855
# File 'lib/puppet/parser/scope.rb', line 847

def effective_symtable(use_ephemeral)
  s = @ephemeral[-1]
  return s || @symtable if use_ephemeral

  while s && !s.is_local_scope?()
    s = s.parent
  end
  s || @symtable
end

#enclosing_scopePuppet::Parser::Scope

The enclosing scope (topscope or nodescope) of this scope. The enclosing scopes are produced when a class or define is included at some point. The parent scope of the included class or define becomes the scope in which it was included. The chain of parent scopes is followed until a node scope or the topscope is found


575
576
577
578
579
580
581
582
583
# File 'lib/puppet/parser/scope.rb', line 575

def enclosing_scope
   if has_enclosing_scope?
    if parent.is_topscope? || parent.is_nodescope?
      parent
    else
      parent.enclosing_scope
    end
   end
end

#environmentObject

Alias for `compiler.environment`


32
33
34
# File 'lib/puppet/parser/scope.rb', line 32

def environment
  @compiler.environment
end

#ephemeral_from(match, file = nil, line = nil) ⇒ Object


1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
# File 'lib/puppet/parser/scope.rb', line 1001

def ephemeral_from(match, file = nil, line = nil)
  case match
  when Hash
    # Create local scope ephemeral and set all values from hash
    new_ephemeral(true)
    match.each {|k,v| setvar(k, v, :file => file, :line => line, :ephemeral => true) }
    # Must always have an inner match data scope (that starts out as transparent)
    # In 3x slightly wasteful, since a new nested scope is created for a match
    # (TODO: Fix that problem)
    new_ephemeral(false)
  else
    raise(ArgumentError,_("Invalid regex match data. Got a %{klass}") % { klass: match.class }) unless match.is_a?(MatchData)
    # Create a match ephemeral and set values from match data
    new_match_scope(match)
  end
end

#ephemeral_levelObject


914
915
916
# File 'lib/puppet/parser/scope.rb', line 914

def ephemeral_level
  @ephemeral.size
end

#exist?(name) ⇒ Boolean

Returns true if the variable of the given name is set to any value (including nil)


283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
# File 'lib/puppet/parser/scope.rb', line 283

def exist?(name)
  # Note !! ensure the answer is boolean
  !! if name =~ /^(.*)::(.+)$/
    class_name = $1
    variable_name = $2
    return true if class_name == '' && BUILT_IN_VARS.include?(variable_name)

    # lookup class, but do not care if it is not evaluated since that will result
    # in it not existing anyway. (Tests may run with just scopes and no evaluated classes which
    # will result in class_scope for "" not returning topscope).
    klass = find_hostclass(class_name)
    other_scope = klass.nil? ? nil : class_scope(klass)
    if other_scope.nil?
      class_name == '' ? compiler.topscope.exist?(variable_name) : false
    else
      other_scope.exist?(variable_name)
    end
  else
    next_scope = inherited_scope || enclosing_scope
    effective_symtable(true).include?(name) || next_scope && next_scope.exist?(name) || BUILT_IN_VARS.include?(name)
  end
end

#find_builtin_resource_type(type) ⇒ 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.

Raises:


1024
1025
1026
# File 'lib/puppet/parser/scope.rb', line 1024

def find_builtin_resource_type(type)
  raise Puppet::DevError, _("Scope#find_builtin_resource_type() is no longer supported, use Puppet::Pops::Evaluator::Runtime3ResourceSupport instead")
end

#find_defined_resource_type(type) ⇒ 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.

Raises:


1029
1030
1031
# File 'lib/puppet/parser/scope.rb', line 1029

def find_defined_resource_type(type)
  raise Puppet::DevError, _("Scope#find_defined_resource_type() is no longer supported, use Puppet::Pops::Evaluator::Runtime3ResourceSupport instead")
end

#find_definition(name) ⇒ Object


348
349
350
# File 'lib/puppet/parser/scope.rb', line 348

def find_definition(name)
  environment.known_resource_types.find_definition(name)
end

#find_global_scopeObject


352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
# File 'lib/puppet/parser/scope.rb', line 352

def find_global_scope()
  # walk upwards until first found node_scope or top_scope
  if is_nodescope? || is_topscope?
    self
  else
    next_scope = inherited_scope || enclosing_scope
    if next_scope.nil?
      # this happens when testing, and there is only a single test scope and no link to any
      # other scopes
      self
    else
      next_scope.find_global_scope()
    end
  end
end

#find_hostclass(name) ⇒ Object


344
345
346
# File 'lib/puppet/parser/scope.rb', line 344

def find_hostclass(name)
  environment.known_resource_types.find_hostclass(name)
end

#find_resource_type(type) ⇒ 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.

Raises:


1019
1020
1021
# File 'lib/puppet/parser/scope.rb', line 1019

def find_resource_type(type)
  raise Puppet::DevError, _("Scope#find_resource_type() is no longer supported, use Puppet::Pops::Evaluator::Runtime3ResourceSupport instead")
end

#findresource(type, title = nil) ⇒ Object


368
369
370
# File 'lib/puppet/parser/scope.rb', line 368

def findresource(type, title = nil)
  @compiler.catalog.resource(type, title)
end

#get_local_variable(name) ⇒ 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.


630
631
632
# File 'lib/puppet/parser/scope.rb', line 630

def get_local_variable(name)
  @ephemeral.last[name]
end

#handle_not_found(class_name, variable_name, position, reason = nil) ⇒ Object


634
635
636
637
638
639
640
641
642
643
644
645
646
# File 'lib/puppet/parser/scope.rb', line 634

def handle_not_found(class_name, variable_name, position, reason = nil)
  unless Puppet[:strict_variables]
    # Do not issue warning if strict variables are on, as an error will be raised by variable_not_found
    location = if position[:lineproc]
                 Puppet::Util::Errors.error_location_with_space(nil, position[:lineproc].call)
               else
                 Puppet::Util::Errors.error_location_with_space(position[:file], position[:line])
               end
    variable_not_found("#{class_name}::#{variable_name}", "#{reason}#{location}")
    return nil
  end
  variable_not_found("#{class_name}::#{variable_name}", reason)
end

#has_local_variable?(name) ⇒ 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.


625
626
627
# File 'lib/puppet/parser/scope.rb', line 625

def has_local_variable?(name)
  @ephemeral.last.include?(name)
end

#include?(name) ⇒ Boolean

Returns true if the variable of the given name has a non nil value. TODO: This has vague semantics - does the variable exist or not?

use ['name'] to get nil or value, and if nil check with exist?('name')
this include? is only useful because of checking against the boolean value false.

272
273
274
275
276
277
# File 'lib/puppet/parser/scope.rb', line 272

def include?(name)
  catch(:undefined_variable) {
    return ! self[name].nil?
  }
  false
end

#inherited_scopePuppet::Parser::Scope

The class scope of the inherited thing of this scope's resource.


560
561
562
563
564
565
566
# File 'lib/puppet/parser/scope.rb', line 560

def inherited_scope
  if resource && resource.type == TYPENAME_CLASS && !resource.resource_type.parent.nil?
    qualified_scope(resource.resource_type.parent)
  else
    nil
  end
end

#is_classscope?Boolean


585
586
587
# File 'lib/puppet/parser/scope.rb', line 585

def is_classscope?
  resource && resource.type == TYPENAME_CLASS
end

#is_default?(type, key, value) ⇒ Boolean

Check if the given value is a known default for the given type


457
458
459
460
461
462
463
464
# File 'lib/puppet/parser/scope.rb', line 457

def is_default?(type, key, value)
  defaults_for_type = @defaults[type]
  unless defaults_for_type.nil?
    default_param = defaults_for_type[key]
    return true if !default_param.nil? && value == default_param.value
  end
  !parent.nil? && parent.is_default?(type, key, value)
end

#is_nodescope?Boolean


589
590
591
# File 'lib/puppet/parser/scope.rb', line 589

def is_nodescope?
  resource && resource.type == TYPENAME_NODE
end

#is_topscope?Boolean


593
594
595
# File 'lib/puppet/parser/scope.rb', line 593

def is_topscope?
  equal?(@compiler.topscope)
end

#lookup_qualified_variable(fqn, options) ⇒ 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.


598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
# File 'lib/puppet/parser/scope.rb', line 598

def lookup_qualified_variable(fqn, options)
  table = @compiler.qualified_variables
  val = table[fqn]
  return val if !val.nil? || table.include?(fqn)

  # not found - search inherited scope for class
  leaf_index = fqn.rindex('::')
  unless leaf_index.nil?
    leaf_name = fqn[ (leaf_index+2)..-1 ]
    class_name = fqn[ 0, leaf_index ]
    begin
      qs = qualified_scope(class_name)
      unless qs.nil?
        return qs.get_local_variable(leaf_name) if qs.has_local_variable?(leaf_name)
        iscope = qs.inherited_scope
        return lookup_qualified_variable("#{iscope.source.name}::#{leaf_name}", options) unless iscope.nil?
      end
    rescue RuntimeError => e
      # because a failure to find the class, or inherited should be reported against given name
      return handle_not_found(class_name, leaf_name, options, e.message)
    end
  end
  # report with leading '::' by using empty class_name
  return handle_not_found('', fqn, options)
end

#lookupdefaults(type) ⇒ Object

Collect all of the defaults set at any higher scopes. This is a different type of lookup because it's additive – it collects all of the defaults, with defaults in closer scopes overriding those in later scopes.

The lookupdefaults searches in the the order:

* inherited
* contained (recursive)
* self

434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
# File 'lib/puppet/parser/scope.rb', line 434

def lookupdefaults(type)
  values = {}

  # first collect the values from the parents
  if parent
    parent.lookupdefaults(type).each { |var,value|
      values[var] = value
    }
  end

  # then override them with any current values
  # this should probably be done differently
  if @defaults.include?(type)
    @defaults[type].each { |var,value|
      values[var] = value
    }
  end

  values
end

#lookuptype(name) ⇒ Object

Look up a defined type.


467
468
469
470
471
# File 'lib/puppet/parser/scope.rb', line 467

def lookuptype(name)
  # This happens a lot, avoid making a call to make a call
  krt = environment.known_resource_types
  krt.find_definition(name) || krt.find_hostclass(name)
end

#lookupvar(name, options = EMPTY_HASH) ⇒ Object

Lookup a variable within this scope using the Puppet language's scoping rules. Variables can be qualified using just as in a manifest.


491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
# File 'lib/puppet/parser/scope.rb', line 491

def lookupvar(name, options = EMPTY_HASH)
  unless name.is_a? String
    raise Puppet::ParseError, _("Scope variable name %{name} is a %{klass}, not a string") % { name: name.inspect, klass: name.class }
  end

  # If name has '::' in it, it is resolved as a qualified variable
  unless (idx = name.index('::')).nil?
    # Always drop leading '::' if present as that is how the values are keyed.
    return lookup_qualified_variable(idx == 0 ? name[2..-1] : name, options)
  end

  # At this point, search is for a non qualified (simple) name
  table = @ephemeral.last
  val = table[name]
  return val unless val.nil? && !table.include?(name)

  next_scope = inherited_scope || enclosing_scope
  if next_scope
    next_scope.lookupvar(name, options)
  else
    variable_not_found(name)
  end
end

#merge_settings(env_name, set_in_this_scope = true) ⇒ Object

Merge all settings for the given env_name into this scope


712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
# File 'lib/puppet/parser/scope.rb', line 712

def merge_settings(env_name, set_in_this_scope=true)
  settings = Puppet.settings
  table = effective_symtable(false)
  global_table = compiler.qualified_variables
  all_local = {}
  settings.each_key do |name|
    next if :name == name
    key = name.to_s
    value = transform_setting(settings.value_sym(name, env_name))
    if set_in_this_scope
      table[key] = value
    end
    all_local[key] = value
    # also write the fqn into global table for direct lookup
    global_table["settings::#{key}"] = value
  end
  # set the 'all_local' - a hash of all settings
  global_table["settings::all_local"] = all_local
  nil
end

#new_ephemeral(local_scope = false) ⇒ Object

TODO: Who calls this?


919
920
921
922
923
924
925
# File 'lib/puppet/parser/scope.rb', line 919

def new_ephemeral(local_scope = false)
  if local_scope
    @ephemeral.push(LocalScope.new(@ephemeral.last))
  else
    @ephemeral.push(MatchScope.new(@ephemeral.last, nil))
  end
end

#new_match_scope(match_data) ⇒ Object

Nests a match data scope


997
998
999
# File 'lib/puppet/parser/scope.rb', line 997

def new_match_scope(match_data)
  @ephemeral.push(MatchScope.new(@ephemeral.last, match_data))
end

#newscope(options = {}) ⇒ Object

Create a new scope and set these options.


683
684
685
# File 'lib/puppet/parser/scope.rb', line 683

def newscope(options = {})
  compiler.newscope(self, options)
end

#parent_module_nameObject


687
688
689
690
# File 'lib/puppet/parser/scope.rb', line 687

def parent_module_name
  return nil unless @parent && @parent.source
  @parent.source.module_name
end

#pop_ephemerals(level) ⇒ Array

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.

Pop ephemeral scopes up to level and return them


903
904
905
# File 'lib/puppet/parser/scope.rb', line 903

def pop_ephemerals(level)
  @ephemeral.pop(@ephemeral.size - level)
end

#push_ephemerals(ephemeral_scopes) ⇒ 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.

Push ephemeral scopes onto the ephemeral scope stack


910
911
912
# File 'lib/puppet/parser/scope.rb', line 910

def push_ephemerals(ephemeral_scopes)
  ephemeral_scopes.each { |ephemeral_scope| @ephemeral.push(ephemeral_scope) } unless ephemeral_scopes.nil?
end

#resolve_type_and_titles(type, titles) ⇒ 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.

To be removed when enough time has passed after puppet 5.0.0

Raises:


1050
1051
1052
# File 'lib/puppet/parser/scope.rb', line 1050

def resolve_type_and_titles(type, titles)
  raise Puppet::DevError, _("Scope#resolve_type_and_title() is no longer supported, use Puppet::Pops::Evaluator::Runtime3ResourceSupport instead")
end

#set_facts(hash) ⇒ Object


810
811
812
# File 'lib/puppet/parser/scope.rb', line 810

def set_facts(hash)
  setvar('facts', deep_freeze(hash), :privileged => true)
end

#set_match_data(match_data) ⇒ Object

Sets match data in the most nested scope (which always is a MatchScope), it clobbers match data already set there


992
993
994
# File 'lib/puppet/parser/scope.rb', line 992

def set_match_data(match_data)
  @ephemeral.last.match_data = match_data
end

#set_server_facts(hash) ⇒ Object


814
815
816
# File 'lib/puppet/parser/scope.rb', line 814

def set_server_facts(hash)
  setvar('server_facts', deep_freeze(hash), :privileged => true)
end

#set_trusted(hash) ⇒ Object


806
807
808
# File 'lib/puppet/parser/scope.rb', line 806

def set_trusted(hash)
  setvar('trusted', deep_freeze(hash), :privileged => true)
end

#setvar(name, value, options = EMPTY_HASH) ⇒ Object

Set a variable in the current scope. This will override settings in scopes above, but will not allow variables in the current scope to be reassigned.

It's preferred that you use self[]= instead of this; only use this

when you need to set options.


761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
# File 'lib/puppet/parser/scope.rb', line 761

def setvar(name, value, options = EMPTY_HASH)
  if name =~ /^[0-9]+$/
    raise Puppet::ParseError.new(_("Cannot assign to a numeric match result variable '$%{name}'") % { name: name }) # unless options[:ephemeral]
  end
  unless name.is_a? String
    raise Puppet::ParseError, _("Scope variable name %{name} is a %{class_type}, not a string") % { name: name.inspect, class_type: name.class }
  end

  # Check for reserved variable names
  if (name == VARNAME_TRUSTED || name == VARNAME_FACTS) && !options[:privileged]
    raise Puppet::ParseError, _("Attempt to assign to a reserved variable name: '%{name}'") % { name: name }
  end

  # Check for server_facts reserved variable name
  if name == VARNAME_SERVER_FACTS && !options[:privileged]
    raise Puppet::ParseError, _("Attempt to assign to a reserved variable name: '%{name}'") % { name: name }
  end

  table = effective_symtable(options[:ephemeral])
  if table.bound?(name)
    error = Puppet::ParseError.new(_("Cannot reassign variable '$%{name}'") % { name: name })
    error.file = options[:file] if options[:file]
    error.line = options[:line] if options[:line]
    raise error
  end

  table[name] = value

  # Assign the qualified name in the environment
  # Note that Settings scope has a source set to Boolean true.
  #
  # Only meaningful to set a fqn globally if table to assign to is the top of the scope's ephemeral stack
  if @symtable.equal?(table)
    if is_topscope?
      # the scope name is '::'
      compiler.qualified_variables[name] = value
    elsif source.is_a?(Puppet::Resource::Type) && source.type == :hostclass
      # the name is the name of the class
      sourcename = source.name
      compiler.qualified_variables["#{sourcename}::#{name}"] = value
    end
  end
  value
end

#to_hash(recursive = true, include_undef = false) ⇒ Object

Returns a Hash containing all variables and their values, optionally (and by default) including the values defined in parent. Local values shadow parent values. Ephemeral scopes for match results ($0 - $n) are not included. Optionally include the variables that are explicitly set to `undef`.


667
668
669
670
671
672
673
674
675
676
677
678
679
680
# File 'lib/puppet/parser/scope.rb', line 667

def to_hash(recursive = true, include_undef = false)
  if recursive and has_enclosing_scope?
    target = enclosing_scope.to_hash(recursive)
    if !(inherited = inherited_scope).nil?
      target.merge!(inherited.to_hash(recursive))
    end
  else
    target = Hash.new
  end

  # add all local scopes
  @ephemeral.last.add_entries_to(target, include_undef)
  target
end

#to_sObject Also known as: inspect

Used mainly for logging


873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
# File 'lib/puppet/parser/scope.rb', line 873

def to_s
  # As this is used for logging, this should really not be done in this class at all...
  return "Scope(#{@resource})" unless @resource.nil?

  # For logging of function-scope - it is now showing the file and line.
  detail = Puppet::Pops::PuppetStack.top_of_stack
  return "Scope()" if detail.empty?

  # shorten the path if possible
  path = detail[0]
  env_path = nil
  env_path = environment.configuration.path_to_env unless (environment.nil? || environment.configuration.nil?)
  # check module paths first since they may be in the environment (i.e. they are longer)
  module_path = environment.full_modulepath.detect {|m_path| path.start_with?(m_path) }
  if module_path
    path = "<module>" + path[module_path.length..-1]
  elsif env_path && path && path.start_with?(env_path)
    path = "<env>" + path[env_path.length..-1]
  end
  # Make the output appear as "Scope(path, line)"
  "Scope(#{[path, detail[1]].join(', ')})" 
end

#transform_and_assert_classnames(names) ⇒ Array<String>

Transforms references to classes to the form suitable for lookup in the compiler.

Makes names passed in the names array absolute if they are relative.

Transforms Class[] and Resource[] type references to class name or raises an error if a Class[] is unspecific, if a Resource is not a 'class' resource, or if unspecific (no title).


1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
# File 'lib/puppet/parser/scope.rb', line 1067

def transform_and_assert_classnames(names)
  names.map do |name|
    case name
    when NilClass
      raise ArgumentError, _("Cannot use undef as a class name")
    when String
      raise ArgumentError, _("Cannot use empty string as a class name") if name.empty?
      name.sub(/^([^:]{1,2})/, '::\1')

    when Puppet::Resource
      assert_class_and_title(name.type, name.title)
      name.title.sub(/^([^:]{1,2})/, '::\1')

    when Puppet::Pops::Types::PClassType
      #TRANSLATORS "Class" and "Type" are Puppet keywords and should not be translated
      raise ArgumentError, _("Cannot use an unspecific Class[] Type") unless name.class_name
      name.class_name.sub(/^([^:]{1,2})/, '::\1')

    when Puppet::Pops::Types::PResourceType
      assert_class_and_title(name.type_name, name.title)
      name.title.sub(/^([^:]{1,2})/, '::\1')
    end.downcase
  end
end

#undef_as(x, v) ⇒ Object


473
474
475
476
477
478
479
# File 'lib/puppet/parser/scope.rb', line 473

def undef_as(x,v)
  if v.nil? or v == :undef
    x
  else
    v
  end
end

#variable_not_found(name, reason = nil) ⇒ Object


522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
# File 'lib/puppet/parser/scope.rb', line 522

def variable_not_found(name, reason=nil)
  # Built in variables and numeric variables always exist
  if BUILT_IN_VARS.include?(name) || name =~ Puppet::Pops::Patterns::NUMERIC_VAR_NAME
    return nil
  end
  begin
    throw(:undefined_variable, reason)
  rescue  UNCAUGHT_THROW_EXCEPTION
    case Puppet[:strict]
    when :off
      # do nothing
    when :warning
      Puppet.warn_once(UNDEFINED_VARIABLES_KIND, _("Variable: %{name}") % { name: name },
      _("Undefined variable '%{name}'; %{reason}") % { name: name, reason: reason } )
    when :error
      raise ArgumentError, _("Undefined variable '%{name}'; %{reason}") % { name: name, reason: reason }
    end
  end
  nil
end

#with_global_scope {|global_scope| ... } ⇒ 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.

Execute given block in global scope with no ephemerals present

Yield Parameters:

  • global_scope (Scope)

    the global and ephemeral less scope


933
934
935
# File 'lib/puppet/parser/scope.rb', line 933

def with_global_scope(&block)
  find_global_scope.without_ephemeral_scopes(&block)
end

#with_guarded_scopeObject

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.

Execute given block and ensure that ephemeral level is restored


981
982
983
984
985
986
987
988
# File 'lib/puppet/parser/scope.rb', line 981

def with_guarded_scope
  elevel = ephemeral_level
  begin
    yield
  ensure
    pop_ephemerals(elevel)
  end
end

#with_local_scope(scope_variables) ⇒ 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.

Execute given block with a ephemeral scope containing the given variables


939
940
941
942
943
944
945
946
947
948
# File 'lib/puppet/parser/scope.rb', line 939

def with_local_scope(scope_variables)
  local = LocalScope.new(@ephemeral.last)
  scope_variables.each_pair { |k, v| local[k] = v }
  @ephemeral.push(local)
  begin
    yield(self)
  ensure
    @ephemeral.pop
  end
end

#with_parameter_scope(callee_name, param_names) {|param_scope| ... } ⇒ 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.

Nests a parameter scope

Yield Parameters:


968
969
970
971
972
973
974
# File 'lib/puppet/parser/scope.rb', line 968

def with_parameter_scope(callee_name, param_names)
  param_scope = ParameterScope.new(@ephemeral.last, callee_name, param_names)
  with_guarded_scope do
    @ephemeral.push(param_scope)
    yield(param_scope)
  end
end

#without_ephemeral_scopesObject

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.

Execute given block with all ephemeral popped from the ephemeral stack


953
954
955
956
957
958
959
960
961
# File 'lib/puppet/parser/scope.rb', line 953

def without_ephemeral_scopes
  save_ephemeral = @ephemeral
  begin
    @ephemeral = [ @symtable ]
    yield(self)
  ensure
    @ephemeral = save_ephemeral
  end
end