super_stack 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a294ebb0f063bbe92fa34ae949daa7600db5143d
-  data.tar.gz: 138e2b64f4dcff40756b94ff72cd6fd2fbf70dcf
+  metadata.gz: 9a35826dd6aa1c436784d40750be42b5d903a9e8
+  data.tar.gz: 4036c864e855b5a9f420953ef0d99f4e83acbc36
 SHA512:
-  metadata.gz: d459615c5cf1dc58f135cac32e4c39963c976d2ae62013391788b193be1c33b1b606745250b7dcab6edc7636d2aa64850fe07ce9a410b4d4f68d815a2126a948
-  data.tar.gz: a68bf1915f90e400d95072b7d82078a77288698778e6fab033d89f12e6b52f72e2edca02bdacba6f6d399f9e08d510c06335614e870ef1e2cf6af84ffbe2d4e0
+  metadata.gz: 79a519c5e1a9f202ce7ff2d2be502f94adb204a6b6c9e52775e56d6d0c0dd679add921e772c250bafcbba89c925872bbd7d10dc74964231b1e4af91281968579
+  data.tar.gz: b0a89dffd813a711c242498bcda46882c1f3b5dd941fe79056aa423cf57c4bed0888e88946b151af11b312bce2430eceeaf6ca75a1ef21a95fb1f3f61ddf4143

data/README.md

@@ -21,7 +21,96 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Create a manager
+
+The manager contains your different layers (hashes basically), allows you to set priorities among them, and provides
+a policy to merge them.
+
+To use the manager, you just need to:
+
+```ruby
+require 'super_stack'
+
+manager = SuperStack::Manager.new
+```
+
+This is from the manager, that you will get the result of the merge of the different layers. Use `manager[]` to access
+the result of the merge of all layers as a hash. It will be done according to the priority the layers have and the merge
+policy chosen.
+
+You can directly access to a particular key of the resulting merging by simply doing `manager[:your_key]` like you would
+do with a hash. (`manager` itself has no `Hash` in its ancestors, whereas `manager[]` *is* actually a `Hash`).
+
+**None of the layers is modified by the manager**.
+
+
+### Layers
+
+Layers are actually simple hashes that include the `SuperStack::LayerWrapper` module. Therefore you can create a layer by
+different means:
+
+* by invoking `SuperStack::Layer.new`. You can use you all options you would use on a hash.
+* by calling `SuperStack::LayerWrapper.from_hash(your_hash)`. That will just add the module `SuperStack::LayerWrapper`
+  to your hash.
+* by adding manually adding the module to your hash (`your_hash.extend SuperStack::LayerWrapper`), which is strictly
+  equivalent to the previous method.
+
+When you create a new layer from scratch or by extending your own hash, it has automatically a name assigned, and no
+particular priority. but as soon as it is added to a manager by doing either `manager << your_hash_or_layer` or
+`manager.add_layer(your_hash_or_layer)`, it will see its name automatically changed (numbers automatically added) **if
+the name conflicts with another layer already handled by the manager**.
+
+You can notice by the way that it gives a third way to create a layer from a hash, as when adding a hash to a manager,
+it automatically adds the `SuperStack::LayerWrapper` module to the hash.
+
+Layers can be populated from a file anytime using the `load` method:
+
+```ruby
+layer = SuperStack::Layer.new.load 'a_file_somewhere'
+# Once loaded you can get the file name used to load the layed anytime
+puts layer.file_name
+# And you can load or reload the layer
+layer.has_file? # => true
+layer.load
+layer.reload
+```
+
+On top of this you can reload all the layers which have an associated file at once using the manager. If a layer has
+no associated `file_name`, it won't be altered.
+
+```ruby
+layer1 = SuperStack::Layer.new.load 'a_file_somewhere'
+layer1 = SuperStack::Layer.new.load 'another_file_somewhere'
+manager = SuperStack::Manager.new
+
+manager << layer1
+manager << layer2
+
+manager.reload_layers
+```
+
+
+### Merge policies
+
+You can get the list of merge policies by doing `SuperStack::MergePolicies.list`, but basically, four types currently
+exist:
+
+* `SuperStack::MergePolicies::KeepPolicy`, that when merging two layers will keep the first one (the one you are merging
+  to).
+* `SuperStack::MergePolicies::OverridePolicy`, that when merging two layers will keep the second one(the one you are
+  merging with).
+* `SuperStack::MergePolicies::StandardMergePolicy`, that will perform the ruby standard `Hash#merge` method. There are
+  a lot of limitations with it (like not recursive, not merging arrays within hash etc... read ruby doc for more).
+  **This is the default merge method**
+* `SuperStack::MergePolicies::FullMergePolicy` is actually using the [deep_merge gem][DMG] to merge two hashes. It is
+  fully merging two hashes including arrays etc... Only when two types are incompatible (like Array replacing a String),
+  the second one replaces the first. Much more complete implementation than the one in ActiveSupport. The way it is used
+  in the gem is compliant with both the plain Ruby and the Rails implementations (see [the documentation][DMGithub])
+
+The manager has a `default_merge_policy`, but each layer can have its own `merge_policy`. By default the internal merge
+process will use the `default_merge_policy` except if a layer specifies its own.
+
+In most cases you will just have to set the merge policy at the manager level using `default_merge_policy=`.
 
 ## Contributing
 
