yaml_extend 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 709ab41867197b612c61535154fe7e65bad1354c7605417d0fcad1601d45c134
-  data.tar.gz: 72f4e212f76e450b96420bb61eeff03aa2e7dc685c6600312ebc767b34987c80
+  metadata.gz: b056650bc04768e6d55177c1125ef048d7f02d4764e8cecdd851f75e07b816c5
+  data.tar.gz: bc70a195072c63c7af2116b619f8ea5677b7fae0925128f9cfbedb8d216d7d9c
 SHA512:
-  metadata.gz: aebb3c47f6b90557ac6683ed673a036a3b05a469b543c7bf4b3eb07108ff721410a6a5e57b5fa3a643360fe27cf59f3eb99b724a98f8bd483c34159d1d40956e
-  data.tar.gz: e15f2449c5c4d93abb0ba1a56cde3928fd06a7219d2cedb6ee20290cabc8fe1c2a27ecd976a04558395b26e26ab42c60f080595ca458c337996861313b532494
+  metadata.gz: 6f3588a3e5a0a07d4102e19ed7d0c87af68f0638037d141df85c4d24c7791743b3fd449fc77a6316d44f602e157297c6560dba9dabc304ee46c36f3ccb8d9155
+  data.tar.gz: 7ff4beefad210bd1a503a8cfc4563042c53751099441beb04d2ad1680eebad697b87db82e10421c4ca958439bda4c850770729211db8f0f67e3e8a5b6feecc05

data/README.md

@@ -31,11 +31,11 @@ It is possible to build inheritance trees like:
 ```
 or like this:
 ```
-default.yml   english.yml          default.yml   german.yml       
+fruits.yml   vegetables.yml          default.yml   extensions.yml       
          \    /                             \    /                
-          uk.yml                            de.yml
+          food.yml                          merged.yml
                                               |
-                                            at.yml
+                                            another_extended.yml
 ```
 
 A file can inherit from as many as you want. Trees can be nested as deep as you want.
@@ -151,11 +151,26 @@ config = YAML.ext_load_file 'custom2.yml', ['options','extend_file']
 ```
 
 ## Documentation
