yaml_extend 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 709ab41867197b612c61535154fe7e65bad1354c7605417d0fcad1601d45c134
4
- data.tar.gz: 72f4e212f76e450b96420bb61eeff03aa2e7dc685c6600312ebc767b34987c80
3
+ metadata.gz: b056650bc04768e6d55177c1125ef048d7f02d4764e8cecdd851f75e07b816c5
4
+ data.tar.gz: bc70a195072c63c7af2116b619f8ea5677b7fae0925128f9cfbedb8d216d7d9c
5
5
  SHA512:
6
- metadata.gz: aebb3c47f6b90557ac6683ed673a036a3b05a469b543c7bf4b3eb07108ff721410a6a5e57b5fa3a643360fe27cf59f3eb99b724a98f8bd483c34159d1d40956e
7
- data.tar.gz: e15f2449c5c4d93abb0ba1a56cde3928fd06a7219d2cedb6ee20290cabc8fe1c2a27ecd976a04558395b26e26ab42c60f080595ca458c337996861313b532494
6
+ metadata.gz: 6f3588a3e5a0a07d4102e19ed7d0c87af68f0638037d141df85c4d24c7791743b3fd449fc77a6316d44f602e157297c6560dba9dabc304ee46c36f3ccb8d9155
7
+ data.tar.gz: 7ff4beefad210bd1a503a8cfc4563042c53751099441beb04d2ad1680eebad697b87db82e10421c4ca958439bda4c850770729211db8f0f67e3e8a5b6feecc05
data/README.md CHANGED
@@ -31,11 +31,11 @@ It is possible to build inheritance trees like:
31
31
  ```
32
32
  or like this:
33
33
  ```
34
- default.yml english.yml default.yml german.yml
34
+ fruits.yml vegetables.yml default.yml extensions.yml
35
35
  \ / \ /
36
- uk.yml de.yml
36
+ food.yml merged.yml
37
37
  |
38
- at.yml
38
+ another_extended.yml
39
39
  ```
40
40
 
41
41
  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']
151
151
  ```
152
152
 
153
153
  ## Documentation
