laminate 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e77157349328090e7c00245481ec1d53804a835f
+  data.tar.gz: c181e76a479b851250cb11de2536af6c3476bd68
+SHA512:
+  metadata.gz: 60b365e0eb3cf0c11d8db3fbfbab76cc65be39c366507f5dd6b204669bfc838ca10f6783896ea549e748469321ae7f7e03b617bfe5ec222dda0d21bf18219c9c
+  data.tar.gz: bbdea1d7aa0aa019e5f3d51ece65efd2e509d4a9d8edcceb8d0ada5fd6c69086db0d872c5fd9c24437e672d58b93335e683113c4ec57eddf530f73b419d0a9c6

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Cameron C. Dutro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,130 @@
+## laminate
+
+Turn any Ruby module into a composable decorator.
+
+## Installation
+
+`gem install laminate`
+
+or put it in your Gemfile:
+
+```ruby
+gem 'laminate'
+```
+
+### Background
+
+If you've ever worked on a large Ruby application, you've probably seen a few classes get too big. A typical example in a Rails application is the `User` model, which is a convenient place to put all the functionality for the site's logged-in experience. If allowed to grow unchecked, these bloated classes can become increasingly difficult to hold in your head at once, meaning they're more difficult to change, meaning you change them less often out of fear you'll break a fundamental part of your application.
+
+Enter modules.
+
+At their core, Ruby modules are just bags of methods. They're commonly used to encapsulate shared functionality, but they can also be used to separate shared groups of methods from classes that are getting too big. What this means in practical terms is a `User` model that looks something like this:
+
+```ruby
+class User < ActiveRecord::Base
+  include LoginMethods
+  include EmailMethods
+  include RoleMethods
+  ...
+end
+```
+
+Each of the modules represents a cohesive group of methods that we're basically injecting into `User` when the application starts up. The upside is that now `User` contains a lot less code.
+
+Or does it? What have we really done here? As it turns out, nothing. `User` still contains the same methods it did before. The only difference is that now the methods are spread out in different files. Logically the `User` class hasn't changed at all and we're still stuck with the same problem - it's still too large to reason about and still too scary to change.
+
+But that's not all. The separation has now made it even more difficult for the programmer to track down potential bugs. The programmer can still call all the same methods on instances of `User` but those methods aren't actually defined in user.rb.
+
+But that's also not all. When you include a module, you're actually adding that module to the host class or module's inheritance chain. Any _public or private_ methods in the host class will take precedence over included methods. For example, consider the following class and included module:
+
+```ruby
+module HarvestHelpers
+  def harvest
+    :harvest_from_helper
+  end
+end
+
+class VegetableGarden
+  include HarvestHelpers
+  
+  def harvest
+    :harvest_from_garden
+  end
+end
+```
+
+What gets returned if I run `VegetableGarden.new.harvest`? Perhaps a bit counterintuitively, you'll get `:harvest_from_garden`. Now imagine `VegetableGarden` is a huge class with 15 included modules, any of which may define the `#harvest` method. If you define the `#harvest` method in `VegetableGarden` without realizing it's already defined, you could end up breaking your application in subtle, difficult-to-debug ways. Sure, you could `prepend` the `HarvestHelpers` module instead of `include`-ing it, but that could mean stepping on the toes of another prepended or included module. What's worse, remember that both public _and_ private methods are affected, even though your private methods are probably only designed to be used in the module in which they're defined.
+
+### Ok, so how can this gem help?
+
+Laminate tries to address the downsides of module inclusion by converting modules into composable decorators called layers. Layers are composable because they can be progressively applied, or laid on top of one another. For example, you could add `HarvestHelpers` progressively to an instance of `VegetableGarden`. First, we'll need to turn `HarvestHelper` and `VegetableGarden` into a layers:
+
+```ruby
+module HarvestHelpers
+  include Laminate::Layer
+  
+  def harvest
+    :harvest_from_helper
+  end
+end
+
+class VegetableGarden
+  include Laminate::Layer
+end
+```
+
+Once that's done, we can layer `HarvestHelpers` onto instances of `VegetableGarden` whenever we want harvest functionality:
+
+```ruby
+garden = VegetableGarden.new.with_layer(HarvestHelpers)
+garden.harvest
+```
+
+What's more, you can create a layer out of more than one module at a time:
+
+```ruby
+module PlantHelpers
+  def dig_hole
+    # dig dig
+  end
+end
+
+garden = VegetableGarden.new.with_layers([HarvestHelpers, PlantHelpers])
+# returns #<VegetableGarden::WithHarvestHelpersAndPlantHelpers:0x007f7f9c836da0>
+
+garden.dig_hole
+garden.harvest
+```
+
+### Sweet! How does it work?
+
+The `garden` variable is an instance of `VegetableGarden::WithHarvestHelpers`, a class laminate dynamically created and cached for you (these dynamically created classes will be created once and reused the next time `#with_layer` is called).
+
+`VegetableGarden::WithHarvestHelpers` forwards all _public_ methods already defined in `VegetableGarden` but none of the _private_ methods, meaning layers can define private methods without fearing those methods will be inadvertently overridden by other modules.
+
+### What about already defined methods?
+
+Glad you asked. If `#harvest` is already defined in `VegetableGarden`, laminate will raise a helpful error:
+
+```ruby
+VegetableGarden.new.with_layer(HarvestHelpers)
+
+# Laminate::MethodAlreadyDefinedError: Unable to add layer:
+#   `#harvest' is already defined by VegetableGarden
+```
+
+If you want the layer's method to override its ancestor's method, pass `allow_overrides: true`:
+
+```ruby
+VegetableGarden.new.with_layer(HarvestHelpers, allow_overrides: true)
+```
+
+If overrides are allowed, any method defined in `HarvestHelpers` will override the corresponding method defined in `VegetableGarden`. You should consider your use case carefully before using this rather large hammer.
+
+## License
+
+Licensed under the MIT license. See LICENSE for details.
+
+## Authors
+
+* Cameron C. Dutro: http://github.com/camertron

data/laminate.gemspec

@@ -0,0 +1,18 @@
+$:.unshift File.join(File.dirname(__FILE__), 'lib')
+require 'laminate/version'
+
+Gem::Specification.new do |s|
+  s.name     = 'laminate'
+  s.version  = ::Laminate::VERSION
+  s.authors  = ['Cameron Dutro']
+  s.email    = ['camertron@gmail.com']
+  s.homepage = 'https://github.com/camertron/laminate'
+
+  s.description = s.summary = 'Turn any Ruby module into a composable decorator.'
+
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+
+  s.require_path = 'lib'
+  s.files = Dir['{lib,spec}/**/*', 'README.md', 'laminate.gemspec', 'LICENSE']
+end

data/lib/laminate.rb

@@ -0,0 +1,5 @@
+module Laminate
+  autoload :MethodAlreadyDefinedError, 'laminate/errors'
+  autoload :UnsupportedStrategyError,  'laminate/errors'
+  autoload :Layer,                     'laminate/layer'
+end

data/lib/laminate/errors.rb

@@ -0,0 +1,4 @@
+module Laminate
+  class MethodAlreadyDefinedError < StandardError; end
+  class UnsupportedStrategyError < StandardError; end
+end

data/lib/laminate/layer.rb

@@ -0,0 +1,121 @@
+require 'forwardable'
+
+module Laminate
+  module Layer
+    def with_layer(layer_module, options = {})
+      with_layers(Array(layer_module), options)
+    end
+
+    def with_layers(layer_modules, options = {})
+      # If layer_module isn't a ruby module, blow up.
+      unless layer_modules.all? { |mod| mod.is_a?(Module) }
+        raise ArgumentError, 'layers must all be modules'
+      end
+
+      # Grab the cache from the super class's singleton. It's not correct to
+      # simply reference the @@__laminate_layer_cache variable because of
+      # lexical scoping. If we were to reference the variable directly, Ruby
+      # would think we wanted to associate it with the Layer module, where in
+      # reality we want to associate it with each module Layer is mixed into.
+      cache = self.class.class_variable_get(:@@__laminate_layer_cache)
+
+      # We don't want to generate each wrapper class more than once, so keep
+      # track of the modules => dynamic wrapper mapping and avoid re-creating
+      # them on every call to with_layer.
+      cache[layer_modules] ||= begin
+        layer_module_methods = layer_modules.flat_map do |mod|
+          mod.instance_methods(false)
+        end
+
+        unless options.fetch(:allow_overrides, false)
+          # Identify method collisions. In order to minimize accidental
+          # monkeypatching, Celophane will error if you try to wrap an object
+          # with a layer that defines any method with the same name as a method
+          # the object already responds to. Starts with self, or more accurately,
+          # the methods defined on self. The loop walks the ancestor chain an
+          # checks each ancestor for previously defined methods.
+          ancestor = self
+
+          while ancestor
+            # Filter out Object's methods, which are common to all objects and not
+            # ones we should be forwarding. Also filter out Layer's methods for
+            # the same reason.
+            ancestor_methods = ancestor.class.instance_methods - (
+              Object.methods + Layer.instance_methods(false)
+            )
+
+            # Calculate the intersection between the layer's methods and the
+            # methods defined by the current ancestor.
+            already_defined = ancestor_methods & layer_module_methods
+
+            unless already_defined.empty?
+              ancestor_modules = [self.class] + (ancestor.instance_variable_get(:@__laminate_modules) || [])
+
+              error_messages = already_defined.map do |method_name|
+                ancestor_module = ancestor_modules.find do |mod|
+                  mod.method_defined?(method_name)
+                end
+
+                "  `##{method_name}' is already defined in #{ancestor_module.name}"
+              end
+
+              layer_plural = error_messages.size == 1 ? 'layer' : 'layers'
+
+              # @TODO: fix the English here
+              raise MethodAlreadyDefinedError,
+                "Unable to add #{layer_plural} (pass `allow_overrides: true` if "\
+                  "intentional):\n#{error_messages.join("\n")}"
+            end
+
+            # Grab the next ancestor and keep going. The loop exits when ancestor
+            # is nil, which happens whenever the end of the ancestor chain has
+            # been reached (i.e. when iteration reaches the base object).
+            ancestor = ancestor.instance_variable_get(:@__laminate_ancestor)
+          end
+        end
+
+        ancestor_methods = self.class.instance_methods - (
+          Object.methods + Layer.instance_methods(false) + layer_module_methods
+        )
+
+        # Dynamically define a new class and mix in the layer modules. Forward
+        # all the ancestor's methods to the ancestor. Dynamic layer classes keep
+        # track of both the ancestor itself as well as the modules it was
+        # constructed from.
+        klass = Class.new do
+          layer_modules.each do |layer_module|
+            include layer_module
+          end
+
+          extend Forwardable
+
+          # Forward all the ancestor's methods to the ancestor.
+          def_delegators :@__laminate_ancestor, *ancestor_methods
+
+          def initialize(ancestor, layer_modules)
+            # Use absurd variable names to avoid re-defining instance variables
+            # introduced by the layer module.
+            @__laminate_ancestor = ancestor
+            @__laminate_modules = layer_modules
+          end
+        end
+
+        module_names = layer_modules.map { |mod| mod.name.split('::').last }
+        wrapper_name = 'With' + module_names.join('And')
+
+        # Assign the new wrapper class to a constant inside self, with 'With'
+        # prepended. For example, if the module is called Engine the wrapper
+        # class will be assigned to a constant named WithEngine.
+        self.class.const_set(wrapper_name, klass)
+        klass
+      end
+
+      # Wrap self in a new instance of the wrapper class.
+      cache[layer_modules].new(self, layer_modules)
+    end
+
+    def self.included(base)
+      base.class_variable_set(:@@__laminate_layer_cache, {})
+    end
+  end
+end

