bolt 0.8.0 → 0.9.0

data/vendored/puppet/lib/puppet/pops/types/type_parser.rb

@@ -201,6 +201,7 @@ class TypeParser
         'semverrange'  => TypeFactory.sem_ver_range,
         'timestamp'    => TypeFactory.timestamp,
         'timespan'     => TypeFactory.timespan,
+        'uri'          => TypeFactory.uri,
     }.freeze
   end
 
@@ -356,6 +357,11 @@ class TypeParser
       raise_invalid_parameters_error('Pattern', '1 or more', parameters.size) unless parameters.size >= 1
       TypeFactory.pattern(*parameters)
 
+    when 'uri'
+      # 1 parameter which is a string or a URI
+      raise_invalid_parameters_error('URI', '1', parameters.size) unless parameters.size == 1
+      TypeFactory.uri(parameters[0])
+
     when 'variant'
       # 1..m parameters being strings or regular expressions
       raise_invalid_parameters_error('Variant', '1 or more', parameters.size) unless parameters.size >= 1

data/vendored/puppet/lib/puppet/pops/types/type_with_members.rb

@@ -0,0 +1,43 @@
+module Puppet::Pops
+module Types
+
+# Interface implemented by a type that has IvocableMembers
+module TypeWithMembers
+  # @return [InvocableMember,nil] An invocable member if it exists, or `nil`
+  def [](member_name)
+    raise NotImplementedError, "'#{self.class.name}' should implement #[]"
+  end
+end
+
+# Interface implemented by attribute and function members
+module InvocableMember
+  # Performs type checking of arguments and invokes the method that corresponds to this
+  # method. The result of the invocation is returned
+  #
+  # @param receiver [Object] The receiver of the call
+  # @param scope [Puppet::Parser::Scope] The caller scope
+  # @param args [Array] Array of arguments.
+  # @return [Object] The result returned by the member function or attribute
+  #
+  # @api private
+  def invoke(receiver, scope, args, &block)
+    raise NotImplementedError, "'#{self.class.name}' should implement #invoke"
+  end
+end
+
+# Plays the same role as an PAttribute in the PObjectType. Provides
+# access to known attr_readers and plain reader methods.
+class AttrReader
+  include InvocableMember
+
+  def initialize(message)
+    @message = message.to_sym
+  end
+
+  def invoke(receiver, scope, args, &block)
+    receiver.send(@message)
+  end
+end
+end
+end
+

data/vendored/puppet/lib/puppet/pops/types/types.rb

@@ -1414,6 +1414,8 @@ class PIterableType < PTypeWithContainedType
         o >= 0
       when PIntegerType
         o.finite_range?
+      when PTypeAliasType
+        instance?(o.resolved_type, guard)
       else
         false
       end
@@ -3623,6 +3625,7 @@ require_relative 'p_timestamp_type'
 require_relative 'p_binary_type'
 require_relative 'p_init_type'
 require_relative 'p_object_type_extension'
+require_relative 'p_uri_type'
 require_relative 'type_set_reference'
 require_relative 'implementation_registry'
 require_relative 'tree_iterators'

data/vendored/puppet/lib/puppet/provider/package/gem.rb

@@ -8,7 +8,7 @@ Puppet::Type.type(:package).provide :gem, :parent => Puppet::Provider::Package d
     specified source is used, also pass `--clear-sources` via `install_options`.
     If source is present but is not a valid URL, it will be interpreted as the
     path to a local gem file. If source is not present, the gem will be
-    installed from the default gem repositories.
+    installed from the default gem repositories. Note that to modify this for Windows, it has to be a valid URL.
 
     This provider supports the `install_options` and `uninstall_options` attributes,
     which allow command-line flags to be passed to the gem command.

data/vendored/puppet/lib/puppet/provider/package/nim.rb

@@ -97,14 +97,13 @@ Puppet::Type.type(:package).provide :nim, :parent => :aix, :source => :aix do
     end
 
     if (package_type == nil)
