her 0.1 → 0.1.1

data/README.md

@@ -39,6 +39,12 @@ User.find(1)  # => Fetches "https://api.example.com/users/1" and return a User o
 
 ## Relationships
 
+You can define `has_many` relationships in your models. The relationship data is handled in two different ways. When parsing a resource from JSON data, if there’s a relationship data included, it will be used to create new Ruby objects.
+
+If no relationship data was included when parsing a resource, calling a method with the same name as the relationship will fetch the data (providing there’s an HTTP request available for it).
+
+For example, with this setup:
+
 ```ruby
 class User
   include Her::Model
@@ -48,15 +54,43 @@ end
 class Comment
   include Her::Model
 end
+```
+
+Including relationship data in the resource, no extra HTTP request is made when calling the `#comments` method:
+
+```ruby
+@user = User.find(1) # { :data => { :id => 1, :name => "Rémi Prévost", :comments => [{ :id => 1, :text => "Foo" }, { :id => 2, :text => "Bar" }] }}
+@user.comments # => [#<Comment id=1>, #<Comment id=2>] fetched directly from @user
+```
+
+If there’s no relationship data in the resource, an extra HTTP request (to `GET /users/1/comments`) is made when calling the `#comments` method:
 
-user = User.find(1)
-user.comments # => [#<Comment id=1>, #<Comment id=2>]
+```ruby
+@user = User.find(1) # { :data => { :id => 1, :name => "Rémi Prévost" }}
+@user.comments # => [#<Comment id=1>, #<Comment id=2>] fetched from /users/1/comments
 ```
 
+However, subsequent calls to `#comments` will not trigger the extra HTTP request.
+
 ## Custom requests
 
-TBD.
+You can easily add custom methods for your models. You can either use `get_collection` (which maps the returned data to a collection of resources), `get_resource` (which maps the returned data to a single resource) or `get_raw` (which yields the parsed data return from the HTTP request).
 
-## Hooks
+```ruby
+class User
+  include Her::Model
 
-TBD.
+  def self.popular
+    get_collection("/users/popular")
+  end
+
+  def self.total
+    get_raw("/users/stats") do |parsed_data|
+      parsed_data[:data][:total_users]
+    end
+  end
+end
+
+User.popular  # => [#<User id=1>, #<User id=2>]
+User.total    # => 42
+```

data/lib/her/api.rb

@@ -26,7 +26,7 @@ module Her
       @parse_with = lambda do |response|
         json = JSON.parse(response.body, :symbolize_names => true)
         {
-          :resource => json[:data],
+          :data => json[:data],
           :errors => json[:errors],
           :metadata => json[:metadata],
         }
@@ -38,7 +38,7 @@ module Her
     end # }}}
 
     # Define a custom parsing procedure. The procedure is passed the response object and is
-    # expected to return a hash with three keys: a main resource Hash, an errors Array
+    # expected to return a hash with three keys: a main data Hash, an errors Array
     # and a metadata Hash.
     #
     # @example

data/lib/her/model/http.rb

@@ -12,7 +12,6 @@ module Her
       # @example
       #  class User
       #    include Her::Model
-      #    uses_api $example_api
       #    collection_path "users"
       #  end
       def collection_path(path=nil) # {{{
@@ -28,36 +27,99 @@ module Her
       end # }}}
 
       # Make a GET request and return the parsed JSON response (not mapped to objects)
-      #
-      # @example
-      #   User.get "/users/1"
-      def get(path, attrs={}, &block) # {{{
+      def get_raw(path, attrs={}, &block) # {{{
         request(attrs.merge(:_method => :get, :_path => path), &block)
       end # }}}
 
