her 0.2 → 0.2.1

data/Guardfile

@@ -0,0 +1,7 @@
+require "guard/guard"
+
+guard "rspec", :cli => "--colour --format=documentation" do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/.+\.rb$}) { "spec" }
+  watch("spec/spec_helper.rb") { "spec" }
+end

data/README.md

@@ -1,9 +1,9 @@
 # Her
 
-[![Build Status](https://secure.travis-ci.org/remiprev/her.png)](http://travis-ci.org/remiprev/her)
-
 Her is an ORM (Object Relational Mapper) that maps REST resources to Ruby objects. It is designed to build applications that are powered by a RESTful API and no database.
 
+[![Build Status](https://secure.travis-ci.org/remiprev/her.png)](http://travis-ci.org/remiprev/her)
+
 ## Installation
 
 In your Gemfile, add:
@@ -60,17 +60,19 @@ Since Her relies on [Faraday](https://github.com/technoweenie/faraday) to send H
 
 ### Authentication
 
-Her doesn’t support any kind of authentication. However, it’s very easy to implement one with a request middleware. Using the `add_middleware` key, we add it to the default list of middleware.
+Her doesn’t support any kind of authentication. However, it’s very easy to implement one with a request middleware. Using the builder block, we add it to the default list of middleware.
 
 ```ruby
 class MyAuthentication < Faraday::Middleware
   def call(env)
     env[:request_headers]["X-API-Token"] = "bb2b2dd75413d32c1ac421d39e95b978d1819ff611f68fc2fdd5c8b9c7331192"
-    @all.call(env)
+    @app.call(env)
   end
 end
 
-Her::API.setup :base_uri => "https://api.example.com", :add_middleware => [MyAuthentication]
+Her::API.setup :base_uri => "https://api.example.com" do |builder|
+  builder.use MyAuthentication
+end
 ```
 
 Now, each HTTP request made by Her will have the `X-API-Token` header.
@@ -89,12 +91,12 @@ 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 is expected to set `env[:body]` to a hash with three keys: `data`, `errors` and `metadata`. The following code enables parsing JSON data and treating the result as first-level properties. Using the `parse_middleware` key, we then replace the default parser.
+However, you can define your own parsing method, using a response middleware. The middleware is expected to set `env[:body]` to a hash with three keys: `data`, `errors` and `metadata`. The following code enables parsing JSON data and treating the result as first-level properties. Using the builder block, we then replace the default parser.
 
 ```ruby
 class MyCustomParser < Faraday::Response::Middleware
   def on_complete(env)
-    json = MultiJson.load(body, :symbolize_keys => true)
+    json = MultiJson.load(env[:body], :symbolize_keys => true)
     env[:body] = {
       :data => json[:data],
       :errors => json[:errors],
@@ -103,10 +105,82 @@ class MyCustomParser < Faraday::Response::Middleware
   end
 end
 
-Her::API.setup :base_uri => "https://api.example.com", :parse_middleware => MyCustomParser
+Her::API.setup :base_uri => "https://api.example.com" do |builder|
+  builder.delete Her::Middleware::DefaultParseJSON
+  builder.use MyCustomParser
+end
 # User.find(1) will now expect "https://api.example.com/users/1" to return something like '{ "data" => { "id": 1, "name": "Tobias Fünke" }, "errors" => [] }'
 ```
 
+### 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 :base_uri => "https://api.twitter.com/1/" do |builder|
+  builder.use FaradayMiddleware::OAuth, TWITTER_CREDENTIALS
+end
+
+class Tweet
+  include Her::Model
+end
+
+@tweets = Tweet.get("/statuses/home_timeline.json")
+```
+
+### Caching
+
+Again, using the `faraday_middleware` makes it very easy to cache requests and responses:
+
+In your Gemfile:
+
+```ruby
+gem "her"
+gem "faraday_middleware"
+```
+
+In your Ruby code:
+
+```ruby
+class MyCache
+  def write(key, value); end
+  def read(key); end
+  def fetch(key, &block); end
+end
+
+# A cache system must respond to `#write`, `#read` and `#fetch`.
+$cache = MyCache.new
+
+Her::API.setup :base_uri => "https://api.example.com" do |builder|
+  builder.use FaradayMiddleware::Caching, $cache
+end
+
+class User
+  include Her::Model
+end
+
+@user = User.find(1)
+@user = User.find(1) # This request will be fetched from the cache
+```
+
 ## Relationships
 
 You can define `has_many`, `has_one` and `belongs_to` 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.
@@ -255,6 +329,35 @@ User.get("/users/popular") # => [#<User id=1>, #<User id=2>]
 # GET /users/popular
 ```
 
+## Custom paths
+
+You can define custom HTTP paths for your models:
+
+```ruby
+class User
+  include Her::Model
+  collection_path "/hello_users/:id"
+end
+
+@user = User.find(1)
+# GET /hello_users/1
+```
+
+You can include custom variables in your paths:
+
+```ruby
+class User
+  include Her::Model
+  collection_path "/organizations/:organization_id/users/:id"
+end
+
+@user = User.find(1, :_organization_id => 2)
+# GET /organizations/2/users/1
+
+@user = User.all(:_organization_id => 2)
+# GET /organizations/2/users
+```
+
 ## Multiple APIs
 
 It is possible to use different APIs for different models. Instead of calling `Her::API.setup`, you can create instances of `Her::API`:
@@ -290,7 +393,6 @@ Category.all
 
 ## Things to be done
 
-* Add support for collection paths of nested resources (eg. `/users/:user_id/comments` for the `Comment` model)
 * Better error handling
 * Better documentation
 

data/examples/twitter-oauth/Gemfile

@@ -0,0 +1,13 @@
+source :rubygems
+
+gem "sinatra"
+gem "haml"
+gem "thin", :require => false
+gem "faraday_middleware"
+gem "simple_oauth"
+
+gem "her", :path => File.join(File.dirname(__FILE__),"../..")
+
+group :development do
+  gem "shotgun"
+end

data/examples/twitter-oauth/app.rb

@@ -0,0 +1,42 @@
+# Create custom parser
+class TwitterSearchParser < Faraday::Response::Middleware
+  METADATA_KEYS = [:completed_in, :max_id, :max_id_str, :next_page, :page, :query, :refresh_url, :results_per_page, :since_id, :since_id_str]
+
+  def on_complete(env)
+    json = MultiJson.load(env[:body], :symbolize_keys => true)
+    errors = [json.delete(:error)]
+    env[:body] = {
+      :data => json,
+      :errors => errors,
+      :metadata => {},
+    }
+  end
+end
+
+TWITTER_CREDENTIALS = {
+  :consumer_key => "",
+  :consumer_secret => "",
+  :token => "",
+  :token_secret => ""
+}
+
+# Initialize API
+Her::API.setup :base_uri => "https://api.twitter.com/1/", :parse_middleware => TwitterSearchParser, :add_middleware => [FaradayMiddleware::OAuth => TWITTER_CREDENTIALS]
+
+# Define classes
+class Tweet
+  include Her::Model
+
+  def self.timeline
+    get "/statuses/home_timeline.json"
+  end
+
+  def username
+    user[:screen_name]
+  end
+end
+
+get "/" do
+  @tweets = Tweet.timeline
+  haml :index
+end

data/examples/twitter-oauth/config.ru

@@ -0,0 +1,5 @@
+require "bundler"
+Bundler.require
+
+require "./app"
+run Sinatra::Application

data/examples/twitter-oauth/views/index.haml

@@ -0,0 +1,9 @@
+!!!
+%html
+%body
+  %ul
+    - @tweets.each do |tweet|
+      %li{ :style => "margin: 0 0 10px" }
+        %span= tweet.text
+        %br
+        %strong= tweet.username

data/examples/twitter-search/Gemfile

@@ -0,0 +1,11 @@
+source :rubygems
+
+gem "sinatra"
+gem "haml"
+gem "thin", :require => false
+
+gem "her", :path => File.join(File.dirname(__FILE__),"../..")
+
+group :development do
+  gem "shotgun"
+end

data/examples/twitter-search/app.rb

@@ -0,0 +1,30 @@
+# Create custom parser
+class TwitterSearchParser < Faraday::Response::Middleware
+  METADATA_KEYS = [:completed_in, :max_id, :max_id_str, :next_page, :page, :query, :refresh_url, :results_per_page, :since_id, :since_id_str]
+
+  def on_complete(env)
+    json = MultiJson.load(env[:body], :symbolize_keys => true)
+    env[:body] = {
+      :data => json[:results],
+      :errors => [json[:error]],
+      :metadata => json.select { |key, value| METADATA_KEYS.include?(key) }
+    }
+  end
+end
+
+# Initialize API
+Her::API.setup :base_uri => "http://search.twitter.com", :parse_middleware => TwitterSearchParser
+
+# Define classes
+class Tweet
+  include Her::Model
+
+  def self.search(query, attrs={})
+    get("/search.json", attrs.merge(:q => query))
+  end
+end
+
+get "/" do
+  @tweets = Tweet.search("github", :rpp => 30)
+  haml :index
+end

data/examples/twitter-search/config.ru

@@ -0,0 +1,5 @@
+require "bundler"
+Bundler.require
+
+require "./app"
+run Sinatra::Application

data/examples/twitter-search/views/index.haml

@@ -0,0 +1,9 @@
+!!!
+%html
+%body
+  %ul
+    - @tweets.each do |tweet|
+      %li{ :style => "margin: 0 0 10px" }
+        %span= tweet.text
+        %br
+        %strong= tweet.from_user

data/her.gemspec

@@ -7,23 +7,27 @@ Gem::Specification.new do |s|
   s.version     = Her::VERSION
   s.authors     = ["Rémi Prévost"]
   s.email       = ["remi@exomel.com"]
-  s.homepage    = "https://github.com/remiprev/her"
+  s.homepage    = "http://remiprev.github.com/her"
   s.summary     = "A simple Representational State Transfer-based Hypertext Transfer Protocol-powered Object Relational Mapper. Her?"
-  s.description = "Her is an ORM that maps REST resources to Ruby objects"
+  s.description = "Her is an ORM that maps REST resources and collections to Ruby objects"
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  s.add_development_dependency "rake"
-  s.add_development_dependency "rspec"
-  s.add_development_dependency "yard"
+  s.add_development_dependency "rake", "0.9.2.2"
+  s.add_development_dependency "rspec", "2.9.0"
+  s.add_development_dependency "yard", "0.7.5"
   s.add_development_dependency "redcarpet", "1.17.2"
-  s.add_development_dependency "mocha"
-  s.add_development_dependency "fakeweb"
+  s.add_development_dependency "mocha", "0.11.3"
+  s.add_development_dependency "fakeweb", "1.3.0"
+  s.add_development_dependency "guard", "1.0.1"
+  s.add_development_dependency "guard-rspec", "0.7.0"
+  s.add_development_dependency "rb-fsevent", "0.9.1"
+  s.add_development_dependency "growl", "1.0.3"
 
-  s.add_runtime_dependency "activesupport"
-  s.add_runtime_dependency "faraday"
-  s.add_runtime_dependency "multi_json"
+  s.add_runtime_dependency "activesupport", "3.2.3"
+  s.add_runtime_dependency "faraday", "0.8.0"
+  s.add_runtime_dependency "multi_json", "1.3.4"
 end

data/lib/her.rb

@@ -8,4 +8,5 @@ module Her
   autoload :Model,       "her/model"
   autoload :API,         "her/api"
   autoload :Middleware,  "her/middleware"
+  autoload :Errors,      "her/errors"
 end

data/lib/her/api.rb

@@ -8,16 +8,20 @@ module Her
     # Setup a default API connection. Accepted arguments and options are the same as {API#setup}.
     def self.setup(attrs={}) # {{{
       @@default_api = new
-      @@default_api.setup(attrs)
+      connection = @@default_api.setup(attrs)
+      yield connection.builder if block_given?
+      connection
     end # }}}
 
     # Setup the API connection.
     #
     # @param [Hash] attrs the options to create a message with
     # @option attrs [String] :base_uri The main HTTP API root (eg. `https://api.example.com`)
-    # @option attrs [Array, Class] :middleware A list of the only middleware Her will use
-    # @option attrs [Array, Class] :add_middleware A list of middleware to add to Her’s default middleware
-    # @option attrs [Class] :parse_middleware A middleware that will replace {Her::Middleware::FirstLevelParseJSON} to parse the received JSON
+    # @option attrs [Array, Class] :middleware **Deprecated** A list of the only middleware Her will use
+    # @option attrs [Array, Class] :add_middleware **Deprecated** A list of middleware to add to Her’s default middleware
+    # @option attrs [Class] :parse_middleware **Deprecated** A middleware that will replace {Her::Middleware::FirstLevelParseJSON} to parse the received JSON
+    #
+    # @return Faraday::Connection
     #
     # @example Setting up the default API connection
     #   Her::API.setup :base_uri => "https://api.example"
@@ -29,7 +33,9 @@ module Her
     #       @all.call(env)
     #     end
     #   end
-    #   Her::API.setup :base_uri => "https://api.example.com", :add_middleware => [MyAuthentication]
+    #   Her::API.setup :base_uri => "https://api.example.com" do |builder|
+    #     builder.use MyAuthentication
+    #   end
     #
     # @example A custom parse middleware
     #   class MyCustomParser < Faraday::Response::Middleware
@@ -40,7 +46,10 @@ module Her
     #       env[:body] = { :data => json, :errors => errors, :metadata => metadata }
     #     end
     #   end
-    #   Her::API.setup :base_uri => "https://api.example.com", :parse_middleware => MyCustomParser
+    #   Her::API.setup :base_uri => "https://api.example.com" do |builder|
+    #     builder.delete Her::Middleware::DefaultParseJSON
+    #     builder.use MyCustomParser
+    #   end
     def setup(attrs={}) # {{{
       @base_uri = attrs[:base_uri]
       @middleware = Her::API.default_middleware
@@ -52,8 +61,18 @@ module Her
       @middleware.flatten!
       middleware = @middleware
       @connection = Faraday.new(:url => @base_uri) do |builder|
-        middleware.each { |m| builder.use(m) }
+        middleware.each do |item|
+          klass = item.is_a?(Hash) ? item.keys.first : item
+          args = item.is_a?(Hash) ? item.values.first : nil
+          if args
+            builder.use klass, args
+          else
+            builder.use klass
+          end
+        end
       end
+      yield @connection.builder if block_given?
+      @connection
     end # }}}
 
     # Define a custom parsing procedure. The procedure is passed the response object and is
@@ -64,6 +83,7 @@ module Her
     def request(attrs={}) # {{{
       method = attrs.delete(:_method)
       path = attrs.delete(:_path)
+      attrs.delete_if { |key, value| key =~ /^_/ } # Remove all internal parameters
       response = @connection.send method do |request|
         if method == :get
           # For GET requests, treat additional parameters as querystring data

data/lib/her/errors.rb

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