purzelrakete-restful 0.2.1

data/lib/restful/serializers/atom_like_serializer.rb

@@ -0,0 +1,51 @@
+require 'restful/serializers/base'
+require 'builder'
+
+#
+#  Converts an APIModel to and from XML. 
+#
+module Restful
+  module Serializers
+    class AtomLikeSerializer < XMLSerializer
+      
+      serializer_name :atom_like
+      
+      protected
+        
+        def root_resource(node)
+          url_base = node.attribute(:base, :xml)
+          me_node = node.delete_element("link[@rel='self']")
+          own_url = me_node.attribute(:href)
+          Restful.resource(node.name, :path => own_url, :base => url_base)
+        end
+      
+        def build_link(el, type)
+          Restful.link(revert_link_name(el.attribute('rel')), nil, el.attribute('href'), type)
+        end
+        
+        def calculate_node_type(el)
+          return :link if el.name.downcase == "link"
+          (el.attributes["type"] || "string").to_sym
+        end
+                
+        def add_link_to(resource, builder, options = {})
+          is_self = !!options[:self]
+          builder.tag!("link", { :href => resource.path, :rel => (is_self ? "self" : resource.name) })
+        end
+        
+        def root_element(resource)
+          decorations = {}
+          
+          unless @nested_root
+            decorations =  { :"xml:base" => Restful::Rails.api_hostname } unless Restful::Rails.api_hostname.blank?
+            @nested_root = true
+          end
+          
+          [resource.name, decorations]
+        end
+        
+        def decorations(value); {}; end
+        def collections_decorations; {}; end                
+    end
+  end
+end

data/lib/restful/serializers/base.rb

@@ -0,0 +1,41 @@
+#
+#  Converts an APIModel to and from a given format.  
+#
+module Restful
+  module Serializers
+    class Base
+      cattr_accessor :serializers
+      
+      def serialize(resource, options = {}) # implement me. 
+        raise NotImplementedError.new
+      end
+      
+      def deserialize(resource, options = {}) # implement me. 
+        raise NotImplementedError.new        
+      end
+      
+      #
+      #  Grabs a serializer, given...
+      #
+      #    .serialize(:xml, Resource.new(:animal => "cow"))
+      #
+      def self.serializer(type)
+        serializers[type].new
+      end
+      
+      def self.serializer_name(key)
+        self.serializers ||= {}
+        self.serializers[key] = self
+      end
+      
+      protected
+        def transform_link_name(name)
+          name.to_s.gsub /_id$/, "-restful-url"
+        end
+      
+        def revert_link_name(name)
+          name.to_s.gsub /-restful-url$/, "_id"
+        end      
+    end
+  end
+end

data/lib/restful/serializers/hash_serializer.rb

@@ -0,0 +1,45 @@
+require 'restful/serializers/base'
+
+#
+#  AR params hash.
+#
+module Restful
+  module Serializers
+    class HashSerializer < Base
+      
+      serializer_name :hash
+      
+      def serialize(resource, options = {})
+        params = {}
+        
+        resource.values.each do |value|
+          if value.type == :collection # serialize the stuffs
+            resources = value.value
+            name = resources.first.name.pluralize
+            
+            array = []
+            resources.each { |r| array << serialize(r) } 
+            
+            params["#{value.name}".to_sym] = array
+          elsif value.type == :link
+            params[value.name] = Restful::Rails.tools.dereference(value.value)
+          elsif value.type == :resource
+            params["#{value.name}".to_sym] = serialize(value)
+          else # plain ole
+            string_value = case value.extended_type
+            when :datetime
+              value.value.xmlschema
+            else
+              value.value
+            end
+            
+            params[value.name] = string_value
+          end
+        end
+        
+        params["restful_url"] = resource.full_url
+        params
+      end
+    end
+  end
+end

data/lib/restful/serializers/json_serializer.rb