-      #TRANSLATORS Full message: "Unable to find package #{pkg} with version #{version} on lpp_source #{source}"
-      errmsg = _("Unable to find package '%{pkg}' ") % { pkg: pkg }
-      if (version_specified)
-        #TRANSLATORS Full message: "Unable to find package #{pkg} with version #{version} on lpp_source #{source}"
-        errmsg << _("with version '%{version}' ") % { version: version }
-      end
-      #TRANSLATORS Full message: "Unable to find package #{pkg} with version #{version} on lpp_source #{source}"
-      errmsg << "on lpp_source '#{source}'"
+
+      errmsg = if version_specified
+                 _("Unable to find package '%{package}' with version '%{version}' on lpp_source '%{source}'") %
+                     { package: pkg, version: version, source: source }
+               else
+                 _("Unable to find package '%{package}' on lpp_source '%{source}'") % { package: pkg, source: source }
+               end
       self.fail errmsg
     end
 

data/vendored/puppet/lib/puppet/provider/package/opkg.rb

@@ -22,7 +22,7 @@ Puppet::Type.type(:package).provide :opkg, :source => :opkg, :parent => Puppet::
           packages << new(hash)
           hash = {}
         else
-          warning(_("Failed to match line %s" % line))
+          warning(_("Failed to match line %{line}") % { line: line })
         end
       }
     end

data/vendored/puppet/lib/puppet/provider/package/pkg.rb

@@ -43,7 +43,8 @@ Puppet::Type.type(:package).provide :pkg, :parent => Puppet::Provider::Package d
       when '-'
         {:status => 'known'}
       else
-        raise ArgumentError, _('Unknown format %s: %s[%s]') % [self.name, flags, flags[0..0]]
+        raise ArgumentError, _('Unknown format %{resource_name}: %{full_flags}[%{bad_flag}]') %
+            { resource_name: self.name, full_flags: flags, bad_flag: flags[0..0] }
       end
     ).merge(
       case flags[1..1]
@@ -52,7 +53,8 @@ Puppet::Type.type(:package).provide :pkg, :parent => Puppet::Provider::Package d
       when '-'
         {}
       else
-        raise ArgumentError, _('Unknown format %s: %s[%s]') % [self.name, flags, flags[1..1]]
+        raise ArgumentError, _('Unknown format %{resource_name}: %{full_flags}[%{bad_flag}]') %
+            { resource_name: self.name, full_flags: flags, bad_flag: flags[1..1] }
       end
     )
   end
@@ -82,7 +84,7 @@ Puppet::Type.type(:package).provide :pkg, :parent => Puppet::Provider::Package d
     when /known/
       {:status => 'known'}
     else
-      raise ArgumentError, _('Unknown format %s: %s') % [self.name, state]
+      raise ArgumentError, _('Unknown format %{resource_name}: %{state}') % { resource_name: self.name, state: state }
     end
   end
 
@@ -101,7 +103,7 @@ Puppet::Type.type(:package).provide :pkg, :parent => Puppet::Provider::Package d
       {:publisher => $1, :name => $2, :ensure => $3}.merge pkg_state($4).merge(ufoxi_flag($5))
 
     else
-      raise ArgumentError, _('Unknown line format %s: %s') % [self.name, line]
+      raise ArgumentError, _('Unknown line format %{resource_name}: %{parse_line}') % { resource_name: self.name, parse_line: line }
     end).merge({:provider => self.name})
   end
 

data/vendored/puppet/lib/puppet/provider/package/pkgutil.rb

@@ -70,7 +70,7 @@ Puppet::Type.type(:package).provide :pkgutil, :parent => :sun, :source => :sun d
       if line =~ /\s*(\S+)\s+(\S+)\s+(.*)/
         { :alias => $1, :name => $2, :avail => $3 }
       else
-        Puppet.warning _("Cannot match %s") % line
+        Puppet.warning _("Cannot match %{line}") % { line: line }
       end
     end.reject { |h| h.nil? }
   end
@@ -88,7 +88,7 @@ Puppet::Type.type(:package).provide :pkgutil, :parent => :sun, :source => :sun d
     output = output.split("\n")
 
     if output[-1] == "Not in catalog"
-      Puppet.warning _("Package not in pkgutil catalog: %s") % hash[:justme]
+      Puppet.warning _("Package not in pkgutil catalog: %{package}") % { package: hash[:justme] }
       return nil
     end
 
