her 0.1.7 → 0.1.8

data/lib/her/model/http.rb

@@ -37,13 +37,35 @@ module Her
         yield @her_api.request(attrs)
       end # }}}
 
+      # Make a GET request and return either a collection or a resource
+      #
+      # @example
+      #   class User
+      #     include Her::Model
+      #   end
+      #
+      #   @popular_users = User.get(:popular)
+      #   # Fetched via GET "/users/popular"
+      def get(path, attrs={}) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
+        get_raw(path, attrs) do |parsed_data|
+          if parsed_data[:data].is_a?(Array)
+            new_collection(parsed_data)
+          else
+            new(parsed_data[:data])
+          end
+        end
+      end # }}}
+
       # Make a GET request and return the parsed JSON response (not mapped to objects)
       def get_raw(path, attrs={}, &block) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
         request(attrs.merge(:_method => :get, :_path => path), &block)
       end # }}}
 
       # Make a GET request and return a collection of resources
       def get_collection(path, attrs={}) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
         get_raw(path, attrs) do |parsed_data|
           new_collection(parsed_data)
         end
@@ -51,18 +73,33 @@ module Her
 
       # Make a GET request and return a collection of resources
       def get_resource(path, attrs={}) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
         get_raw(path, attrs) do |parsed_data|
           new(parsed_data[:data])
         end
       end # }}}
 
+      # Make a POST request and return either a collection or a resource
+      def post(path, attrs={}) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
+        post_raw(path, attrs) do |parsed_data|
+          if parsed_data[:data].is_a?(Array)
+            new_collection(parsed_data)
+          else
+            new(parsed_data[:data])
+          end
+        end
+      end # }}}
+
       # Make a POST request and return the parsed JSON response (not mapped to objects)
       def post_raw(path, attrs={}, &block) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
         request(attrs.merge(:_method => :post, :_path => path), &block)
       end # }}}
 
       # Make a POST request and return a collection of resources
       def post_collection(path, attrs={}) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
         post_raw(path, attrs) do |parsed_data|
           new_collection(parsed_data)
         end
@@ -70,18 +107,33 @@ module Her
 
       # Make a POST request and return a collection of resources
       def post_resource(path, attrs={}) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
         post_raw(path, attrs) do |parsed_data|
           new(parsed_data[:data])
         end
       end # }}}
 
+      # Make a PUT request and return either a collection or a resource
+      def put(path, attrs={}) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
+        put_raw(path, attrs) do |parsed_data|
+          if parsed_data[:data].is_a?(Array)
+            new_collection(parsed_data)
+          else
+            new(parsed_data[:data])
+          end
+        end
+      end # }}}
+
       # Make a PUT request and return the parsed JSON response (not mapped to objects)
       def put_raw(path, attrs={}, &block) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
         request(attrs.merge(:_method => :put, :_path => path), &block)
       end # }}}
 
       # Make a PUT request and return a collection of resources
       def put_collection(path, attrs={}) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
         put_raw(path, attrs) do |parsed_data|
           new_collection(parsed_data)
         end
@@ -89,18 +141,33 @@ module Her
 
       # Make a PUT request and return a collection of resources
       def put_resource(path, attrs={}) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
         put_raw(path, attrs) do |parsed_data|
           new(parsed_data[:data])
         end
       end # }}}
 
+      # Make a PATCH request and return either a collection or a resource
+      def patch(path, attrs={}) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
+        patch_raw(path, attrs) do |parsed_data|
+          if parsed_data[:data].is_a?(Array)
+            new_collection(parsed_data)
+          else
+            new(parsed_data[:data])
+          end
+        end
+      end # }}}
+
       # Make a PATCH request and return the parsed JSON response (not mapped to objects)
       def patch_raw(path, attrs={}, &block) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
         request(attrs.merge(:_method => :patch, :_path => path), &block)
       end # }}}
 
       # Make a PATCH request and return a collection of resources
       def patch_collection(path, attrs={}) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
         patch_raw(path, attrs) do |parsed_data|
           new_collection(parsed_data)
         end
@@ -108,18 +175,33 @@ module Her
 
       # Make a PATCH request and return a collection of resources
       def patch_resource(path, attrs={}) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
         patch_raw(path, attrs) do |parsed_data|
           new(parsed_data[:data])
         end
       end # }}}
 