@@ -0,0 +1,20 @@
+require 'restful/serializers/base'
+require 'yajl'
+
+#
+#  AR params hash.
+#
+module Restful
+  module Serializers
+    class JsonSerializer < Base
+      
+      serializer_name :json
+      
+      def serialize(resource, options = {})
+        hasher = Restful::Serializers::HashSerializer.new
+        hash = hasher.serialize(resource, options)
+        Yajl::Encoder.encode(hash)
+      end
+    end
+  end
+end

data/lib/restful/serializers/params_serializer.rb

@@ -0,0 +1,40 @@
+require 'restful/serializers/base'
+require 'builder'
+
+#
+#  AR params hash.
+#
+module Restful
+  module Serializers
+    class ParamsSerializer < Base
+      
+      serializer_name :params
+      
+      def serialize(resource, options = {})
+        params = {}
+        
+        resource.values.each do |value|
+          if value.type == :collection # serialize the stuffs
+            resources = value.value
+            name = resources.first.name.pluralize
+            
+            array = []
+            resources.each do |resource|
+              array << serialize(resource)
+            end              
+            
+            params["#{value.name.to_sym}_attributes".to_sym] = array
+          elsif value.type == :link
+            params[value.name] = Restful::Rails.tools.dereference(value.value)
+          elsif value.type == :resource
+            params["#{value.name.to_sym}_attributes".to_sym] = serialize(value)
+          else # plain ole
+            params[value.name] = value.value
+          end
+        end
+        
+        params
+      end
+    end
+  end
+end

data/lib/restful/serializers/xml_serializer.rb

@@ -0,0 +1,146 @@
+require 'restful/serializers/base'
+require "rexml/document"
+require 'builder'
+require 'ruby-debug'
+
+#
+#  Converts an APIModel to and from XML. 
+#
+module Restful
+  module Serializers
+    class XMLSerializer < Base
+      
+      serializer_name :xml
+      
+      def serialize(resource, options = {})
+        xml = options[:builder] || Builder::XmlMarkup.new(:indent => 2)
+        xml.instruct! unless options[:instruct].is_a?(FalseClass)
+        
+        xml.tag!(*root_element(resource)) do
+          add_link_to(resource, xml, :self => true)
+                    
+          resource.values.each do |value|
+            
+            if value.type == :collection # serialize the stuffs
+              resources = value.value
+              if first_resource = resources.first
+                xml.tag!(first_resource.name.pluralize, collections_decorations) do
+                  resources.each do |resource|
+                    serialize(resource,  { :instruct => false, :builder => xml })
+                  end              
+                end
+              end
+              
+            elsif value.type == :link
+              add_link_to(value, xml)
+            elsif value.type == :resource
+              serialize(value, {:instruct => false, :builder => xml})
+            else # plain ole
+              add_tag(xml, value)
+            end
+          end
+        end       
+      end
+      
+      # returns a resource, or collection of resources. 
+      def deserialize(xml, options = {})
+        build_resource(REXML::Document.new(xml).root)
+      end
+      
+      protected
+      
+        def add_link_to(resource, builder, options = {})
+          is_self = !!options[:self]
+          
+          attributes = {:type => "link"}
+          attributes.merge!(:nil => "true") if resource.full_url.blank?
+          builder.tag!((is_self ? "restful-url" : transform_link_name(resource.name)), resource.full_url, attributes)
+        end
+      
+        def add_tag(builder, value)
+          string_value = case value.extended_type
+          when :datetime
+            value.value.xmlschema
+          else
+            value.value.to_s
+          end
+          
+          builder.tag!(
+            value.name.to_s.dasherize,
+            string_value,
+            decorations(value)
+          )
+        end
+        
+        def decorations(value)
+          decorations = {}
+
+          if value.extended_type == :binary
+            decorations[:encoding] = 'base64'
+          end
+
+          if value.extended_type != :string and value.extended_type != :notype
+            decorations[:type] = value.extended_type
+          end
+
+          if value.extended_type == :datetime
+            decorations[:type] = :datetime
+          end
+
+          if value.value.nil?
+            decorations[:nil] = true
+          end
+          
+          decorations
+        end
+        
+        def collections_decorations
+          { :type => "array" }
+        end
+        
+        def root_element(resource, options = {})
+          [resource.name]
+          end
+          
+        # turns a rexml node into a Resource
+        def build_resource(node)
+          resource = root_resource(node)
+          
+          node.elements.each do |el|
+            type = calculate_node_type(el)
+            resource.values << case type
+            
+            when :link : build_link(el, type)
+            when :datetime
+              Restful.attr(el.name, DateTime.parse(el.text), type)
+            when :resource
+              build_resource(el)
+            when :array
+              Restful.collection(el.name, el.elements.map { |child| build_resource(child) }, type)
+            else 
+              Restful.attr(el.name, el.text, type)
+            end
+          end
+
+          resource
+        end
+        
+        def calculate_node_type(el)
+          if el.children.size > 1 && el.attributes["type"].blank? 
+            return :resource
+          else
+            (el.attributes["type"] || "string").to_sym
+          end
+        end
+        
+        def build_link(el, type)
+          Restful.link(revert_link_name(el.name), nil, el.text, type)
+        end
+        
+        def root_resource(node)
+          url = node.delete_element("restful-url").try(:text)
+          Restful.resource(node.name, :url => url)
+        end
+    end
+  end
+end