@@ -142,7 +142,7 @@ Puppet::Type.type(:package).provide :pkgutil, :parent => :sun, :source => :sun d
 
       return hash
     else
-      Puppet.warning _("Cannot match %s") % line
+      Puppet.warning _("Cannot match %{line}") % { line: line }
       return nil
     end
   end

data/vendored/puppet/lib/puppet/provider/service/init.rb

@@ -171,7 +171,7 @@ Puppet::Type.type(:service).provide :init, :parent => :base do
 
   def texecute(type, command, fof = true, squelch = false, combine = true)
     if type == :start && Facter.value(:osfamily) == "Solaris"
-        command =  ["/usr/bin/ctrun -l none", command].flatten.join(" ")
+        command =  ["/usr/bin/ctrun -l child", command].flatten.join(" ")
     end
     super(type, command, fof, squelch, combine)
   end

data/vendored/puppet/lib/puppet/syntax_checkers/base64.rb

@@ -24,12 +24,11 @@ class Puppet::SyntaxCheckers::Base64 < Puppet::Plugins::SyntaxCheckers::SyntaxCh
       # simply skips all non base64 characters
       Base64.strict_decode64(cleaned_text)
     rescue => e
-      if (cleaned_text.bytes.to_a.size * 8) % 6 != 0
-        msg2 = _("padding is not correct")
-      else
-        msg2 = _("contains letters outside strict base 64 range (or whitespace)")
-      end
-      msg = _("Base64 syntax checker: Cannot parse invalid Base64 string - %{msg2}") % { msg2: msg2 }
+      msg = if (cleaned_text.bytes.to_a.size * 8) % 6 != 0
+              _("Base64 syntax checker: Cannot parse invalid Base64 string - padding is not correct")
+            else
+              _("Base64 syntax checker: Cannot parse invalid Base64 string - contains letters outside strict base 64 range (or whitespace)")
+            end
 
       # TODO: improve the pops API to allow simpler diagnostic creation while still maintaining capabilities
       # and the issue code. (In this case especially, where there is only a single error message being issued).

data/vendored/puppet/lib/puppet/transaction.rb

@@ -177,7 +177,7 @@ class Puppet::Transaction
       else
         resource.info _("Starting to evaluate the resource") if Puppet[:evaltrace] and @catalog.host_config?
         seconds = thinmark { block.call(resource) }
-        resource.info _("Evaluated in %0.2f seconds") % seconds if Puppet[:evaltrace] and @catalog.host_config?
+        resource.info _("Evaluated in %{seconds} seconds") % { seconds: "%0.2f" % seconds } if Puppet[:evaltrace] and @catalog.host_config?
       end
     end
 

data/vendored/puppet/lib/puppet/type.rb

@@ -1289,9 +1289,7 @@ class Type
   end
 
   newmetaparam(:audit) do
-    desc "(This metaparameter is deprecated and will be ignored in a future release.)
-
-      Marks a subset of this resource's unmanaged attributes for auditing. Accepts an
+    desc "Marks a subset of this resource's unmanaged attributes for auditing. Accepts an
       attribute name, an array of attribute names, or `all`.
 
       Auditing a resource attribute has two effects: First, whenever a catalog
@@ -1312,12 +1310,6 @@ class Type
       and the second run will log the edit made by Puppet.)"
 
     validate do |list|
-      if Puppet.settings[:strict] != :off
-        # Only warn if `audit` metaparam came from a manifest
-        if file && line
-          puppet_deprecation_warning(_("The `audit` metaparameter is deprecated and will be ignored in a future release."), { :line => line, :file => file })
-        end
-      end
       list = Array(list).collect {|p| p.to_sym}
       unless list == [:all]
         list.each do |param|

data/vendored/puppet/lib/puppet/type/schedule.rb

@@ -371,7 +371,7 @@ module Puppet
         values.each { |value|
           unless value.is_a?(String) and
               (value =~ /^[0-6]$/ or value =~ /^(Mon|Tues?|Wed(?:nes)?|Thu(?:rs)?|Fri|Sat(?:ur)?|Sun)(day)?$/i)
-            raise ArgumentError, _("%s is not a valid day of the week") % value
+            raise ArgumentError, _("%{value} is not a valid day of the week") % { value: value }
           end
         }
       end

