Module: Puppet::Pal

Defined in:
lib/puppet/pal/pal_impl.rb,
lib/puppet/pal/pal_api.rb,
lib/puppet/pal/compiler.rb,
lib/puppet/pal/plan_signature.rb,
lib/puppet/pal/task_signature.rb,
lib/puppet/pal/script_compiler.rb,
lib/puppet/pal/catalog_compiler.rb,
lib/puppet/pal/function_signature.rb,
lib/puppet/pal/json_catalog_encoder.rb

Defined Under Namespace

Classes: CatalogCompiler, Compiler, FunctionSignature, JsonCatalogEncoder, PlanSignature, ScriptCompiler, TaskSignature

Constant Summary collapse

T_STRING = 
Puppet::Pops::Types::PStringType::NON_EMPTY
T_STRING_ARRAY = 
Puppet::Pops::Types::TypeFactory.array_of(T_STRING)
T_ANY_ARRAY = 
Puppet::Pops::Types::TypeFactory.array_of_any
T_BOOLEAN = 
Puppet::Pops::Types::PBooleanType::DEFAULT
T_GENERIC_TASK_HASH = 
Puppet::Pops::Types::TypeFactory.hash_kv(
  Puppet::Pops::Types::TypeFactory.pattern(/\A[a-z][a-z0-9_]*\z/), Puppet::Pops::Types::TypeFactory.data
)

Class Method Summary collapse

Class Method Details

.assert_non_empty_string(s, what, allow_nil = false) ⇒ Object 



562
563
564
 
# File 'lib/puppet/pal/pal_impl.rb', line 562

def self.assert_non_empty_string(s, what, allow_nil = false)
  assert_type(T_STRING, s, what, allow_nil)
end

.assert_type(type, value, what, allow_nil = false) ⇒ Object 



558
559
560
 
# File 'lib/puppet/pal/pal_impl.rb', line 558

def self.assert_type(type, value, what, allow_nil = false)
  Puppet::Pops::Types::TypeAsserter.assert_instance_of(nil, type, value, allow_nil) { _('Puppet Pal: %{what}') % { what: what } }
end

.create_internal_compiler(compiler_class_reference, node) ⇒ Object 



538
539
540
541
542
543
544
545
546
547
 
# File 'lib/puppet/pal/pal_impl.rb', line 538

def self.create_internal_compiler(compiler_class_reference, node)
  case compiler_class_reference
  when :script
    Puppet::Parser::ScriptCompiler.new(node.environment, node.name)
  when :catalog
    Puppet::Parser::CatalogCompiler.new(node)
  else
    raise ArgumentError, "Internal Error: Invalid compiler type requested."
  end
end

.evaluate_script_manifest(manifest_file) ⇒ Object

Deprecated.

Use #with_script_compiler and then evaluate_file on the given compiler - to be removed in 1.0 version

Evaluates a Puppet Language script (.pp) file.

Parameters:

  • manifest_file (String) —

    a file with Puppet Language source code

Returns:

  • (Object) —

    what the Puppet Language manifest_file contents evaluates to



128
129
130
131
132
 
# File 'lib/puppet/pal/pal_impl.rb', line 128

def self.evaluate_script_manifest(manifest_file)
  with_script_compiler do |compiler|
    compiler.evaluate_file(manifest_file)
  end
end

.evaluate_script_string(code_string) ⇒ Object

Deprecated.

Use #with_script_compiler and then evaluate_string on the given compiler - to be removed in 1.0 version

Evaluates a Puppet Language script string.

Parameters:

  • code_string (String) —

    a snippet of Puppet Language source code

Returns:

  • (Object) —

    what the Puppet Language code_string evaluates to



115
116
117
118
119
120
121
 
# File 'lib/puppet/pal/pal_impl.rb', line 115

def self.evaluate_script_string(code_string)
  # prevent the default loading of Puppet[:manifest] which is the environment's manifest-dir by default settings
  # by setting code_string to 'undef'
  with_script_compiler do |compiler|
    compiler.evaluate_string(code_string)
  end
end

.in_environment(env_name, modulepath: nil, pre_modulepath: [], post_modulepath: [], settings_hash: {}, env_dir: nil, envpath: nil, facts: nil, variables: {}) {|context,| ... } ⇒ Object

Defines the context in which to perform puppet operations (evaluation, etc) The code to evaluate in this context is given in a block.

