Module: Puppet::Pal

Defined in:
lib/puppet_pal.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 



1078
1079
1080
 
# File 'lib/puppet_pal.rb', line 1078

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 



1074
1075
1076
 
# File 'lib/puppet_pal.rb', line 1074

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 



1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
 
# File 'lib/puppet_pal.rb', line 1055

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



691
692
693
694
695
 
# File 'lib/puppet_pal.rb', line 691

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



678
679
680
681
682
683
684
 
# File 'lib/puppet_pal.rb', line 678

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



824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
 
# File 'lib/puppet_pal.rb', line 824

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



777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
 
# File 'lib/puppet_pal.rb', line 777

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



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
753
754
755
756
757
758
759
760
761
762
763
764
 
# File 'lib/puppet_pal.rb', line 727

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



634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
 
# File 'lib/puppet_pal.rb', line 634

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