Module: Puppet::Pal

Defined in:
lib/puppet/pal/pal_api.rb,
lib/puppet/pal/compiler.rb,
lib/puppet/pal/pal_impl.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

Defined Under Namespace

Classes: CatalogCompiler, Compiler, FunctionSignature, 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 



500
501
502
 
# File 'lib/puppet/pal/pal_impl.rb', line 500

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 



496
497
498
 
# File 'lib/puppet/pal/pal_impl.rb', line 496

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 



477
478
479
480
481
482
483
484
485
486
 
# File 'lib/puppet/pal/pal_impl.rb', line 477

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



113
114
115
116
117
 
# File 'lib/puppet/pal/pal_impl.rb', line 113

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



100
101
102
103
104
105
106
 
# File 'lib/puppet/pal/pal_impl.rb', line 100

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



246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
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
 
# File 'lib/puppet/pal/pal_impl.rb', line 246

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



199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
 
# File 'lib/puppet/pal/pal_impl.rb', line 199

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: nil, variables: nil, &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: nil) —

    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: nil) —

    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



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/puppet/pal/pal_impl.rb', line 149

def self.with_catalog_compiler(
  configured_by_env: false,
    manifest_file:     nil,
    code_string:       nil,
    facts:             nil,
    variables:         nil,
    &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]
  else
    # 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.
    #
    if manifest_file.nil? && code_string.nil?
      code_string = 'undef'
    end
  end

  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_file, facts, variables, :catalog, &block)
end

.with_script_compiler(configured_by_env: false, manifest_file: nil, code_string: nil, facts: nil, variables: nil, &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: nil) —

    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: nil) —

    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



56
57
58
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
 
# File 'lib/puppet/pal/pal_impl.rb', line 56

def self.with_script_compiler(
    configured_by_env: false,
    manifest_file:     nil,
    code_string:       nil,
    facts:             nil,
    variables:         nil,
    &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]
  else
    # 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.
    #
    if manifest_file.nil? && code_string.nil?
      code_string = 'undef'
    end
  end

  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_file, facts, variables, :script, &block)
end