roar 0.8.0 → 0.8.1

data/Gemfile

@@ -3,10 +3,10 @@ source "http://rubygems.org"
 # Specify your gem's dependencies in roar.gemspec
 gemspec
 
-#gem "representable", :path => "/home/nick/projects/representable"
+#gem "representable", :path => "../representable"
 #gem "test_xml", :path => "/home/nick/projects/test_xml" #"~> 0.1.0" 
 
 group :test do
-  gem "rails", "~> 3.0.0"
+  gem "rails", "~> 3.1.0"
   gem "sqlite3"
 end

data/README.textile

@@ -3,6 +3,8 @@ h1. ROAR
 _Streamlines the development of RESTful, Resource-Oriented Architectures in Ruby._
 
 
+Lets make documents suit our models and not models fit to documents
+
 h2. Introduction
 
 Roar is a framework for developing distributed applications while using hypermedia as key for application workflow.
@@ -63,7 +65,9 @@ h2. Representers
 To render a representational document, the backend service has to define a representer.
 
 <pre>module JSON
-  class Article < Roar::Representer::JSON
+  class Article
+    include Roar::Representer::JSON
+    
     property :title
     property :id
     
@@ -125,7 +129,9 @@ What if we wanted to check an existing order? We'd @GET http://orders/1@, right?
 Since orders may contain a composition of articles, how would the order service define its representer?
 
 <pre>module JSON
-  class Order < Roar::Representer::JSON
+  class Order 
+    include Roar::Representer::JSON
+    
     property :id
     property :client_id
     

data/Rakefile

@@ -7,7 +7,7 @@ task :default => [:test, :testrails]
 
 Rake::TestTask.new(:test) do |test|
   test.libs << 'test'
-  test.test_files = FileList['test/xml_representer_test.rb', 'test/model_representing_test.rb', 'test/representer_test.rb', 'test/transport_test.rb', 'test/http_verbs_test.rb', 'test/integration_test.rb', 'test/json_representer_test.rb', 'test/xml_hypermedia_test.rb', 'test/hypermedia_test.rb']
+  test.test_files = FileList['test/*_test.rb'] - ['test/integration_test.rb']
   test.verbose = true
 end
 

data/lib/roar/rails/representer_methods.rb

@@ -44,7 +44,8 @@ module Roar
           
           super name, options.reverse_merge(
             :as => "representer/#{namespace}/#{singular_name}".classify.constantize,
-            :tag => singular_name)
+            #:tag => singular_name  # FIXME: how/where to decide if singular TAG or not?
+            )
         end
       end
     end

data/lib/roar/representer/base.rb

@@ -0,0 +1,65 @@
+require 'representable'
+
+module Roar
+  module Representer
+    module Base
+      def self.included(base)
+        base.class_eval do
+          include Representable
+          extend ClassMethods
+          
+          class << self
+            alias_method :property, :representable_property
+            alias_method :collection, :representable_collection
+          end
+        end
+      end
+      
+        
+      module ClassMethods
+        # Creates a representer instance and fills it with +attributes+.
+        def from_attributes(attributes) # DISCUSS: better move to #new? how do we handle the original #new then?
+          new.tap do |representer|
+            yield representer if block_given?
+            attributes.each { |p,v| representer.public_send("#{p}=", v) }
+          end
+        end
+      end
+      
+      
+      # Convert representer's attributes to a nested attributes hash.
+      def to_attributes
+        {}.tap do |attributes|
+          self.class.representable_attrs.each do |definition|
+            value = public_send(definition.getter)
+            
+            if definition.typed?
+              value = definition.apply(value) do |v|
+                v.to_attributes  # applied to each typed attribute (even in collections).
+              end
+            end
+            
+            attributes[definition.name] = value
+          end
+        end
+      end
+    
+    private
+      def before_serialize(*)
+      end
+      
+      # Returns block used in #from_json and #from_xml to filter incoming arguments.
+      # This method is subject to change and might be removed, soon.
+      def deserialize_block_for_options(options)
+        return unless props = options[:except] || options[:include]
+        props.collect!{ |name| name.to_s }
+        
+        lambda do |bind| 
+          res = props.include?(bind.definition.name)
+          options[:include] ? res : !res
+        end
+      end
+      
+    end
+  end
+end

data/lib/roar/representer/feature/http_verbs.rb

@@ -1,16 +1,15 @@
 require 'roar/client/transport'
 
 module Roar
-  # Used in Models as convenience, ActiveResource-like methods. # FIXME: currently this is meant for clients like Representers.
+  # Gives HTTP-power to representers where those can automatically serialize, send, process and deserialize HTTP-requests.
   module Representer
     module Feature
       module HttpVerbs
-        extend ActiveSupport::Concern
-        
-        included do |base|
-          base.class_attribute :resource_base
+        def self.included(base)
+          base.extend ClassMethods
         end
         