The name of an environment (env_name) is always given. The location of that environment on disk is then either constructed by:

  • searching a given envpath where name is a child of a directory on that path, or

  • it is the directory given in env_dir (which must exist).

The env_dir and envpath options are mutually exclusive.

Parameters:

  • env_name (String) —

    the name of an existing environment

  • modulepath (Array<String>) (defaults to: nil) —

    an array of directory paths containing Puppet modules, overrides the modulepath of an existing env. Defaults to ‘env_dir/modules` if `env_dir` is given,

  • pre_modulepath (Array<String>) (defaults to: []) —

    like modulepath, but is prepended to the modulepath

  • post_modulepath (Array<String>) (defaults to: []) —

    like modulepath, but is appended to the modulepath

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

    a hash of settings - currently not used for anything, defaults to empty hash

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

    a reference to a directory being the named environment (mutually exclusive with ‘envpath`)

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

    a path of directories in which there are environments to search for ‘env_name` (mutually exclusive with `env_dir`). Should be a single directory, or several directories separated with platform specific `File::PATH_SEPARATOR` character.

  • facts (Hash) (defaults to: nil) —

    optional map of fact name to fact value - if not given will initialize the facts (which is a slow operation)

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

    optional map of fully qualified variable name to value

Yield Parameters:

  • context, (Puppet::Pal) —

    a context that responds to Puppet::Pal methods

Returns:

  • (Object) —

    returns what the given block returns



277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
 
# File 'lib/puppet/pal/pal_impl.rb', line 277

def self.in_environment(env_name,
                        modulepath: nil,
                        pre_modulepath: [],
                        post_modulepath: [],
                        settings_hash: {},
                        env_dir:       nil,
                        envpath:       nil,
                        facts:         nil,
                        variables:     {},
                        &block)
  # TRANSLATORS terms in the assertions below are names of terms in code
  assert_non_empty_string(env_name, 'env_name')
  assert_optionally_empty_array(modulepath, 'modulepath', true)
  assert_optionally_empty_array(pre_modulepath, 'pre_modulepath', false)
  assert_optionally_empty_array(post_modulepath, 'post_modulepath', false)
  assert_mutually_exclusive(env_dir, envpath, 'env_dir', 'envpath')

  unless block_given?
    raise ArgumentError, _("A block must be given to 'in_environment'") # TRANSLATORS 'in_environment' is a name, do not translate
  end

  if env_dir
    unless Puppet::FileSystem.exist?(env_dir)
      raise ArgumentError, _("The environment directory '%{env_dir}' does not exist") % { env_dir: env_dir }
    end

    # a nil modulepath for env_dir means it should use its ./modules directory
    mid_modulepath = modulepath.nil? ? [Puppet::FileSystem.expand_path(File.join(env_dir, 'modules'))] : modulepath

    env = Puppet::Node::Environment.create(env_name, pre_modulepath + mid_modulepath + post_modulepath)
    environments = Puppet::Environments::StaticDirectory.new(env_name, env_dir, env) # The env being used is the only one...
  else
    assert_non_empty_string(envpath, 'envpath')

    # The environment is resolved against the envpath. This is setup without a basemodulepath
    # The modulepath defaults to the 'modulepath' in the found env when "Directories" is used
    #
    if envpath.is_a?(String) && envpath.include?(File::PATH_SEPARATOR)
      # potentially more than one directory to search
      env_loaders = Puppet::Environments::Directories.from_path(envpath, [])
      environments = Puppet::Environments::Combined.new(*env_loaders)
    else
      environments = Puppet::Environments::Directories.new(envpath, [])
    end
    env = environments.get(env_name)
    if env.nil?
      raise ArgumentError, _("No directory found for the environment '%{env_name}' on the path '%{envpath}'") % { env_name: env_name, envpath: envpath }
    end

    # A given modulepath should override the default
    mid_modulepath = modulepath.nil? ? env.modulepath : modulepath
    env_path = env.configuration.path_to_env
    env = env.override_with(:modulepath => pre_modulepath + mid_modulepath + post_modulepath)
    # must configure this in case logic looks up the env by name again (otherwise the looked up env does
    # not have the same effective modulepath).
    environments = Puppet::Environments::StaticDirectory.new(env_name, env_path, env) # The env being used is the only one...
  end
  in_environment_context(environments, env, facts, variables, &block)
end

.in_tmp_environment(env_name, modulepath: [], settings_hash: {}, facts: nil, variables: {}) {|context,| ... } ⇒ Object

Defines the context in which to perform puppet operations (evaluation, etc) The code to evaluate in this context is given in a block.

Parameters:

  • env_name (String) —

    a name to use for the temporary environment - this only shows up in errors

  • modulepath (Array<String>) (defaults to: []) —

    an array of directory paths containing Puppet modules, may be empty, defaults to empty array

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

    a hash of settings - currently not used for anything, defaults to empty hash

  • facts (Hash) (defaults to: nil) —

    optional map of fact name to fact value - if not given will initialize the facts (which is a slow operation)

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

    optional map of fully qualified variable name to value

Yield Parameters:

  • context, (Puppet::Pal) —

    a context that responds to Puppet::Pal methods

Returns:

  • (Object) —

    returns what the given block returns



230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/puppet/pal/pal_impl.rb', line 230

def self.in_tmp_environment(env_name,
                            modulepath:    [],
                            settings_hash: {},
                            facts:         nil,
                            variables:     {},
                            &block)
  assert_non_empty_string(env_name, _("temporary environment name"))
  # TRANSLATORS: do not translate variable name string in these assertions
  assert_optionally_empty_array(modulepath, 'modulepath')

  unless block_given?
    raise ArgumentError, _("A block must be given to 'in_tmp_environment'") # TRANSLATORS 'in_tmp_environment' is a name, do not translate
  end

  env = Puppet::Node::Environment.create(env_name, modulepath)

  in_environment_context(
    Puppet::Environments::Static.new(env), # The tmp env is the only known env
    env, facts, variables, &block
  )
end

.with_catalog_compiler(configured_by_env: false, manifest_file: nil, code_string: nil, facts: {}, variables: {}, target_variables: {}, &block) {|compiler,| ... } ⇒ Object

Defines a context in which multiple operations in an env with a catalog producing compiler can be performed in a given block. The calls that takes place to PAL inside of the given block are all with the same instance of the compiler. The parameter ‘configured_by_env` makes it possible to either use the configuration in the environment, or specify `manifest_file` or `code_string` manually. If neither is given, an empty `code_string` is used.

