yaml_extend 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5ab39dd4d1b790d1d73de077e99b30963040951ef98b583085ce58331083144
-  data.tar.gz: a67afd6dce0a398d466efda67c773d00bdaffeaa5eddac74ab07469e425e9177
+  metadata.gz: e05fc2afe5d8f44419bf0c3d7a2fc801ab04e81864114b000080f6beea8337fd
+  data.tar.gz: 46ac756ebcb6b620930eeda313673c2a5990d6e78f8fe7bf4c609576664429a3
 SHA512:
-  metadata.gz: 604d8a4232dfe3eed9d74d8077ee16c9cfe7341c730fc06667a0bfdd0ab24d3a9bdf67e0ee5b87f4230d1b14c010d9b187b3dd5d34d8db3b3f734fca544dad46
-  data.tar.gz: 12cee38d68fabaee77b4cfd039d17bafce15b3545fd4937bf25135a8c5a812c05072162b8592c0fd742751a572be6de331e94ccd43786fe0268d8710d09c8b3b
+  metadata.gz: 87f97749740b0954e62bf184418950f57d19612fdead49ae1cc7afb4ce6291f842bff5a887d3b4ba8fda1e2d512a61eb6a9eddf17737fe45136615138ddec27b
+  data.tar.gz: a922bc2aa0479db54e03bda900535bad1abfb23a03360f1024aa0caea3a7a0d478c6a6861a8c8af775f9e4df63dc8b88bac93f6e755cb8fd66fd90fe941e5c45

data/README.md

@@ -3,16 +3,6 @@
 Extends YAML to support file based inheritance,
 to e.g. to build a configuration hierachy.
 
-It is possible to build inheritance trees like
-```
-default.yml   english.yml          default.yml   german.yml         de.yml
-         \    /                             \    /                    |
-          uk.yml                            de.yml                  at.yml
-```
-
-A file can inherit from as many as you want. Trees can be nested as deep as you want.
-The child file overwrites same values if given in the parent file.
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -28,6 +18,24 @@ And then execute:
 Or install it yourself as:
 
     $ gem install yaml_extend
+    
+## Common information
+
+It is possible to build inheritance trees like
+```
+default.yml   english.yml          default.yml   german.yml         de.yml
+         \    /                             \    /                    |
+          uk.yml                            de.yml                  at.yml
+```
+
+A file can inherit from as many as you want. Trees can be nested as deep as you want.
+
+YAML files are deep merged, the latest specified child file overwrites the former ones.
+Array values are merged as well by default. You can specifiy this with the 3rd Parameter.
+
+The files to inherit from are specified by the key 'extends:' in the YAML file.
+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.
@@ -36,7 +44,10 @@ This method works like the original YAML#load_file, by extending it with file in
 
 ### Examples
 
-```
+#### Basic Inheritance
+Given the following both files are defined:
+
+```yaml
 # start.yml
 extends: 'super.yml'
 data:
@@ -46,7 +57,7 @@ data:
         - 'Raspberrys'
 ```
 
-```
+```yaml
 # super.yml
 data:
     name: 'Unknown'
@@ -55,14 +66,16 @@ data:
         - 'Bananas'
         - 'Apples'
 ```
-#### Basic Inheritance
-```
-YAML.ext_load_file('start.yml')
-```
 
-results in
+When you then call #ext_load_file
 
+```ruby
+YAML.ext_load_file 'start.yml'
 ```
+
+the returned YAML value results in
+
+```yaml
 data:
     name: 'Mr. Superman'
     age: 134
@@ -75,7 +88,10 @@ data:
 
 #### Inherit from several files
 
-```
+If you want to inherit from several files, you can specify a list (Array) of files.
+They are merged from top to bottom, so the latest file "wins" - that means it overwrites duplicate values if they exist with the values in the latest file where they occur.
+
+```yaml
 extends:
     - 'super_file.yml'
     - 'parent_file.yml'
@@ -83,19 +99,36 @@ extends:
 ```
 
 #### Using custom extend key
-```
+
+If you don't want to use the default key 'extends:', you can specify your own custom key in two ways.
+
+```yaml
 #custom1.yml
 inherit_from:
     - 'super_file.yml'
 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.
+```ruby
+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'
 ```
-YAML.ext_load_file('custom1.yml','inherit_from')
+##### Reset the global key
+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
 ```
 #### Using custom nested extend key
-```
+```yaml
 #custom2.yml
 options:
     extend_file: 'super_file.yml'
@@ -104,8 +137,8 @@ foo: 'bar'
 ...
 ```
 
-```
-YAML.ext_load_file('custom2.yml',['options','extend_file'])
+```ruby
+YAML.ext_load_file 'custom2.yml', ['options','extend_file']
 ```
 
 ## Documentation

data/Rakefile

@@ -1,6 +1,8 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+task :default do
+  system 'rake --tasks'
+end
 
-task :default => :spec
+RSpec::Core::RakeTask.new(:spec)

data/lib/yaml_extend.rb

@@ -10,6 +10,28 @@ require_relative 'custom_errors/invalid_key_type_error'
 #
 
 module YAML
+  # default path in the yaml file where the files to inherit from are defined
+  DEFAULT_INHERITANCE_KEY = 'extends'
+  @@ext_load_key = nil
+  #
+  # Set a custom inheritance key globally once.
+  # So you don't need to specify it on every call of ext_load_file()
+  #
+  # @param key [String|Array<String>|nil] the key in the yaml file, containing the file strings to extend from. Set nil or call #reset_load_key to reset the key.
+  def self.ext_load_key=(key)
+    if key.is_a?(String) || key.is_a?(Array) || key.nil?
+      @@ext_load_key = key
+    else
+      raise "Parameter 'key' must be of type String or Array<String> or nil"
+    end
+  end
+
+  #
+  # Reset the ext_load_key and use the default settings
+  #
+  def self.reset_load_key()
+    @@ext_load_key = nil
+  end
   #
   # Extended variant of the #load_file method by providing the 
   # ability to inherit from other YAML file(s)
@@ -21,7 +43,10 @@ module YAML
   #
   # @return [Hash] the resulting yaml config 
   #
-  def self.ext_load_file(yaml_path, inheritance_key='extends', extend_existing_arrays=true, config = {})
+  def self.ext_load_file(yaml_path, inheritance_key=nil, extend_existing_arrays=true, config = {})
+    if inheritance_key.nil?
+      inheritance_key = @@ext_load_key || DEFAULT_INHERITANCE_KEY
+    end
     total_config ||= {}
     yaml_path = YAML.make_absolute_path yaml_path
     super_config = YAML.load_file(File.open(yaml_path))

data/lib/yaml_extend/version.rb

@@ -1,3 +1,3 @@
 module YamlExtend
-  VERSION = '0.1.1'.freeze
+  VERSION = '0.2.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yaml_extend
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Matthäus Beyrle
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-02-22 00:00:00.000000000 Z
+date: 2018-03-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: deep_merge