restful_serializer 0.1.0 → 0.1.1

data/README.rdoc

@@ -6,7 +6,7 @@ If the model has a name column, it will be used to describe the resource.
 
 This library does not attempt to provide href info for transitions, or deal much with questions of authorization beyond what is specified in the serialization configuration lines.  It assumes that these issues would be resolved in the controller.  It assumes standard naming conventions for routes.
 
-So far only tested with Rails 2.x
+So far only tested with Rails 2.1.0
 
 == Example 
 
@@ -73,3 +73,6 @@ Example output:
   #    "column1"=>1,
   #    "column2"=>2,}}
 
+= More Docs
+
+Please see the Restful rdoc and the specs for more details.

data/lib/restful.rb

@@ -5,27 +5,29 @@ require 'restful/serializer'
 # This library is used to decorate ActiveRecord with methods to assist in generating 
 # Restful content for Web Services.
 #
-# It produces a hash of reference, object and href information for an ActiveRecord instance
-# or association.  Output is highly configurable both through Rails initialization and
-# method calls.
+# It produces a hash of reference, object and href information for an
+# ActiveRecord instance or association.  Output is highly configurable both
+# through Rails initialization and method calls.
 #
 # = Options
 #
-# The following options may be set in the Restful.model_configuration hash on a per model class
-# basis.
+# The following options may be set in the Restful.model_configuration hash on a
+# per model class basis.
 #
-# * :name => method to call on an instance to produce a human meaningful reference for the instance.
-#   Defaults to :name.
-# * :serialization => options to be passed to ActiveRecord::Serialization::Serializer to configure
-#   serialization of the ActiveRecord instance itself.  See ActiveRecord::Serialization.to_json
-# * :url_for => if the named_route helper method cannot be guessed from normal Rails restful
-#   syntax, it may be overriden here.
+# * :name => method to call on an instance to produce a human meaningful
+#   reference for the instance.  Defaults to :name.
+# * :serialization => options to be passed to
+#   ActiveRecord::Serialization::Serializer to configure serialization of the
+#   ActiveRecord instance itself.  See ActiveRecord::Serialization.to_json
+# * :url_for => if the named_route helper method cannot be guessed from normal
+#   Rails restful syntax, it may be overriden here.
 # * :associations => you may include href references to the instance's associations
-# * :shallow => if you are serializing an association, by default member includes and association 
-#   references are stripped.  Set this to false to traverse deeply.
-# * :no_inherited_options => normally a subclass inherits and overrides its base class settings.
-#   Setting this to true prevents this so that only the options specifically set for the class
-#   will be used.  Default false.
+# * :shallow => if you are serializing an association, by default member
+#   includes and association references are stripped.  Set this to false to
+#   traverse deeply.
+# * :no_inherited_options => normally a subclass inherits and overrides its
+#   base class settings.  Setting this to true prevents this so that only the
+#   options specifically set for the class will be used.  Default false.
 #
 # = Usage
 #
@@ -56,7 +58,7 @@ require 'restful/serializer'
 #
 #   Restful.model_configuration = {
 #     :person => {
-#       :serialization => { :except => :secrets }
+#       :serialization => { :except => [:secrets] }
 #       :associations => :books,
 #     }
 #     :book => {
@@ -74,10 +76,48 @@ require 'restful/serializer'
 #   #      'first_name' => 'Bob',
 #   #      'last_name' => 'Bob',
 #   #      'age' : 17,
+#   #   },
 #   #   'href' => 'http://www.example.com/web_service/people/1' }
 #   #   'books_href' => 'http://www.example.com/web_service/people/1/books' }
 #   # }
 #
+# Options may be overridden at call time, by default this overwrite the passed options completely:
+#  
+#   bob = Person.new(:first_name => 'Bob', :last_name => 'Smith', :age => 41, :secrets => 'untold')
+#   bob.restful(:serialization => { :except => [:id] })
+#   # => { 
+#   #   'name' => 'Bob Smith'
+#   #   'person' => { 
+#   #      'first_name' => 'Bob',
+#   #      'last_name' => 'Bob',
+#   #      'age' : 17,
+#   #      'secrets' : 'untold',
+#   #   },
+#   #   'href' => 'http://www.example.com/web_service/people/1' }
+#   #   'books_href' => 'http://www.example.com/web_service/people/1/books' }
+#   # }
+#
+# To perform a deep merge of options instead, place the options to be deeply merged
+# inside a :deep_merge hash:
+#
+#   bob = Person.new(:first_name => 'Bob', :last_name => 'Smith', :age => 41, :secrets => 'untold')
+#   bob.restful(:deep_merge => { :serialization => { :except => [:id] } })
+#   # => { 
+#   #   'name' => 'Bob Smith'
+#   #   'person' => { 
+#   #      'first_name' => 'Bob',
+#   #      'last_name' => 'Bob',
+#   #      'age' : 17,
+#   #   },
+#   #   'href' => 'http://www.example.com/web_service/people/1' }
+#   #   'books_href' => 'http://www.example.com/web_service/people/1/books' }
+#   # }
+#
+# These two techniques can be combined, but overwriting will occur prior to a deep merge...
+#
+# (There is a trap in how deep merge handles this.  If the above :except values had
+# not been configured as arrays, then deep merge would have overwritten rather than merging
+# them.  This could probably be adjusted with a closer look into the deep_merge docs.)
 module Restful
   # Route prefix for api calls.
   mattr_accessor :api_prefix

