Class: Puppet::Parser::Scope

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Resource::TypeCollectionHelper, Util::Errors, Util::MethodHelper
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

AST = 
Puppet::Parser::AST
BUILT_IN_VARS =

Variables that always exist with nil value even if not set

['module_name'.freeze, 'caller_module_name'.freeze].freeze
UNDEFINED_VARIABLES_KIND = 
'undefined_variables'.freeze
RESERVED_VARIABLE_NAMES = 
['trusted', 'facts'].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Util::Errors

#adderrorcontext, #devfail, #error_context, #exceptwrap, #fail

Methods included from Resource::TypeCollectionHelper

#known_resource_types

Methods included from Util::MethodHelper

#requiredopts, #set_options, #symbolize_options

Constructor Details

#initialize(compiler, options = {}) ⇒ Scope

Initialize our new scope. Defaults to having no parent.

Raises:



370
371
372
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
402
403
404
 
# File 'lib/puppet/parser/scope.rb', line 370

def initialize(compiler, options = {})
  if compiler.is_a? Puppet::Parser::Compiler
    self.compiler = compiler
  else
    raise Puppet::DevError, "you must pass a compiler instance to a new scope object"
  end

  if n = options.delete(:namespace)
    @namespaces = [n.freeze].freeze
  else
    @namespaces = ["".freeze].freeze
  end

  raise Puppet::DevError, "compiler passed in options" if options.include? :compiler
  set_options(options)

  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 



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

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!"
  end
end

Instance Attribute Details

#compiler ⇒ Object 



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

def compiler
  @compiler
end

#defaults ⇒ Object (readonly)

Hash of hashes of default values per type name



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

def defaults
  @defaults
end

#namespaces ⇒ Object (readonly) 



35
36
37
 
# File 'lib/puppet/parser/scope.rb', line 35

def namespaces
  @namespaces
end

#parent ⇒ Object 



34
35
36
 
# File 'lib/puppet/parser/scope.rb', line 34

def parent
  @parent
end

#resource ⇒ Object 



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

def resource
  @resource
end

#source ⇒ Object 



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

def source
  @source
end

Class Method Details

.number?(value) ⇒ Boolean

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

Returns:

  • (Boolean) 


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

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.

Returns:

  • (Boolean) 


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

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

Instance Method Details

#[](varname, options = {}) ⇒ 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.

Parameters:

  • varname (String) —

    the name of the variable (may be a qualified name using ‘(ns’::‘)*varname`

  • options (Hash) (defaults to: {}) —

    Additional options, not part of api.

Returns:

  • (Object) —

    the value assigned to the given varname

See Also:



542
543
544
 
# File 'lib/puppet/parser/scope.rb', line 542

def [](varname, options={})
  lookupvar(varname, options)
end

#[]=(varname, value, options = {}) ⇒ 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.

Parameters:

  • varname (String) —

    The variable name to which the value is assigned. Must not contain ‘::`

  • value (String) —

    The value to assign to the given variable name.

  • options (Hash) (defaults to: {}) —

    Additional options, not part of api.



818
819
820
 
# File 'lib/puppet/parser/scope.rb', line 818

def []=(varname, value, options = {})
  setvar(varname, value, options = {})
end

#bound?(name) ⇒ Boolean

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

Returns:

  • (Boolean) 


306
307
308
309
 
# File 'lib/puppet/parser/scope.rb', line 306

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.

Returns:

  • (Object) —

    the result of the called function

Raises:

  • ArgumentError if the function does not exist



1056
1057
1058
 
# File 'lib/puppet/parser/scope.rb', line 1056

def call_function(func_name, args, &block)
  Puppet::Pops::Parser::EvaluatingParser.new.evaluator.external_call_function(func_name, args, self, &block)
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.



420
421
422
423
424
 
# File 'lib/puppet/parser/scope.rb', line 420

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.



408
409
410
411
412
413
414
 
# File 'lib/puppet/parser/scope.rb', line 408

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.



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

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.name} }; cannot redefine", param.line, param.file)
    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).

Parameters:

  • use_ephemeral (Boolean) —

    whether the top most ephemeral (of any kind) should be used or not



795
796
797
798
799
800
801
802
803
804
805
 