+      # Make a DELETE request and return either a collection or a resource
+      def delete(path, attrs={}) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
+        delete_raw(path, attrs) do |parsed_data|
+          if parsed_data[:data].is_a?(Array)
+            new_collection(parsed_data)
+          else
+            new(parsed_data[:data])
+          end
+        end
+      end # }}}
+
       # Make a DELETE request and return the parsed JSON response (not mapped to objects)
       def delete_raw(path, attrs={}, &block) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
         request(attrs.merge(:_method => :delete, :_path => path), &block)
       end # }}}
 
       # Make a DELETE request and return a collection of resources
       def delete_collection(path, attrs={}) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
         delete_raw(path, attrs) do |parsed_data|
           new_collection(parsed_data)
         end
@@ -127,10 +209,70 @@ module Her
 
       # Make a DELETE request and return a collection of resources
       def delete_resource(path, attrs={}) # {{{
+        path = "#{@her_collection_path}/#{path}" if path.is_a?(Symbol)
         delete_raw(path, attrs) do |parsed_data|
           new(parsed_data[:data])
         end
       end # }}}
+
+      # Define custom GET requests
+      #
+      # @example
+      #   class User
+      #     include Her::Model
+      #     custom_get :popular
+      #   end
+      #
+      #   User.popular
+      #   # Fetched from GET "/users/popular"
+      def custom_get(*paths) # {{{
+        metaclass = (class << self; self; end)
+        paths.each do |path|
+          metaclass.send(:define_method, path.to_sym) do |*attrs|
+            get(path, attrs.first || Hash.new)
+          end
+        end
+      end # }}}
+
+      # Define custom POST requests
+      def custom_post(*paths) # {{{
+        metaclass = (class << self; self; end)
+        paths.each do |path|
+          metaclass.send(:define_method, path.to_sym) do |*attrs|
+            post(path, attrs.first || Hash.new)
+          end
+        end
+      end # }}}
+
+      # Define custom PUT requests
+      def custom_put(*paths) # {{{
+        metaclass = (class << self; self; end)
+        paths.each do |path|
+          metaclass.send(:define_method, path.to_sym) do |*attrs|
+            put(path, attrs.first || Hash.new)
+          end
+        end
+      end # }}}
+
+      # Define custom PATCH requests
+      def custom_patch(*paths) # {{{
+        metaclass = (class << self; self; end)
+        paths.each do |path|
+          metaclass.send(:define_method, path.to_sym) do |*attrs|
+            patch(path, attrs.first || Hash.new)
+          end
+        end
+      end # }}}
+
+      # Define custom DELETE requests
+      def custom_delete(*paths) # {{{
+        metaclass = (class << self; self; end)
+        paths.each do |path|
+          metaclass.send(:define_method, path.to_sym) do |*attrs|
+            delete(path, attrs.first || Hash.new)
+          end
+        end
+      end # }}}
     end
   end
 end

data/lib/her/model/introspection.rb

@@ -0,0 +1,32 @@
+module Her
+  module Model
+    module Introspection
+      # Inspect an element, returns it for introspection.
+      #
+      # @example
+      #   class User
+      #     include Her::Model
+      #   end
+      #
+      #   @user = User.find(1)
+      #   p @user # => #<User(/users/1) id=1 name="Tobias Fünke">
+      def inspect # {{{
+        resource_path = self.class.collection_path
+        resource_path << "/#{id}" if @data.include?(:id)
+        "#<#{self.class}(#{resource_path}) #{@data.inject([]) { |memo, item| key, value = item; memo << "#{key}=#{attribute_for_inspect(value)}"}.join(" ")}>"
+      end # }}}
+
+      private
+      # @private
+      def attribute_for_inspect(value) # {{{
+        if value.is_a?(String) && value.length > 50
+          "#{value[0..50]}...".inspect
+        elsif value.is_a?(Date) || value.is_a?(Time)
+          %("#{value}")
+        else
+          value.inspect
+        end
+      end # }}}
+    end
+  end
+end

data/lib/her/model/orm.rb

@@ -32,15 +32,23 @@ module Her
       end # }}}
 
       # Initialize a collection of resources with raw data from an HTTP request