Examples:

define a catalog compiler without any initial logic

pal.with_catalog_compiler do | compiler |
  # do things with compiler
end

define a catalog compiler with a code_string containing initial logic

pal.with_catalog_compiler(code_string: '$myglobal_var = 42')  do | compiler |
  # do things with compiler
end

Parameters:

  • configured_by_env (Boolean) (defaults to: false) —

    when true the environment’s settings are used, otherwise the given ‘manifest_file` or `code_string`

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

    a Puppet Language file to load and evaluate before calling the given block, mutually exclusive with ‘code_string`

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

    a Puppet Language source string to load and evaluate before calling the given block, mutually exclusive with ‘manifest_file`

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

    optional map of fact name to fact value - if not given will initialize the facts (which is a slow operation) If given at the environment level, the facts given here are merged with higher priority.

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

    optional map of fully qualified variable name to value. If given at the environment level, the variables given here are merged with higher priority.

  • block (Proc) —

    the block performing operations on compiler

Yield Parameters:

Returns:

  • (Object) —

    what the block returns



164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/puppet/pal/pal_impl.rb', line 164

def self.with_catalog_compiler(
  configured_by_env: false,
  manifest_file:     nil,
  code_string:       nil,
  facts:             {},
  variables:         {},
  target_variables:  {},
  &block
)
  # TRANSLATORS: do not translate variable name strings in these assertions
  assert_mutually_exclusive(manifest_file, code_string, 'manifest_file', 'code_string')
  assert_non_empty_string(manifest_file, 'manifest_file', true)
  assert_non_empty_string(code_string, 'code_string', true)
  assert_type(T_BOOLEAN, configured_by_env, "configured_by_env", false)

  if configured_by_env
    unless manifest_file.nil? && code_string.nil?
      # TRANSLATORS: do not translate the variable names in this error message
      raise ArgumentError, _("manifest_file or code_string cannot be given when configured_by_env is true")
    end

    # Use the manifest setting
    manifest_file = Puppet[:manifest]
  elsif manifest_file.nil? && code_string.nil?
    # An "undef" code_string is the only way to override Puppet[:manifest] & Puppet[:code] settings since an
    # empty string is taken as Puppet[:code] not being set.
    #
    code_string = 'undef'
  end

  # We need to make sure to set these back when we're done
  previous_tasks_value = Puppet[:tasks]
  previous_code_value = Puppet[:code]

  Puppet[:tasks] = false
  # After the assertions, if code_string is non nil - it has the highest precedence
  Puppet[:code] = code_string unless code_string.nil?

  # If manifest_file is nil, the #main method will use the env configured manifest
  # to do things in the block while a Script Compiler is in effect
  main(
    manifest: manifest_file,
    facts: facts,
    variables: variables,
    target_variables: target_variables,
    internal_compiler_class: :catalog,
    set_local_facts: false,
    &block
  )
ensure
  # Clean up after ourselves
  Puppet[:tasks] = previous_tasks_value
  Puppet[:code] = previous_code_value
end

.with_script_compiler(configured_by_env: false, manifest_file: nil, code_string: nil, facts: {}, variables: {}, set_local_facts: true, &block) {|compiler,| ... } ⇒ Object

Defines a context in which multiple operations in an env with a script compiler can be performed in a given block. The calls that takes place to PAL inside of the given block are all with the same instance of the compiler. The parameter ‘configured_by_env` makes it possible to either use the configuration in the environment, or specify `manifest_file` or `code_string` manually. If neither is given, an empty `code_string` is used.

