Module | Chef::Mixin::DeepMerge
In: | lib/chef/mixin/deep_merge.rb

## Chef::Mixin::DeepMerge

Implements a deep merging algorithm for nested data structures.

#### Notice:

      This code is imported from deep_merge by Steve Midgley. deep_merge is
      available under the MIT license from
      http://trac.misuse.org/science/wiki/DeepMerge

### Methods

clear_or_nil deep_merge! merge overwrite_unmergeables

### Classes and Modules

Class Chef::Mixin::DeepMerge::InvalidParameter

### Constants

DEFAULT_FIELD_KNOCKOUT_PREFIX | = | '--' unless defined?(DEFAULT_FIELD_KNOCKOUT_PREFIX)

### Public Class methods

clear_or_nil(obj)
deep_merge!(source, dest, options = {})

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_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

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

merge(first, second)
overwrite_unmergeables(source, dest, options)

allows deep_merge! to uniformly handle overwriting of unmergeable entities

[Validate]