data/lib/restful/serializer.rb

@@ -1,17 +1,19 @@
 # This file is part of restful_serializer.  Copyright 2011 Joshua Partlow.  This is free software, see the LICENSE file for details.
 require 'active_record'
 require 'action_controller'
+require 'deep_merge'
 
 module Restful
   module UrlForHelpers
 
-    # Used to construct and attempt to call named routes be providing resource strings out
-    # of which an named route method name will be constructed:
+    # Used to construct and attempt to call named routes be providing resource
+    # strings out of which a named route method name will be constructed:
     #
     # Options:
     #
-    # * :resources => a symbol, string or array of same describing segments of the helper method name.
-    #   e.g. [:user, :comments] => user_comments (to which _url will be appended...)
+    # * :resources => a symbol, string or array of same describing segments of
+    #   the helper method name.  e.g. [:user, :comments] => user_comments (to
+    #   which _url will be appended...)
     # * :method => overrides the use of :resources and :prefix
     # * :args => any arguments to be passed to the named_route when it is called
     #
@@ -39,16 +41,23 @@ module Restful
     def initialize(subject, *args)
       self.subject = subject
 
-      self.base_klass = subject.class.base_class.name.underscore if subject.class.respond_to?(:base_class)
-      self.klass = subject.class.name.underscore
+      self.base_klass = subject.class.base_class.name.demodulize.underscore if subject.class.respond_to?(:base_class)
+      self.klass = subject.class.name.demodulize.underscore
 
       passed_options = (args.pop || {}).symbolize_keys
-      base_options = Restful.model_configuration_for(base_klass) || {}
-      class_options = Restful.model_configuration_for(klass) || {}
-      self.options = (klass == base_klass || class_options[:no_inherited_options]) ? 
-        class_options : 
-        base_options.merge(class_options)
-      self.options.merge!(passed_options)
+      if subject.kind_of?(Array)
+        # preserve options as is to be passed to array members
+        self.options = passed_options
+      else
+        deeply_merge = passed_options.delete(:deep_merge)
+        base_options = Restful.model_configuration_for(base_klass) || {}
+        class_options = Restful.model_configuration_for(klass) || {}
+        self.options = (klass == base_klass || class_options[:no_inherited_options]) ? 
+          class_options : 
+          base_options.merge(class_options)
+        self.options.merge!(passed_options)
+        self.options.deep_merge(deeply_merge) if deeply_merge
+      end
 
       self.shallow = options[:shallow]
     end

data/lib/restful/version.rb

@@ -1,3 +1,3 @@
 module Restful
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/restful_serializer.gemspec

@@ -27,4 +27,5 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency(%q<activerecord>, [">= 2.1.0", "<3.0.0"])
   s.add_runtime_dependency(%q<activesupport>, [">= 2.1.0", "<3.0.0"])
   s.add_runtime_dependency(%q<actionpack>, [">= 2.1.0", "<3.0.0"])
+  s.add_runtime_dependency(%q<deep_merge>, [">= 0.1.0"])
 end

data/spec/restful_spec.rb

@@ -19,13 +19,13 @@ describe Restful do
 
   describe "looking up model configurations" do
 
-    class Foo; end
-    class FooBar < Foo; end
+    class Super; end
+    class SubClass < Super; end
 
     before(:each) do
       Restful.model_configuration = {
-        :foo => :foo_config,
-        :foo_bar => :foo_bar_config,
+        :super => :super_config,
+        :sub_class => :sub_class_config,
       }
     end
 
@@ -34,36 +34,36 @@ describe Restful do
     end
 
     it "should lookup entries by symbol" do
-      Restful.model_configuration_for(:foo).should == :foo_config
+      Restful.model_configuration_for(:super).should == :super_config
     end
 
     it "should lookup entries from a string" do
-      Restful.model_configuration_for('foo').should == :foo_config
+      Restful.model_configuration_for('super').should == :super_config
     end
 
     it "should lookup entries by Class" do
-      Restful.model_configuration_for(Foo).should == :foo_config
-      Restful.model_configuration_for(FooBar).should == :foo_bar_config
+      Restful.model_configuration_for(Super).should == :super_config
+      Restful.model_configuration_for(SubClass).should == :sub_class_config
     end
 
     it "should lookup entries by instance class" do