+      #
+      # @param [Hash] parsed_data The raw `parsed_data` parsed from the HTTP response
       def new_collection(parsed_data) # {{{
         collection_data = parsed_data[:data]
         Her::Model::ORM.initialize_collection(self.to_s.downcase.to_sym, collection_data)
       end # }}}
 
+      # Return `true` if a resource was not saved yet
+      def new? # {{{
+        !@data.include?(:id)
+      end # }}}
+
       # Fetch a specific resource based on an ID
       #
       # @example
-      #   @user = User.find(1) GET /users/1
+      #   @user = User.find(1)
+      #   # Fetched via GET "/users/1"
       def find(id, params={}) # {{{
         request(params.merge(:_method => :get, :_path => "#{@her_collection_path}/#{id}")) do |parsed_data|
           new(parsed_data[:data])
@@ -50,7 +58,8 @@ module Her
       # Fetch a collection of resources
       #
       # @example
-      #   @users = User.all # GET /users
+      #   @users = User.all
+      #   # Fetched via GET "/users"
       def all(params={}) # {{{
         request(params.merge(:_method => :get, :_path => "#{@her_collection_path}")) do |parsed_data|
           new_collection(parsed_data)
@@ -60,7 +69,8 @@ module Her
       # Create a resource and return it
       #
       # @example
-      #   @user = User.create({ :fullname => "Tobias Fünke" }) # POST /users/1
+      #   @user = User.create({ :fullname => "Tobias Fünke" })
+      #   # Called via POST "/users/1"
       def create(params={}) # {{{
         resource = new(params)
         perform_hook(resource, :before, :create)
@@ -80,7 +90,8 @@ module Her
       # Save an existing resource and return it
       #
       # @example
-      #   @user = User.save_existing(1, { :fullname => "Tobias Fünke" }) # PUT /users/1
+      #   @user = User.save_existing(1, { :fullname => "Tobias Fünke" })
+      #   # Called via PUT "/users/1"
       def save_existing(id, params) # {{{
         resource = new(params.merge(:id => id))
         resource.save
@@ -89,32 +100,44 @@ module Her
       # Save a resource
       #
       # @example Save a resource after fetching it
-      #   @user = User.find(1) # GET /users/1
+      #   @user = User.find(1)
+      #   # Fetched via GET "/users/1"
       #   @user.fullname = "Tobias Fünke"
-      #   @user.save # PUT /users/1
+      #   @user.save
+      #   # Called via PUT "/users/1"
       #
       # @example Save a new resource by creating it
       #   @user = User.new({ :fullname => "Tobias Fünke" })
-      #   @user.save # POST /users
+      #   @user.save
+      #   # Called via POST "/users"
       def save # {{{
         params = @data.dup
+        resource = self
         if @data[:id]
-          self.class.perform_hook(self, :before, :update)
-          self.class.perform_hook(self, :before, :save)
+          self.class.class_eval do
+            perform_hook(resource, :before, :update)
+            perform_hook(resource, :before, :save)
+          end
           self.class.request(params.merge(:_method => :put, :_path => "#{self.class.collection_path}/#{id}")) do |parsed_data|
             @data = parsed_data[:data]
           end
-          self.class.perform_hook(self, :after, :save)
-          self.class.perform_hook(self, :after, :update)
+          self.class.class_eval do
+            perform_hook(resource, :after, :save)
+            perform_hook(resource, :after, :update)
+          end
           self
         else
-          self.class.perform_hook(self, :before, :create)
-          self.class.perform_hook(self, :before, :save)
+          self.class.class_eval do
+            perform_hook(resource, :before, :create)
+            perform_hook(resource, :before, :save)
+          end
           self.class.request(params.merge(:_method => :post, :_path => "#{self.class.collection_path}")) do |parsed_data|
             @data = parsed_data[:data]
           end
-          self.class.perform_hook(self, :after, :save)
-          self.class.perform_hook(self, :after, :create)
+          self.class.class_eval do
+            perform_hook(resource, :after, :save)
+            perform_hook(resource, :after, :create)
+          end
         end
         self
       end # }}}
@@ -122,22 +145,25 @@ module Her
       # Destroy a resource
       #
       # @example
-      #   @user = User.find(1) # GET /users/1
-      #   @user.destroy # DELETE /users/1
+      #   @user = User.find(1)
+      #   @user.destroy
+      #   # Called via DELETE "/users/1"
       def destroy # {{{
         params = @data.dup
