compositor 0.1.3 → 0.1.4

data/README.md

@@ -3,10 +3,12 @@ Compositor
 
 [![Build status](https://secure.travis-ci.org/wanelo/compositor.png)](http://travis-ci.org/wanelo/compositor)
 
-Composite pattern with a neat DSL for constructing trees of objects in order to render them as a Hash, and subsequently
-JSON.  Used by Wanelo to generate all JSON API responses by compositing multiple objects together, converting to
-a hash and then JSON.
+A Composite Design Pattern with a neat DSL for constructing trees of objects in order to render them as a Hash, and subsequently
+JSON.  Used by Wanelo to generate all JSON API responses by compositing multiple objects together in API responses, converting to
+a plain ruby Hash (or an Array) and then using OJ gem to convert Hash to JSON.
 
+The performance of this approach to generate JSON was faster than using RABL in our limited testing, although if performance
+is not an issue for you, RABL is still an excellent choice, and served us well for almost a year.
 
 ## Installation
 
@@ -25,21 +27,22 @@ Or install it yourself as:
 ## Usage
 
 For each model that needs a hash/json representation you need to create a ruby class that subclasses ```Composite::Leaf```,
-adds some custom state that's important for rendering that object in addition to ```view_context```, and implement the ```#to_hash```
-method.
+adds some custom state that's important for rendering that object in addition to ```context```, implements a proper constructor
+(see example), and finally implement the main rendering ```#to_hash``` method (used as the "operation" in the Composite pattern
+terminology).
 
-The ```view_context``` variable is a reference to an object holding necessary helpers for generating JSON, for example
-view_context is automatically available inside Rails controllers, and contains helper methods necessary to generate application URLs.
-Outside of Rails application, ```view_context``` can be any other object holding application helpers or state.  All
-subclasses of ```Compositor::Leaf``` inherit view_context reference, and can use it to construct Hash representations.
+The ```context``` variable is a reference to an object holding necessary helpers for generating JSON, for example
+Rails Controllers expose a ```view_context``` instance, which contains helper methods necessary to generate application URLs.
 
-We recommend you place your Compositor classes in eg ```app/compositors/*``` directory, that has one compositor
-class per model class you will be rendering. Example below would be ```app/compositors/user.rb```, a compositor class
-wrapping ```User``` model.
+Outside of Rails application, ```context``` can be any other object holding application helpers or state.  All
+subclasses of ```Compositor::Leaf``` such as ```UserCompositor``` inherit ```context``` attribute and accessors, and so can
+use the context in generating URLs, or calling any other application helpers.
 
-```ruby
-# The actual class name "User" is converted into a DSL method named "user", shown later.
+We recommend that you place your Compositor classes in eg ```app/compositors/*``` directory, which defines one
+(or more than one) compositor(s) per model class you will be rendering.
 
+```ruby
+# File: app/compositors/user_compositor.rb
 class UserCompositor < Compositor::Leaf
   attr_accessor :user
 
@@ -55,27 +58,75 @@ class UserCompositor < Compositor::Leaf
         location: user.location,
         bio: user.bio,
         url: user.url,
-        image_url: context.image_path(user.avatar),
+        image_url: context.image_path(user.avatar),  # using context to generate URL path from routes
         ...
     }
   end
 end
 ```
 
-This small class automatically registers "user" DSL method, which receives a user object and any other
-important attributes.
+You could create this class directly, as in
 
-Then this class can be merged with other similar "leaf" classes, or another "composite" class, such as
-Composite::Map or Composite::List to create a Hash or an Array as the top-level JSON data structure.
+```ruby
 
-Once the tree of composite objects has been setup, calling #to_hash on the top level object quickly
-generates hash by walking the tree and merging everything together.
+   uc = UserCompositor.new(view_context, user, {})
+   uc.to_hash # => returns a Hash representation
+   uc.to_json # => calls to_hash, and then renders JSON
+```
 
-In the example below, application defines also ```StoreCompositor```, ```ProductCompositor``` classes
-that similar to ```UserCompositor``` return hash representations of each model object.
+But constructing trees of objects that represent a complex API responses requires a lot more than that, such as
+constructing lists (arrays) or maps (hashes) of objects, and deciding which order they appear, and whether each
+inner Hash comes with a "root" element, such as ```:product => { :id => 1, ... }``` where ```:product``` is the root
+element.
+
+So here is how to create a list of users in this way, but explicitly declaring classes:
 
 ```ruby
+   compositor = Compositor::Map.new(view_context,
+        :collection => @users.map{|user| UserCompositor.new(view_context, user, { :root => true }),
+        :root => :users
+```
+
+When calling ```to_hash``` on the top level compositor, we get:
+
+```ruby
+:users => {
+  :user => {
+      id: 1234,
+      username: "kigster",
+      location: "San Francisco",
+      bio: "",
+      url: "",
+      image_url: "http://cdn-app.domain.com/kigster/avatar/200.jpg"
+  },
+  :user => {
+      id: 1235,
+      username: "johnny",
+      location: "Sunnyvale",
+      bio: "",
+      url: "",
+      image_url: "http://cdn-app.domain.com/johnny/avatar/200.jpg"
+  }
+}
+```
+
+So this is how you can assemple multiple compositors together without the DSL.
+
+But the real power of this gem is in the additional DSL class, that dramatically simplifies definition
+of complex responses, as described below.
+
+### Using the DSL
 
+```UserCompositor``` class, when defined, automatically adds a ```user``` method to the DSL class, which effictively
+instantiates the new UserCompositor instance, passing the context into it automatically.
+
+Using built-in ```Compositor::Map``` and ```Compositor::List``` we can construct multiple objects into a larger
+hierarchy.
+
+In the example below, an application is assumed to define ```StoreCompositor```and ```ProductCompositor``` classes
+similar to ```UserCompositor```, but wrapping ```Store``` and ```Product``` ActiveRecord models.
+
+```ruby
    compositor = Compositor::DSL.create(context) do
      map do
        store @store, root: :store
@@ -86,8 +137,8 @@ that similar to ```UserCompositor``` return hash representations of each model o
      end
    end
 
+   # now we can call to_hash or to_json on the compositor:
    puts compositor.to_hash # =>
-
    {
       :store => {
          id: 12354,
@@ -104,16 +155,39 @@ that similar to ```UserCompositor``` return hash representations of each model o
          url: "",
          image_url: "http://cdn-app.domain.com/kigster/avatar/200.jpg"
       },
-      :products => {
-           [ id: 1234, :name => "Awesome Product", ... ],
-           [ id: 4325, :name => "Another Awesome Product", ... ]
+      :products => [
+           { id: 1234, :name => "Awesome Product", ... },
+           { id: 4325, :name => "Another Awesome Product", ... }
       }
    }
 ```
 
-The context is an object that can contain helpers, instance variables, or anything that can be used
-within leaves. For example, you can pass in the view_context from the controller to get access to any
-Rails routes or helpers.
+Inside the list definition above, ```@products``` is a collection of Products, ```ActiveRecord``` objects,
+and the block maps each to a Compositor using ```product()``` method, registered by ProductCompositor.
+
+### Instance Variables
+
+One thing to note, is that when ```Compositor::DSL``` is used, the gem copies all instance variables
+from the ```context``` into the DSL instance, so in the above example instance variable ```@user```
+was defined on ```view_context``` (by Rails, which copies them from the Controller instance), and
+so became automatically available inside DSL.  Note that all instance variables must be
+defined *before* the DSL instance is created.
+
+### Method Name Collisions in the DSL
+
+Because DSL uses only the last word of the class name (eg, ```user``` for a class named ```MyModule::UserCompositor```),
+there is a possibility of name collisions. In order to prevent that, Compositor will detect if a DSL method is already
+defined and throw exception if another class tries to redefine it.
+
+If you prefer to have your own ```Compositor``` class hierarchy, or just compositors that should not be added to the
+DSL, you can name the classes starting with ```Abstract```, such as ```MyModule::AbstractCompositor```.
+
+### Performance
+
+Note of caution: despite the fact that typical DSL generation can take mere 50-100 microseconds, defining complex responses
+with DSL does carry a performance penantly of about 50% (we measured it!). Which generally means that generating
+multiple Composite objects in a loop using the DSL is probably not recommended, but doing it once per web/API
+request is completely reasonable.
 
 ## Contributing
 

data/lib/compositor/base.rb

@@ -1,4 +1,6 @@
 module Compositor
+  class MethodAlreadyDefinedError < RuntimeError; end
+
   class Base
     attr_reader :attrs
     attr_accessor :root, :context
@@ -41,7 +43,11 @@ module Compositor
 
     def self.inherited(subclass)
       method_name = root_class_name(subclass)
-      unless method_name.eql?("base") # check if it's already defined
+      unless method_name.eql?("base") || method_name.start_with?("abstract")
+        # check if it's already defined
+        if Compositor::DSL.instance_methods.include?(method_name.to_sym)
+          raise MethodAlreadyDefinedError.new("Method #{method_name} is already defined on the DSL class.")
+        end
         Compositor::DSL.send(:define_method, method_name) do |*args, &block|
           subclass.
             new(@context, *args).

data/lib/compositor/version.rb

@@ -1,3 +1,3 @@
 module Compositor
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

data/spec/compositor/base_spec.rb

@@ -9,5 +9,36 @@ describe Compositor::Base do
     it "returns the underscored class name with compositor stripped out" do
       Compositor::Base.root_class_name(DslStringCompositor).should == "dsl_string"
     end
+
+    it "raises exception when two subclasses that clash on the same name are defined" do
+      block = lambda {
+        # first class
+        class UserCompositor < Compositor::Leaf
+        end
+
+        # 2nd class
+        module ::Foo
+          class UserCompositor < Compositor::Leaf
+          end
+        end
+      }
+      expect { block.call }.to raise_error
+    end
+
+    it "does not add DSL when class name begins with Abstract" do
+      block = lambda {
+        class AbstractUserCompositor < Compositor::Leaf
+        end
+        # Normally this would cause an exception, but since they both
+        # start with Abstract, neither is added to the DSL.
+        module ::Foo
+          class AbstractUserCompositor < Compositor::Leaf
+          end
+        end
+      }
+      expect { block.call }.not_to raise_error
+      Compositor::DSL.instance_methods.should_not include(:abstract_user)
+    end
+
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: compositor
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-31 00:00:00.000000000 Z
+date: 2013-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oj
@@ -136,7 +136,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.25
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Composite design pattern with a convenient DSL for building JSON/Hashes of
@@ -151,3 +151,4 @@ test_files:
 - spec/compositor/performance_spec.rb
 - spec/spec_helper.rb
 - spec/support/sample_dsl.rb
+has_rdoc: