activesupport-decorators 0.9 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ec2236b08c2f672564e38201de862f16d36077b3
-  data.tar.gz: a0d82c89cd824d7699eafc8114d6ad5aa28b9483
+  metadata.gz: 7ac0e53aa4f0f2a5552ebdffb9bc6f8862bfb583
+  data.tar.gz: 0bc4b6985d4c867c732345478627e3ed2c69be1f
 SHA512:
-  metadata.gz: 0cf349af37ab49b04a3963a0e439dadbe008494ad8aad5f2b1d344959594153811d8c52d304e69cf2118675a73383d591517d342a86a7a939c49f93553090299
-  data.tar.gz: 19691a0734337d8c0ff8cebe4b027be8b2154e7c55dc6d36c11d285393e87fc3ca1d0aac48ceb950b5b0299a6635133f0a7fb42d829ba8fe8fd9a280cf0f82ae
+  metadata.gz: a7ea6a25f3474820c952786c12d9c04d6062ee8bc398b2b003170432561ef479bc82d32a3367f86640349c5d204da5ca4832078e4eeccad10163fe1129b3bb46
+  data.tar.gz: d68066a4e76725ffd03bfd4efa174f7fed47ebc686f006c9e458b551ef311a6d72bee37e8f039b492b942f87fdd612612d2df3154a4b8a8559bcd49d9a93c6a3

data/README.md

@@ -1,54 +1,111 @@
-ActiveSupportDecorators
-=======================
+ActiveSupport Decorators
+========================
 
-The decorator pattern is particularly useful when extending constants in rails engines or vica versa.  To implement
+The decorator pattern is particularly useful when extending constants in rails engines or vice versa.  To implement
 the decorator pattern, you need to load the decorator after the original file has been loaded.  When you reference a
 class in a Rails application, ActiveSupport will only load the first file it finds that matches the class name.  This
 means that you will need to manually load the additional (decorator) file.  Usually you don't want to want to introduce
 hard dependencies such as require statements.  You also don't want to preload a bunch of classes in a Rails initializer.
-This is a tiny gem that provides you with a simple way to specify load dependencies.
+This is a tiny gem that provides you with a simple way to specify load file dependencies.
 
-Example
-=======
+## Installation
 
-Lets say your main rails application defines a model called Pet (in app/models/pet.rb):
+Add it to your Gemfile and run bundle install:
+
+```Ruby
+gem 'activesupport-decorators', '~> 1.0'
+```
+
+## Example 1 - Engine extends application class.
+
+Your main rails application defines a model called Pet (in app/models/pet.rb):
 
 ```Ruby
 class Pet < ActiveRecord::Base
 end
 ```
 
-Your rails engine adds the concept of pet owners to the application.  You can extend the Pet model in the engine with
-the following model decorator (in my_engine/app/models/pet.rb).
+Your rails engine adds the concept of pet owners to the application.  You extend the Pet model in the engine with
+the following model decorator (in my_engine/app/models/pet_decorator.rb).
 
 ```Ruby
-class Pet
+Pet.class_eval do
   belongs_to :owner
 end
 ```
 
-Now tell ActiveSupportDecorators to load any matching file in my_engine/app/models when a file is loaded from
-app/models.  A convenient place to do this is in a Rails initializer in the engine:
+Now tell ActiveSupportDecorators to load any matching decorator file in my_engine/app when a file is loaded from
+app/.  A convenient place to do this is in a Rails initializer in the engine:
 
 ```Ruby
 module MyEngine
   module Rails
     class Engine < ::Rails::Engine
-      initializer :decorator_dependencies do |app|
-        ActiveSupportDecorators.add_dependency("#{app.root}/app/models", "#{config.root}/app/models")
+      initializer :set_decorator_dependencies do |app|
+        ActiveSupportDecorators.add("#{app.root}/app", "#{config.root}/app")
       end
     end
   end
 end
 ```
 
-Note that you could specify the path as "/app" to allow decorating controllers, models, helpers, etc.
+## Example 2 - Application extends engine class.
+
+Similar to the example above except the initializer is placed in the main application instead of the engine.  Create a
+file called config/initializers/set_decorator_dependencies.rb (or any other name) with content:
+
+```Ruby
+ActiveSupportDecorators.add("#{MyEngine::Rails::Engine.root}/app", "#{Rails.root}/app")
+```
 
