roar 0.8.1 → 0.8.2

data/CHANGES.markdown

@@ -0,0 +1,8 @@
+h2. 0.8.2
+
+* Removing `restfulie` dependency - we now use `Net::HTTP`.
+
+
+h2. 0.8.1
+
+* Added the :except and :include options to `#from_*`.

data/Gemfile

@@ -4,9 +4,3 @@ source "http://rubygems.org"
 gemspec
 
 #gem "representable", :path => "../representable"
-#gem "test_xml", :path => "/home/nick/projects/test_xml" #"~> 0.1.0" 
-
-group :test do
-  gem "rails", "~> 3.1.0"
-  gem "sqlite3"
-end

data/README.textile

@@ -1,28 +1,27 @@
 h1. ROAR
 
-_Streamlines the development of RESTful, Resource-Oriented Architectures in Ruby._
+_Resource-Oriented Architectures in Ruby._
 
+"Lets make documents suit our models and not models fit to documents."
 
-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.
+REST is about representations. Representations are documents. Documents are pushed back and forth between clients and REST services. Roar focuses on providing object-oriented representations.
 
-REST is an architectural style for distributed systems. However, many implementations forget about the _distributed_ part of REST and simply map CRUD operations to HTTP verbs in a monolithic application.
+Most REST gems provide a neat HTTP interface, automatic parsing of documents and a more or less convenient way for rendering representations. Roar is different. The central concept of Roar are *representers* - object-oriented documents suitable for parsing _and_ rendering, extendable at runtime and with hypermedia support. The Representer concept is the answer to the missing REST abstraction layer in most frameworks.
 
 
 h2. Features
 
-* Roar worries about incoming and outgoing *representation documents*.
-* Representers let you declaratively *define your representations*.
-* Representations now are *OOP instances* with accessors, methods and behaviour.
-* Both *rendering and parsing* representations is handled by representers which keeps knowledge in one place.
-* Features as *hypermedia* support and *HTTP* methods can be mixed in dynamically.
-* Representers are packagable in gems for *distribution to services and clients*.
-* *Framework agnostic*, runs with Sinatra, Rails & Co.
-* Extra support for *Rails*.
-* Makes *testing distributed REST systems* as easy as possible.
+* OOP access to documents.
+* Parsing _and_ rendering of representations in one place.
+* Declaratively define document syntax and semantics.
+* Hypermedia support.
+* ActiveResource-like client support.
+* Useable in both client _and_ server.
+* Framework agnostic, runs with sinatra, Rails, webmachine and friends.
+
 
 h2. Example
 
@@ -64,17 +63,16 @@ h2. Representers
 
 To render a representational document, the backend service has to define a representer.
 
-<pre>module JSON
-  class Article
-    include Roar::Representer::JSON
-    
-    property :title
-    property :id
-    
-    link :self do
-      article_url(represented)
-    end 
-  end
+<pre>
+class Article
+  include Roar::Representer::JSON
+  
+  property :title
+  property :id
+  
+  link :self do
+    article_url(represented)
+  end 
 end
 </pre>
 
@@ -85,18 +83,10 @@ h3. Rendering Representations in the Service
 
 In order to *render* an actual document, the backend service would have to do a few steps: creating a representer, filling in data, and then serialize it.
 
-<pre>JSON::Article.new(
-  :title  => "Lonestar",
-  :id     => 666).
-  serialize # => "{\"article\":{\"id\":666, ...
-</pre>
-
-Using the @ModelRepresenting@ feature module we can take a shortcut.
-
-<pre>@beer = Article.find_by_title("Lonestar")
-
-JSON::Article.from_model(@beer).
-  serialize # => "{\"article\":{\"id\":666, ...
+<pre>Article.new(
+  title: "Lonestar",
+  id:    666).
+  to_json # => "{\"article\":{\"id\":666, ...
 </pre>
 
 Articles itself are useless, so they may be placed into orders. This is the next example.
