yaml_extend 0.2.3 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 805447b25c0ac209e4c59d10d8c9f5dc2432a7271aafd0e9d9f16ccd984e6522
-  data.tar.gz: 654ad7daaec70841729bcef0131f4e29108456a8fdd17fc9898eedbd89f69e4f
+  metadata.gz: b056650bc04768e6d55177c1125ef048d7f02d4764e8cecdd851f75e07b816c5
+  data.tar.gz: bc70a195072c63c7af2116b619f8ea5677b7fae0925128f9cfbedb8d216d7d9c
 SHA512:
-  metadata.gz: 5af7d94d3783ffdb7a3c28fe5e2459d2c3423197f25939bfe3d5f2e88da1db044e94e38d08e8751ca165d4c89b656adc1f6a2104f5065eade9d2d6c34e59cb07
-  data.tar.gz: ebd14878f223d0bdb4f6c2a480e1a3d9ac91131f98db8202d4a4dda35347ad24457e0b86cc57765b48bb8a1ce02742280207bd882e1516a6d80728234d4b28df
+  metadata.gz: 6f3588a3e5a0a07d4102e19ed7d0c87af68f0638037d141df85c4d24c7791743b3fd449fc77a6316d44f602e157297c6560dba9dabc304ee46c36f3ccb8d9155
+  data.tar.gz: 7ff4beefad210bd1a503a8cfc4563042c53751099441beb04d2ad1680eebad697b87db82e10421c4ca958439bda4c850770729211db8f0f67e3e8a5b6feecc05

data/CODE_OF_CONDUCT.md

@@ -55,7 +55,7 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at m.beyrle@walz.de. All
+reported by contacting the project team at yaml_extend.gemspec@mail.magynhard.de. All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
 obligated to maintain confidentiality with regard to the reporter of an incident.

data/README.md

@@ -22,11 +22,20 @@ Or install it yourself as:
     
 ## Common information
 
-It is possible to build inheritance trees like
+It is possible to build inheritance trees like:
 ```
-default.yml   english.yml          default.yml   german.yml         de.yml
-         \    /                             \    /                    |
-          uk.yml                            de.yml                  at.yml
+     defaults.yml   
+  ________\_________    
+  \        \        \                         
+ dev.yml  int.yml  prod.yml                   
+```
+or like this:
+```
+fruits.yml   vegetables.yml          default.yml   extensions.yml       
+         \    /                             \    /                
+          food.yml                          merged.yml
+                                              |
+                                            another_extended.yml
 ```
 
 A file can inherit from as many as you want. Trees can be nested as deep as you want.
@@ -39,9 +48,9 @@ That key can be customized if you prefer another one.
 See the examples below.
 
 ## Usage
-yaml_extend adds the method YAML#ext_load_file to YAML.
+yaml_extend adds the method YAML.ext_load_file to YAML.
 
-This method works like the original YAML#load_file, by extending it with file inheritance.
+This method works like the original YAML.load_file, by extending it with file inheritance.
 
 ### Examples
 
@@ -68,10 +77,10 @@ data:
         - 'Apples'
 ```
 
-When you then call #ext_load_file
+When you then call `ext_load_file`
 
 ```ruby
-YAML.ext_load_file 'start.yml'
+config = YAML.ext_load_file 'start.yml'
 ```
 
 the returned YAML value results in
@@ -111,19 +120,18 @@ foo: 'bar'
 ...
 ```
 ##### 1. Specify by parameter
-You can specify the key by parameter, this is the way to go if you want to  use the different key only once or you use the #ext_load_file method only once in your application.
+You can specify the key by parameter, this is the way to go if you want to  use the different key only once or you use the `ext_load_file` method only once in your application.
 ```ruby
-YAML.ext_load_file 'custom1.yml', 'inherit_from'
+config = YAML.ext_load_file 'custom1.yml', 'inherit_from'
 ```
 ##### 2. Global configuration of the key
 You can specify the key by configuration globally. So you only need to set the key once and not as parameter anymore
 ```ruby
 YAML.ext_load_key = 'inherit_from'
-YAML.ext_load_file 'custom1.yml'
-YAML.ext_load_file 'custom2.yml'
+config = YAML.ext_load_file 'custom1.yml'
 ```
 ##### Reset the global key
-To reset the global inheritance key, you can either set it to nil or call the #reset_load_key  method.
+To reset the global inheritance key, you can either set it to nil or call the `reset_load_key`  method.
 ```ruby
 YAML.reset_load_key # more readable
 YAML.ext_load_key = nil # more explicit
@@ -139,16 +147,30 @@ foo: 'bar'
 ```
 
 ```ruby
-YAML.ext_load_file 'custom2.yml', ['options','extend_file']
+config = YAML.ext_load_file 'custom2.yml', ['options','extend_file']
 ```
 
 ## Documentation