-Debugging
-=========
+## Example 3 - Engine extends another engine class.
+
+```Ruby
+module MyEngine
+  module Rails
+    class Engine < ::Rails::Engine
+      initializer :set_decorator_dependencies do |app|
+        ActiveSupportDecorators.add("#{AnotherEngine::Rails::Engine.root}/app", "#{Rails.root}/app")
+      end
+    end
+  end
+end
+```
+
+## Debugging
 
 Need to know which decorator files are loaded?  Enable debug output:
 
 ```Ruby
 ActiveSupportDecorators.debug = true
-```
+```
+
+## Decorator file pattern
+
+By default decorator files are matched with '_decorator' appended to the file name.  You can remove this suffix
+completely or use your own one.  Note the method signature of add:
+
+```Ruby
+ActiveSupportDecorators.add(path, decorator_path, file_pattern = '_decorator')
+```
+
+## Decorating decorators
+
+Nested decorators are supported.  Just set them to decorate a path where the dependant decorators are placed.
+
+## Comparison to other gems
+
+This is yet another decorator gem because it:
+* allows you to specify where and how you name decorators.
+* allows you to limit the paths you decorate.
+* other gems tend to eager load as seen [here]
+  (https://github.com/atd/rails_engine_decorators/blob/master/lib/rails_engine_decorators/engine/configuration.rb)
+  and [here](https://github.com/parndt/decorators/blob/master/lib/decorators/railtie.rb).
+* other gems assume you use 'MyClass.class_eval' to define decorators since it is how you trigger activesupport to load
+  the original file.  This gem allows you to use the normal 'class MyClass' which means you can define constants in
+  decorators.
+
+However if you do not want to specify which path's you allow to be decorated, you should use another gem.  Instead of
+single file look ups it will need to search your decorator directories for a matching file, which is not feasible
+especially in a context where any ruby file may be decorated.  The best solution for such a scenario would be to
+eager load the decorators like other gems do.

data/lib/active_support_decorators/active_support_decorators.rb

@@ -1,16 +1,18 @@
 require 'active_support_decorators/graph'
 
 module ActiveSupportDecorators
+  Dependency = Struct.new(:path, :decorator_path, :file_pattern)
+
+  def self.clear
+    dependencies.clear
+  end
+
   def self.dependencies
-    @dependencies ||= {}
+    @dependencies ||= []
   end
 
-  def self.add_dependency(path, decorator_path)
-    if dependencies.include?(path)
-      dependencies[path] << decorator_path
-    else
-      dependencies[path] = [decorator_path]
-    end
+  def self.add(path, decorator_path, file_pattern = '_decorator')
+    dependencies << Dependency.new(path, decorator_path, file_pattern)
   end
 
   def self.debug
@@ -21,37 +23,37 @@ module ActiveSupportDecorators
     @debug = debugging_enabled
   end
 
+  private
   def self.load_path_order(file_name)
-    graph = Graph.new
-    graph.add(file_name)
+    # Do not process with .rb extension if provided.
+    sanitized_file_name = file_name.sub(/\.rb$/,'')
 
-    # If an attempt is made to load the original file, ensure the decorators are loaded afterwards.
-    dependencies.each do |path, decorator_paths|
-      if file_name.starts_with?(path)
-        relative_name = file_name.gsub(path, '')
+    graph = Graph.new
+    graph.add(sanitized_file_name)
 
-        decorator_paths.each do |decorator_path|
-          decorator_file = "#{decorator_path}#{relative_name}"
+    dependencies.each do |dep|
+      # If an attempt is made to load the original file, ensure the decorators are loaded afterwards.
+      if sanitized_file_name.starts_with?(dep.path)
+        relative_name = sanitized_file_name.sub(dep.path, '')
+        decorator_file = "#{dep.decorator_path}#{relative_name}#{dep.file_pattern}"
 
-          if File.file?(decorator_file) || File.file?(decorator_file + '.rb')
-            graph.add_dependency(file_name, decorator_file)
-          end
+        if File.file?(decorator_file + '.rb')
+          graph.add_with_edge(sanitized_file_name, decorator_file)
         end
       end
 
-      # If an attempt is made to load a decorator file, ensure the original file is loaded first.
-      decorator_paths.each do |decorator_path|
-        if file_name.starts_with?(decorator_path)
-          relative_name = file_name.gsub(decorator_path, '')
-          decorated_file = "#{path}#{relative_name}"
+      # If an attempt is made to load a decorator file, ensure the original/decorated file is loaded first.
+      # This is only supported when a decorator was not added with add_global.
+      if dep.path && sanitized_file_name.starts_with?(dep.decorator_path)
+        relative_name = sanitized_file_name.sub(dep.decorator_path, '')
+        decorated_file = "#{dep.path}#{relative_name}".sub(/#{dep.file_pattern}$/, '')
 
-          if File.file?(decorated_file) || File.file?(decorated_file + '.rb')
-            graph.add_dependency(decorated_file, file_name)
-          end
+        if File.file?(decorated_file + '.rb')
+          graph.add_with_edge(decorated_file, sanitized_file_name)
         end
       end
     end
 
-    graph.resolve_object_order
+    graph.list_by_order
   end
-end
+end

data/lib/active_support_decorators/dependencies_patch.rb

@@ -14,4 +14,4 @@ module ActiveSupport::Dependencies
       require_or_load_without_multiple(path, const_path)
     end
   end
-end
+end

data/lib/active_support_decorators/graph.rb

@@ -9,7 +9,7 @@ class Graph
     @nodes = []
   end
 
-  def resolve_object_order
+  def list_by_order
     result = []
 
     until @nodes.empty?
@@ -29,14 +29,15 @@ class Graph
     find_or_add_node(object)
   end
 
-  def add_dependency(from_object, to_object)
-    raise 'Objects are identical' if from_object == to_object
+  def add_with_edge(from_object, to_object)
+    fail 'Can not add edge from object to itself' if from_object == to_object
     from_node = find_or_add_node(from_object)
     to_node = find_or_add_node(to_object)
     to_node.depends_on << from_node
-    raise 'EMPTY' if from_node.nil?
+    fail 'EMPTY' if from_node.nil?
   end
 
+  private
   def find_or_add_node(object)
     node = @nodes.find { |n| n.object == object }
     unless node

data/lib/active_support_decorators/version.rb

@@ -1,3 +1,3 @@
 module ActiveSupportDecorators
-  VERSION = '0.9'
+  VERSION = '1.0.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activesupport-decorators
 version: !ruby/object:Gem::Version
-  version: '0.9'
+  version: 1.0.1
 platform: ruby
 authors:
 - Pierre Pretorius
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-28 00:00:00.000000000 Z
+date: 2014-03-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,14 +16,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 description: Useful when extending functionality with Rails engines.
 email:
 - pierre@labs.epiuse.com