+        
         module ClassMethods
           include Client::Transport
           
@@ -40,7 +39,7 @@ module Roar
           
           self.class.representable_attrs.each do |definition|
 
-            send(definition.setter, rep.public_send(definition.accessor))
+            send(definition.setter, rep.public_send(definition.getter))
           end # TODO: this sucks. do this with #properties and #replace_properties.
         end
         
@@ -48,7 +47,7 @@ module Roar
           rep = self.class.get(url, format) # TODO: where's the format? why do we need class here?
           
           self.class.representable_attrs.each do |definition|
-            send(definition.setter, rep.public_send(definition.accessor))
+            send(definition.setter, rep.public_send(definition.getter))
           end # TODO: this sucks. do this with #properties and #replace_properties.
         end
         

data/lib/roar/representer/feature/hypermedia.rb

@@ -1,21 +1,52 @@
-require "roar/model"
-
 module Roar
   module Representer
     module Feature
-      # Adds links methods to the model which can then be used for hypermedia links when
-      # representing the model.
-      module Hypermedia # TODO: test me.
-        extend ActiveSupport::Concern
+      # Adds #link to the representer to define hypermedia links in the representation.
+      #
+      # Example:
+      #
+      #   class Order
+      #     include Roar::Representer::JSON
+      #
+      #     property :id
+      #
+      #     link :self do
+      #       "http://orders/#{id}"
+      #     end
+      module Hypermedia
+        def self.included(base)
+          base.extend ClassMethods
+        end
+        
+        def before_serialize(options={})
+          prepare_links! unless options[:links] == false  # DISCUSS: doesn't work when links are already setup (e.g. from #deserialize).
+          super # Representer::Base
+        end
         
-        def links=(links)
-          @links = LinkCollection.new(links)
+        def links=(link_list)
+          links.replace(link_list)
         end
         
         def links
-          @links
+          @links ||= LinkCollection.new
         end
         
+      protected
+        # Setup hypermedia links by invoking their blocks. Usually called by #serialize.
+        def prepare_links!
+          links_def = self.class.find_links_definition or return
+          links_def.rel2block.each do |link|
+            links << links_def.sought_type.from_attributes({  # create Hyperlink representer.
+            "rel"   => link[:rel],
+            "href"  => run_link_block(link[:block])})
+          end
+        end
+        
+        def run_link_block(block)
+          instance_exec(&block)
+        end
+        
+        
         class LinkCollection < Array
           def [](rel)
             link = find { |l| l.rel.to_s == rel.to_s } and return link.href
@@ -24,19 +55,28 @@ module Roar
         
         
         module ClassMethods
-          # Defines an embedded hypermedia link.
+          # Defines a hypermedia link to be embedded in the document.
           def link(rel, &block)
-            unless links = representable_attrs.find { |d| d.is_a?(LinksDefinition)}
+            unless links = find_links_definition
               links = LinksDefinition.new(:links, links_definition_options)
               representable_attrs << links
-              #add_reader(links) # TODO: refactor in Roxml.
-#              attr_writer(links.accessor)
             end
             
             links.rel2block << {:rel => rel, :block => block}
           end
+          
+          def find_links_definition
+            representable_attrs.find do |d| d.is_a?(LinksDefinition) end
+          end
         end
         
+        
+        class LinksDefinition < Representable::Definition
+          # TODO: hide rel2block in interface.
+          def rel2block
+            @rel2block ||= []
+          end
+        end
       end
     end
   end

data/lib/roar/representer/feature/model_representing.rb

@@ -39,7 +39,7 @@ module Roar
         # Properties that are mapped to a model attribute.
         class ModelDefinition < ::Representable::Definition
           def compute_attribute_for(represented, attributes)
-            value = represented.send(accessor)
+            value = represented.send(getter)
                 
             if typed?
               value = apply(value) do |v|
@@ -47,40 +47,32 @@ module Roar
               end
             end
             
-            attributes[accessor] = value
+            attributes[name] = value
           end
         end
       end
       
       
       module ActiveRecordMethods
-        def to_nested_attributes # FIXME: works on first level only, doesn't check if we really need to suffix _attributes and is horriby implemented. just for protoyping.  
-          attrs = {}
-          
-          to_attributes.each do |k,v|
-          
-          
-          
-          #next if k.to_s == "links"  # FIXME: how to skip virtual attributes that are not mapped in a model?
-          clear_attributes(attrs)  
-            
-            attrs[k] = v
-            if v.is_a?(Hash) or v.is_a?(Array)
-              attrs["#{k}_attributes"] = attrs.delete(k)
+        def to_nested_attributes # FIXME: extract iterating with #to_attributes. 
+          {}.tap do |attributes|
+            self.class.representable_attrs.each do |definition|
+              next unless definition.kind_of?(ModelRepresenting::ModelDefinition)
+              
+              value = public_send(definition.getter)
+              
+              if definition.typed?
+                value = definition.apply(value) do |v|
+                  v.to_nested_attributes  # applied to each typed attribute (even in collections).
+                end
+              end
+              
+              key = definition.name
+              key = "#{key}_attributes" if definition.typed?
+              
+              attributes[key] = value
             end
           end