data/vendored/puppet/lib/puppet/util/log.rb

@@ -168,10 +168,9 @@ class Puppet::Util::Log
   def Log.coerce_string(str)
     return Puppet::Util::CharacterEncoding.convert_to_utf_8(str) if str.valid_encoding?
 
-    annotated_string = _("Received a Log attribute with invalid encoding:")
-    annotated_string << Puppet::Util::CharacterEncoding.convert_to_utf_8(str.dump) << "\n"
     # We only select the last 10 callers in the stack to avoid being spammy
-    annotated_string << _("Backtrace:") << "\n" << caller[0..10].join("\n")
+    _("Received a Log attribute with invalid encoding:%{log_message}\nBacktrace:\n%{backtrace}") %
+        { log_message: Puppet::Util::CharacterEncoding.convert_to_utf_8(str.dump), backtrace: caller[0..10].join("\n") }
   end
 
   public

data/vendored/puppet/lib/puppet/util/plist.rb

@@ -45,7 +45,7 @@ module Puppet::Util::Plist
                                                   {:failonfail => true, :combine => true})
           return parse_plist(plist)
         rescue Puppet::ExecutionFailure => detail
-          Puppet.warning(_("Cannot read file %{file_path}; Puppet is skipping it.\n") % { file_path: file_path } + _("Details: %{detail}") % { detail: detail })
+          Puppet.warning(_("Cannot read file %{file_path}; Puppet is skipping it.\nDetails: %{detail}") % { file_path: file_path, detail: detail })
         end
       end
       return nil

data/vendored/puppet/lib/puppet/util/reference.rb

@@ -13,8 +13,7 @@ class Puppet::Util::Reference
   instance_load(:reference, 'puppet/reference')
 
   def self.footer
-    #TRANSLATORS message accompanied by date of generation
-    "\n\n----------------\n\n*" + _("This page autogenerated on ") + "#{Time.now}*\n"
+    "\n\n----------------\n\n" + _("*This page autogenerated on %{current_time}*\n") % { current_time: Time.now.to_s }
   end
 
   def self.modes
@@ -113,7 +112,7 @@ class Puppet::Util::Reference
     # First the header
     text = markdown_header(@title, 1)
     #TRANSLATORS message accompanied by date of generation
-    text << _("\n\n**This page is autogenerated; any changes will get overwritten** *(last generated on ") + "#{Time.now.to_s})*\n\n"
+    text << _("\n\n**This page is autogenerated; any changes will get overwritten** *(last generated on %{current_time})*\n\n") % { current_time: Time.now.to_s }
 
     text << @header
 

data/vendored/puppet/lib/puppet_pal.rb

@@ -16,59 +16,301 @@ require 'puppet/parser/script_compiler'
 #   end
 #   # The result is the value 6
 #
-# @example Making a run_plan call
+# @example Calling a function
 #   require 'puppet_pal'
 #   result = Puppet::Pal.in_tmp_environment('pal_env', modulepath: ['/tmp/testmodules']) do |pal|
-#     pal.run_plan('mymodule::myplan', plan_args: { 'arg1' => 10, 'arg2' => '20 })
+#     pal.call_function('mymodule::myfunction', 10, 20)
 #   end
-#   # The result is what 'mymodule::myplan' returns
+#   # The result is what 'mymodule::myfunction' returns
 #
-module Puppet::Pal
+module Puppet
+module Pal
 