Examples:

define a script compiler without any initial logic

pal.with_script_compiler do | compiler |
  # do things with compiler
end

define a script compiler with a code_string containing initial logic

pal.with_script_compiler(code_string: '$myglobal_var = 42')  do | compiler |
  # do things with compiler
end

Parameters:

  • configured_by_env (Boolean) (defaults to: false) —

    when true the environment’s settings are used, otherwise the given ‘manifest_file` or `code_string`

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

    a Puppet Language file to load and evaluate before calling the given block, mutually exclusive with ‘code_string`

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

    a Puppet Language source string to load and evaluate before calling the given block, mutually exclusive with ‘manifest_file`

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

    optional map of fact name to fact value - if not given will initialize the facts (which is a slow operation) If given at the environment level, the facts given here are merged with higher priority.

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

    optional map of fully qualified variable name to value. If given at the environment level, the variables given here are merged with higher priority.

  • set_local_facts (Boolean) (defaults to: true) —

    when true, the $facts, $server_facts, and $trusted variables are set for the scope.

  • block (Proc) —

    the block performing operations on compiler

Yield Parameters:

Returns:

  • (Object) —

    what the block returns



59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/puppet/pal/pal_impl.rb', line 59

def self.with_script_compiler(
  configured_by_env: false,
  manifest_file:     nil,
  code_string:       nil,
  facts:             {},
  variables:         {},
  set_local_facts:   true,
  &block
)
  # TRANSLATORS: do not translate variable name strings in these assertions
  assert_mutually_exclusive(manifest_file, code_string, 'manifest_file', 'code_string')
  assert_non_empty_string(manifest_file, 'manifest_file', true)
  assert_non_empty_string(code_string, 'code_string', true)
  assert_type(T_BOOLEAN, configured_by_env, "configured_by_env", false)

  if configured_by_env
    unless manifest_file.nil? && code_string.nil?
      # TRANSLATORS: do not translate the variable names in this error message
      raise ArgumentError, _("manifest_file or code_string cannot be given when configured_by_env is true")
    end

    # Use the manifest setting
    manifest_file = Puppet[:manifest]
  elsif manifest_file.nil? && code_string.nil?
    # An "undef" code_string is the only way to override Puppet[:manifest] & Puppet[:code] settings since an
    # empty string is taken as Puppet[:code] not being set.
    #
    code_string = 'undef'
  end

  previous_tasks_value = Puppet[:tasks]
  previous_code_value = Puppet[:code]
  Puppet[:tasks] = true
  # After the assertions, if code_string is non nil - it has the highest precedence
  Puppet[:code] = code_string unless code_string.nil?

  # If manifest_file is nil, the #main method will use the env configured manifest
  # to do things in the block while a Script Compiler is in effect
  main(
    manifest: manifest_file,
    facts: facts,
    variables: variables,
    internal_compiler_class: :script,
    set_local_facts: set_local_facts,
    &block
  )
ensure
  Puppet[:tasks] = previous_tasks_value
  Puppet[:code] = previous_code_value
end