-        self.class.perform_hook(self, :before, :destroy)
+        resource = self
+        self.class.class_eval { perform_hook(resource, :before, :destroy) }
         self.class.request(params.merge(:_method => :delete, :_path => "#{self.class.collection_path}/#{id}")) do |parsed_data|
           @data = parsed_data[:data]
         end
-        self.class.perform_hook(self, :after, :destroy)
+        self.class.class_eval { perform_hook(resource, :after, :destroy) }
         self
       end # }}}
 
       # Destroy an existing resource
       #
       # @example
-      #   User.destroy_existing(1) # DELETE /users/1
+      #   User.destroy_existing(1)
+      #   # Called via DELETE "/users/1"
       def destroy_existing(id) # {{{
         params = {}
         request(params.merge(:_method => :delete, :_path => "#{collection_path}/#{id}")) do |parsed_data|

data/lib/her/model/relationships.rb

@@ -28,13 +28,24 @@ module Her
         data
       end # }}}
 
-      # Define an *has_many* relationship for the resource
+      # Define an *has_many* relationship.
       #
-      # * `User.has_many :comments` is used to check if the "user" JSON
-      #   resource we receive has a `comments` key and map it to an array
-      #   of Comment objects
-      # * `User.has_many :comments` creates a User.comments method to would
-      #   make an extra HTTP request (to `/users/:id/comments`) if there was no "comments" key
+      # @param [Symbol] name The name of the model
+      # @param [Hash] attrs Options (currently not used)
+      #
+      # @example
+      #   class User
+      #     include Her::API
+      #     has_many :articles
+      #   end
+      #
+      #   class Article
+      #     include Her::API
+      #   end
+      #
+      #   @user = User.find(1)
+      #   @user.articles # => [#<Article(articles/2) id=2 title="Hello world.">]
+      #   # Fetched via GET "/users/1/articles"
       def has_many(name, attrs={}) # {{{
         @her_relationships ||= {}
         (@her_relationships[:has_many] ||= []) << attrs.merge(:name => name)
@@ -46,12 +57,24 @@ module Her
         end
       end # }}}
 
-      # Define an *has_one* relationship for the resource
+      # Define an *has_one* relationship.
+      #
+      # @param [Symbol] name The name of the model
+      # @param [Hash] attrs Options (currently not used)
+      #
+      # @example
+      #   class User
+      #     include Her::API
+      #     has_one :organization
+      #   end
       #
-      # * `User.has_one :category` is used to check if the "category" JSON
-      #   resource we receive has a `category` key and map it to a Category object
-      # * `User.has_one :category` creates a User.category method to would
-      #   make an extra HTTP request (to `/users/category`) if there was no "category" key
+      #   class Organization
+      #     include Her::API
+      #   end
+      #
+      #   @user = User.find(1)
+      #   @user.organization # => #<Organization(organizations/2) id=2 name="Foobar Inc.">
+      #   # Fetched via GET "/users/1/organization"
       def has_one(name, attrs={}) # {{{
         @her_relationships ||= {}
         (@her_relationships[:has_one] ||= []) << attrs.merge(:name => name)
@@ -63,12 +86,24 @@ module Her
         end
       end # }}}
 
-      # Define a *belongs_to* relationship for the resource
+      # Define a *belongs_to* relationship.
+      #
+      # @param [Symbol] name The name of the model
+      # @param [Hash] attrs Options (currently not used)
+      #
+      # @example
+      #   class User
+      #     include Her::API
+      #     belongs_to :team
+      #   end
+      #
+      #   class Team
+      #     include Her::API
+      #   end
       #
-      # * `User.belongs_to :organization` is used to check if the "organization" JSON
-      #   resource we receive has a `organization` key and map it to an Organization object
-      # * `User.belongs_to :organization` creates a User.organization method to would
-      #   make an extra HTTP request (to `/organizations/:organization_id`) if there was no "organization" key
+      #   @user = User.find(1)
+      #   @user.team # => #<Team(teams/2) id=2 name="Developers">
+      #   # Fetched via GET "/teams/2"
       def belongs_to(name, attrs={}) # {{{
         @her_relationships ||= {}
         (@her_relationships[:belongs_to] ||= []) << attrs.merge(:name => name)