-  # Evaluates a Puppet Language script string.
-  # @param code_string [String] a snippet of Puppet Language source code
-  # @return [Object] what the Puppet Language code_string evaluates to
-  #
-  def self.evaluate_script_string(code_string)
-    Puppet[:tasks] = true
-    Puppet[:code] = code_string
-    main
+  # @param compiler [Puppet::Pal::Compiler] a configured compiler as obtained in the callback from `with_script_compiler`
+
+  class Compiler
+    attr_reader :internal_compiler
+    protected :internal_compiler
+
+    attr_reader :internal_evaluator
+    protected :internal_evaluator
+
+    def initialize(internal_compiler)
+      @internal_compiler = internal_compiler
+      @internal_evaluator = Puppet::Pops::Parser::EvaluatingParser.new
+    end
+
+    # Calls a function given by name with arguments specified in an `Array`, and optionally accepts a code block.
+    # @param function_name [String] the name of the function to call
+    # @param args [Object] the arguments to the function
+    # @param block [Proc] an optional callable block that is given to the called function
+    # @return [Object] what the called function returns
+    #
+    def call_function(function_name, *args, &block)
+      # TRANSLATORS: do not translate variable name strings in these assertions
+      Pal::assert_non_empty_string(function_name, 'function_name', false)
+      Pal::assert_type(Pal::T_ANY_ARRAY, args, 'args', false)
+      internal_evaluator.evaluator.external_call_function(function_name, args, topscope, &block)
+    end
+
+    # Returns an Array[Puppet::Pops::Types::PCallableType] describing the given function's signatures, or empty array if function not found.
+    # @param function_name [String] the name of the function to get a signature for
+    # @return [Array<Puppet::Pops::Types::PCallableType>] an array of callable signatures, or an empty array if function not found
+    def function_signatures(function_name)
+      loader = internal_compiler.loaders.private_environment_loader
+      if func = loader.load(:function, function_name)
+        t = func.class.dispatcher.to_type
+        return t.is_a?(Puppet::Pops::Types::PVariantType) ? t.types : [t]
+      end
+      # Could not find function
+      Puppet::Pops::EMPTY_ARRAY
+    end
+
+    # Evaluates a string of puppet language code in top scope.
+    # A "source_file" reference to a source can be given - if not an actual file name, by convention the name should
+    # be bracketed with < > to indicate it is something symbolic; for example `<commandline>` if the string was given on the
+    # command line.
+    #
+    # If the given `puppet_code` is `nil` or an empty string, `nil` is returned, otherwise the result of evaluating the
+    # puppet language string. The given string must form a complete and valid expression/statement as an error is raised
+    # otherwise. That is, it is not possible to divide a compound expression by line and evaluate each line individually.
+    #
+    # @param puppet_code [String, nil] the puppet language code to evaluate, must be a complete expression/statement
+    # @param source_file [String, nil] an optional reference to a source (a file or symbolic name/location)
+    # @return [Object] what the `puppet_code` evaluates to
+    #
+    def evaluate_string(puppet_code, source_file = nil)
+      return nil if puppet_code.nil? || puppet_code == ''
+      unless puppet_code.is_a?(String)
+        raise ArgumentError, _("The argument 'puppet_code' must be a String, got %{type}") % { type: puppet_code.class }
+      end
+      evaluate(parse_string(puppet_code, source_file))
+    end
+
+    # Evaluates a puppet language file in top scope.
+    # The file must exist and contain valid puppet language code or an error is raised.
+    #
+    # @param file [Path, String] an absolute path to a file with puppet language code, must exist
+    # @return [Object] what the last evaluated expression in the file evaluated to
+    #
+    def evaluate_file(file)
+      evaluate(parse_file(file))
+    end
+
+    # Evaluates an AST obtained from `parse_string` or `parse_file` in topscope.
+    # If the ast is a `Puppet::Pops::Model::Program` (what is returned from the `parse` methods, any definitions
+    # in the program (that is, any function, plan, etc. that is defined will be made available for use).
+    #
+    # @param ast [Puppet::Pops::Model::PopsObject] typically the returned `Program` from the parse methods, but can be any `Expression`
+    # @returns [Object] whatever the ast evaluates to
+    #
+    def evaluate(ast)
+      if ast.is_a?(Puppet::Pops::Model::Program)
+        loaders = Puppet.lookup(:loaders)
+        loaders.instantiate_definitions(ast, loaders.public_environment_loader)
+      end
+      internal_evaluator.evaluate(topscope, ast)
+    end
+
+    # Produces a literal value if the AST obtained from `parse_string` or `parse_file` does not require any actual evaluation.
+    # This method is useful if obtaining an AST that represents literal values; string, integer, float, boolean, regexp, array, hash;
+    # for example from having read this from the command line or as values in some file.
+    #
+    # @param ast [Puppet::Pops::Model::PopsObject] typically the returned `Program` from the parse methods, but can be any `Expression`
+    # @returns [Object] whatever the literal value the ast evaluates to
+    #
+    def evaluate_literal(ast)
+      catch :not_literal do
+        return Puppet::Pops::Evaluator::LiteralEvaluator.new().literal(ast)
+      end
+      # TRANSLATORS, the 'ast' is the name of a parameter, do not translate
+      raise ArgumentError, _("The given 'ast' does not represent a literal value")
+    end
+
+    # Parses and validates a puppet language string and returns an instance of Puppet::Pops::Model::Program on success.
+    # If the content is not valid an error is raised.
+    #
+    # @param code_string [String] a puppet language string to parse and validate
+    # @param source_file [String] an optional reference to a file or other location in angled brackets
+    # @return [Puppet::Pops::Model::Program] returns a `Program` instance on success
+    #
+    def parse_string(code_string, source_file = nil)
+      unless code_string.is_a?(String)
+        raise ArgumentError, _("The argument 'code_string' must be a String, got %{type}") % { type: code_string.class }
+      end
+      internal_evaluator.parse_string(code_string, source_file)
+    end
+
+    # Parses and validates a puppet language file and returns an instance of Puppet::Pops::Model::Program on success.
+    # If the content is not valid an error is raised.
+    #
+    # @param file [String] a file with puppet language content to parse and validate
+    # @return [Puppet::Pops::Model::Program] returns a `Program` instance on success
+    #
+    def parse_file(file)
+      unless file.is_a?(String)
+        raise ArgumentError, _("The argument 'file' must be a String, got %{type}") % { type: puppet_code.class }
+      end
+      internal_evaluator.parse_file(file)
+    end
+
+    # Parses a puppet data type given in String format and returns that type, or raises an error.
+    # A type is needed in calls to `new` to create an instance of the data type, or to perform type checking
+    # of values - typically using `type.instance?(obj)` to check if `obj` is an instance of the type.
+    #
+    # @example Verify if obj is an instance of a data type
+    #   # evaluates to true
+    #   pal.type('Enum[red, blue]').instance?("blue")
+    #
+    # @example Create an instance of a data type
+    #   # using an already create type
+    #   t = pal.type('Car')
+    #   pal.create(t, 'color' => 'black', 'make' => 't-ford')
+    #
+    #   # letting 'new_object' parse the type from a string
+    #   pal.create('Car', 'color' => 'black', 'make' => 't-ford')
+    #
+    # @param type_string [String] a puppet language data type
+    # @return [Puppet::Pops::Types::PAnyType] the data type
+    #
+    def type(type_string)
+      Puppet::Pops::Types::TypeParser.singleton.parse(type_string)
+    end
+
+    # Creates a new instance of a given data type.
+    # @param data_type [String, Puppet::Pops::Types::PAnyType] the data type as a data type or in String form.
+    # @param arguments [Object] one or more arguments to the called `new` function
+    # @return [Object] an instance of the given data type,
+    #   or raises an error if it was not possible to parse data type or create an instance.
+    #
+    def create(data_type, *arguments)
+      t = data_type.is_a?(String) ? type(data_type) : data_type
+      unless t.is_a?(Puppet::Pops::Types::PAnyType)
+        raise ArgumentError, _("Given data_type value is not a data type, got '%{type}'") % {type: t.class}
+      end
+      call_function('new', t, *arguments)
+    end
+
+    private
+
+    def topscope
+      internal_compiler.topscope
+    end
   end
 