154
- YAML.ext_load_file(yaml_path, inheritance_key='extends', extend_existing_arrays=true)
155
-
156
- - *yaml_path* relative or absolute path to yaml file to inherit from
157
- - *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'
158
- - *extend_existing_arrays* Extends existing arrays in yaml structure instead of replacing them. Default: true
154
+ ```ruby
155
+ YAML.ext_load_file(yaml_path, inheritance_key='extends', options = {})
156
+ ```
157
+ - `yaml_path` (String) relative or absolute path to yaml file to inherit from
158
+ - `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'`
159
+ - `options` (Hash) collection of optional options, including all options of the based `deep_merge` gem
160
+ - `:preserve_inheritance_key` (Boolean) Preserve inheritance key(s) from resulting yaml, does most time not make sense especially in multiple inheritance - DEFAULT: false
161
+ - The following options are deep merge options that can be passed by - but the defaults differ from original
162
+ https://github.com/danielsdeleo/deep_merge#options
163
+ - `:preserve_unmergeables` (Boolean) Set to true to skip any unmergeable elements from source - DEFAULT: false
164
+ - `:knockout_prefix` (String) Set to string value to signify prefix which deletes elements from existing element - DEFAULT: nil
165
+ - `:overwrite_arrays` (Boolean) Set to true if you want to avoid merging arrays - DEFAULT: false
166
+ - `:sort_merged_arrays` (Boolean) Set to true to sort all arrays that are merged together - DEFAULT: false
167
+ - `:unpack_arrays` (String) Set to string value to run "Array::join" then "String::split" against all arrays - DEFAULT: nil
168
+ - `:merge_hash_arrays` (Boolean) Set to true to merge hashes within arrays - DEFAULT: false
169
+ - `:extend_existing_arrays` (Boolean) Set to true to extend existing arrays, instead of overwriting them - DEFAULT: true
170
+ - `:merge_nil_values` (Boolean) Set to true to merge nil hash values, overwriting a possibly non-nil value - DEFAULT: false
171
+ - `:merge_debug` (Boolean) Set to true to get console output of merge process for debugging - DEFAULT: false
172
+
173
+ See also rubydoc at [https://www.rubydoc.info/gems/yaml_extend](https://www.rubydoc.info/gems/yaml_extend)
159
174
 
160
175
  ## Contributing
161
176
 
@@ -13,6 +13,19 @@ module YAML
13
13
  # default path in the yaml file where the files to inherit from are defined
14
14
  DEFAULT_INHERITANCE_KEY = 'extends'
15
15
  @@ext_load_key = nil
16
+
17
+ DEEP_MERGE_OPTIONS = [
18
+ :preserve_unmergeables,
19
+ :knockout_prefix,
20
+ :overwrite_arrays,
21
+ :sort_merged_arrays,
22
+ :unpack_arrays,
23
+ :merge_hash_arrays,
24
+ :extend_existing_arrays,
25
+ :merge_nil_values,
26
+ :merge_debug,
27
+ ]
28
+
16
29
  #
17
30
  # Set a custom inheritance key globally once.
18
31
  # So you don't need to specify it on every call of ext_load_file()
@@ -37,13 +50,29 @@ module YAML
37
50
  # Extended variant of the YAML.load_file method by providing the
38
51
  # ability to inherit from other YAML file(s)
39
52
  #
40
- # @param yaml_path [String] the path to the yaml file to be loaded
41
- # @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']
42
- # @param extend_existing_arrays [Boolean] extend existing arrays instead of replacing them
53
+ # @param [String] yaml_path the path to the yaml file to be loaded
54
+ # @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']
55
+ # @param [Hash] options to pass, including deep_merge options as well as
56
+ # @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
57
+ #
58
+ # deep merge options that can be passed by - but the defaults differ from original
59
+ # https://github.com/danielsdeleo/deep_merge#options
60
+ #
61
+ # @option options [Boolean] :preserve_unmergeables Set to true to skip any unmergeable elements from source - DEFAULT: false
62
+ # @option options [String] :knockout_prefix Set to string value to signify prefix which deletes elements from existing element - DEFAULT: nil
63
+ # @option options [Boolean] :overwrite_arrays Set to true if you want to avoid merging arrays - DEFAULT: false
64
+ # @option options [Boolean] :sort_merged_arrays Set to true to sort all arrays that are merged together - DEFAULT: false
65
+ # @option options [String] :unpack_arrays Set to string value to run "Array::join" then "String::split" against all arrays - DEFAULT: nil
66
+ # @option options [Boolean] :merge_hash_arrays Set to true to merge hashes within arrays - DEFAULT: false
67
+ # @option options [Boolean] :extend_existing_arrays Set to true to extend existing arrays, instead of overwriting them - DEFAULT: true
68
+ # @option options [Boolean] :merge_nil_values Set to true to merge nil hash values, overwriting a possibly non-nil value - DEFAULT: false
69
+ # @option options [Boolean] :merge_debug Set to true to get console output of merge process for debugging - DEFAULT: false
70
+ #
71
+ # @param [Boolean] options Fallback for backward compatiblity: extend existing arrays instead of replacing them (deep_merge)
43
72
  # @return [Hash] the resulting yaml config
44
73
  #
45
- def self.ext_load_file(yaml_path, inheritance_key=nil, extend_existing_arrays=true)
46
- YAML.ext_load_file_recursive(yaml_path, inheritance_key, extend_existing_arrays, {})
74
+ def self.ext_load_file(yaml_path, inheritance_key = nil, options = {})
75
+ YAML.ext_load_file_recursive(yaml_path, inheritance_key, options, {})
47
76
  end
48
77
 
49
78
  private
@@ -51,32 +80,52 @@ module YAML
51
80
  #
52
81
  # @param config [Hash] a hash to be merged into the result, usually only recursivly called by the method itself
53
82
  #
54
- def self.ext_load_file_recursive(yaml_path, inheritance_key, extend_existing_arrays, config)
83
+ def self.ext_load_file_recursive(yaml_path, inheritance_key, options = {}, config)
84
+ # backward compatibility to 1.0.1
85
+ if options == true || options == false
86
+ options = {extend_existing_arrays: options}
87
+ end
88
+ default_options = {
89
+ preserve_inheritance_key: false,
90
+ preserve_unmergeables: false,
91
+ knockout_prefix: nil,
92
+ overwrite_arrays: false,
93
+ sort_merged_arrays: false,
94
+ unpack_arrays: nil,
95
+ merge_hash_arrays: false,
96
+ extend_existing_arrays: true,
97
+ merge_nil_values: false,
98
+ merge_debug: false,
99
+ }
100
+ options = default_options.merge options
55
101
  private_class_method
56
102
  if inheritance_key.nil?
57
103
  inheritance_key = @@ext_load_key || DEFAULT_INHERITANCE_KEY
58
104
  end
59
105
  total_config = config.clone
60
-
106
+
61
107
  yaml_path = YAML.make_absolute_path yaml_path
62
108
  super_config = YAML.load_file(File.open(yaml_path))
63
109
  super_inheritance_files = yaml_value_by_key inheritance_key, super_config
64
- delete_yaml_key inheritance_key, super_config # we don't merge the super inheritance keys into the base yaml
65
-
110
+ unless options[:preserve_inheritance_key]
111
+ delete_yaml_key inheritance_key, super_config # we don't merge the super inheritance keys into the base yaml
112
+ end
113
+
66
114
  if super_inheritance_files && super_inheritance_files != ''
67
115
  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
68
116
  super_inheritance_files.each_with_index do |super_inheritance_file, index|
69
117
  # Extend a YAML path in an absolute directory
70
118
  if YAML.absolute_path?(super_inheritance_file)
71
119
  super_config_path = YAML.make_absolute_path(super_inheritance_file)
72
- # Extend a YAML path in a relative directory
120
+ # Extend a YAML path in a relative directory
73
121
  else
74
122
  super_config_path = File.dirname(yaml_path) + '/' + super_inheritance_file
75
123
  end
76
- total_config = YAML.ext_load_file_recursive(super_config_path, inheritance_key, extend_existing_arrays, total_config)
124
+ total_config = YAML.ext_load_file_recursive(super_config_path, inheritance_key, options, total_config)
77
125
  end
78
126
  end
79
- total_config.deeper_merge!(super_config, extend_existing_arrays: extend_existing_arrays)
127
+ deep_merge_options = options.select { |k, v| DEEP_MERGE_OPTIONS.include? k }
128
+ total_config.deeper_merge!(super_config, deep_merge_options)
80
129
  end
81
130
 
82
131
  # some logic to ensure absolute file inheritance as well as
@@ -90,7 +139,7 @@ module YAML
90
139
  # [2] is the exteranl caller of YAML.ext_load_file
91
140
  base_path = File.dirname(caller_locations[2].path)
92
141
  return base_path + '/' + file_path if File.exist? base_path + '/' + file_path # relative path from yaml file
93
- return Dir.pwd + '/' + file_path if File.exist? Dir.pwd + '/' + file_path # relative path from project
142
+ return Dir.pwd + '/' + file_path if File.exist? Dir.pwd + '/' + file_path # relative path from project
94
143
  error_message = "Can not find absolute path of '#{file_path}'"
95
144
  unless YAML.absolute_path? file_path
96
145
  error_message += "\nAlso tried:\n- #{base_path + '/' + file_path}\n"\
@@ -102,7 +151,7 @@ module YAML
102
151
  def self.absolute_path?(path)
103
152
  private_class_method
104
153
  path.start_with?('/') || # unix like
105
- (path.length >= 3 && path[1] == ':') # ms windows
154
+ (path.length >= 3 && path[1] == ':') # ms windows
106
155
  end
107
156
 
108
157
  # Return the value of the corresponding key
@@ -124,7 +173,7 @@ module YAML
124
173
 
125
174
  def self.valid_key_type?(key)
126
175
  key.is_a?(Array) || key.is_a?(String) ||
127
- raise(InvalidKeyTypeError,"Invalid key of type '#{key.class.name}'. Valid types are String and Array.")
176
+ raise(InvalidKeyTypeError, "Invalid key of type '#{key.class.name}'. Valid types are String and Array.")
128
177
  end
129
178
 
130
179
  def self.delete_yaml_key(key, config)
@@ -1,3 +1,3 @@
1
1
  module YamlExtend
2
- VERSION = '1.0.1'.freeze
2
+ VERSION = '1.0.2'.freeze
3
3
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: yaml_extend
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.0.1
4
+ version: 1.0.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Matthäus Beyrle
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2020-07-22 00:00:00.000000000 Z
11
+ date: 2020-12-01 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: deep_merge
@@ -107,7 +107,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
107
107
  - !ruby/object:Gem::Version
108
108
  version: '0'
109
109
  requirements: []
110
- rubygems_version: 3.1.3
110
+ rubygems_version: 3.0.8
111
111
  signing_key:
112
112
  specification_version: 4
113
113
  summary: Extends YAML to support file based inheritance