@@ -128,23 +118,22 @@ 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 
-    include Roar::Representer::JSON
-    
-    property :id
-    property :client_id
-    
-    collection :articles, :as => Article
-    
-    link :self do
-      order_url(represented)
-    end
-    
-    link :items do
-      items_url
-    end 
+<pre>
+class Order 
+  include Roar::Representer::JSON
+  
+  property :id
+  property :client_id
+  
+  collection :articles, :as => Article
+  
+  link :self do
+    order_url(represented)
   end
+  
+  link :items do
+    items_url
+  end 
 end
 </pre>
 
@@ -159,21 +148,11 @@ If we were to implement an endpoint for creating new orders, we'd allow POST to
 
 <pre>
   post "/orders" do
-    incoming = JSON::Order.deserialize(request.body.string)
+    incoming = Order.deserialize(request.body.string)
     puts incoming.to_attributes #=> {:client_id => 815}
 </pre>
  
-Again, the @ModelRepresenting@ module comes in handy for creating a new database record.
-
-<pre>
-  post "/orders" do
-    # ...
-    @order = Order.create(incoming.to_nested_attributes)
-    
-    JSON::Order.for_model(@order).serialize
-</pre>
-
-Look how the @#to_nested_attributes@ method helps extracting data from the incoming document and, again, @#serialize@ returns the freshly created order's representation. Roar's representers are truely working in both directions, rendering and parsing and thus prevent you from redundant knowledge sharing.
+Look how the @#to_attributes@ method helps extracting data from the incoming document and, again, @#to_json@ returns the freshly created order's representation. Roar's representers are truely working in both directions, rendering and parsing and thus prevent you from redundant knowledge sharing.
 
 
 h2. Representers in the Client
@@ -189,7 +168,7 @@ To create a new order, the frontend needs to POST to the REST backend. Here's ho
 
 
 <pre>
-  order = JSON::Order.new(:client_id => current_user.id)
+  order = Order.new(:client_id => current_user.id)
   order.post!("http://orders/")
 </pre>
 
@@ -239,7 +218,7 @@ h3. Using Hypermedia
 Let the frontend add the delicious "Lonestar" beer to our order, now!
 
 <pre>
-beer = JSON::Article.new(:title => "Lonestar Beer")
+beer = Article.new(:title => "Lonestar Beer")
 beer.post(order.links[:items])
 </pre>
 
@@ -280,7 +259,7 @@ What if the ordering API is going a different way? What if we had to place artic
 Here's what could happen in the frontend.
 
 <pre>
-beer = JSON::Article.new(:title => "Lonestar Beer")
+beer = Article.new(:title => "Lonestar Beer")
 order.items << beer
 order.post!(order.links[:self])
 </pre>

data/TODO.markdown

@@ -0,0 +1 @@
+* Add proxies, so nested models can be lazy-loaded.

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

@@ -1,4 +1,4 @@
-require 'roar/client/transport'
+require 'roar/representer/feature/transport'
 
 module Roar
   # Gives HTTP-power to representers where those can automatically serialize, send, process and deserialize HTTP-requests.
@@ -11,7 +11,7 @@ module Roar
         
         
         module ClassMethods
-          include Client::Transport
+          include Transport
           
           def get(url, format)  # TODO: test me!
             #url = resource_base + variable_path.to_s

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

@@ -0,0 +1,43 @@
+require "net/http"
+require "uri"
+
+module Roar
+  module Representer
+    module Feature
+      # Implements the HTTP verbs with Net::HTTP.
+      module Transport
+        # TODO: generically handle return codes/let Restfulie do it.
+        def get_uri(uri, as)
+          do_request(Net::HTTP::Get, uri, as)
+        end
+        
+        def post_uri(uri, body, as)
+          do_request(Net::HTTP::Post, uri, as)
+        end
+        
+        def put_uri(uri, body, as)
+          do_request(Net::HTTP::Put, uri, as)
+        end
+        
+        def patch_uri(uri, body, as)
+          do_request(Net::HTTP::Patch, uri, as)
+        end
+        
+        def delete_uri(uri, as)
+          do_request(Net::HTTP::Delete, uri, as)
+        end
+      
+      private
+        def do_request(what, uri, as, body="")
+          # DISCUSS: can this be made easier?
+          uri   = URI.parse(uri)
+          http  = Net::HTTP.new(uri.host, uri.port)
+          req   = what.new(uri.request_uri)
+          req.content_type  = as
+          req.body          = body if body
+          http.request(req)
+        end
+      end
+    end
+  end
+end