-  # Evaluates a Puppet Language script (.pp) file.
-  # @param manifest_file [String] a file with Puppet Language source code
-  # @return [Object] what the Puppet Language manifest_file contents evaluates to
-  #
-  def self.evaluate_script_manifest(manifest_file)
-    assert_non_empty_string(manifest_file, _("manifest file"))
-    Puppet[:tasks] = true
-    main(manifest_file)
+  class ScriptCompiler < Compiler
+    # Returns the signature callable of the given plan (the arguments it accepts, and the data type it returns)
+    # @param plan_name [String] the name of the plan to get the signature of
+    # @return [Puppet::Pops::Types::PCallableType, nil] returns a callable data type, or nil if plan is not found
+    #
+    def plan_signature(plan_name)
+      loader = internal_compiler.loaders.private_environment_loader
+      if func = loader.load(:plan, plan_name)
+        return func.class.dispatcher.to_type
+      end
+      # Could not find plan
+      nil
+    end
   end
 
-  # Runs the given named plan passing arguments by name in a hash.
-  # @param plan_name [String] the name of the plan to run
-  # @param plan_args [Hash] arguments to the plan - a map of plan parameter name to value, defaults to empty hash
-  # @param manifest_file [String] a Puppet Language file to load and evaluate before running the plan, mutually exclusive with code_string
-  # @param code_string [String] a Puppet Language source string to load and evaluate before running the plan, mutually exclusive with manifest_file
-  # @return [Object] returns what the evaluated plan returns
+  # 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.
+  #
+  # @example define a script compiler without any initial logic
+  #   pal.with_script_compiler do | compiler |
+  #     # do things with compiler
+  #   end
+  #
+  # @example 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
+  #
+  # @param configured_by_env [Boolean] when true the environment's settings are used, otherwise the given `manifest_file` or `code_string`
+  # @param manifest_file [String] a Puppet Language file to load and evaluate before calling the given block, mutually exclusive with `code_string`
+  # @param code_string [String] a Puppet Language source string to load and evaluate before calling the given block, mutually exclusive with `manifest_file`
+  # @param facts [Hash] 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.
+  # @param variables [Hash] optional map of fully qualified variable name to value. If given at the environment level, the variables
+  #   given here are merged with higher priority.
+  # @param block [Proc] the block performing operations on compiler
+  # @return [Object] what the block returns
+  # @yieldparam [Puppet::Pal::ScriptCompiler] compiler, a ScriptCompiler to perform operations on.
   #