-          
-          attrs
-        end
-        
-      private
-        def clear_attributes(attrs)
-          puts "clearing #{attrs.inspect}"
-          attrs.each do |k,v|
-            attrs.delete(k) if k == "links"
-            
-            clear_attributes(v) if v.is_a?(Hash) 
-          end
         end
       end
     end

data/lib/roar/representer/json.rb

@@ -1,32 +1,62 @@
-require 'roar/representer'
+require 'roar/representer/base'
 require 'representable/json'
 
-
 module Roar
   module Representer
-    class JSON < Base
-      include Representable::JSON
+    module JSON
+      def self.included(base)
+        base.class_eval do
+          include Base
+          include Representable::JSON
+          
+          extend ClassMethods
+          include InstanceMethods # otherwise Representable overrides our #to_json.
+        end
+      end
       
-      def serialize
-        to_json
+      module InstanceMethods
+        def to_json(*args)
+          before_serialize(*args)
+          super
+        end
+        
+        def from_json(document, options={})
+          document ||= "{}" # DISCUSS: provide this for convenience, or better not?
+          
+          if block = deserialize_block_for_options(options) and 
+            return super(document, &block)
+          end
+          
+          super
+        end
+        
+        # Generic entry-point for rendering.
+        def serialize(*args)
+          to_json(*args)
+        end
       end
       
-      def self.deserialize(json)
-        from_json(json)
+      
+      module ClassMethods
+        def deserialize(json)
+          from_json(json)
+        end
+        
+        # TODO: move to instance method, or remove?
+        def links_definition_options
+          {:as => [Hyperlink]}
+        end
       end
       
+      
       # Encapsulates a hypermedia link.
-      class Hyperlink < self
+      class Hyperlink
+        include JSON
         self.representation_name = :link
         
         property :rel
         property :href
       end
-      
-      def self.links_definition_options
-        {:as => [Hyperlink]}
-      end
     end
-    
   end
 end

data/lib/roar/representer/xml.rb

@@ -1,43 +1,67 @@
-require 'roar/representer'
+require 'roar/representer/base'
 require 'representable/xml'
 
-
 module Roar
-  # Basic work-flow
-  # in:   * representer parses representation
-  #       * recognized elements are stored as representer attributes
-  # out:  * attributes in representer are assigned - either as hash in #to_xml, by calling #serialize(represented),
-  #         by calling representer's accessors (eg in client?) or whatever else
-  #       * representation is compiled from representer only
-  # TODO: make XML a module to include in Hyperlink < Base.
+  # Includes #from_xml and #to_xml into your represented object.
+  # In addition to that, some more options are available when declaring properties.
   module Representer
-    class XML < Base
-      include Representable::XML
-      
-      def serialize
-        to_xml.serialize
+    module XML
+      def self.included(base)
+        base.class_eval do
+          include Base
+          include Representable::XML
+
+          extend ClassMethods
+          include InstanceMethods # otherwise Representable overrides our #to_xml.
+        end
       end
       
-      def self.deserialize(xml)
-        from_xml(xml)
+      module InstanceMethods
+        def from_xml(document, options={})
+          if block = deserialize_block_for_options(options)
+            return super(document, &block)
+          end
+          
+          super
+        end
+        
+        def to_xml(*args)
+          before_serialize(*args)
+          super.serialize
+        end
+        
+        # Generic entry-point for rendering.
+        def serialize(*args)
+          to_xml(*args)
+        end
       end
       
       
+      module ClassMethods
+        include Representable::XML::ClassMethods
+        
+        def links_definition_options
+          {:from => :link, :as => [Hyperlink]}
+        end
+        
+        # Generic entry-point for parsing.
+        def deserialize(*args)
+          from_xml(*args)
+        end
+      end
+      
+            
       # Encapsulates a hypermedia <link ...>.
-      class Hyperlink < self
+      class Hyperlink
+        # TODO: make XML a module to include in Hyperlink < Base.
+        include XML
+        
         self.representation_name = :link
         
         property :rel,  :from => "@rel"
         property :href, :from => "@href"
       end
       
-      
-      def self.links_definition_options
-        {:tag => :link, :as => [Hyperlink]}
-      end
-      
-      require 'roar/representer/feature/hypermedia'
-      include Feature::Hypermedia
     end
   end
 end