bolt 0.20.0 → 0.20.2

data/vendored/puppet/lib/puppet/util/windows/user.rb

@@ -0,0 +1,309 @@
+require 'puppet/util/windows'
+
+require 'facter'
+require 'ffi'
+
+module Puppet::Util::Windows::User
+  extend Puppet::Util::Windows::String
+  extend FFI::Library
+
+  def admin?
+    elevated_supported = Puppet::Util::Windows::Process.supports_elevated_security?
+
+    # if Vista or later, check for unrestricted process token
+    return Puppet::Util::Windows::Process.elevated_security? if elevated_supported
+
+    # otherwise 2003 or less
+    check_token_membership
+  end
+  module_function :admin?
+
+
+  # https://msdn.microsoft.com/en-us/library/windows/desktop/ee207397(v=vs.85).aspx
+  SECURITY_MAX_SID_SIZE = 68
+
+  # https://msdn.microsoft.com/en-us/library/windows/desktop/ms681385(v=vs.85).aspx
+  # These error codes indicate successful authentication but failure to
+  # logon for a separate reason
+  ERROR_ACCOUNT_RESTRICTION = 1327
+  ERROR_INVALID_LOGON_HOURS = 1328
+  ERROR_INVALID_WORKSTATION = 1329
+  ERROR_ACCOUNT_DISABLED    = 1331
+
+  def check_token_membership
+    is_admin = false
+    FFI::MemoryPointer.new(:byte, SECURITY_MAX_SID_SIZE) do |sid_pointer|
+      FFI::MemoryPointer.new(:dword, 1) do |size_pointer|
+        size_pointer.write_uint32(SECURITY_MAX_SID_SIZE)
+
+        if CreateWellKnownSid(:WinBuiltinAdministratorsSid, FFI::Pointer::NULL, sid_pointer, size_pointer) == FFI::WIN32_FALSE
+          raise Puppet::Util::Windows::Error.new(_("Failed to create administrators SID"))
+        end
+      end
+
+      if IsValidSid(sid_pointer) == FFI::WIN32_FALSE
+        raise Puppet::Util::Windows::Error.new(_("Invalid SID"))
+      end
+
+      FFI::MemoryPointer.new(:win32_bool, 1) do |ismember_pointer|
+        if CheckTokenMembership(FFI::Pointer::NULL_HANDLE, sid_pointer, ismember_pointer) == FFI::WIN32_FALSE
+          raise Puppet::Util::Windows::Error.new(_("Failed to check membership"))
+        end
+
+        # Is administrators SID enabled in calling thread's access token?
+        is_admin = ismember_pointer.read_win32_bool
+      end
+    end
+
+    is_admin
+  end
+  module_function :check_token_membership
+
+  def password_is?(name, password)
+    begin
+      logon_user(name, password) { |token| }
+    rescue Puppet::Util::Windows::Error => detail
+
+      authenticated_error_codes = Set[
+        ERROR_ACCOUNT_RESTRICTION,
+        ERROR_INVALID_LOGON_HOURS,
+        ERROR_INVALID_WORKSTATION,
+        ERROR_ACCOUNT_DISABLED,
+      ]
+
+      return authenticated_error_codes.include?(detail.code)
+    end
+  end
+  module_function :password_is?
+
+  def logon_user(name, password, &block)
+    fLOGON32_LOGON_NETWORK = 3
+    fLOGON32_PROVIDER_DEFAULT = 0
+
+    token = nil
+    begin
+      FFI::MemoryPointer.new(:handle, 1) do |token_pointer|
+        if LogonUserW(wide_string(name), wide_string('.'), password.nil? ? FFI::Pointer::NULL : wide_string(password),
+            fLOGON32_LOGON_NETWORK, fLOGON32_PROVIDER_DEFAULT, token_pointer) == FFI::WIN32_FALSE
+          raise Puppet::Util::Windows::Error.new(_("Failed to logon user %{name}") % { name: name.inspect })
+        end
+
+        yield token = token_pointer.read_handle
+      end
+    ensure
+      FFI::WIN32.CloseHandle(token) if token
+    end
+
+    # token has been closed by this point
+    true
+  end
+  module_function :logon_user
+
+  def load_profile(user, password)
+    logon_user(user, password) do |token|
+      FFI::MemoryPointer.from_string_to_wide_string(user) do |lpUserName|
+        pi = PROFILEINFO.new
+        pi[:dwSize] = PROFILEINFO.size
+        pi[:dwFlags] = 1 # PI_NOUI - prevents display of profile error msgs
+        pi[:lpUserName] = lpUserName
+
+        # Load the profile. Since it doesn't exist, it will be created
+        if LoadUserProfileW(token, pi.pointer) == FFI::WIN32_FALSE
+          raise Puppet::Util::Windows::Error.new(_("Failed to load user profile %{user}") % { user: user.inspect })
+        end
+
+        Puppet.debug("Loaded profile for #{user}")
+
+        if UnloadUserProfile(token, pi[:hProfile]) == FFI::WIN32_FALSE
+          raise Puppet::Util::Windows::Error.new(_("Failed to unload user profile %{user}") % { user: user.inspect })
+        end
+      end
+    end
+  end
+  module_function :load_profile
+
+  ffi_convention :stdcall
+
+  # https://msdn.microsoft.com/en-us/library/windows/desktop/aa378184(v=vs.85).aspx
+  # BOOL LogonUser(
+  #   _In_      LPTSTR lpszUsername,
+  #   _In_opt_  LPTSTR lpszDomain,
+  #   _In_opt_  LPTSTR lpszPassword,
+  #   _In_      DWORD dwLogonType,
+  #   _In_      DWORD dwLogonProvider,
+  #   _Out_     PHANDLE phToken
+  # );
+  ffi_lib :advapi32
+  attach_function_private :LogonUserW,
+    [:lpwstr, :lpwstr, :lpwstr, :dword, :dword, :phandle], :win32_bool
+
+  # https://msdn.microsoft.com/en-us/library/windows/desktop/bb773378(v=vs.85).aspx
+  # typedef struct _PROFILEINFO {
+  #   DWORD  dwSize;
+  #   DWORD  dwFlags;
+  #   LPTSTR lpUserName;
+  #   LPTSTR lpProfilePath;
+  #   LPTSTR lpDefaultPath;
+  #   LPTSTR lpServerName;
+  #   LPTSTR lpPolicyPath;
+  #   HANDLE hProfile;
+  # } PROFILEINFO, *LPPROFILEINFO;
+  # technically
+  # NOTE: that for structs, buffer_* (lptstr alias) cannot be used
+  class PROFILEINFO < FFI::Struct
+    layout :dwSize, :dword,
+           :dwFlags, :dword,
+           :lpUserName, :pointer,
+           :lpProfilePath, :pointer,
+           :lpDefaultPath, :pointer,
+           :lpServerName, :pointer,
+           :lpPolicyPath, :pointer,
+           :hProfile, :handle
+  end
+
+  # https://msdn.microsoft.com/en-us/library/windows/desktop/bb762281(v=vs.85).aspx
+  # BOOL WINAPI LoadUserProfile(
+  #   _In_     HANDLE hToken,
+  #   _Inout_  LPPROFILEINFO lpProfileInfo
+  # );
+  ffi_lib :userenv
+  attach_function_private :LoadUserProfileW,
+    [:handle, :pointer], :win32_bool
+
+  # https://msdn.microsoft.com/en-us/library/windows/desktop/bb762282(v=vs.85).aspx
+  # BOOL WINAPI UnloadUserProfile(
+  #   _In_  HANDLE hToken,
+  #   _In_  HANDLE hProfile
+  # );
+  ffi_lib :userenv
+  attach_function_private :UnloadUserProfile,
+    [:handle, :handle], :win32_bool
+
+  # https://msdn.microsoft.com/en-us/library/windows/desktop/aa376389(v=vs.85).aspx
+  # BOOL WINAPI CheckTokenMembership(
+  #   _In_opt_  HANDLE TokenHandle,
+  #   _In_      PSID SidToCheck,
+  #   _Out_     PBOOL IsMember
+  # );
+  ffi_lib :advapi32
+  attach_function_private :CheckTokenMembership,
+    [:handle, :pointer, :pbool], :win32_bool
+
+  # https://msdn.microsoft.com/en-us/library/windows/desktop/aa379650(v=vs.85).aspx
+  WELL_KNOWN_SID_TYPE = enum(
+    :WinNullSid                                   , 0,
+    :WinWorldSid                                  , 1,
+    :WinLocalSid                                  , 2,
+    :WinCreatorOwnerSid                           , 3,
+    :WinCreatorGroupSid                           , 4,
+    :WinCreatorOwnerServerSid                     , 5,
+    :WinCreatorGroupServerSid                     , 6,
+    :WinNtAuthoritySid                            , 7,
+    :WinDialupSid                                 , 8,
+    :WinNetworkSid                                , 9,
+    :WinBatchSid                                  , 10,
+    :WinInteractiveSid                            , 11,
+    :WinServiceSid                                , 12,
+    :WinAnonymousSid                              , 13,
+    :WinProxySid                                  , 14,
+    :WinEnterpriseControllersSid                  , 15,
+    :WinSelfSid                                   , 16,
+    :WinAuthenticatedUserSid                      , 17,
+    :WinRestrictedCodeSid                         , 18,
+    :WinTerminalServerSid                         , 19,
+    :WinRemoteLogonIdSid                          , 20,
+    :WinLogonIdsSid                               , 21,
+    :WinLocalSystemSid                            , 22,
+    :WinLocalServiceSid                           , 23,
+    :WinNetworkServiceSid                         , 24,
+    :WinBuiltinDomainSid                          , 25,
+    :WinBuiltinAdministratorsSid                  , 26,
+    :WinBuiltinUsersSid                           , 27,
+    :WinBuiltinGuestsSid                          , 28,
+    :WinBuiltinPowerUsersSid                      , 29,
+    :WinBuiltinAccountOperatorsSid                , 30,
+    :WinBuiltinSystemOperatorsSid                 , 31,
+    :WinBuiltinPrintOperatorsSid                  , 32,
+    :WinBuiltinBackupOperatorsSid                 , 33,
+    :WinBuiltinReplicatorSid                      , 34,
+    :WinBuiltinPreWindows2000CompatibleAccessSid  , 35,
+    :WinBuiltinRemoteDesktopUsersSid              , 36,
+    :WinBuiltinNetworkConfigurationOperatorsSid   , 37,
+    :WinAccountAdministratorSid                   , 38,
+    :WinAccountGuestSid                           , 39,
+    :WinAccountKrbtgtSid                          , 40,
+    :WinAccountDomainAdminsSid                    , 41,
+    :WinAccountDomainUsersSid                     , 42,
+    :WinAccountDomainGuestsSid                    , 43,
+    :WinAccountComputersSid                       , 44,
+    :WinAccountControllersSid                     , 45,
+    :WinAccountCertAdminsSid                      , 46,
+    :WinAccountSchemaAdminsSid                    , 47,
+    :WinAccountEnterpriseAdminsSid                , 48,
+    :WinAccountPolicyAdminsSid                    , 49,
+    :WinAccountRasAndIasServersSid                , 50,
+    :WinNTLMAuthenticationSid                     , 51,
+    :WinDigestAuthenticationSid                   , 52,
+    :WinSChannelAuthenticationSid                 , 53,
+    :WinThisOrganizationSid                       , 54,
+    :WinOtherOrganizationSid                      , 55,
+    :WinBuiltinIncomingForestTrustBuildersSid     , 56,
+    :WinBuiltinPerfMonitoringUsersSid             , 57,
+    :WinBuiltinPerfLoggingUsersSid                , 58,
+    :WinBuiltinAuthorizationAccessSid             , 59,
+    :WinBuiltinTerminalServerLicenseServersSid    , 60,
+    :WinBuiltinDCOMUsersSid                       , 61,
+    :WinBuiltinIUsersSid                          , 62,
+    :WinIUserSid                                  , 63,
+    :WinBuiltinCryptoOperatorsSid                 , 64,
+    :WinUntrustedLabelSid                         , 65,
+    :WinLowLabelSid                               , 66,
+    :WinMediumLabelSid                            , 67,
+    :WinHighLabelSid                              , 68,
+    :WinSystemLabelSid                            , 69,
+    :WinWriteRestrictedCodeSid                    , 70,
+    :WinCreatorOwnerRightsSid                     , 71,
+    :WinCacheablePrincipalsGroupSid               , 72,
+    :WinNonCacheablePrincipalsGroupSid            , 73,
+    :WinEnterpriseReadonlyControllersSid          , 74,
+    :WinAccountReadonlyControllersSid             , 75,
+    :WinBuiltinEventLogReadersGroup               , 76,
+    :WinNewEnterpriseReadonlyControllersSid       , 77,
+    :WinBuiltinCertSvcDComAccessGroup             , 78,
+    :WinMediumPlusLabelSid                        , 79,
+    :WinLocalLogonSid                             , 80,
+    :WinConsoleLogonSid                           , 81,
+    :WinThisOrganizationCertificateSid            , 82,
+    :WinApplicationPackageAuthoritySid            , 83,
+    :WinBuiltinAnyPackageSid                      , 84,
+    :WinCapabilityInternetClientSid               , 85,
+    :WinCapabilityInternetClientServerSid         , 86,
+    :WinCapabilityPrivateNetworkClientServerSid   , 87,
+    :WinCapabilityPicturesLibrarySid              , 88,
+    :WinCapabilityVideosLibrarySid                , 89,
+    :WinCapabilityMusicLibrarySid                 , 90,
+    :WinCapabilityDocumentsLibrarySid             , 91,
+    :WinCapabilitySharedUserCertificatesSid       , 92,
+    :WinCapabilityEnterpriseAuthenticationSid     , 93,
+    :WinCapabilityRemovableStorageSid             , 94
+  )
+
+  # https://msdn.microsoft.com/en-us/library/windows/desktop/aa446585(v=vs.85).aspx
+  # BOOL WINAPI CreateWellKnownSid(
+  #   _In_       WELL_KNOWN_SID_TYPE WellKnownSidType,
+  #   _In_opt_   PSID DomainSid,
+  #   _Out_opt_  PSID pSid,
+  #   _Inout_    DWORD *cbSid
+  # );
+  ffi_lib :advapi32
+  attach_function_private :CreateWellKnownSid,
+    [WELL_KNOWN_SID_TYPE, :pointer, :pointer, :lpdword], :win32_bool
+
+  # https://msdn.microsoft.com/en-us/library/windows/desktop/aa379151(v=vs.85).aspx
+  # BOOL WINAPI IsValidSid(
+  #   _In_  PSID pSid
+  # );
+  ffi_lib :advapi32
+  attach_function_private :IsValidSid,
+    [:pointer], :win32_bool
+end

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