data/lib/restful.rb

@@ -0,0 +1,64 @@
+require 'restful/rails'
+require 'restful/rails/active_record/configuration'
+require 'restful/rails/active_record/metadata_tools'
+require 'restful/rails/action_controller'
+require 'restful/converters/active_record'
+require 'restful/apimodel/resource'
+require 'restful/apimodel/attribute'
+require 'restful/apimodel/collection'
+require 'restful/apimodel/link'
+require 'restful/serializers/xml_serializer'
+require 'restful/serializers/json_serializer'
+require 'restful/serializers/atom_like_serializer'
+require 'restful/serializers/params_serializer'
+require 'restful/serializers/hash_serializer'
+
+module Restful
+    
+  MAJOR = 0
+  MINOR = 1
+  REVISION = 2
+  VERSION = [MAJOR, MINOR, REVISION].join(".")
+  
+  #
+  #  Restful.from_xml, #from_atom_like. Methods correspond with
+  #  resgistered serializers. 
+  #
+  def self.method_missing(method, *args, &block)
+    if method.to_s.match(/^from_(.*)$/)
+      if serializer_clazz = Restful::Serializers::Base.serializers[type = $1.to_sym]
+        s = serializer_clazz.new
+        s.deserialize(args.first)
+      else
+        super
+      end
+    else
+      super
+    end
+  end
+  
+  #
+  #  Shortcuts past the namespaces
+  #
+  
+  def self.cfg(*options)
+    Restful::Rails::ActiveRecord::Configuration::Config.new(*options)
+  end
+  
+  def self.attr(*options)
+    Restful::ApiModel::Attribute.new(*options)    
+  end
+  
+  def self.link(*options)
+    Restful::ApiModel::Link.new(*options)
+  end
+  
+  def self.collection(*options)
+    Restful::ApiModel::Collection.new(*options)
+  end
+  
+  def self.resource(*options)
+    Restful::ApiModel::Resource.new(*options)
+  end
+  
+end

data/rails/init.rb

@@ -0,0 +1 @@
+require 'restful'

data/restful.gemspec

