her 0.4 → 0.4.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NmU4ZjBhMTAxNGJhNTE5ZThjNDY5OTcxZmFkOGM5NzQwZjBhYTIyOA==
+  data.tar.gz: !binary |-
+    MTIxOGI1NjljNzBiNjFlNmM2ODczZDZiNDlhNGIxZmQ0Njk3NjEyNw==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    NGNjNDg0MjIzMmRhOTA5MDU3MWIyMWZkYzIyMzFkNWViNDdiYmFkZDE3ZjQ1
+    ZTA1NTExMzA1YTc2MTE3MGM0NTYxNjg2ZjI1OTllYWFlZGQ3ZDY2ZWIwYjQ5
+    NTUwYjI4NTBhMTk3MTVjZTExYjNkZDNmM2Q1MjM5YjkwN2U2ZGY=
+  data.tar.gz: !binary |-
+    NjAzM2JlOWZlZDBjMzZjYjI2OWJkYzc5NTY4MzAyNzhhZGVkODlhMmZmZGJm
+    NjUzY2JlMjExZDAzYjljOTI1YzE1NWJkOWM0OTY0NzE2MDQwYjY1NmZmN2M4
+    YzU0YmYyNDY0YWE3ZWVjZWY0N2NkY2Y0NGQ1ODFhMzg2MTIxN2E=

data/README.md

@@ -143,6 +143,44 @@ end
 
 Now, each HTTP request made by Her will have the `X-API-Token` header.
 
+### OAuth
+
+Using the `faraday_middleware` and `simple_oauth` gems, it’s fairly easy to use OAuth authentication with Her.
+
+In your Gemfile:
+
+```ruby
+gem "her"
+gem "faraday_middleware"
+gem "simple_oauth"
+```
+
+In your Ruby code:
+
+```ruby
+# Create an application on `https://dev.twitter.com/apps` to set these values
+TWITTER_CREDENTIALS = {
+  :consumer_key => "",
+  :consumer_secret => "",
+  :token => "",
+  :token_secret => ""
+}
+
+Her::API.setup :url => "https://api.twitter.com/1/" do |connection|
+  connection.use FaradayMiddleware::OAuth, TWITTER_CREDENTIALS
+  connection.use Her::Middleware::DefaultParseJSON
+  connection.use Faraday::Adapter::NetHttp
+end
+
+class Tweet
+  include Her::Model
+end
+
+@tweets = Tweet.get("/statuses/home_timeline.json")
+```
+
+See the *Authentication* middleware section for an example of how to pass different credentials based on the current user.
+
 ### Parsing JSON data
 
 By default, Her handles JSON data. It expects the resource/collection data to be returned at the first level.
@@ -155,7 +193,9 @@ By default, Her handles JSON data. It expects the resource/collection data to be
 [{ "id" : 1, "name" : "Tobias Fünke" }]
 ```
 
-However, you can define your own parsing method using a response middleware. The middleware should set `env[:body]` to a hash with three keys: `data`, `errors` and `metadata`. The following code uses a custom middleware to parse the JSON data:
+However, if you want Her to be able to parse the data from a single root element (usually based on the model name), you’ll have to use the `parse_root_in_json` method (See the **JSON attributes-wrapping** section).
+
+Also, you can define your own parsing method using a response middleware. The middleware should set `env[:body]` to a hash with three keys: `data`, `errors` and `metadata`. The following code uses a custom middleware to parse the JSON data:
 
 ```ruby
 # Expects responses like:
@@ -185,44 +225,6 @@ Her::API.setup :url => "https://api.example.com" do |connection|
 end
 ```
 