-      Restful.model_configuration_for(Foo.new).should == :foo_config
-      Restful.model_configuration_for(FooBar.new).should == :foo_bar_config
+      Restful.model_configuration_for(Super.new).should == :super_config
+      Restful.model_configuration_for(SubClass.new).should == :sub_class_config
     end
 
     describe "with deep structures" do
 
       before(:each) do
         Restful.model_configuration = {
-          :foo => { :setting => {:with => :nested_hash } }
+          :super => { :setting => {:with => :nested_hash } }
         }
       end
 
       it "should provide deep clones of model_configuration elements" do
-        config = Restful.model_configuration_for(:foo)
+        config = Restful.model_configuration_for(:super)
         config[:setting][:with] = "changed"
         Restful.model_configuration.should == {
-          :foo => { :setting => {:with => :nested_hash } }
+          :super => { :setting => {:with => :nested_hash } }
         } 
       end
 

data/spec/serializer_spec.rb

@@ -140,6 +140,20 @@ describe Restful::Serializer do
       }
     end
 
+    it "should deeply merge overridden options" do
+      rs = Restful::Serializer.new(@foo, 
+        :deep_merge => { :serialization => { :only => [:id] } }
+      )
+      rs.serialize.should == {
+        'name' => @foo.fancy_name,
+        'foo' => { 
+          'id' => @foo.id,
+          'name' => @foo.name,
+          :a_method => @foo.a_method,
+        },
+        'href' => "http://test.org/prefix/foos/#{@foo.id}",
+      }
+    end
   end
 
   describe "with associations" do
@@ -183,7 +197,6 @@ describe Restful::Serializer do
         'special_href' => "http://test.org/foos/#{@bar1.foo_id}",
       }
     end
-
   end
 
   describe "with subclasses" do
@@ -218,7 +231,7 @@ describe Restful::Serializer do
           :associations => :bars,
         },
         :bar => {
-          :serialization => { :only => :name, :include => { :dingos => { :only =>  [ :name, :id] } } },
+          :serialization => { :only => [:name], :include => { :dingos => { :only =>  [ :name, :id] } } },
           :associations => [:foo, :dingos],
         },
       }
@@ -276,6 +289,52 @@ describe Restful::Serializer do
         },
       ] 
     end
+
+    it "should override options during initialization for each member" do
+      rs = Restful::Serializer.new(@foo.bars, 
+        :serialization => { :only => :id } 
+      )
+      rs.serialize.should == [
+        {
+          'name' => @bar1.name,
+          'href' => "http://test.org/bars/#{@bar1.id}",
+          'bar'  =>  {
+            'id' => @bar1.id,
+          },
+        },
+        {
+          'name' => @bar2.name,
+          'href' => "http://test.org/bars/#{@bar2.id}",
+          'bar'  =>  {
+            'id' => @bar2.id,
+          },
+        },
+      ] 
+    end
+
+    it "should deeply merge overridden options for each member" do
+      rs = Restful::Serializer.new(@foo.bars, 
+        :deep_merge => { :serialization => { :only => [:id] } }
+      )
+      rs.serialize.should == [
+        {
+          'name' => @bar1.name,
+          'href' => "http://test.org/bars/#{@bar1.id}",
+          'bar'  =>  {
+            'id' => @bar1.id,
+            'name' => @bar1.name,
+          },
+        },
+        {
+          'name' => @bar2.name,
+          'href' => "http://test.org/bars/#{@bar2.id}",
+          'bar'  =>  {
+            'id' => @bar2.id,
+            'name' => @bar2.name,
+          },
+        },
+      ] 
+    end
   end
 
   it "should hook into activerecord" do

data/spec/spec.opts

@@ -1,2 +1,4 @@
 --color
 --format nested
+--diff
+--debugger

data/spec/spec_helper.rb

@@ -1,5 +1,6 @@
 $LOAD_PATH.unshift(File.dirname(__FILE__))
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'rubygems'
 require 'restful'
 require 'spec'
 require 'spec/autorun'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: restful_serializer
 version: !ruby/object:Gem::Version 
-  hash: 27
-  prerelease: 
+  hash: 25
+  prerelease: false
   segments: 
   - 0
   - 1
-  - 0
-  version: 0.1.0
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Josh Partlow
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-08 00:00:00 -07:00
+date: 2011-04-21 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -106,6 +106,22 @@ dependencies:
         version: 3.0.0
   type: :runtime
   version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: deep_merge
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 0
+        - 1
+        - 0
+        version: 0.1.0
+  type: :runtime
+  version_requirements: *id005
 description: This library is used to decorate ActiveRecord with methods to assist in generating Restful content for Web Services.
 email: jpartlow@glatisant.org
 executables: []
@@ -162,7 +178,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: Helps with serializing activerecord instances as Restful resources.