@@ -0,0 +1,36 @@
+require 'yaml'
+
+module Puppet::Util::Yaml
+  if defined?(::Psych::SyntaxError)
+    YamlLoadExceptions = [::StandardError, ::Psych::SyntaxError]
+  else
+    YamlLoadExceptions = [::StandardError]
+  end
+
+  class YamlLoadError < Puppet::Error; end
+
+  def self.load_file(filename, default_value = false, strip_classes = false)
+    if(strip_classes) then
+      data = YAML::parse_file(filename)
+      data.root.each do |o|
+        if o.respond_to?(:tag=) and
+           o.tag != nil and
+           o.tag.start_with?("!ruby")
+          o.tag = nil
+        end
+      end
+      data.to_ruby || default_value
+    else
+      yaml = YAML.load_file(filename)
+      yaml || default_value
+    end
+  rescue *YamlLoadExceptions => detail
+    raise YamlLoadError.new(detail.message, detail)
+  end
+
+  def self.dump(structure, filename)
+    Puppet::Util.replace_file(filename, 0660) do |fh|
+      YAML.dump(structure, fh)
+    end
+  end
+end

data/vendored/puppet/lib/puppet/vendor.rb

@@ -0,0 +1,57 @@
+module Puppet
+  # Simple module to manage vendored code.
+  #
+  # To vendor a library:
+  #
+  # * Download its whole git repo or untar into `lib/puppet/vendor/<libname>`
+  # * Create a vendor/puppetload_libraryname.rb file to add its libdir into the $:.
+  #   (Look at existing load_xxx files, they should all follow the same pattern).
+  # * Add a <libname>/PUPPET_README.md file describing what the library is for
+  #   and where it comes from.
+  # * To load the vendored lib upfront, add a `require '<vendorlib>'`line to
+  #   `vendor/require_vendored.rb`.
+  # * To load the vendored lib on demand, add a comment to `vendor/require_vendored.rb`
+  #    to make it clear it should not be loaded upfront.
+  #
+  # At runtime, the #load_vendored method should be called. It will ensure
+  # all vendored libraries are added to the global `$:` path, and
+  # will then call execute the up-front loading specified in `vendor/require_vendored.rb`.
+  #
+  # The intention is to not change vendored libraries and to eventually
+  # make adding them in optional so that distros can simply adjust their
+  # packaging to exclude this directory and the various load_xxx.rb scripts
+  # if they wish to install these gems as native packages.
+  #
+  class Vendor
+    class << self
+      # @api private
+      def vendor_dir
+        File.join([File.dirname(File.expand_path(__FILE__)), "vendor"])
+      end
+
+      # @api private
+      def load_entry(entry)
+        Puppet.debug("Loading vendored #{$1}")
+        load "#{vendor_dir}/#{entry}"
+      end
+
+      # @api private
+      def require_libs
+        require 'puppet/vendor/require_vendored'
+      end
+
+      # Configures the path for all vendored libraries and loads required libraries.
+      # (This is the entry point for loading vendored libraries).
+      #
+      def load_vendored
+        Dir.entries(vendor_dir).each do |entry|
+          if entry.match(/load_(\w+?)\.rb$/)
+            load_entry entry
+          end
+        end
+
+        require_libs
+      end
+    end
+  end
+end