data/lib/roar/version.rb

@@ -1,3 +1,3 @@
 module Roar
-  VERSION = "0.8.1"
+  VERSION = "0.8.2"
 end

data/roar.gemspec

@@ -20,11 +20,9 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
   
   s.add_runtime_dependency "representable", "~> 0.9.2"
-  s.add_runtime_dependency "restfulie", "~> 1.0.0"
-  s.add_runtime_dependency "hooks",     "~> 0.1.4"
+  s.add_runtime_dependency "hooks",         "~> 0.1.4"
   
   s.add_development_dependency "test_xml"
   s.add_development_dependency "minitest",         "~> 1.6.0"
   s.add_development_dependency "sinatra",          "~> 1.2.6"
-  s.add_development_dependency "sinatra-reloader", "~> 0.5.0"
 end

data/test/transport_test.rb

@@ -1,28 +1,28 @@
 require 'test_helper'
-require 'roar/client/transport'
+require 'roar/representer/feature/transport'
 
 class TransportTest < MiniTest::Spec
   describe "Transport" do
     before do
       @klass = Class.new(Object) do
-        include Roar::Client::Transport
+        include Roar::Representer::Feature::Transport
       end
       @o = @klass.new
     end
     
-    it "#get_uri returns Restfulie response" do
+    it "#get_uri returns response" do
       assert_equal "<method>get</method>",  @o.get_uri("http://localhost:9999/method", "application/xml").body
     end
     
-    it "#post_uri returns Restfulie response" do
+    it "#post_uri returns response" do
       assert_equal "<method>post</method>",  @o.post_uri("http://localhost:9999/method", "booty", "application/xml").body
     end
     
-    it "#put_uri returns Restfulie response" do
+    it "#put_uri returns response" do
       assert_equal "<method>put</method>",  @o.put_uri("http://localhost:9999/method", "booty", "application/xml").body
     end
     
-    it "#delete_uri returns Restfulie response" do
+    it "#delete_uri returns response" do
       assert_equal "<method>delete</method>",  @o.delete_uri("http://localhost:9999/method", "application/xml").body
     end
     

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 8
-  - 1
-  version: 0.8.1
+  - 2
+  version: 0.8.2
 platform: ruby
 authors: 
 - Nick Sutterer
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-11-25 00:00:00 +01:00
+date: 2011-11-27 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -32,25 +32,10 @@ dependencies:
         version: 0.9.2
   type: :runtime
   version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: restfulie
-  prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ~>
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 1
-        - 0
-        - 0
-        version: 1.0.0
-  type: :runtime
-  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
   name: hooks
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -61,11 +46,11 @@ dependencies:
         - 4
         version: 0.1.4
   type: :runtime
-  version_requirements: *id003
+  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
   name: test_xml
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -74,11 +59,11 @@ dependencies:
         - 0
         version: "0"
   type: :development
-  version_requirements: *id004
+  version_requirements: *id003
 - !ruby/object:Gem::Dependency 
   name: minitest
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -89,11 +74,11 @@ dependencies:
         - 0
         version: 1.6.0
   type: :development
-  version_requirements: *id005
+  version_requirements: *id004
 - !ruby/object:Gem::Dependency 
   name: sinatra
   prerelease: false
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -104,22 +89,7 @@ dependencies:
         - 6
         version: 1.2.6
   type: :development
-  version_requirements: *id006
-- !ruby/object:Gem::Dependency 
-  name: sinatra-reloader
-  prerelease: false
-  requirement: &id007 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ~>
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        - 5
-        - 0
-        version: 0.5.0
-  type: :development
-  version_requirements: *id007
+  version_requirements: *id005
 description: Streamlines the development of RESTful, resource-oriented architectures in Ruby.
 email: 
 - apotonick@gmail.com