# File 'lib/puppet/parser/scope.rb', line 795

def effective_symtable(use_ephemeral)
  s = @ephemeral.last
  if use_ephemeral
    return s || @symtable
  else
    while s && !s.is_local_scope?()
      s = s.parent
    end
    s || @symtable
  end
end

#enclosing_scope ⇒ Puppet::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

Returns:



565
566
567
568
569
570
571
572
573
574
575
 
# File 'lib/puppet/parser/scope.rb', line 565

def enclosing_scope
  if has_enclosing_scope?
    if parent.is_topscope? or parent.is_nodescope?
      parent
    else
      parent.enclosing_scope
    end
  else
    nil
  end
end

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



947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
 
# File 'lib/puppet/parser/scope.rb', line 947

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 #{match.class}") unless match.is_a?(MatchData)
    # Create a match ephemeral and set values from match data
    new_match_scope(match)
  end
end

#ephemeral_level ⇒ Object 



876
877
878
 
# File 'lib/puppet/parser/scope.rb', line 876

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)

Returns:

  • (Boolean) —

    if variable exists or not



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

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 



970
971
972
 
# File 'lib/puppet/parser/scope.rb', line 970

def find_builtin_resource_type(type)
  Puppet::Type.type(type.to_s.downcase.to_sym)
end

#find_defined_resource_type(type) ⇒ Object 



974
975
976
 
# File 'lib/puppet/parser/scope.rb', line 974

def find_defined_resource_type(type)
  known_resource_types.find_definition(type.to_s.downcase)
end

#find_definition(name) ⇒ Object 



346
347
348
 
# File 'lib/puppet/parser/scope.rb', line 346

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

#find_global_scope ⇒ Object 



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

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 



342
343
344
 
# File 'lib/puppet/parser/scope.rb', line 342

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

#find_resource_type(type) ⇒ Object 



964
965
966
967
968
 
# File 'lib/puppet/parser/scope.rb', line 964

def find_resource_type(type)
  # It still works fine without the type == 'class' short-cut, but it is a lot slower.
  return nil if ["class", "node"].include? type.to_s.downcase
  find_builtin_resource_type(type) || find_defined_resource_type(type)
end

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



609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
 
# File 'lib/puppet/parser/scope.rb', line 609

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]
                 " at #{position[:lineproc].call}"
               elsif position[:file] && position[:line]
                 " at #{position[:file]}:#{position[:line]}"
               else
                 ""
               end
    variable_not_found("#{class_name}::#{variable_name}", "#{reason}#{location}")
    return nil
  end
  variable_not_found("#{class_name}::#{variable_name}", reason)
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.

Returns:

  • (Boolean) 


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

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

#inherited_scope ⇒ Puppet::Parser::Scope

The scope of the inherited thing of this scope’s resource. This could either be a node that was inherited or the class.

Returns:



550
551
552
553
554
555
556
 
# File 'lib/puppet/parser/scope.rb', line 550

def inherited_scope
  if has_inherited_class?
    qualified_scope(resource.resource_type.parent)
  else
    nil
  end
end

#is_classscope? ⇒ Boolean

Returns:

  • (Boolean) 


577
578
579
 
# File 'lib/puppet/parser/scope.rb', line 577

def is_classscope?
  resource and resource.type == "Class"
end

#is_nodescope? ⇒ Boolean

Returns:

  • (Boolean) 


581
582
583
 
# File 'lib/puppet/parser/scope.rb', line 581

def is_nodescope?
  resource and resource.type == "Node"
end

#is_topscope? ⇒ Boolean

Returns:

  • (Boolean) 


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

def is_topscope?
  compiler and self == compiler.topscope
end

#lookup_as_local_name?(class_name, variable_name) ⇒ Boolean