@@ -30,3 +119,8 @@ TODO: Write usage instructions here
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+
+[DMG]:      https://rubygems.org/gems/deep_merge        "Deep Merge gem"
+[DMGithub]: https://github.com/danielsdeleo/deep_merge  "Deep Merge Github project"
+

data/lib/super_stack/layer_wrapper.rb

@@ -4,6 +4,7 @@ module SuperStack
   module LayerWrapper
 
     include Comparable
+    include SuperStack::MergePolicies::PolicyHandler
 
     DEFAULT_LAYER_NAME = 'Unknown layer'
 
@@ -22,9 +23,14 @@ module SuperStack
       @name || DEFAULT_LAYER_NAME
     end
 
-    def load(file_name, type = :yaml)
-      raise 'Invalid file' unless File.readable? file_name
+    def load(file_name=self.file_name, type = :yaml)
+      raise "Cannot read file '#{file_name}'" unless File.readable? file_name
       load_from_yaml file_name if type == :yaml
+      self
+    end
+
+    def reload
+      self.load if has_file?
     end
 
     def has_file?
@@ -37,7 +43,17 @@ module SuperStack
     end
 
     def inspect
-      "name: #{name}, priority: #{priority}, #{super}"
+      file_add_on = has_file? ? "file: '#{file_name}', " : ''
+      priority_add_on = priority.nil? ? '' : "priority: #{priority}, "
+      "{name: '#{name}', #{priority_add_on}#{file_add_on}#{super}}"
+    end
+
+    def to_s
+      inspect
+    end
+
+    def self.from_hash(hash)
+      hash.extend self
     end
 
     private
@@ -46,8 +62,9 @@ module SuperStack
       begin
         self.replace Hash[YAML::load(File.open(file_name)).map { |k, v| [k.to_sym, v] }]
 
-      rescue  NoMethodError
+      rescue  NoMethodError => e
         # Empty file...
+        raise "Invalid file '#{file_name}'" unless e.message =~ /false:FalseClass/
       end
       @file_name = file_name
     end

data/lib/super_stack/manager.rb

@@ -1,18 +1,28 @@
 module SuperStack
   class Manager
 
-    DEFAULT_INTERVAL = 10
+    include SuperStack::MergePolicies::PolicyHandler
+    alias_method :default_merge_policy, :merge_policy
+    alias_method :'default_merge_policy=', :'merge_policy='
 