@@ -131,13 +101,12 @@ extra_rdoc_files: []
 
 files: 
 - .gitignore
+- CHANGES.markdown
 - Gemfile
 - README.textile
 - Rakefile
+- TODO.markdown
 - lib/roar.rb
-- lib/roar/client/entity_proxy.rb
-- lib/roar/client/proxy.rb
-- lib/roar/client/transport.rb
 - lib/roar/rails.rb
 - lib/roar/rails/controller_methods.rb
 - lib/roar/rails/representer_methods.rb
@@ -146,6 +115,7 @@ files:
 - lib/roar/representer/feature/http_verbs.rb
 - lib/roar/representer/feature/hypermedia.rb
 - lib/roar/representer/feature/model_representing.rb
+- lib/roar/representer/feature/transport.rb
 - lib/roar/representer/json.rb
 - lib/roar/representer/xml.rb
 - lib/roar/version.rb

data/lib/roar/client/entity_proxy.rb

@@ -1,58 +0,0 @@
-require "roar/model"
-require "roar/representer/xml"
-require "active_support/core_ext/module/attr_internal"
-require "roar/client/proxy"
-
-module Roar
-  module Client
-    # Wraps associated objects, they can be retrieved with #finalize!
-    # Used e.g. in Representer::Xml.has_proxied.
-    class EntityProxy
-      # FIXME: where to move me? i do Representable and i use Transport. however, i'm only for clients.
-      include Model
-      include Representer::Xml # FIXME: why does EntityProxy know about xml? get this from Representable or so.
-      extend Proxy
-      
-      attr_internal :proxied_resource
-      
-      
-      
-      class << self
-        attr_accessor :options
-        
-        def class_for(options)
-          Class.new(self).tap { |k| k.options = options }
-        end
-      
-        def model_name
-          options[:class].model_name  # proxy!
-        end
-        
-        def from_attributes(attrs)  # FIXME: move to Representable or so.
-          new(attrs)
-        end
-      end
-      
-      # Get the actual proxied resource.
-      def finalize!(*)
-        # TODO: move to class.
-        # DISCUSS: how to compute uri? what if NO uri passed? exception?
-        self.proxied_resource = self.class.get_model(original_attributes["uri"], self.class.options[:class])
-      end
-      
-      def attributes
-        # DISCUSS: delegate all unknown methods to the proxied object?
-        proxied_resource.attributes # proxy!
-      end
-      
-      def attributes_for_xml(*options)
-        original_attributes
-      end
-      
-    private
-      def original_attributes
-        @attributes
-      end
-    end
-  end
-end

data/lib/roar/client/proxy.rb

@@ -1,14 +0,0 @@
-module Roar
-  module Client
-    
-    module Proxy
-      include Transport
-      
-      def get_model(uri, klass) # DISCUSS: not directly used in models. USED in EntityProxy.
-        body = get_uri(uri).body
-        klass.from_xml(body)  # DISCUSS: knows about DE-serialization and representation-type!
-      end
-    end
-  end
-  
-end

data/lib/roar/client/transport.rb

@@ -1,29 +0,0 @@
-require "restfulie"
-
-module Roar
-  module Client
-    # Implements the HTTP verbs by abstracting Restfulie.
-    module Transport
-      # TODO: generically handle return codes/let Restfulie do it.
-      def get_uri(uri, as)
-        Restfulie.at(uri).accepts(as).get # TODO: debugging/logging here.
-      end
-      
-      def post_uri(uri, body, as)
-        Restfulie.at(uri).as(as).post(body)
-      end
-      
-      def put_uri(uri, body, as)
-        Restfulie.at(uri).as(as).put(body)
-      end
-      
-      def patch_uri(uri, body, as)
-        Restfulie.at(uri).as(as).patch(body)
-      end
-      
-      def delete_uri(uri, as)
-        Restfulie.at(uri).accepts(as).delete # TODO: debugging/logging here.
-      end
-    end
-  end
-end