+      # Make a GET request and return a collection of resources
+      def get_collection(path, attrs={}) # {{{
+        get_raw(path, attrs) do |parsed_data|
+          new_collection(parsed_data)
+        end
+      end # }}}
+
+      # Make a GET request and return a collection of resources
+      def get_resource(path, attrs={}) # {{{
+        get_raw(path, attrs) do |parsed_data|
+          new(parsed_data[:data])
+        end
+      end # }}}
+
       # Make a POST request and return the parsed JSON response (not mapped to objects)
-      #
-      # @example
-      #   User.post "/users", :fullname => "G.O.B. Bluth"
-      def post(path, attrs={}, &block) # {{{
+      def post_raw(path, attrs={}, &block) # {{{
         request(attrs.merge(:_method => :post, :_path => path), &block)
       end # }}}
 
+      # Make a POST request and return a collection of resources
+      def post_collection(path, attrs={}) # {{{
+        post_raw(path, attrs) do |parsed_data|
+          new_collection(parsed_data)
+        end
+      end # }}}
+
+      # Make a POST request and return a collection of resources
+      def post_resource(path, attrs={}) # {{{
+        post_raw(path, attrs) do |parsed_data|
+          new(parsed_data[:data])
+        end
+      end # }}}
+
       # Make a PUT request and return the parsed JSON response (not mapped to objects)
-      #
-      # @example
-      #   User.put "/users/1", :email => "gob@bluthcompany.com"
-      def put(path, attrs={}, &block) # {{{
+      def put_raw(path, attrs={}, &block) # {{{
         request(attrs.merge(:_method => :put, :_path => path), &block)
       end # }}}
 
+      # Make a PUT request and return a collection of resources
+      def put_collection(path, attrs={}) # {{{
+        put_raw(path, attrs) do |parsed_data|
+          new_collection(parsed_data)
+        end
+      end # }}}
+
+      # Make a PUT request and return a collection of resources
+      def put_resource(path, attrs={}) # {{{
+        put_raw(path, attrs) do |parsed_data|
+          new(parsed_data[:data])
+        end
+      end # }}}
+
+      # Make a PATCH request and return the parsed JSON response (not mapped to objects)
+      def patch_raw(path, attrs={}, &block) # {{{
+        request(attrs.merge(:_method => :patch, :_path => path), &block)
+      end # }}}
+
+      # Make a PATCH request and return a collection of resources
+      def patch_collection(path, attrs={}) # {{{
+        patch_raw(path, attrs) do |parsed_data|
+          new_collection(parsed_data)
+        end
+      end # }}}
+
+      # Make a PATCH request and return a collection of resources
+      def patch_resource(path, attrs={}) # {{{
+        patch_raw(path, attrs) do |parsed_data|
+          new(parsed_data[:data])
+        end
+      end # }}}
+
       # Make a DELETE request and return the parsed JSON response (not mapped to objects)
-      #
-      # @example
-      #   User.delete "/users/1"
-      def delete(path, attrs={}, &block) # {{{
+      def delete_raw(path, attrs={}, &block) # {{{
         request(attrs.merge(:_method => :delete, :_path => path), &block)
       end # }}}
+
+      # Make a DELETE request and return a collection of resources
+      def delete_collection(path, attrs={}) # {{{
+        delete_raw(path, attrs) do |parsed_data|
+          new_collection(parsed_data)
+        end
+      end # }}}
+
+      # Make a DELETE request and return a collection of resources
+      def delete_resource(path, attrs={}) # {{{
+        delete_raw(path, attrs) do |parsed_data|
+          new(parsed_data[:data])
+        end
+      end # }}}
     end
   end
 end

data/lib/her/model/orm.rb

@@ -9,37 +9,67 @@ module Her
         @data = self.class.parse_relationships(@data)
       end # }}}
 
+      # Initialize a collection of resources with raw data from an HTTP request
+      #
+      # @example
+      #   User.get("/users/popular") { |data| User.new_collection(data) }
+      def new_collection(parsed_data) # {{{
+        collection_data = parsed_data[:data]
+        Her::Model::ORM.initialize_collection(self.to_s.downcase.to_sym, collection_data)
+      end # }}}
+
       # Initialize a collection of resources
       # @private
       def self.initialize_collection(name, collection_data) # {{{
         collection_data.map { |item_data| Object.const_get(name.to_s.classify).new(item_data) }
       end # }}}
 