-### OAuth
-
-Using the `faraday_middleware` and `simple_oauth` gems, it’s fairly easy to use OAuth authentication with Her.
-
-In your Gemfile:
-
-```ruby
-gem "her"
-gem "faraday_middleware"
-gem "simple_oauth"
-```
-
-In your Ruby code:
-
-```ruby
-# Create an application on `https://dev.twitter.com/apps` to set these values
-TWITTER_CREDENTIALS = {
-  :consumer_key => "",
-  :consumer_secret => "",
-  :token => "",
-  :token_secret => ""
-}
-
-Her::API.setup :url => "https://api.twitter.com/1/" do |connection|
-  connection.use FaradayMiddleware::OAuth, TWITTER_CREDENTIALS
-  connection.use Her::Middleware::DefaultParseJSON
-  connection.use Faraday::Adapter::NetHttp
-end
-
-class Tweet
-  include Her::Model
-end
-
-@tweets = Tweet.get("/statuses/home_timeline.json")
-```
-
-See the *Authentication* middleware section for an example of how to pass different credentials based on the current user.
-
 ### Caching
 
 Again, using the `faraday_middleware` and `memcached` gems makes it very easy to cache requests and responses.
@@ -675,7 +677,7 @@ end
 
 ## Upgrade
 
-See the [UPGRADE.md](https://github.com/remiprev/her/blob/master/docs/UPGRADE.md) for backward compability issues.
+See the [UPGRADE.md](https://github.com/remiprev/her/blob/master/UPGRADE.md) for backward compability issues.
 
 ## Her IRL
 
@@ -686,15 +688,15 @@ Most projects I know that use Her are internal or private projects but here’s
 
 ## History
 
-I told myself a few months ago that it would be great to build a gem to replace Rails’ [ActiveResource](http://api.rubyonrails.org/classes/ActiveResource/Base.html) since it was barely maintained, lacking features and hard to extend/customize. I had built a few of these REST-powered ORMs for client projects before but I decided I wanted to write one for myself that I could release as an open-source project.
+I told myself a few months ago that it would be great to build a gem to replace Rails’ [ActiveResource](http://api.rubyonrails.org/classes/ActiveResource/Base.html) since it was barely maintained (and now removed from Rails 4.0), lacking features and hard to extend/customize. I had built a few of these REST-powered ORMs for client projects before but I decided I wanted to write one for myself that I could release as an open-source project.
 
-Most of Her’s core codebase was written on a Saturday morning ([first commit](https://github.com/remiprev/her/commit/689d8e88916dc2ad258e69a2a91a283f061cbef2) at 7am!) while I was visiting my girlfiend’s family in [Ayer’s Cliff](https://en.wikipedia.org/wiki/Ayer%27s_Cliff).
+Most of Her’s core codebase was written on a Saturday morning of April 2012 ([first commit](https://github.com/remiprev/her/commit/689d8e88916dc2ad258e69a2a91a283f061cbef2) at 7am!).
 
 ## Contribute
 
 Yes please! Feel free to contribute and submit issues/pull requests [on GitHub](https://github.com/remiprev/her/issues).
 
-See [CONTRIBUTING.md](https://github.com/remiprev/her/blob/master/docs/CONTRIBUTING.md) for best practices.
+See [CONTRIBUTING.md](https://github.com/remiprev/her/blob/master/CONTRIBUTING.md) for best practices.
 
 ### Contributors
 
@@ -718,4 +720,4 @@ These fine folks helped with Her:
 
 ## License
 
-Her is © 2012 [Rémi Prévost](http://exomel.com) and may be freely distributed under the [MIT license](https://github.com/remiprev/her/blob/master/LICENSE). See the `LICENSE` file.
+Her is © 2012-2013 [Rémi Prévost](http://exomel.com) and may be freely distributed under the [MIT license](https://github.com/remiprev/her/blob/master/LICENSE). See the `LICENSE` file.

data/her.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
 
   s.add_development_dependency "rake", "~> 10.0"
-  s.add_development_dependency "rspec", "~> 2.12"
+  s.add_development_dependency "rspec", "~> 2.13"
   s.add_development_dependency "mocha", "~> 0.13"
 
   s.add_runtime_dependency "activesupport", ">= 3.0.0"

data/lib/her/api.rb

@@ -11,6 +11,22 @@ module Her
       @@default_api.setup(attrs, &block)
     end
 
+    # Create a new API object. This is useful to create multiple APIs and use them with the `uses_api` method.
+    # If your application uses only one API, you should use Her::API.setup to configure the default API
+    #
+    # @example Setting up a new API
+    #   api = Her::API.new :url => "https://api.example" do |connection|
+    #     connection.use Faraday::Request::UrlEncoded
+    #     connection.use Her::Middleware::DefaultParseJSON
+    #   end
+    #
+    #   class User
+    #     uses_api api
+    #   end
+    def initialize(*args, &blk)
+      self.setup(*args, &blk)
+    end
+
     # Setup the API connection.
     #
     # @param [Hash] attrs the Faraday options
@@ -49,13 +65,14 @@ module Her
     #     connection.use MyCustomParser
     #     connection.use Faraday::Adapter::NetHttp
     #   end
-    def setup(attrs={})
+    def setup(attrs={}, &blk)
       attrs[:url] = attrs.delete(:base_uri) if attrs.include?(:base_uri) # Support legacy :base_uri option
       @base_uri = attrs[:url]
       @options = attrs
       @connection = Faraday.new(@options) do |connection|
         yield connection if block_given?
       end
+      self
     end
 
     # Define a custom parsing procedure. The procedure is passed the response object and is

data/lib/her/errors.rb

@@ -1,5 +1,6 @@
 module Her
   module Errors
     class PathError < StandardError; end;
+    class RelationshipUnknownError < StandardError; end;
   end
 end

data/lib/her/middleware/first_level_parse_json.rb

@@ -22,7 +22,12 @@ module Her
       #
       # @param [Hash] env The response environment
       def on_complete(env)
-        env[:body] = parse(env[:body])
+        case env[:status]
+        when 204
+          env[:body] = parse('{}')
+        else
+          env[:body] = parse(env[:body])
+        end
       end
     end
   end

data/lib/her/model.rb

@@ -5,6 +5,7 @@ require "her/model/relationships"
 require "her/model/hooks"
 require "her/model/introspection"
 require "her/model/paths"
+require "her/model/nested_attributes"
 
 module Her
   # This module is the main element of Her. After creating a Her::API object,
@@ -25,6 +26,7 @@ module Her
     include Her::Model::Introspection
     include Her::Model::Paths
     include Her::Model::Relationships
+    include Her::Model::NestedAttributes
 
     # Class methods
     included do

data/lib/her/model/http.rb

@@ -44,7 +44,7 @@ module Her
           if parsed_data[:data].is_a?(Array)
             new_collection(parsed_data)
           else
-            new(parsed_data[:data].merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
+            new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
           end
         end
       end
@@ -56,7 +56,7 @@ module Her
       end
 
       # Make a GET request and return a collection of resources
-      def get_collection(path, attrs={})
+      def get_collection(path=nil, attrs={})
         path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
         get_raw(path, attrs) do |parsed_data|
           new_collection(parsed_data)
@@ -67,7 +67,7 @@ module Her
       def get_resource(path, attrs={})
         path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
         get_raw(path, attrs) do |parsed_data|
-          new(parsed_data[:data].merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
+          new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
         end
       end
 
@@ -78,7 +78,7 @@ module Her
           if parsed_data[:data].is_a?(Array)
             new_collection(parsed_data)
           else
-            new(parsed_data[:data].merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
+            new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
           end
         end
       end
@@ -101,7 +101,7 @@ module Her
       def post_resource(path, attrs={})
         path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
         post_raw(path, attrs) do |parsed_data|
-          new(parsed_data[:data])
+          new(parse(parsed_data[:data]))
         end
       end
 
@@ -112,7 +112,7 @@ module Her
           if parsed_data[:data].is_a?(Array)
             new_collection(parsed_data)
           else
-            new(parsed_data[:data].merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
+            new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
           end
         end
       end
@@ -135,7 +135,7 @@ module Her
       def put_resource(path, attrs={})
         path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
         put_raw(path, attrs) do |parsed_data|
-          new(parsed_data[:data].merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
+          new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
         end
       end
 
@@ -146,7 +146,7 @@ module Her
           if parsed_data[:data].is_a?(Array)
             new_collection(parsed_data)
           else
-            new(parsed_data[:data].merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
+            new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
           end
         end
       end
@@ -169,7 +169,7 @@ module Her
       def patch_resource(path, attrs={})
         path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
         patch_raw(path, attrs) do |parsed_data|
-          new(parsed_data[:data].merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
+          new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
         end
       end
 
@@ -180,7 +180,7 @@ module Her
           if parsed_data[:data].is_a?(Array)
             new_collection(parsed_data)
           else
-            new(parsed_data[:data].merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
+            new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
           end
         end
       end
@@ -203,7 +203,7 @@ module Her
       def delete_resource(path, attrs={})
         path = "#{build_request_path(attrs)}/#{path}" if path.is_a?(Symbol)
         delete_raw(path, attrs) do |parsed_data|
-          new(parsed_data[:data].merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
+          new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:data], :_errors => parsed_data[:errors])
         end
       end
 

data/lib/her/model/nested_attributes.rb

@@ -0,0 +1,57 @@
+module Her
+  module Model
+    module NestedAttributes
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        def accepts_nested_attributes_for(*relationship_names)
+          relationship_names.each do |relationship_name|
+            type = nil
+            [:belongs_to, :has_one, :has_many].each do |relation_type|
+              if !relationships[relation_type].nil? && relationships[relation_type].any? { |relation| relation[:name] == relationship_name }
+                type = relation_type
+              end
+            end
+            if type.nil?
+              raise(RelationshipUnknownError.new("Unknown relationship name :#{relationship_name}"))
+            end
+            class_eval <<-eoruby, __FILE__, __LINE__ + 1
+              if method_defined?(:#{relationship_name}_attributes=)
+                remove_method(:#{relationship_name}_attributes=)
+              end
+              def #{relationship_name}_attributes=(attributes)
+                assign_nested_attributes_for_#{type}_relationship(:#{relationship_name}, attributes)
+              end
+            eoruby
+          end
+        end
+      end
+
+      def assign_nested_attributes_for_belongs_to_relationship(relationship_name, attributes)
+        assign_nested_attributes_for_simple_relationship(:belongs_to, relationship_name, attributes)
+      end
+
+      def assign_nested_attributes_for_has_one_relationship(relationship_name, attributes)
+        assign_nested_attributes_for_simple_relationship(:has_one, relationship_name, attributes)
+      end
+
+      def assign_nested_attributes_for_has_many_relationship(relationship_name, attributes)
+        relationship = self.class.relationships[:has_many].find { |relation| relation[:name] == relationship_name }
+        klass = self.class.nearby_class(relationship[:class_name])
+        self.send("#{relationship[:name]}=", Her::Model::ORM.initialize_collection(klass, :data => attributes))
+      end
+
+      private
+      def assign_nested_attributes_for_simple_relationship(relationship_type, relationship_name, attributes)
+        relationship = self.class.relationships[relationship_type].find { |relation| relation[:name] == relationship_name }
+        if has_data?(relationship[:name])
+          self.send("#{relationship[:name]}").assign_data(attributes)
+        else
+          klass = self.class.nearby_class(relationship[:class_name])
+          instance = klass.new(klass.parse(attributes))
+          self.send("#{relationship[:name]}=", instance)
+        end
+      end
+    end
+  end
+end

data/lib/her/model/orm.rb

@@ -9,15 +9,10 @@ module Her
 
       # Initialize a new object with data received from an HTTP request
       def initialize(params={})
-        @data = {}
         @metadata = params.delete(:_metadata) || {}
         @errors = params.delete(:_errors) || {}
 
-        # Use setter methods first, then translate attributes of relationships
-        # into relationship instances, then merge the parsed_data into @data.
-        unset_data = Her::Model::ORM.use_setter_methods(self, params)
-        parsed_data = self.class.parse_relationships(unset_data)
-        @data.update(parsed_data)
+        update_data(params)
       end
 
       # Initialize a collection of resources
@@ -150,7 +145,7 @@ module Her
 
         self.class.wrap_in_hooks(resource, *hooks) do |resource, klass|
           klass.request(params.merge(:_method => method, :_path => "#{request_path}")) do |parsed_data|
-            self.data = self.class.parse(parsed_data[:data]) if parsed_data[:data].any?
+            update_data(self.class.parse(parsed_data[:data])) if parsed_data[:data].any?
             self.metadata = parsed_data[:metadata]
             self.errors = parsed_data[:errors]
 
@@ -171,7 +166,7 @@ module Her
         resource = self
         self.class.wrap_in_hooks(resource, :destroy) do |resource, klass|
           klass.request(:_method => :delete, :_path => "#{request_path}") do |parsed_data|
-            self.data = self.class.parse(parsed_data[:data])
+            update_data(self.class.parse(parsed_data[:data])) if parsed_data[:data].any?
             self.metadata = parsed_data[:metadata]
             self.errors = parsed_data[:errors]
           end
@@ -179,6 +174,16 @@ module Her
         self
       end
 
+      # @private
+      def update_data(raw_data)
+        @data ||= {}
+        # Use setter methods first, then translate attributes of relationships
+        # into relationship instances, then merge the parsed_data into @data.
+        unset_data = Her::Model::ORM.use_setter_methods(self, raw_data)
+        parsed_data = self.class.parse_relationships(unset_data)
+        @data.update(parsed_data)
+      end
+
       # Convert into a hash of request parameters
       #
       # @example
@@ -260,7 +265,7 @@ module Her
             request(params.merge(:_method => :post, :_path => "#{build_request_path(params)}")) do |parsed_data|
               data = parse(parsed_data[:data])
               resource.instance_eval do
-                @data = data
+                update_data(data)
                 @metadata = parsed_data[:metadata]
                 @errors = parsed_data[:errors]
               end