-    attr_reader :layers, :merge_policy
+    DEFAULT_PRIORITY_INTERVAL = 10
+    DEFAULT_MERGE_POLICY = SuperStack::MergePolicies::StandardMergePolicy
+
+    attr_reader :layers
+
+    def initialize
+      @layers = {}
+      self.default_merge_policy = DEFAULT_MERGE_POLICY
+    end
 
     def [](filter=nil)
-      raise 'Manager not ready (no merge policy specified)' unless ready?
       layers = to_a
       return [] if layers.empty?
       return layers[0] if layers.count == 1
       first_layer = layers.shift
       res = layers.inject(first_layer) do |stack, layer|
-        merge_policy.merge stack, layer
+        policy_to_apply = layer.merge_policy.nil? ? default_merge_policy : layer.merge_policy
+        policy_to_apply.merge stack, layer
       end
       if filter.nil?
         res
@@ -21,36 +31,45 @@ module SuperStack
       end
     end
 
-    def initialize
-      @layers = {}
-    end
-
     def to_a
       layers.values.sort
     end
 
     def add_layer(layer)
-      raise 'Layer should have a name' unless layer.respond_to? :name
-      raise 'Layer already existing' if layers.keys.include? layer.name
+      if layer.is_a? Hash and not layer.class.included_modules.include? SuperStack::LayerWrapper
+        SuperStack::LayerWrapper.from_hash layer
+      end
+      set_valid_name_for layer if layers.keys.include? layer.name
       layer.priority = get_unused_priority if layer.priority.nil?
       layers[layer.name] = layer
     end
 
-    def merge_policy=(policy)
-      raise "Invalid merge policy #{policy}" unless SuperStack::MergePolicies.list.include? policy
-      @merge_policy = policy
+    def <<(layer)
+      add_layer layer
     end
 
-    def ready?
-      !@merge_policy.nil?
+    def reload_layers
+      layers.values.each &:reload
     end
 
     private
 
     def get_unused_priority
       ordered = self.to_a
-      return DEFAULT_INTERVAL if ordered.empty?
-      ordered.last.priority + DEFAULT_INTERVAL
+      return DEFAULT_PRIORITY_INTERVAL if ordered.empty?
+      ordered.last.priority + DEFAULT_PRIORITY_INTERVAL
+    end
+
+    def set_valid_name_for(layer)
+      name_pattern = /^(?<layer_name>.+) #(?<number>\d+)\s*$/
+      while layers.keys.include? layer.name
+        layer.name = "#{layer.name} #1" unless layer.name =~ name_pattern
+        layer.name.match(name_pattern) do |md|
+          layer.name = "#{md[:layer_name]} ##{md[:number].to_i + 1}"
+          next
+        end
+      end
+      layer.name
     end
 
   end

data/lib/super_stack/merge_policies.rb

@@ -1,3 +1,4 @@
+require 'super_stack/merge_policies/keep_policy'
 require 'super_stack/merge_policies/override_policy'
 require 'super_stack/merge_policies/standard_merge_policy'
 require 'super_stack/merge_policies/full_merge_policy'
@@ -10,5 +11,16 @@ module SuperStack
       constants.map(&:to_s).grep(/Policy$/).map{|policy_name| const_get policy_name}
     end
 
+    module PolicyHandler
+
+      attr_reader :merge_policy
+
+      def merge_policy=(policy)
+        raise "Invalid merge policy #{policy}" unless SuperStack::MergePolicies.list.include? policy
+        @merge_policy = policy
+      end
+
+    end
+
   end
 end

data/lib/super_stack/merge_policies/keep_policy.rb

@@ -0,0 +1,11 @@
+module SuperStack
+  module MergePolicies
+    module KeepPolicy
+
+      def self.merge(h1, h2)
+        h1
+      end
+
+    end
+  end
+end

data/lib/super_stack/version.rb

@@ -1,3 +1,3 @@
 module SuperStack