-      # Handles missing methods
+      # Handles missing methods by routing them through @data
       # @private
-      def method_missing(method) # {{{
-        method = method.to_s.gsub(/(\?|\!)$/, "").to_sym
-        @data.include?(method) ? @data[method] : super
+      def method_missing(method, attrs=nil) # {{{
+        assignment_method = method.to_s =~ /\=$/
+        method = method.to_s.gsub(/(\?|\!|\=)$/, "").to_sym
+        if @data.include?(method)
+          if attrs and assignment_method
+            @data[method.to_s.gsub(/\=$/, "").to_sym] = attrs
+          else
+            @data[method]
+          end
+        else
+          super
+        end
       end # }}}
 
       # Fetch a specific resource based on an ID
       def find(id, params={}) # {{{
         request(params.merge(:_method => :get, :_path => "#{@her_collection_path}/#{id}")) do |parsed_data|
-          new(parsed_data[:resource])
+          new(parsed_data[:data])
         end
       end # }}}
 
       # Fetch a collection of resources
       def all(params={}) # {{{
         request(params.merge(:_method => :get, :_path => "#{@her_collection_path}")) do |parsed_data|
-          Her::Model::ORM.initialize_collection(to_s.downcase.pluralize, parsed_data[:resource])
+          Her::Model::ORM.initialize_collection(to_s.downcase.pluralize, parsed_data[:data])
         end
       end # }}}
 
       # Create a resource
       def create(params={}) # {{{
         request(params.merge(:_method => :post, :_path => "#{@her_collection_path}")) do |parsed_data|
-          new(parsed_data[:resource])
+          new(parsed_data[:data])
+        end
+      end # }}}
+
+      # Save a resource
+      def save # {{{
+        params = @data.dup
+        if @data[:id]
+          self.class.request(params.merge(:_method => :put, :_path => "#{self.class.collection_path}/#{id}")) do |parsed_data|
+            @data = parsed_data[:data]
+          end
+        else
+          self.class.create(params)
         end
       end # }}}
     end

data/lib/her/model/relationships.rb

@@ -34,9 +34,7 @@ module Her
 
         define_method(name) do
           return @data[name] if @data.include?(name) # Do not fetch from API again if we have it in @data
-          self.class.get("#{collection_path}/#{id}/#{Object.const_get(name.to_s.classify).collection_path}") do |parsed_data|
-            @data[name] = Her::Model::ORM.initialize_collection(name, parsed_data[:resource])
-          end
+          self.class.get_collection("#{collection_path}/#{id}/#{Object.const_get(name.to_s.classify).collection_path}")
         end
       end # }}}
 
@@ -50,6 +48,8 @@ module Her
       def belongs_to(name, attrs={}) # {{{
         @her_relationships ||= {}
         (@her_relationships[:belongs_to] ||= []) << attrs.merge(:name => name)
+
+        # TODO Write some code here
       end # }}}
     end
   end

data/lib/her/version.rb

@@ -1,3 +1,3 @@
 module Her
-  VERSION = "0.1"
+  VERSION = "0.1.1"
 end

data/spec/model_spec.rb

@@ -3,7 +3,7 @@ require File.join(File.dirname(__FILE__), "spec_helper.rb")
 
 describe Her::Model do
   describe Her::Model::HTTP do
-    context "binding a model with an API" do # {{{
+    context "binding a model with an API" do
       it "binds a model to an instance of Her::API" do # {{{
         @api = Her::API.new
         @api.setup :base_uri => "https://api.example.com"
@@ -78,7 +78,7 @@ describe Her::Model do
           @her_api.base_uri.should == "https://api2.example.com"
         end
       end # }}}