Handles the special case of looking up fully qualified variable in not yet evaluated top scope This is ok if the lookup request originated in topscope (this happens when evaluating bindings; using the top scope to provide the values for facts.

Parameters:

  • class_name (String) —

    the classname part of a variable name, may be special “”

  • variable_name (String) —

    the variable name without the absolute leading ‘::’

Returns:

  • (Boolean) —

    true if the given variable name should be looked up directly in this scope



632
633
634
635
636
637
638
 
# File 'lib/puppet/parser/scope.rb', line 632

def lookup_as_local_name?(class_name, variable_name)
  # not a local if name has more than one segment
  return nil if variable_name =~ /::/
  # partial only if the class for "" cannot be found
  return nil unless class_name == "" && klass = find_hostclass(class_name) && class_scope(klass).nil?
  is_topscope?
end

#lookup_qualified_variable(class_name, variable_name, position) ⇒ Object 



589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
 
# File 'lib/puppet/parser/scope.rb', line 589

def lookup_qualified_variable(class_name, variable_name, position)
  begin
    if lookup_as_local_name?(class_name, variable_name)
      if is_topscope?
        # This is the case where $::x is looked up from within the topscope itself, or from a local scope
        # parented at the top scope. In this case, the lookup must ignore local and ephemeral scopes.
        #
        handle_not_found(class_name, variable_name, position) unless @symtable.include?(variable_name)
        @symtable[variable_name]
      else
        self[variable_name]
      end
    else
      qualified_scope(class_name).lookupvar(variable_name, position)
    end
  rescue RuntimeError => e
    handle_not_found(class_name, variable_name, position, e.message)
  end
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



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

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.



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

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

#lookupvar(name, options = {}) ⇒ Object

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

Parameters:

  • name (String) —

    the variable name to lookup

Returns:

  • Object the value of the variable, or nil if it’s not found



481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
 
# File 'lib/puppet/parser/scope.rb', line 481

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

  table = @ephemeral.last

  if name =~ /^(.*)::(.+)$/
    class_name = $1
    variable_name = $2
    lookup_qualified_variable(class_name, variable_name, options)

  # TODO: optimize with an assoc instead, this searches through scopes twice for a hit
  elsif table.include?(name)
    table[name]
  else
    next_scope = inherited_scope || enclosing_scope
    if next_scope
      next_scope.lookupvar(name, options)
    else
      variable_not_found(name)
    end
  end
end

#new_ephemeral(local_scope = false) ⇒ Object

TODO: Who calls this?



881
882
883
884
885
886
887
 
# File 'lib/puppet/parser/scope.rb', line 881

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



943
944
945
 
# File 'lib/puppet/parser/scope.rb', line 943

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.



681
682
683
 
# File 'lib/puppet/parser/scope.rb', line 681

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

#parent_module_name ⇒ Object 



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

def parent_module_name
  return nil unless @parent
  return nil unless @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

Parameters:

  • level (Fixnum) —

    a positive integer

Returns:

  • (Array) —

    the removed ephemeral scopes



865
866
867
 
# File 'lib/puppet/parser/scope.rb', line 865

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

Parameters:

  • ephemeral_scopes (Array) 


872
873
874
 
# File 'lib/puppet/parser/scope.rb', line 872

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

Raises:

  • (ArgumentError) 


993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
 
# File 'lib/puppet/parser/scope.rb', line 993

def resolve_type_and_titles(type, titles)
  raise ArgumentError, "titles must be an array" unless titles.is_a?(Array)

  case type.downcase
  when "class"
    # resolve the titles
    titles = titles.collect do |a_title|
      hostclass = find_hostclass(a_title)
      hostclass ?  hostclass.name : a_title
    end
  when "node"
    # no-op
  else
    # resolve the type
    resource_type = find_resource_type(type)
    type = resource_type.name if resource_type
  end

  return [type, titles]
end

#set_facts(hash) ⇒ Object 



758
759
760
 
# File 'lib/puppet/parser/scope.rb', line 758

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



938
939
940
 
# File 'lib/puppet/parser/scope.rb', line 938

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

#set_server_facts(hash) ⇒ Object 



762
763
764
 
# File 'lib/puppet/parser/scope.rb', line 762

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

#set_trusted(hash) ⇒ Object 



754
755
756
 
# File 'lib/puppet/parser/scope.rb', line 754

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

#setvar(name, value, options = {}) ⇒ 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.



715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
 
# File 'lib/puppet/parser/scope.rb', line 715

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

  # Check for reserved variable names
  if !options[:privileged] && RESERVED_VARIABLE_NAMES.include?(name)
    raise Puppet::ParseError, "Attempt to assign to a reserved variable name: '#{name}'"
  end

  # Check for server_facts reserved variable name if the trusted_sever_facts setting is true
  if Puppet[:trusted_server_facts] && name == 'server_facts' && !options[:privileged]
    raise Puppet::ParseError, "Attempt to assign to a reserved variable name: '#{name}'"
  end

  table = effective_symtable(options[:ephemeral])
  if table.bound?(name)
    if options[:append]
      error = Puppet::ParseError.new("Cannot append, variable '$#{name}' is defined in this scope")
    else
      error = Puppet::ParseError.new("Cannot reassign variable '$#{name}'")
    end
    error.file = options[:file] if options[:file]
    error.line = options[:line] if options[:line]
    raise error
  end

  if options[:append]
    # produced result (value) is the resulting appended value, note: the table[]= does not return the value
    table[name] = (value = append_value(undef_as('', self[name]), value))
  else
    table[name] = value
  end
  value
end

#to_hash(recursive = true) ⇒ 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.



661
662
663
664
665
666
667
668
669
670
671
672
673
674
 
# File 'lib/puppet/parser/scope.rb', line 661

def to_hash(recursive = true)
  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)
  target