-YAML#ext_load_file(yaml_path, inheritance_key='extends', extend_existing_arrays=true, config = {})
-
-- *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
-- *config* only intended to be used by the method itself due recursive algorithm
+```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

@@ -3,8 +3,6 @@ require 'yaml_extend/version'
 require 'yaml'
 require 'deep_merge/rails_compat'
 
-require_relative 'yaml_extend/yaml_extend_helper'
-
 require_relative 'custom_errors/invalid_key_type_error'
 
 #
@@ -15,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()
@@ -34,48 +45,99 @@ module YAML
   def self.reset_load_key()
     @@ext_load_key = nil
   end
+
   #
-  # Extended variant of the #load_file method by providing the 
+  # 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 config [Hash] a hash to be merged into the result, usually only recursivly called by the method itself
+  # @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, config = {})
+  def self.ext_load_file(yaml_path, inheritance_key = nil, options = {})
+    YAML.ext_load_file_recursive(yaml_path, inheritance_key, options, {})
+  end
+
+  private
+
+  #
+  # @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, 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 ||= {}
+    total_config = config.clone
+
     yaml_path = YAML.make_absolute_path yaml_path
-    super_config = YamlExtendHelper.encode_booleans YAML.load_file(File.open(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
-    merged_config = config.clone.deeper_merge(super_config, extend_existing_arrays: extend_existing_arrays)
+    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|
-        super_config_path = File.dirname(yaml_path) + '/' + super_inheritance_file
-        total_config = YamlExtendHelper.encode_booleans YAML.ext_load_file(super_config_path, inheritance_key, extend_existing_arrays, total_config.deeper_merge(merged_config, extend_existing_arrays: extend_existing_arrays))
+        # 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
+        else
+          super_config_path = File.dirname(yaml_path) + '/' + super_inheritance_file
+        end
+        total_config = YAML.ext_load_file_recursive(super_config_path, inheritance_key, options, total_config)
       end
-      YamlExtendHelper.decode_booleans total_config
-    else
-      delete_yaml_key inheritance_key, merged_config
-      YamlExtendHelper.decode_booleans merged_config
     end
+    deep_merge_options = options.select { |k, v| DEEP_MERGE_OPTIONS.include? k }
+    total_config.deeper_merge!(super_config, deep_merge_options)
   end
 
-  private
-
   # some logic to ensure absolute file inheritance as well as 
   # relative file inheritance in yaml files  
   def self.make_absolute_path(file_path)
     private_class_method
     return file_path if YAML.absolute_path?(file_path) && File.exist?(file_path)
-    base_path = File.dirname(caller_locations[1].path)
+    # caller_locations returns the current execution stack
+    #   [0] is the call from ext_load_file_recursive,
+    #   [1] is inside ext_load_file,
+    #   [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
     error_message = "Can not find absolute path of '#{file_path}'"
@@ -89,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
@@ -111,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 = '0.2.3'.freeze
+  VERSION = '1.0.2'.freeze
 end

data/yaml_extend.gemspec

@@ -31,7 +31,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'deep_merge', '~> 1.1'
 
-  spec.add_development_dependency 'bundler',  '~> 1.14'
-  spec.add_development_dependency 'rake',     '~> 10.0'
-  spec.add_development_dependency 'rspec',    '~> 3.0'
+  spec.add_development_dependency 'bundler',  '>= 1.14'
+  spec.add_development_dependency 'rake',     '>= 10.0'
+  spec.add_development_dependency 'rspec',    '>= 3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yaml_extend
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 1.0.2
 platform: ruby
 authors:
 - Matthäus Beyrle
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2018-12-04 00:00:00.000000000 Z
+date: 2020-12-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: deep_merge
@@ -28,45 +28,45 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.14'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
-description: 
+description:
 email:
 - yaml_extend.gemspec@mail.magynhard.de
 executables: []
@@ -86,14 +86,13 @@ files:
 - lib/custom_errors/invalid_key_type_error.rb
 - lib/yaml_extend.rb
 - lib/yaml_extend/version.rb
-- lib/yaml_extend/yaml_extend_helper.rb
 - yaml_extend.gemspec
 homepage: https://github.com/magynhard/yaml_extend
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -108,9 +107,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.7
-signing_key: 
+rubygems_version: 3.0.8
+signing_key:
 specification_version: 4
 summary: Extends YAML to support file based inheritance
 test_files: []

data/lib/yaml_extend/yaml_extend_helper.rb

@@ -1,68 +0,0 @@
-
-#
-# This class includes a workaround patch, providing a solution of the unaccepted pull request
-# 'false is not overriden by true if preserve_unmergeables'
-# https://github.com/danielsdeleo/deep_merge/pull/28
-#
-# It ensures, that booleans can be merged correctly, by en- and decoding them to strings, before and after merging
-# see #encode_boolens and #decode_booleans
-#
-
-class YamlExtendHelper
-
-  TRUE_CLASS_ENCODED = '#={TrueClass}=#'
-  FALSE_CLASS_ENCODED = '#={FalseClass}=#'
-
-  def self.encode_booleans(hash)
-    hash.each_with_object({}) do |(k,v),g|
-      g[k] = if v.is_a? Hash
-               YamlExtendHelper.encode_booleans(v)
-             elsif v.is_a? Array
-               v.each_with_index do |av, ai|
-                  v[ai] = if av.is_a? Hash
-                            YamlExtendHelper.encode_booleans(av)
-                          elsif av.is_a? TrueClass
-                            TRUE_CLASS_ENCODED
-                          elsif av.is_a? FalseClass
-                            FALSE_CLASS_ENCODED
-                          else
-                            av
-                          end
-               end
-             elsif v.is_a? TrueClass
-               TRUE_CLASS_ENCODED
-             elsif v.is_a? FalseClass
-               FALSE_CLASS_ENCODED
-             else
-               v
-             end
-    end
-  end
-
-  def self.decode_booleans(hash)
-    hash.each_with_object({}) do |(k,v),g|
-      g[k] = if v.is_a? Hash
-               YamlExtendHelper.decode_booleans(v)
-             elsif v.is_a? Array
-               v.each_with_index do |av, ai|
-                 v[ai] = if av.is_a? Hash
-                           YamlExtendHelper.decode_booleans(av)
-                         elsif av === TRUE_CLASS_ENCODED
-                           true
-                         elsif av === FALSE_CLASS_ENCODED
-                           false
-                         else
-                           av
-                         end
-               end
-             elsif v === TRUE_CLASS_ENCODED
-               true
-             elsif v === FALSE_CLASS_ENCODED
-               false
-             else
-               v
-             end
-    end
-  end
-
-end