@@ -0,0 +1,17 @@
+Gem::Specification.new do |s|
+  s.name = "restful"
+  s.version = "0.2.1"
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Daniel Bornkessel", "Rany Keddo"] 
+  s.date = "2009-08-11"
+  s.email = "M4SSIVE@m4ssive.com"
+  s.extra_rdoc_files = %w{ README.markdown }
+  s.files = %w{ init.rb lib/restful/apimodel/attribute.rb lib/restful/apimodel/collection.rb lib/restful/apimodel/link.rb lib/restful/apimodel/resource.rb lib/restful/converters/active_record.rb lib/restful/rails/action_controller.rb lib/restful/rails/active_record/configuration.rb lib/restful/rails/active_record/metadata_tools.rb lib/restful/rails.rb lib/restful/serializers/atom_like_serializer.rb lib/restful/serializers/base.rb lib/restful/serializers/hash_serializer.rb lib/restful/serializers/json_serializer.rb lib/restful/serializers/params_serializer.rb lib/restful/serializers/xml_serializer.rb lib/restful.rb LICENSE.markdown rails/init.rb Rakefile README.markdown restful.gemspec test/converters/active_record_converter_test.rb test/fixtures/models/person.rb test/fixtures/models/pet.rb test/fixtures/models/wallet.rb test/fixtures/people.json.yaml test/fixtures/people.xml.yaml test/fixtures/pets.xml.yaml test/rails/active_record_metadata_test.rb test/rails/configuration_test.rb test/rails/restful_publish_test.rb test/serializers/atom_serializer_test.rb test/serializers/json_serializer_test.rb test/serializers/params_serializer_test.rb test/serializers/xml_serializer_test.rb test/test_helper.rb TODO.markdown }
+  s.has_rdoc = true
+  s.rdoc_options = ["--line-numbers", "--inline-source"]
+  s.homepage = "http://github.com/M4SSIVE/restful"
+  s.require_paths = %w{ lib }
+  s.requirements = %w{ brianmario-yajl-ruby }
+  s.rubygems_version = "1.3.1"
+  s.summary = "api niceness. "
+end

data/test/converters/active_record_converter_test.rb

@@ -0,0 +1,108 @@
+require File.dirname(__FILE__) + '/../test_helper.rb'
+
+#
+#  FIXME: remove xml serialzation here and test resource directly. 
+#
+context "active record converter" do
+  setup do
+    Person.restful_publish(:name, :wallet, :current_location, :pets => [:name, :species])
+    Pet.restful_publish(:person_id, :name) # person_id gets converted to a link automagically.
+    
+    @person = Person.create(:name => "Joe Bloggs", :current_location => "Under a tree")
+    @wallet = @person.wallet = Wallet.create!(:contents => "something in the wallet")
+    @pet = @person.pets.create(:name => "Mietze", :species => "cat")
+  end
+  
+  teardown do
+    reset_config
+  end
+  
+  specify "should return link attributes from a model" do
+    @pet.to_restful.links.map { |node| node.name }.sort.should.equal [:person_id]
+  end
+  
+  specify "should convert a NULL inner association such as person.wallet to a link with a null value" do
+    @person.wallet = nil
+    
+    wallet = @person.to_restful(:restful_options => { :expansion => :collapsed }).links.select { |link| link.name == "wallet-restful-url" }.first
+    wallet.should.not.== nil
+    wallet.value.should.== nil
+  end
+  
+  specify "should return plain attributes from a model" do
+    @pet.to_restful.simple_attributes.map { |node| node.name }.should.equal [:name]
+  end
+  
+  specify "should return collections attributes from a model" do
+    restful = @person.to_restful
+    restful.collections.map { |node| node.name }.sort.should.equal [:pets]
+  end
+  
+  specify "should be able to convert themselves to an apimodel containing all and only the attributes exposed by Model.publish_api" do    
+    resource = @person.to_restful
+    
+    resource.simple_attributes.select { |node| node.name == :name }.should.not.blank
+    resource.simple_attributes.select { |node| node.name == :biography }.should.blank
+
+    mietze = @person.to_restful.collections .select { |node| node.name == :pets }.first.value.first
+    mietze.simple_attributes.size.should.== 2
+    mietze.simple_attributes.select { |node| node.name == :name }.should.not.blank
+    mietze.simple_attributes.select { |node| node.name == :species }.should.not.blank
+  end
+
+  specify "should be able to convert themselves to an apimodel containing all and only the attributes exposed by Model.publish_api. this holds true if to_restful is called with some configuration options. " do    
+    resource = @person.to_restful(:restful_options => { :nested => false })
+    resource.simple_attributes.select { |node| node.name == :name }.should.not.blank
+    resource.simple_attributes.select { |node| node.name == :biography }.should.blank
+
+    mietze = resource.collections .select { |node| node.name == :pets }.first.value.first
+    mietze.simple_attributes.size.should.== 2
+    mietze.simple_attributes.select { |node| node.name == :name }.should.not.blank
+    mietze.simple_attributes.select { |node| node.name == :species }.should.not.blank
+  end
+  
+  specify "should be able to override to_restful published fields by passing them into the method" do
+    api = @person.to_restful(:pets)
+
+    api.simple_attributes.should.blank?
+    api.collections.map { |node| node.name }.sort.should.equal [:pets]
+  end
+  
+  specify "should be able to handle relations that are nil/null" do
+    @person.wallet = nil
+    @person.save!
+    @person.reload
+
+    assert_nothing_raised do
+      @person.to_restful
+    end
+  end
+
+  specify "should be able to expand a :belongs_to relationship" do
+    xml_should_eql_fixture(@pet.to_restful_xml(:owner), "pets", :nameless_pet)
+  end
+
+  specify "should return collapsed resources by default when :expansion => :collapsed is passed" do
+    Person.restful_publish(:name, :wallet, :restful_options => { :expansion => :collapsed })
+    xml_should_eql_fixture(@person.to_restful_xml, "people", :joe_bloggs)
+  end
+
+  specify "should be able to export content generated by methods that return strings" do
+    xml_should_eql_fixture(@person.to_restful_xml(:location_sentence), "people", :no_wallet)
+  end
+
+  specify "should be able to export content generated by methods (not attributes) and compute the correct style" do 
+    xml_should_eql_fixture(@person.to_restful_xml(:oldest_pet), "people", :with_oldest_pet)
+  end
+
+  specify "should be able to export content generated by methods (not attributes) while filtering with a nested configuration" do
+    xml_should_eql_fixture(@person.to_restful_xml(:oldest_pet => [:species]), "people", :with_oldest_pet_species)    
+  end
+
+  specify "should create element with nil='true' attribute if no relation is set" do 
+    @person.wallet = nil
+    @person.save
+
+    xml_should_eql_fixture(@person.to_restful_xml(:wallet), "people", :joe_with_zwiebelleder)
+  end
+end