end

#to_s ⇒ Object Also known as: inspect

Used mainly for logging



841
842
843
 
# File 'lib/puppet/parser/scope.rb', line 841

def to_s
  "Scope(#{@resource})"
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).

Parameters:

  • names (Array<String>) —

    names to (optionally) make absolute

Returns:

  • (Array<String>) —

    names after transformation



1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
 
# File 'lib/puppet/parser/scope.rb', line 1027

def transform_and_assert_classnames(names)
  names.map do |name|
    case name
    when String
      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::PHostClassType
      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
  end
end

#undef_as(x, v) ⇒ Object 



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

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

#unset_ephemeral_var(level = :all) ⇒ 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.

Deprecated.

use #pop_epehemeral

Pop ephemeral scopes up to level and return them



851
852
853
854
855
856
857
858
 
# File 'lib/puppet/parser/scope.rb', line 851

def unset_ephemeral_var(level=:all)
  Puppet.deprecation_warning('Method Parser::Scope#unset_ephemeral_var() is deprecated')
  if level == :all
    @ephemeral = [ MatchScope.new(@symtable, nil)]
  else
    @ephemeral.pop(@ephemeral.size - level)
  end
end

#variable_not_found(name, reason = nil) ⇒ Object 



508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
 
# File 'lib/puppet/parser/scope.rb', line 508

def variable_not_found(name, reason=nil)
  # Built in variables always exist
  if BUILT_IN_VARS.include?(name)
    return nil
  end
  if Puppet[:strict_variables]
    throw(:undefined_variable, reason)
  else
    # Always warn, unfortunately without location (unless given in "reason") since
    # a location is in most cases not given to scope (operator [], and lookupvar), and
    # would be too expensive to always give.
    # The ideal solution would be to always throw :undefined_variable, but that has to
    # wait until a major release. It would then force all callers of scope to deal with
    # the case of :undefined_variable. (Should check with include? first or catch the throw).
    # Use deprecation warning to enable turning off these warnings, and to ensure each variable
    # is only logged once.
    unless name =~ Puppet::Pops::Patterns::NUMERIC_VAR_NAME
      Puppet.warn_once(UNDEFINED_VARIABLES_KIND, "Variable: #{name}",
        "Undefined variable '#{name}'; #{reason}" )
    end
    nil
  end
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

Returns:

  • (Object) —

    the return of the block



895
896
897
 
# File 'lib/puppet/parser/scope.rb', line 895

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

#with_guarded_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 and ensure that ephemeral level is restored

Returns:

  • (Object) —

    the return of the block



927
928
929
930
931
932
933
934
 
# File 'lib/puppet/parser/scope.rb', line 927

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

#with_parameter_scope(param_names) ⇒ 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



914
915
916
917
918
919
920
 
# File 'lib/puppet/parser/scope.rb', line 914

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

#without_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.

Execute given block with all ephemeral popped from the ephemeral stack



902
903
904
905
906
907
908
909
910
 
# File 'lib/puppet/parser/scope.rb', line 902

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