-  def self.run_plan(plan_name,
-      plan_args:     {},
-      manifest_file: nil,
-      code_string:   nil
+  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 string in these assertions
+    # 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?
-    main(manifest_file) do | compiler |
-      compiler.topscope.call_function('run_plan', [plan_name, plan_args])
+    overrides = {}
+    unless facts.nil?
+      overrides[:pal_facts] = Puppet.lookup(:pal_facts).merge(facts)
+    end
+    unless variables.nil?
+      overrides[:pal_variables] = Puppet.lookup(:pal_variables).merge(variables)
+    end
+    Puppet.override(overrides, "PAL::with_script_compiler") do # TRANSLATORS: Do not translate, symbolic name
+      # If manifest_file is nil, the #main method will use the env configured manifest
+      # do things in block while a Script Compiler is in effect
+      main(manifest_file, &block)
+    end
+  end
+
+  # Evaluates a Puppet Language script string.
+  # @param code_string [String] a snippet of Puppet Language source code
+  # @return [Object] what the Puppet Language code_string evaluates to
+  # @deprecated Use {#with_script_compiler} and then evaluate_string on the given compiler - to be removed in 1.0 version
+  #
+  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
 
+  # Evaluates a Puppet Language script (.pp) file.
+  # @param manifest_file [String] a file with Puppet Language source code
+  # @return [Object] what the Puppet Language manifest_file contents evaluates to
+  # @deprecated Use {#with_script_compiler} and then evaluate_file on the given compiler - to be removed in 1.0 version
+  #
+  def self.evaluate_script_manifest(manifest_file)
+    with_script_compiler do |compiler|
+      compiler.evaluate_file(manifest_file)
+    end
+  end
+
+
   # Defines the context in which to perform puppet operations (evaluation, etc)
   # The code to evaluate in this context is given in a block.
   #
@@ -76,6 +318,7 @@ module Puppet::Pal
   # @param modulepath [Array<String>] an array of directory paths containing Puppet modules, may be empty, defaults to empty array
   # @param settings_hash [Hash] a hash of settings - currently not used for anything, defaults to empty hash
   # @param facts [Hash] optional map of fact name to fact value - if not given will initialize the facts (which is a slow operation)
+  # @param variables [Hash] optional map of fully qualified variable name to value
   # @return [Object] returns what the given block returns
   # @yieldparam [Puppet::Pal] context, a context that responds to Puppet::Pal methods
   #
@@ -96,9 +339,10 @@ module Puppet::Pal
 
     env = Puppet::Node::Environment.create(env_name, modulepath)
 
-    with_loaded_environment(
+    in_environment_context(
       Puppet::Environments::Static.new(env), # The tmp env is the only known env
-      env, facts, variables, &block)
+      env, facts, variables, &block
+      )
   end
 
   # Defines the context in which to perform puppet operations (evaluation, etc)
@@ -121,6 +365,7 @@ module Puppet::Pal
   # @param envpath [String] 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.
   # @param facts [Hash] optional map of fact name to fact value - if not given will initialize the facts (which is a slow operation)
+  # @param variables [Hash] optional map of fully qualified variable name to value
   # @return [Object] returns what the given block returns
   # @yieldparam [Puppet::Pal] context, a context that responds to Puppet::Pal methods
   #
@@ -181,28 +426,27 @@ module Puppet::Pal
       # 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
-    with_loaded_environment(environments, env, facts, variables, &block)
+    in_environment_context(environments, env, facts, variables, &block)
   end
 
   private
 
-  def self.with_loaded_environment(environments, env, facts, variables, &block)
-    env.each_plugin_directory do |dir|
-      $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
-    end
-
-    # Puppet requires Facter, which initializes its lookup paths. Reset Facter to
-    # pickup the new $LOAD_PATH.
-    Facter.reset
-
+  # Prepares the puppet context with pal information - and delegates to the block
+  # No set up is performed at this step - it is delayed until it is known what the
+  # operation is going to be (for example - using a ScriptCompiler).
+  #
+  def self.in_environment_context(environments, env, facts, variables, &block)
+    # Create a default node to use (may be overridden later)
     node = Puppet::Node.new(Puppet[:node_name_value], :environment => env)
 
     Puppet.override(
-      environments: environments,        # The env being used is the only one...
-      current_node: node,                # to allow it to be picked up instead of created
-      variables: variables
+      environments: environments,     # The env being used is the only one...
+      pal_env: env,                   # provide as convenience
+      pal_current_node: node,         # to allow it to be picked up instead of created
+      pal_variables: variables,       # common set of variables across several inner contexts
+      pal_facts: facts                # common set of facts across several inner contexts (or nil)
     ) do
-      prepare_node_facts(node, facts)
+      # DELAY: prepare_node_facts(node, facts)
       return block.call(self)
     end
   end
@@ -243,8 +487,24 @@ module Puppet::Pal
     end
   end
 
-  def self.main(manifest = nil, facts = nil, &block)
-    node = Puppet.lookup(:current_node)
+  # The main routine for script compiler
+  # Picks up information from the puppet context and configures a script compiler which is given to
+  # the provided block
+  #
+  def self.main(manifest = nil, &block)
+    # Configure the load path
+    env = Puppet.lookup(:pal_env)
+    env.each_plugin_directory do |dir|
+      $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
+    end
+
+    # Puppet requires Facter, which initializes its lookup paths. Reset Facter to
+    # pickup the new $LOAD_PATH.
+    Facter.reset
+
+    node = Puppet.lookup(:pal_current_node)
+    prepare_node_facts(node, Puppet.lookup(:pal_facts))
+
     configured_environment = node.environment || Puppet.lookup(:current_environment)
 
     apply_environment = manifest ?
@@ -287,9 +547,13 @@ module Puppet::Pal
           # create the $settings:: variables
           topscope.merge_settings(node.environment.name, false)
 
-          add_variables(topscope, Puppet.lookup(:variables))
+          add_variables(topscope, Puppet.lookup(:pal_variables))
 
-          compiler.compile(&block)
+          # compiler.compile(&block)
+          compiler.compile do | internal_compiler |
+            # wrap the internal compiler to prevent it from leaking in the PAL API
+            block.call(ScriptCompiler.new(internal_compiler)) unless !block_given?
+          end
 
         rescue Puppet::ParseErrorWithIssue, Puppet::Error => detail
           # already logged and handled by the compiler for these two cases
@@ -304,6 +568,8 @@ module Puppet::Pal
 
   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
 
   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} }
@@ -323,4 +589,11 @@ module Puppet::Pal
     end
   end
 
+  def self.assert_block_given(block)
+    if block.nil?
+      raise ArgumentError, _("A block must be given")
+    end
+  end
+end
 end
+