data/lib/laminate/version.rb

@@ -0,0 +1,3 @@
+module Laminate
+  VERSION = '1.0.0'
+end

data/spec/layer_spec.rb

@@ -0,0 +1,108 @@
+require 'spec_helper'
+
+include TestLayers
+
+describe Laminate::Layer do
+  shared_examples 'a base class' do
+    it 'allows calling base methods' do
+      expect(instance.base_method).to eq(:base)
+    end
+
+    it 'allows calling layer methods' do
+      expect(instance.jog).to eq(:jogging)
+    end
+  end
+
+  shared_examples 'a 2nd level layer class' do
+    it 'allows calling 2nd level layer methods' do
+      expect(instance.run).to eq(:running)
+    end
+  end
+
+  shared_examples 'a 3rd level layer class' do
+    it 'allows calling 3rd level layer methods' do
+      expect(instance.sprint).to eq(:sprinting)
+    end
+  end
+
+  context 'with an instance of the base class' do
+    let(:instance) { Person.new }
+
+    it "doesn't do any nesting for the base layer" do
+      expect(instance).to be_a(Person)
+    end
+
+    it_behaves_like 'a base class'
+  end
+
+  context 'with a single layer' do
+    let(:instance) { Person.new.with_layer(Runner) }
+
+    it 'nests the new module names' do
+      expect(instance).to be_a(Person::WithRunner)
+    end
+
+    it_behaves_like 'a base class'
+    it_behaves_like 'a 2nd level layer class'
+  end
+
+  context 'with a second layer' do
+    let(:instance) { Person.new.with_layer(Runner).with_layer(Sprinter) }
+
+    it 'nests the new module names' do
+      expect(instance).to be_a(Person::WithRunner::WithSprinter)
+    end
+
+    it_behaves_like 'a base class'
+    it_behaves_like 'a 2nd level layer class'
+    it_behaves_like 'a 3rd level layer class'
+  end
+
+  context 'with a combined layer' do
+    let(:instance) { Person.new.with_layers([Runner, Sprinter]) }
+
+    it 'combines the module names for the new constant name' do
+      expect(instance).to be_a(Person::WithRunnerAndSprinter)
+    end
+
+    it_behaves_like 'a base class'
+    it_behaves_like 'a 2nd level layer class'
+    it_behaves_like 'a 3rd level layer class'
+  end
+
+  describe '#with_layer' do
+    it 'raises an error if passed something other than a module' do
+      expect { Person.new.with_layer('foo') }.to(
+        raise_error(ArgumentError, 'layers must all be modules')
+      )
+    end
+
+    it 'raises an error if a method is already defined' do
+      expect { Person.new.with_layer(JogMethodCollision) }.to(
+        raise_error(Laminate::MethodAlreadyDefinedError)
+      )
+    end
+
+    it 'ensures overriding methods does not raise errors if explicitly asked' do
+      instance = -> { Person.new.with_layer(JogMethodCollision, allow_overrides: true) }
+      expect(&instance).to_not raise_error
+    end
+
+    it 'ensures overridden methods take precedence' do
+      person = Person.new.with_layer(JogMethodCollision, allow_overrides: true)
+      expect(person.jog).to eq(:jogging_collision)
+    end
+  end
+
+  describe '#with_layers' do
+    it 'includes modules in order' do
+      layers = [JogMethodCollision, JogMethodCollision2]
+      person = Person.new.with_layers(layers, allow_overrides: true)
+      expect(person.jog).to eq(:jogging_collision2)
+
+      layers = [JogMethodCollision2, JogMethodCollision]
+      person = Person.new.with_layers(layers, allow_overrides: true)
+      expect(person.jog).to eq(:jogging_collision)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,56 @@
+require 'pry-byebug'
+require 'laminate'
+require 'rspec'
+
+RSpec.configure do |config|
+  config.filter_run(focus: true)
+  config.run_all_when_everything_filtered = true
+end
+
+module TestLayers
+  class Base
+    def base_method
+      :base
+    end
+  end
+
+  class Person < Base
+    include Laminate::Layer
+
+    def jog
+      :jogging
+    end
+  end
+
+  module JogMethodCollision
+    include Laminate::Layer
+
+    def jog
+      :jogging_collision
+    end
+  end
+
+  module JogMethodCollision2
+    include Laminate::Layer
+
+    def jog
+      :jogging_collision2
+    end
+  end
+
+  module Runner
+    include Laminate::Layer
+
+    def run
+      :running
+    end
+  end
+
+  module Sprinter
+    include Laminate::Layer
+
+    def sprint
+      :sprinting
+    end
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: laminate
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Cameron Dutro
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-04-27 00:00:00.000000000 Z
+dependencies: []
+description: Turn any Ruby module into a composable decorator.
+email:
+- camertron@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- laminate.gemspec
+- lib/laminate.rb
+- lib/laminate/errors.rb
+- lib/laminate/layer.rb
+- lib/laminate/version.rb
+- spec/layer_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/camertron/laminate
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2
+signing_key: 
+specification_version: 4
+summary: Turn any Ruby module into a composable decorator.
+test_files: []