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


508
509
510
# File 'lib/puppet/pal/pal_impl.rb', line 508

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


504
505
506
# File 'lib/puppet/pal/pal_impl.rb', line 504

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


485
486
487
488
489
490
491
492
493
494
# File 'lib/puppet/pal/pal_impl.rb', line 485

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.


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.


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.

Yield Parameters:

  • context, (Puppet::Pal)

    a context that responds to Puppet::Pal methods


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
305
306
307
308
309
310
311
312
# File 'lib/puppet/pal/pal_impl.rb', line 254

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.

Yield Parameters:

  • context, (Puppet::Pal)

    a context that responds to Puppet::Pal methods


207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
# File 'lib/puppet/pal/pal_impl.rb', line 207

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

Yield Parameters:


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
187
188
189
190
191
192
193
194
# 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

  # 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_file, facts, variables, :catalog, &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: 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

Yield Parameters:


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