-    end # }}}
+    end
 
     context "making HTTP requests" do
       before do # {{{
@@ -86,8 +86,11 @@ describe Her::Model do
         @api.setup :base_uri => "https://api.example.com"
         FakeWeb.register_uri(:get, "https://api.example.com/users", :body => { :data => [{ :id => 1 }] }.to_json)
         FakeWeb.register_uri(:get, "https://api.example.com/users?page=2", :body => { :data => [{ :id => 2 }] }.to_json)
+        FakeWeb.register_uri(:get, "https://api.example.com/users/popular", :body => { :data => [{ :id => 1 }, { :id => 2 }] }.to_json)
+        FakeWeb.register_uri(:get, "https://api.example.com/users/1", :body => { :data => { :id => 1 } }.to_json)
         FakeWeb.register_uri(:post, "https://api.example.com/users", :body => { :data => [{ :id => 3 }] }.to_json)
         FakeWeb.register_uri(:put, "https://api.example.com/users/4", :body => { :data => [{ :id => 4 }] }.to_json)
+        FakeWeb.register_uri(:patch, "https://api.example.com/users/6", :body => { :data => [{ :id => 6 }] }.to_json)
         FakeWeb.register_uri(:delete, "https://api.example.com/users/5", :body => { :data => [{ :id => 5 }] }.to_json)
 
         Object.instance_eval { remove_const :User } if Object.const_defined?(:User)
@@ -97,40 +100,57 @@ describe Her::Model do
         User.uses_api @api
       end # }}}
 
-      it "handle GET" do # {{{
-        User.get("/users") do |parsed_data|
-          parsed_data[:resource].should == [{ :id => 1 }]
+      it "handle raw GET" do # {{{
+        User.get_raw("/users") do |parsed_data|
+          parsed_data[:data].should == [{ :id => 1 }]
+        end
+      end # }}}
+
+      it "handle raw POST" do # {{{
+        User.post_raw("/users") do |parsed_data|
+          parsed_data[:data].should == [{ :id => 3 }]
         end
       end # }}}
 
-      it "handle POST" do # {{{
-        User.post("/users") do |parsed_data|
-          parsed_data[:resource].should == [{ :id => 3 }]
+      it "handle raw PUT" do # {{{
+        User.put_raw("/users/4") do |parsed_data|
+          parsed_data[:data].should == [{ :id => 4 }]
         end
       end # }}}
 
-      it "handle PUT" do # {{{
-        User.put("/users/4") do |parsed_data|
-          parsed_data[:resource].should == [{ :id => 4 }]
+      it "handle raw PATCH" do # {{{
+        User.patch_raw("/users/6") do |parsed_data|
+          parsed_data[:data].should == [{ :id => 6 }]
         end
       end # }}}
 
-      it "handle DELETE" do # {{{
-        User.delete("/users/5") do |parsed_data|
-          parsed_data[:resource].should == [{ :id => 5 }]
+      it "handle raw DELETE" do # {{{
+        User.delete_raw("/users/5") do |parsed_data|
+          parsed_data[:data].should == [{ :id => 5 }]
         end
       end # }}}
 
       it "handle querystring parameters" do # {{{
-        User.get("/users", :page => 2) do |parsed_data|
-          parsed_data[:resource].should == [{ :id => 2 }]
+        User.get_raw("/users", :page => 2) do |parsed_data|
+          parsed_data[:data].should == [{ :id => 2 }]
         end
       end # }}}
+
+      it "handle GET collection" do # {{{
+        @users = User.get_collection("/users/popular")
+        @users.length.should == 2
+        @users.first.id.should == 1
+      end # }}}
+
+      it "handle GET resource" do # {{{
+        @user = User.get_resource("/users/1")
+        @user.id.should == 1
+      end # }}}
     end
   end
 
   describe Her::Model::ORM do