-  VERSION = "0.0.2"
+  VERSION = "0.1.0"
 end

data/spec/layer_spec.rb

@@ -13,6 +13,11 @@ describe SuperStack::Layer do
     expect(subject.name == subject.class.const_get('DEFAULT_LAYER_NAME')).to be_truthy
   end
 
+  it 'could have its own merge policy' do
+    expect( subject.respond_to? :merge_policy).to be_truthy
+    expect( subject.respond_to? :'merge_policy=').to be_truthy
+  end
+
   it 'should allow to change the name' do
     subject.name = 'foo'
     expect(subject.name == 'foo').to be_truthy
@@ -31,15 +36,11 @@ describe SuperStack::Layer do
   end
 
   it 'can be created from any Hash' do
-    expect {Hash.new.extend SuperStack::LayerWrapper }.not_to raise_error
+    expect {SuperStack::LayerWrapper.from_hash Hash.new}.not_to raise_error
   end
 
   context 'when loaded from a YAML file' do
 
-    def file_from_type(file_type)
-      File.expand_path("../../test/layer_content_type_#{file_type}.yml", __FILE__)
-    end
-
     %w(empty standard containing_an_array well_formatted).each do |file_type|
       it "should allow #{file_type} content type" do
         expect {
@@ -49,6 +50,33 @@ describe SuperStack::Layer do
       end
     end
 
+    it 'should remain unchanged when trying to load an invalid file' do
+      subject[:foo] = :bar
+      expect {
+        subject.load file_from_type 'invalid'
+      }.to raise_error
+
+      expect(subject[:foo] == :bar).to be_truthy
+    end
+
+    it 'should override current values when loaded from a valid file' do
+      subject[:foo] = :bar
+      expect {
+        subject.load file_from_type 'well_formatted'
+      }.not_to raise_error
+
+      expect(subject[:foo] == :bar).to be_falsey
+    end
+
+    it 'reload should have no effect when no load has already been done' do
+      expect( subject.reload).to be_nil
+    end
+
+    it 'should allow to reload when a load has already been done' do
+      expect {subject.load file_from_type 'well_formatted'}.not_to raise_error
+      expect {subject.reload}.not_to raise_error
+    end
+
 
   end
 

data/spec/manager_spec.rb

@@ -1,8 +1,19 @@
 require 'spec_helper'
 
+
 describe SuperStack::Manager do
   subject {SuperStack::Manager.new}
 
+  (1..4).each do |layer_number|
+    let("layer#{layer_number}".to_sym) {
+      file_name = file_from_layer layer_number
+      layer = SuperStack::Layer.new
+      layer.load file_name
+      layer.name = "layer#{layer_number}"
+      layer
+    }
+  end
+
 
   it 'should contain layers' do
     expect( subject.respond_to? :layers).to be_truthy
@@ -19,54 +30,83 @@ describe SuperStack::Manager do
     subject.add_layer l2
     subject.add_layer l1
 
+    expect(subject.layers.count == 2).to be_truthy
+
     expect(subject.to_a[0] == l1).to be_truthy
     expect(subject.to_a[1] == l2).to be_truthy
   end
 
-  it 'should have a policy' do
-    expect( subject.respond_to? :merge_policy).to be_truthy
+  it 'should have a default policy' do
+    expect( subject.respond_to? :default_merge_policy).to be_truthy
+    expect( subject.respond_to? :'default_merge_policy=').to be_truthy
   end
 
-  it 'should not be ready unless a merge policy is set' do
-    expect( subject.ready?).to be_falsey
-    subject.merge_policy = SuperStack::MergePolicies.list[0]
-    expect( subject.ready?).to be_truthy
+  it 'should have a default merge policy' do
+    expect( subject.default_merge_policy == SuperStack::Manager::DEFAULT_MERGE_POLICY).to be_truthy
   end
 
   it 'should not accept stupid policies' do
-    expect {subject.merge_policy = :foo}.to raise_error
+    expect {subject.default_merge_policy = :foo}.to raise_error
   end
 
-  context 'when ready' do
+  it 'should support pure hashes as layers' do
+    expect {subject.add_layer({}) }.not_to raise_error
+    expect {subject.add_layer({}) }.not_to raise_error
+    expect(subject.layers.keys.count == 2).to be_truthy
+    expect(subject.layers.keys[0] == SuperStack::Layer::DEFAULT_LAYER_NAME).to be_truthy
+    expect(subject.layers.keys[1] == "#{SuperStack::Layer::DEFAULT_LAYER_NAME} #2").to be_truthy
+  end
 
-    def file_from_layer(layer_number)
-      File.expand_path("../../test/stacked_layer_#{layer_number}.yml", __FILE__)
-    end
+  it 'should allow the same layer to be added multiple times, automatically changing names' do
+    expect {subject.add_layer(layer1) }.not_to raise_error
+    expect {subject.add_layer(layer1) }.not_to raise_error
+    expect {subject.add_layer(layer1) }.not_to raise_error
+    expect(subject.layers.keys.count == 3).to be_truthy
+    expect(subject.layers.keys[0] == 'layer1').to be_truthy
+    expect(subject.layers.keys[1] == 'layer1 #2').to be_truthy
+    expect(subject.layers.keys[2] == 'layer1 #3').to be_truthy
+  end
+
+  it 'should allow to reload all layers at once' do
+      subject.add_layer layer1
+      subject << {bar: :foo}
+      subject.add_layer layer3
+      subject.add_layer layer4
+      expect(subject[:foo] == :bar).to be_falsey
+      subject.layers['layer3'][:foo] = :bar
+      expect(subject[:foo] == :bar).to be_truthy
+      expect(subject[:bar] == :foo).to be_truthy
+      expect {subject.reload_layers}.not_to raise_error
+      expect(subject[:foo] == :bar).to be_falsey
+      expect(subject[:bar] == :foo).to be_truthy
+  end
 
-    (1..4).each do |layer_number|
-      let("layer#{layer_number}".to_sym) {
-        file_name = file_from_layer layer_number
-        layer = SuperStack::Layer.new
-        layer.load file_name
-        layer.name = "layer#{layer_number}"
-        layer
-      }
-    end
 
-    SuperStack::MergePolicies.list.each do |policy|
-      it "should provide a merged view of the layers according to the merge policy: #{policy}" do
-        subject.add_layer layer1
-        subject.add_layer layer2
-        subject.add_layer layer3
-        subject.add_layer layer4
-        subject.merge_policy = policy
-        expect(subject[].is_a? Hash).to be_truthy
-        expect(subject[:layer] == 'four').to be_truthy
-      end
+  SuperStack::MergePolicies.list.each do |policy|
+    it "should provide a merged view of the layers according to the merge policy: #{policy}" do
+      subject.add_layer layer1
+      subject.add_layer layer2
+      subject.add_layer layer3
+      subject.add_layer layer4
+      subject.default_merge_policy = policy
+      expect(subject[].is_a? Hash).to be_truthy
+      policy == SuperStack::MergePolicies::KeepPolicy ?
+          expect(subject[:layer] == 'one').to(be_truthy) : expect(subject[:layer] == 'four').to(be_truthy)
     end
+  end
+
+  context 'when using policies at layer level' do
 
+    it 'should override the default manager policy' do
+      subject.add_layer layer1
+      subject.add_layer layer2
+      subject.default_merge_policy = SuperStack::MergePolicies::FullMergePolicy
+      layer2.merge_policy = SuperStack::MergePolicies::OverridePolicy
 
+      expect(subject[:from_layer_1]).to be_nil
+      expect(subject[:from_layer_2]).not_to be_nil
 
+    end
 
   end
 

data/spec/merge_policies_spec.rb

@@ -4,10 +4,6 @@ describe SuperStack::MergePolicies do
 
   subject {SuperStack::MergePolicies}
 
-  def file_from_layer(layer_number)
-    File.expand_path("../../test/stacked_layer_#{layer_number}.yml", __FILE__)
-  end
-
   (1..4).each do |layer_number|
     let("layer#{layer_number}".to_sym) {
       file_name = file_from_layer layer_number
@@ -19,7 +15,19 @@ describe SuperStack::MergePolicies do
   it 'should have merge policies' do
     policies = subject.list
     expect( policies.is_a? Array).to be_truthy
-    expect( policies.count == 3).to be_truthy
+    expect( policies.count == 4).to be_truthy
+  end
+
+  context 'when dealing with keep policy' do
+
+    subject {SuperStack::MergePolicies::KeepPolicy}
+
+    it 'should retain only the first hash' do
+      merged_hashs = subject.merge(layer1, layer2)
+      expect( merged_hashs == layer1).to be_truthy
+      expect( merged_hashs[:layer] == 'one').to be_truthy
+    end
+
   end
 
   context 'when dealing with override policy' do

data/spec/spec_helper.rb

@@ -17,6 +17,15 @@
 
 require 'super_stack'
 
+
+def file_from_layer(layer_number)
+  File.expand_path("../../test/stacked_layer_#{layer_number}.yml", __FILE__)
+end
+
+def file_from_type(file_type)
+  File.expand_path("../../test/layer_content_type_#{file_type}.yml", __FILE__)
+end
+
 RSpec.configure do |config|
   # rspec-expectations config goes here. You can use an alternate
   # assertion/expectation library such as wrong or the stdlib/minitest

data/test/layer_content_type_invalid.yml

@@ -0,0 +1,10 @@
+Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore
+magna aliquam erat volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis
+nisl ut aliquip ex ea commodo consequat. Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie
+consequat, vel illum dolore eu feugiat nulla facilisis at vero eros et accumsan et iusto odio dignissim qui blandit
+praesent luptatum zzril delenit augue duis dolore te feugait nulla facilisi. Nam liber tempor cum soluta nobis
+eleifend option congue nihil imperdiet doming id quod mazim placerat facer possim assum. Typi non habent claritatem
+insitam; est usus legentis in iis qui facit eorum claritatem. Investigationes demonstraverunt lectores legere me lius
+quod ii legunt saepius. Claritas est etiam processus dynamicus, qui sequitur mutationem consuetudium lectorum. Mirum
+est notare quam littera gothica, quam nunc putamus parum claram, anteposuerit litterarum formas humanitatis per seacula
+quarta decima et quinta decima. Eodem modo typi, qui nunc nobis videntur parum clari, fiant sollemnes in futurum.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: super_stack
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Laurent B.
@@ -101,6 +101,7 @@ files:
 - lib/super_stack/manager.rb
 - lib/super_stack/merge_policies.rb
 - lib/super_stack/merge_policies/full_merge_policy.rb
+- lib/super_stack/merge_policies/keep_policy.rb
 - lib/super_stack/merge_policies/override_policy.rb
 - lib/super_stack/merge_policies/standard_merge_policy.rb
 - lib/super_stack/version.rb
@@ -111,6 +112,7 @@ files:
 - super_stack.gemspec
 - test/layer_content_type_containing_an_array.yml
 - test/layer_content_type_empty.yml
+- test/layer_content_type_invalid.yml
 - test/layer_content_type_standard.yml
 - test/layer_content_type_well_formatted.yml
 - test/stacked_layer_1.yml
@@ -149,6 +151,7 @@ test_files:
 - spec/spec_helper.rb
 - test/layer_content_type_containing_an_array.yml
 - test/layer_content_type_empty.yml
+- test/layer_content_type_invalid.yml
 - test/layer_content_type_standard.yml
 - test/layer_content_type_well_formatted.yml
 - test/stacked_layer_1.yml