data/test/fixtures/models/person.rb

@@ -0,0 +1,17 @@
+class Person < ActiveRecord::Base
+  has_many :pets
+  has_one  :wallet
+
+  accepts_nested_attributes_for :pets
+  accepts_nested_attributes_for :wallet
+  
+  def oldest_pet
+    pets.first :order => "age DESC"
+  end
+  
+  def location_sentence
+    "Hi. I'm currently in #{ current_location }"
+  end  
+  
+  apiable
+end

data/test/fixtures/models/pet.rb

@@ -0,0 +1,5 @@
+class Pet < ActiveRecord::Base
+  belongs_to :owner, :class_name => "Person", :foreign_key => "person_id"
+
+  apiable
+end

data/test/fixtures/models/wallet.rb

@@ -0,0 +1,5 @@
+class Wallet < ActiveRecord::Base
+  belongs_to :person  
+
+  apiable
+end

data/test/fixtures/people.json.yaml

@@ -0,0 +1,16 @@
+bloggs: 
+  |
+    { 
+      "restful_url": "http://example.com:3000/people/<%= @person.to_param %>",
+      "wallet": { 
+        "restful_url": "http://example.com:3000/wallets/<%= @person.wallet.to_param %>",
+        "contents": "an old photo, 5 euros in coins" 
+      },
+      "current_location": "Under a tree",
+      "name": "Joe Bloggs",
+      "pets": [ { 
+        "restful_url": "http://example.com:3000/pets/<%= @person.pets.first.to_param %>", 
+        "name": "mietze" 
+       }],
+      "created_at": "<%= @person.created_at.xmlschema %>"
+    }