-    context "mapping data to Ruby objects" do # {{{
+    context "mapping data to Ruby objects" do
       before do # {{{
         @api = Her::API.new
         @api.setup :base_uri => "https://api.example.com"
@@ -155,13 +175,17 @@ describe Her::Model do
         @users.length.should == 2
         @users.first.name.should == "Tobias Fünke"
       end # }}}
-    end # }}}
+    end
 
     context "creating resources" do
       before do # {{{
-        @api = Her::API.new
-        @api.setup :base_uri => "https://api.example.com"
+        Her::API.setup :base_uri => "https://api.example.com"
         FakeWeb.register_uri(:post, "https://api.example.com/users", :body => { :data => { :id => 1, :fullname => "Tobias Fünke" } }.to_json)
+
+        Object.instance_eval { remove_const :User } if Object.const_defined?(:User)
+        class User
+          include Her::Model
+        end
       end # }}}
 
       it "handle one-line resource creation" do # {{{
@@ -169,11 +193,45 @@ describe Her::Model do
         @user.id.should == 1
         @user.fullname.should == "Tobias Fünke"
       end # }}}
+
+      it "handle resource creation through Model.new + #save" do # {{{
+        @user = User.new(:fullname => "Tobias Fünke")
+        @user.save
+        @user.fullname.should == "Tobias Fünke"
+      end # }}}
+    end
+
+    context "updating resources" do
+      before do # {{{
+        @api = Her::API.new
+        @api.setup :base_uri => "https://api.example.com"
+        FakeWeb.register_uri(:get, "https://api.example.com/users/1", :body => { :data => { :id => 1, :fullname => "Tobias Fünke" } }.to_json)
+        FakeWeb.register_uri(:put, "https://api.example.com/users/1", :body => { :data => { :id => 1, :fullname => "Lindsay Fünke" } }.to_json)
+
+        Object.instance_eval { remove_const :User } if Object.const_defined?(:User)
+        class User
+          include Her::Model
+        end
+      end # }}}
+
+      it "handle resource data update without saving it" do
+        @user = User.find(1)
+        @user.fullname.should == "Tobias Fünke"
+        @user.fullname = "Kittie Sanchez"
+        @user.fullname.should == "Kittie Sanchez"
+      end
+
+      it "handle resource update through #save on an existing resource" do # {{{
+        @user = User.find(1)
+        @user.fullname = "Lindsay Fünke"
+        @user.save
+        @user.fullname.should == "Lindsay Fünke"
+      end # }}}
     end
   end
 
   describe Her::Model::Relationships do
-    context "setting relationships" do # {{{
+    context "setting relationships" do
       before do # {{{
         Object.instance_eval { remove_const :User } if Object.const_defined?(:User)
         class User
@@ -202,9 +260,9 @@ describe Her::Model do
         User.belongs_to :family
         User.relationships[:belongs_to].should == [{ :name => :organization }, { :name => :family }]
       end # }}}
-    end # }}}
+    end
 
-    context "handling relationships" do # {{{
+    context "handling relationships" do
       before do # {{{
         Her::API.setup :base_uri => "https://api.example.com"
         FakeWeb.register_uri(:get, "https://api.example.com/users/1", :body => { :data => { :id => 1, :name => "Tobias Fünke", :comments => [{ :id => 2, :body => "Tobias, you blow hard!" }, { :id => 3, :body => "I wouldn't mind kissing that man between the cheeks, so to speak" }] } }.to_json)
@@ -236,7 +294,6 @@ describe Her::Model do
         @user.comments.first.id.should == 4
         @user.comments.first.body.should == "They're having a FIRESALE?"
       end # }}}
-
-    end # }}}
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: her
 version: !ruby/object:Gem::Version
-  version: '0.1'
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -193,7 +193,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4283356893528248236
+      hash: -3007322587400233058
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -202,7 +202,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4283356893528248236
+      hash: -3007322587400233058
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.18