data/vendored/puppet/lib/puppet/vendor/deep_merge/lib/deep_merge.rb

@@ -0,0 +1,2 @@
+require 'deep_merge/core'
+require 'deep_merge/deep_merge_hash'

data/vendored/puppet/lib/puppet/vendor/deep_merge/lib/deep_merge/core.rb

@@ -0,0 +1,210 @@
+module DeepMerge
+
+  class InvalidParameter < StandardError; end
+
+  DEFAULT_FIELD_KNOCKOUT_PREFIX = '--'
+
+  # Deep Merge core documentation.
+  # deep_merge! method permits merging of arbitrary child elements. The two top level
+  # elements must be hashes. These hashes can contain unlimited (to stack limit) levels
+  # of child elements. These child elements to not have to be of the same types.
+  # Where child elements are of the same type, deep_merge will attempt to merge them together.
+  # Where child elements are not of the same type, deep_merge will skip or optionally overwrite
+  # the destination element with the contents of the source element at that level.
+  # So if you have two hashes like this:
+  #   source = {:x => [1,2,3], :y => 2}
+  #   dest =   {:x => [4,5,'6'], :y => [7,8,9]}
+  #   dest.deep_merge!(source)
+  #   Results: {:x => [1,2,3,4,5,'6'], :y => 2}
+  # By default, "deep_merge!" will overwrite any unmergeables and merge everything else.
+  # To avoid this, use "deep_merge" (no bang/exclamation mark)
+  #
+  # Options:
+  #   Options are specified in the last parameter passed, which should be in hash format:
+  #   hash.deep_merge!({:x => [1,2]}, {:knockout_prefix => '--'})
+  #   :preserve_unmergeables  DEFAULT: false
+  #      Set to true to skip any unmergeable elements from source
+  #   :knockout_prefix        DEFAULT: nil
+  #      Set to string value to signify prefix which deletes elements from existing element
+  #   :sort_merged_arrays     DEFAULT: false
+  #      Set to true to sort all arrays that are merged together
+  #   :unpack_arrays          DEFAULT: nil
+  #      Set to string value to run "Array::join" then "String::split" against all arrays
+  #   :merge_hash_arrays      DEFAULT: false
+  #      Set to true to merge hashes within arrays
+  #   :merge_debug            DEFAULT: false
+  #      Set to true to get console output of merge process for debugging
+  #
+  # Selected Options Details:
+  # :knockout_prefix => The purpose of this is to provide a way to remove elements
+  #   from existing Hash by specifying them in a special way in incoming hash
+  #    source = {:x => ['--1', '2']}
+  #    dest   = {:x => ['1', '3']}
+  #    dest.ko_deep_merge!(source)
+  #    Results: {:x => ['2','3']}
+  #   Additionally, if the knockout_prefix is passed alone as a string, it will cause
+  #   the entire element to be removed:
+  #    source = {:x => '--'}
+  #    dest   = {:x => [1,2,3]}
+  #    dest.ko_deep_merge!(source)
+  #    Results: {:x => ""}
+  # :unpack_arrays => The purpose of this is to permit compound elements to be passed
+  #   in as strings and to be converted into discrete array elements
+  #   irsource = {:x => ['1,2,3', '4']}
+  #   dest   = {:x => ['5','6','7,8']}
+  #   dest.deep_merge!(source, {:unpack_arrays => ','})
+  #   Results: {:x => ['1','2','3','4','5','6','7','8'}
+  #   Why: If receiving data from an HTML form, this makes it easy for a checkbox
+  #    to pass multiple values from within a single HTML element
+  #
+  # :merge_hash_arrays => merge hashes within arrays
+  #   source = {:x => [{:y => 1}]}
+  #   dest   = {:x => [{:z => 2}]}
+  #   dest.deep_merge!(source, {:merge_hash_arrays => true})
+  #   Results: {:x => [{:y => 1, :z => 2}]}
+  # 
+  # There are many tests for this library - and you can learn more about the features
+  # and usages of deep_merge! by just browsing the test examples
+  def self.deep_merge!(source, dest, options = {})
+    # turn on this line for stdout debugging text
+    merge_debug = options[:merge_debug] || false
+    overwrite_unmergeable = !options[:preserve_unmergeables]
+    knockout_prefix = options[:knockout_prefix] || nil
+    raise InvalidParameter, "knockout_prefix cannot be an empty string in deep_merge!" if knockout_prefix == ""
+    raise InvalidParameter, "overwrite_unmergeable must be true if knockout_prefix is specified in deep_merge!" if knockout_prefix && !overwrite_unmergeable
+    # if present: we will split and join arrays on this char before merging
+    array_split_char = options[:unpack_arrays] || false
+    # request that we sort together any arrays when they are merged
+    sort_merged_arrays = options[:sort_merged_arrays] || false
+    # request that arrays of hashes are merged together
+    merge_hash_arrays = options[:merge_hash_arrays] || false
+    di = options[:debug_indent] || ''
+    # do nothing if source is nil
+    return dest if source.nil?
+    # if dest doesn't exist, then simply copy source to it
+    if !(dest) && overwrite_unmergeable
+      dest = source; return dest
+    end
+
+    puts "#{di}Source class: #{source.class.inspect} :: Dest class: #{dest.class.inspect}" if merge_debug
+    if source.kind_of?(Hash)
+      puts "#{di}Hashes: #{source.inspect} :: #{dest.inspect}" if merge_debug
+      source.each do |src_key, src_value|
+        if dest.kind_of?(Hash)
+          puts "#{di} looping: #{src_key.inspect} => #{src_value.inspect} :: #{dest.inspect}" if merge_debug
+          if dest[src_key]
+            puts "#{di} ==>merging: #{src_key.inspect} => #{src_value.inspect} :: #{dest[src_key].inspect}" if merge_debug
+            dest[src_key] = deep_merge!(src_value, dest[src_key], options.merge(:debug_indent => di + '  '))
+          else # dest[src_key] doesn't exist so we want to create and overwrite it (but we do this via deep_merge!)
+            puts "#{di} ==>merging over: #{src_key.inspect} => #{src_value.inspect}" if merge_debug
+            # note: we rescue here b/c some classes respond to "dup" but don't implement it (Numeric, TrueClass, FalseClass, NilClass among maybe others)
+            begin
+              src_dup = src_value.dup # we dup src_value if possible because we're going to merge into it (since dest is empty)
+            rescue TypeError
+              src_dup = src_value
+            end
+            dest[src_key] = deep_merge!(src_value, src_dup, options.merge(:debug_indent => di + '  '))
+          end
+        else # dest isn't a hash, so we overwrite it completely (if permitted)
+          if overwrite_unmergeable
+            puts "#{di}  overwriting dest: #{src_key.inspect} => #{src_value.inspect} -over->  #{dest.inspect}" if merge_debug
+            dest = overwrite_unmergeables(source, dest, options)
+          end
+        end
+      end
+    elsif source.kind_of?(Array)
+      puts "#{di}Arrays: #{source.inspect} :: #{dest.inspect}" if merge_debug
+      # if we are instructed, join/split any source arrays before processing
+      if array_split_char
+        puts "#{di} split/join on source: #{source.inspect}" if merge_debug
+        source = source.join(array_split_char).split(array_split_char)
+        if dest.kind_of?(Array)
+          dest = dest.join(array_split_char).split(array_split_char)
+        end
+      end
+      # if there's a naked knockout_prefix in source, that means we are to truncate dest
+      if knockout_prefix && source.index(knockout_prefix)
+        dest = clear_or_nil(dest); source.delete(knockout_prefix)
+      end
+      if dest.kind_of?(Array)
+        if knockout_prefix
+          print "#{di} knocking out: " if merge_debug
+          # remove knockout prefix items from both source and dest
+          source.delete_if do |ko_item|
+            retval = false
+            item = ko_item.respond_to?(:gsub) ? ko_item.gsub(%r{^#{knockout_prefix}}, "") : ko_item
+            if item != ko_item
+              print "#{ko_item} - " if merge_debug
+              dest.delete(item)
+              dest.delete(ko_item)
+              retval = true
+            end
+            retval
+          end
+          puts if merge_debug
+        end
+        puts "#{di} merging arrays: #{source.inspect} :: #{dest.inspect}" if merge_debug
+        source_all_hashes = source.all? { |i| i.kind_of?(Hash) }
+        dest_all_hashes = dest.all? { |i| i.kind_of?(Hash) }
+        if merge_hash_arrays && source_all_hashes && dest_all_hashes
+          # merge hashes in lists
+          list = []
+          dest.each_index do |i|
+            list[i] = deep_merge!(source[i] || {}, dest[i],
+                                  options.merge(:debug_indent => di + '  '))
+          end
+          list += source[dest.count..-1] if source.count > dest.count
+          dest = list
+        else
+          dest = dest | source
+        end
+        dest.sort! if sort_merged_arrays
+      elsif overwrite_unmergeable
+        puts "#{di} overwriting dest: #{source.inspect} -over-> #{dest.inspect}" if merge_debug
+        dest = overwrite_unmergeables(source, dest, options)
+      end
+    else # src_hash is not an array or hash, so we'll have to overwrite dest
+      puts "#{di}Others: #{source.inspect} :: #{dest.inspect}" if merge_debug
+      dest = overwrite_unmergeables(source, dest, options)
+    end
+    puts "#{di}Returning #{dest.inspect}" if merge_debug
+    dest
+  end # deep_merge!
+
+  # allows deep_merge! to uniformly handle overwriting of unmergeable entities
+  def self.overwrite_unmergeables(source, dest, options)
+    merge_debug = options[:merge_debug] || false
+    overwrite_unmergeable = !options[:preserve_unmergeables]
+    knockout_prefix = options[:knockout_prefix] || false
+    di = options[:debug_indent] || ''
+    if knockout_prefix && overwrite_unmergeable
+      if source.kind_of?(String) # remove knockout string from source before overwriting dest
+        src_tmp = source.gsub(%r{^#{knockout_prefix}},"")
+      elsif source.kind_of?(Array) # remove all knockout elements before overwriting dest
+        src_tmp = source.delete_if {|ko_item| ko_item.kind_of?(String) && ko_item.match(%r{^#{knockout_prefix}}) }
+      else
+        src_tmp = source
+      end
+      if src_tmp == source # if we didn't find a knockout_prefix then we just overwrite dest
+        puts "#{di}#{src_tmp.inspect} -over-> #{dest.inspect}" if merge_debug
+        dest = src_tmp
+      else # if we do find a knockout_prefix, then we just delete dest
+        puts "#{di}\"\" -over-> #{dest.inspect}" if merge_debug
+        dest = ""
+      end
+    elsif overwrite_unmergeable
+      dest = source
+    end
+    dest
+  end
+
+  def self.clear_or_nil(obj)
+    if obj.respond_to?(:clear)
+      obj.clear
+    else
+      obj = nil
+    end
+    obj
+  end
+
+end # module DeepMerge