-YAML.ext_load_file(yaml_path, inheritance_key='extends', extend_existing_arrays=true)
-
-- *yaml_path* relative or absolute path to yaml file to inherit from
-- *inheritance_key* you can overwrite the default key, if you use the default 'extends' already as part of your configuration. The inheritance_key is NOT included, that means it will be deleted, in the final merged file. Default: 'extends'
-- *extend_existing_arrays* Extends existing arrays in yaml structure instead of replacing them. Default: true
+```ruby
+YAML.ext_load_file(yaml_path, inheritance_key='extends', options = {})
+```
+- `yaml_path` (String) relative or absolute path to yaml file to inherit from
+- `inheritance_key` (String) you can overwrite the default key, if you use the default 'extends' already as part of your configuration. The inheritance_key is NOT included, that means it will be deleted, in the final merged file. Default: `'extends'`
+- `options` (Hash) collection of optional options, including all options of the based `deep_merge` gem
+  - `:preserve_inheritance_key` (Boolean) Preserve inheritance key(s) from resulting yaml, does most time not make sense especially in multiple inheritance - DEFAULT: false
+  - The following options are deep merge options that can be passed by - but the defaults differ from original
+    https://github.com/danielsdeleo/deep_merge#options
+  - `:preserve_unmergeables` (Boolean) Set to true to skip any unmergeable elements from source - DEFAULT: false
+  - `:knockout_prefix` (String) Set to string value to signify prefix which deletes elements from existing element - DEFAULT: nil
+  - `:overwrite_arrays` (Boolean) Set to true if you want to avoid merging arrays - DEFAULT: false
+  - `:sort_merged_arrays` (Boolean) Set to true to sort all arrays that are merged together - DEFAULT: false
+  - `:unpack_arrays` (String) Set to string value to run "Array::join" then "String::split" against all arrays - DEFAULT: nil
+  - `:merge_hash_arrays` (Boolean) Set to true to merge hashes within arrays - DEFAULT: false
+  - `:extend_existing_arrays` (Boolean) Set to true to extend existing arrays, instead of overwriting them - DEFAULT: true
+  - `:merge_nil_values` (Boolean) Set to true to merge nil hash values, overwriting a possibly non-nil value - DEFAULT: false
+  - `:merge_debug` (Boolean) Set to true to get console output of merge process for debugging - DEFAULT: false
+
+See also rubydoc at [https://www.rubydoc.info/gems/yaml_extend](https://www.rubydoc.info/gems/yaml_extend)
 
 ## Contributing
 

data/lib/yaml_extend.rb

@@ -13,6 +13,19 @@ module YAML
   # default path in the yaml file where the files to inherit from are defined
   DEFAULT_INHERITANCE_KEY = 'extends'
   @@ext_load_key = nil
+
+  DEEP_MERGE_OPTIONS = [
+      :preserve_unmergeables,
+      :knockout_prefix,
+      :overwrite_arrays,
+      :sort_merged_arrays,
+      :unpack_arrays,
+      :merge_hash_arrays,
+      :extend_existing_arrays,
+      :merge_nil_values,
+      :merge_debug,
+  ]
+
   #
   # Set a custom inheritance key globally once.
   # So you don't need to specify it on every call of ext_load_file()
@@ -37,13 +50,29 @@ module YAML
   # Extended variant of the YAML.load_file method by providing the
   # ability to inherit from other YAML file(s)
   #
-  # @param yaml_path [String] the path to the yaml file to be loaded
-  # @param inheritance_key [String|Array] The key used in the yaml file to extend from another YAML file. Use an Array if you want to use a tree structure key like "options.extends" => ['options','extends']
-  # @param extend_existing_arrays [Boolean] extend existing arrays instead of replacing them
+  # @param [String] yaml_path the path to the yaml file to be loaded
+  # @param [String|Array] inheritance_key The key used in the yaml file to extend from another YAML file. Use an Array if you want to use a tree structure key like "options.extends" => ['options','extends']
+  # @param [Hash] options to pass, including deep_merge options as well as
+  # @option options [Boolean] :preserve_inheritance_key Preserve inheritance key(s) from resulting yaml, does most time not make sense especially in multiple inheritance - DEFAULT: false
+  #
+  # deep merge options that can be passed by - but the defaults differ from original
+  # https://github.com/danielsdeleo/deep_merge#options
+  #
+  # @option options [Boolean] :preserve_unmergeables Set to true to skip any unmergeable elements from source - DEFAULT: false
+  # @option options [String] :knockout_prefix Set to string value to signify prefix which deletes elements from existing element - DEFAULT: nil
+  # @option options [Boolean] :overwrite_arrays Set to true if you want to avoid merging arrays - DEFAULT: false
+  # @option options [Boolean] :sort_merged_arrays Set to true to sort all arrays that are merged together - DEFAULT: false
+  # @option options [String] :unpack_arrays Set to string value to run "Array::join" then "String::split" against all arrays - DEFAULT: nil
+  # @option options [Boolean] :merge_hash_arrays Set to true to merge hashes within arrays - DEFAULT: false
+  # @option options [Boolean] :extend_existing_arrays Set to true to extend existing arrays, instead of overwriting them - DEFAULT: true
+  # @option options [Boolean] :merge_nil_values Set to true to merge nil hash values, overwriting a possibly non-nil value - DEFAULT: false
+  # @option options [Boolean] :merge_debug Set to true to get console output of merge process for debugging - DEFAULT: false
+  #
+  # @param  [Boolean] options Fallback for backward compatiblity: extend existing arrays instead of replacing them (deep_merge)
   # @return [Hash] the resulting yaml config 
   #
-  def self.ext_load_file(yaml_path, inheritance_key=nil, extend_existing_arrays=true)
-    YAML.ext_load_file_recursive(yaml_path, inheritance_key, extend_existing_arrays, {})
+  def self.ext_load_file(yaml_path, inheritance_key = nil, options = {})
+    YAML.ext_load_file_recursive(yaml_path, inheritance_key, options, {})
   end
 
   private
@@ -51,32 +80,52 @@ module YAML
   #
   # @param config [Hash] a hash to be merged into the result, usually only recursivly called by the method itself
   #
-  def self.ext_load_file_recursive(yaml_path, inheritance_key, extend_existing_arrays, config)
+  def self.ext_load_file_recursive(yaml_path, inheritance_key, options = {}, config)
+    # backward compatibility to 1.0.1
+    if options == true || options == false
+      options = {extend_existing_arrays: options}
+    end
+    default_options = {
+        preserve_inheritance_key: false,
+        preserve_unmergeables: false,
+        knockout_prefix: nil,
+        overwrite_arrays: false,
+        sort_merged_arrays: false,
+        unpack_arrays: nil,
+        merge_hash_arrays: false,
+        extend_existing_arrays: true,
+        merge_nil_values: false,
+        merge_debug: false,
+    }
+    options = default_options.merge options
     private_class_method
     if inheritance_key.nil?
       inheritance_key = @@ext_load_key || DEFAULT_INHERITANCE_KEY
     end
     total_config = config.clone
-    
+
     yaml_path = YAML.make_absolute_path yaml_path
     super_config = YAML.load_file(File.open(yaml_path))
     super_inheritance_files = yaml_value_by_key inheritance_key, super_config
-    delete_yaml_key inheritance_key, super_config # we don't merge the super inheritance keys into the base yaml
-    
+    unless options[:preserve_inheritance_key]
+      delete_yaml_key inheritance_key, super_config # we don't merge the super inheritance keys into the base yaml
+    end
+
     if super_inheritance_files && super_inheritance_files != ''
       super_inheritance_files = [super_inheritance_files] unless super_inheritance_files.is_a? Array # we support strings as well as arrays of type string to extend from
       super_inheritance_files.each_with_index do |super_inheritance_file, index|
         # Extend a YAML path in an absolute directory
         if YAML.absolute_path?(super_inheritance_file)
           super_config_path = YAML.make_absolute_path(super_inheritance_file)
-        # Extend a YAML path in a relative directory
+          # Extend a YAML path in a relative directory
         else
           super_config_path = File.dirname(yaml_path) + '/' + super_inheritance_file
         end
-        total_config = YAML.ext_load_file_recursive(super_config_path, inheritance_key, extend_existing_arrays, total_config)
+        total_config = YAML.ext_load_file_recursive(super_config_path, inheritance_key, options, total_config)
       end
     end
-    total_config.deeper_merge!(super_config, extend_existing_arrays: extend_existing_arrays)
+    deep_merge_options = options.select { |k, v| DEEP_MERGE_OPTIONS.include? k }
+    total_config.deeper_merge!(super_config, deep_merge_options)
   end
 
   # some logic to ensure absolute file inheritance as well as 
@@ -90,7 +139,7 @@ module YAML
     #   [2] is the exteranl caller of YAML.ext_load_file
     base_path = File.dirname(caller_locations[2].path)
     return base_path + '/' + file_path if File.exist? base_path + '/' + file_path # relative path from yaml file
-    return Dir.pwd + '/' + file_path if File.exist? Dir.pwd + '/' + file_path     # relative path from project
+    return Dir.pwd + '/' + file_path if File.exist? Dir.pwd + '/' + file_path # relative path from project
     error_message = "Can not find absolute path of '#{file_path}'"
     unless YAML.absolute_path? file_path
       error_message += "\nAlso tried:\n- #{base_path + '/' + file_path}\n"\
@@ -102,7 +151,7 @@ module YAML
   def self.absolute_path?(path)
     private_class_method
     path.start_with?('/') || # unix like
-      (path.length >= 3 && path[1] == ':') # ms windows
+        (path.length >= 3 && path[1] == ':') # ms windows
   end
 
   # Return the value of the corresponding key
@@ -124,7 +173,7 @@ module YAML
 
   def self.valid_key_type?(key)
     key.is_a?(Array) || key.is_a?(String) ||
-        raise(InvalidKeyTypeError,"Invalid key of type '#{key.class.name}'. Valid types are String and Array.")
+        raise(InvalidKeyTypeError, "Invalid key of type '#{key.class.name}'. Valid types are String and Array.")
   end
 
   def self.delete_yaml_key(key, config)

data/lib/yaml_extend/version.rb

@@ -1,3 +1,3 @@
 module YamlExtend
-  VERSION = '1.0.1'.freeze
+  VERSION = '1.0.2'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yaml_extend
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Matthäus Beyrle
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-07-22 00:00:00.000000000 Z
+date: 2020-12-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: deep_merge
@@ -107,7 +107,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.3
+rubygems_version: 3.0.8
 signing_key:
 specification_version: 4
 summary: Extends YAML to support file based inheritance