her 0.5.5 → 0.6

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    OWFlMWJkMGQ3ODVkOTdhZGVmNDM3MDE3OTJiYTIxMThjNDZkZDVhYw==
+    NWYxMjI2MTQ0YjdhOTYyNDA1YTkwZjU4MTNhMDFjZDQ1OTM0OTczMQ==
   data.tar.gz: !binary |-
-    ODljYTk3MjhiNjhmYWM1MjQ1NDczZmJmNjIxYmMxNDA0NDk0ZDU0MQ==
+    ZDk0YzAxYjUzYTlmMGU4Y2FkMGQ0NGQ2MDM0YjM2MjBlZmRmMGVhZg==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    NjlmZmY0MzUxZmZlZjY0MzRkODg3YmM0MzQ1YzI4MDdjOTE5NTM1YTc0NTcw
-    OGZiYjgyMzA3YTlmMGRmMzAyNjRiMzQwZjQ3YjM1ODFmYTQzMDNkZmRmMzBk
-    ZTRkNWUxZWM2Mzk4NmJlNTQ2YmU1YWQwZmRmNzIxZDFkYjk0NTM=
+    ZDE1MWExN2JkZDY5OGYwNWFkMGZhYTVhZDE1MzEzYjMxYjc3YTU3NDc0MDQ4
+    OWMyOTEwMzY3ZTE4OGIxMTNiODlhZDExZGNjMzVlMjYzMWY1ZWNmZGVlM2Qz
+    Yjk2ZWRkZDkxMGU0MmJlMmU2ZjU0ZGI3ODA3ZWU2NDUzNTcxZWQ=
   data.tar.gz: !binary |-
-    ZmExYTE0MzIyODFjN2JiYzAxOGUxM2ZhMzIzNjRiYjc4MjVlYjQxMTBlMWU2
-    ZmE4ZjE2ZDU2YzI0YmIyNjIxZGQ5M2I1MzJlMDU1NzkwNWFiMDk0NmRlN2Vh
-    NDZkMWYxOTNiZDRkNmE0NThjOWFlZjNhZDc4OGMxZjE5NjY2NmI=
+    OTcxYzViZjM1MDVkMDJjODhlZTlkN2M3MTliYzRmZDE1NzQ4NDMzMDgzYzhk
+    NjNhMGIwMjUxNzFiMzA4Mjg2NmE3OTQzNWRhNWNiMDIyM2Q4MzVlMDk3OWM3
+    OTAwNTBlNWYxMmY1MWUwMTlkOWFlYTZkY2E1NDA3NGFkNDdjZjk=

data/.gitignore

@@ -1,6 +1,6 @@
 *.gem
 .bundle
-Gemfile.lock
+/Gemfile.lock
 pkg/*
 rake
 tmp

data/README.md

@@ -1,4 +1,14 @@
-# Her [![Build Status](https://secure.travis-ci.org/remiprev/her.png?branch=master)](http://travis-ci.org/remiprev/her) [![Gem dependency status](https://gemnasium.com/remiprev/her.png?travis)](https://gemnasium.com/remiprev/her)
+# Her
+
+[![Gem Version](https://badge.fury.io/rb/her.png)][gem]
+[![Build Status](https://secure.travis-ci.org/remiprev/her.png?branch=master)][travis]
+[![Dependency Status](https://gemnasium.com/remiprev/her.png?travis)][gemnasium]
+[![Code Climate](https://codeclimate.com/github/remiprev/her.png)][codeclimate]
+
+[gem]: https://rubygems.org/gems/her
+[travis]: http://travis-ci.org/remiprev/her
+[gemnasium]: https://gemnasium.com/remiprev/her
+[codeclimate]: https://codeclimate.com/github/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 instead of a database.
 
@@ -18,7 +28,7 @@ First, you have to define which API your models will be bound to. For example, w
 
 ```ruby
 # config/initializers/her.rb
-Her::API.setup :url => "https://api.example.com" do |connection|
+Her::API.setup url: "https://api.example.com" do |connection|
   connection.use Faraday::Request::UrlEncoded
   connection.use Her::Middleware::DefaultParseJSON
   connection.use Faraday::Adapter::NetHttp
@@ -42,10 +52,10 @@ User.all
 User.find(1)
 # GET https://api.example.com/users/1 and return a User object
 
-@user = User.create(:fullname => "Tobias Fünke")
+@user = User.create(fullname: "Tobias Fünke")
 # POST "https://api.example.com/users" with the data and return a User object
 
-@user = User.new(:fullname => "Tobias Fünke")
+@user = User.new(fullname: "Tobias Fünke")
 @user.occupation = "actor"
 @user.save
 # POST https://api.example.com/users with the data and return a User object
@@ -68,11 +78,11 @@ end
 # Update a fetched resource
 user = User.find(1)
 user.fullname = "Lindsay Fünke"
-# OR user.assign_attributes :fullname => "Lindsay Fünke"
+# OR user.assign_attributes(fullname: "Lindsay Fünke")
 user.save
 
 # Update a resource without fetching it
-User.save_existing(1, :fullname => "Lindsay Fünke")
+User.save_existing(1, fullname: "Lindsay Fünke")
 
 # Destroy a fetched resource
 user = User.find(1)
@@ -83,20 +93,21 @@ User.destroy_existing(1)
 
 # Fetching a collection of resources
 User.all
+User.where(moderator: 1).all
 
 # Create a new resource
-User.create(:fullname => "Maeby Fünke")
+User.create(fullname: "Maeby Fünke")
 
 # Save a new resource
-user = User.new(:fullname => "Maeby Fünke")
+user = User.new(fullname: "Maeby Fünke")
 user.save
 ```
 
-You can look into the `examples` directory for a sample application using Her. For a complete reference of all the methods you can use, check out [the documentation](http://rdoc.info/github/remiprev/her).
+You can look into the [`her-example`](https://github.com/remiprev/her-example) repository for a sample application using Her. For a complete reference of all the methods you can use, check out [the documentation](http://rdoc.info/github/remiprev/her).
 
 ## Middleware
 
-Since Her relies on [Faraday](https://github.com/technoweenie/faraday) to send HTTP requests, you can choose the middleware used to handle requests and responses. Using the block in the `setup` call, you have access to Faraday’s `connection` object and are able to customize the middleware stack used on each request and response.
+Since Her relies on [Faraday](https://github.com/lostisland/faraday) to send HTTP requests, you can choose the middleware used to handle requests and responses. Using the block in the `setup` call, you have access to Faraday’s `connection` object and are able to customize the middleware stack used on each request and response.
 
 ### Authentication
 
@@ -126,7 +137,7 @@ end
 # config/initializers/her.rb
 require "lib/my_token_authentication"
 
-Her::API.setup :url => "https://api.example.com" do |connection|
+Her::API.setup url: "https://api.example.com" do |connection|
   connection.use MyTokenAuthentication
   connection.use Faraday::Request::UrlEncoded
   connection.use Her::Middleware::DefaultParseJSON
@@ -153,13 +164,13 @@ 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 => ""
+  consumer_key: "",
+  consumer_secret: "",
+  token: "",
+  token_secret: ""
 }
 
-Her::API.setup :url => "https://api.twitter.com/1/" do |connection|
+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
@@ -188,7 +199,7 @@ By default, Her handles JSON data. It expects the resource/collection data to be
 
 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:
+Also, you can define your own parsing method using a response middleware. The middleware should set `env[:body]` to a hash with three symbol keys: `:data`, `:errors` and `:metadata`. The following code uses a custom middleware to parse the JSON data:
 
 ```ruby
 # Expects responses like:
@@ -198,21 +209,21 @@ Also, you can define your own parsing method using a response middleware. The mi
 #         "id": 1,
 #         "name": "Tobias Fünke"
 #       },
-#       "errors" => []
+#       "errors": []
 #     }
 #
 class MyCustomParser < Faraday::Response::Middleware
   def on_complete(env)
-    json = MultiJson.load(env[:body], :symbolize_keys => true)
+    json = MultiJson.load(env[:body], symbolize_keys: true)
     env[:body] = {
-      :data => json[:result],
-      :errors => json[:errors],
-      :metadata => json[:metadata]
+      data: json[:result],
+      errors: json[:errors],
+      metadata: json[:metadata]
     }
   end
 end
 
-Her::API.setup :url => "https://api.example.com" do |connection|
+Her::API.setup url: "https://api.example.com" do |connection|
   connection.use MyCustomParser
   connection.use Faraday::Adapter::NetHttp
 end
@@ -233,7 +244,7 @@ gem "memcached"
 In your Ruby code:
 
 ```ruby
-Her::API.setup :url => "https://api.example.com" do |connection|
+Her::API.setup url: "https://api.example.com" do |connection|
   connection.use FaradayMiddleware::Caching, Memcached::Rails.new('127.0.0.1:11211')
   connection.use Her::Middleware::DefaultParseJSON
   connection.use Faraday::Adapter::NetHttp
@@ -289,14 +300,14 @@ If there’s association data in the resource, no extra HTTP request is made whe
 ```ruby
 @user = User.find(1)
 # {
-#   :id => 1,
-#   :name => "George Michael Bluth",
-#   :comments => [
-#     { :id => 1, :text => "Foo" },
-#     { :id => 2, :text => "Bar" }
+#   "id": 1,
+#   "name": "George Michael Bluth",
+#   "comments": [
+#     { "id": 1, "text": "Foo" },
+#     { "id": 2, "text": "Bar" }
 #   ],
-#   :role => { :id => 1, :name => "Admin" },
-#   :organization => { :id => 2, :name => "Bluth Company" }
+#   "role": { "id": 1, "name": "Admin" },
+#   "organization": { "id": 2, "name": "Bluth Company" }
 # }
 @user.comments
 # [#<Comment id=1 text="Foo">, #<Comment id=2 text="Bar">]
@@ -310,13 +321,17 @@ If there’s no association data in the resource, Her makes a HTTP request to re
 
 ```ruby
 @user = User.find(1)
-# { :id => 1, :name => "George Michael Bluth", :organization_id => 2 }
+# { "id": 1, "name": "George Michael Bluth", "organization_id": 2 }
 
 # has_many association:
 @user.comments
 # GET /users/1/comments
 # [#<Comment id=1>, #<Comment id=2>]
 
+@user.comments.where(approved: 1)
+# GET /users/1/comments?approved=1
+# [#<Comment id=1>]
+
 # has_one association:
 @user.role
 # GET /users/1/role
@@ -364,11 +379,11 @@ class User
   include Her::Model
 
   attributes :fullname, :email
-  validates :fullname, :presence => true
-  validates :email, :presence => true
+  validates :fullname, presence: true
+  validates :email, presence: true
 end
 
-@user = User.new(:fullname => "Tobias Fünke")
+@user = User.new(fullname: "Tobias Fünke")
 @user.valid? # => false
 
 @user.save
@@ -386,7 +401,7 @@ class User
   attributes :fullname, :email
 end
 
-@user = User.new(:fullname => "Tobias Fünke")
+@user = User.new(fullname: "Tobias Fünke")
 @user.fullname_changed? # => true
 @user.changes # => { :fullname => [nil, "Tobias Fünke"] }
 
@@ -412,7 +427,7 @@ class User
   end
 end
 
-@user = User.create(:fullname => "Tobias Funke")
+@user = User.create(fullname: "Tobias Funke")
 # POST /users&fullname=Tobias+Fünke&internal_id=42
 
 @user = User.find(1)
@@ -450,10 +465,10 @@ class Article
   include_root_in_json :post
 end
 
-User.create(:fullname => "Tobias Fünke")
+User.create(fullname: "Tobias Fünke")
 # POST { "user": { "fullname": "Tobias Fünke" } } to /users
 
-Article.create(:title => "Hello world.")
+Article.create(title: "Hello world.")
 # POST { "post": { "title": "Hello world." } } to /articles
 ```
 
@@ -473,11 +488,11 @@ class Article
 end
 
 # POST /users returns { "user": { "fullname": "Tobias Fünke" } }
-user = User.create(:fullname => "Tobias Fünke")
+user = User.create(fullname: "Tobias Fünke")
 user.fullname # => "Tobias Fünke"
 
 # POST /articles returns { "post": { "title": "Hello world." } }
-article = Article.create(:title => "Hello world.")
+article = Article.create(title: "Hello world.")
 article.title # => "Hello world."
 ```
 
@@ -502,7 +517,7 @@ User.unpopular
 # GET /users/unpopular
 # [#<User id=3>, #<User id=4>]
 
-User.from_default(:name => "Maeby Fünke")
+User.from_default(name: "Maeby Fünke")
 # POST /users/from_default?name=Maeby+Fünke
 # #<User id=5 name="Maeby Fünke">
 ```
@@ -582,13 +597,13 @@ class User
   collection_path "/organizations/:organization_id/users"
 end
 
-@user = User.find(1, :_organization_id => 2)
+@user = User.find(1, _organization_id: 2)
 # GET /organizations/2/users/1
 
-@user = User.all(:_organization_id => 2)
+@user = User.all(_organization_id: 2)
 # GET /organizations/2/users
 
-@user = User.new(:fullname => "Tobias Fünke", :organization_id => 2)
+@user = User.new(fullname: "Tobias Fünke", organization_id: 2)
 @user.save
 # POST /organizations/2/users
 ```
@@ -603,8 +618,8 @@ class User
   primary_key :_id
 end
 
-user = User.find(1) # GET /users/1 returns { "_id": 1, "name": "Tobias" }
-user.save # PUT /users/1
+user = User.find("4fd89a42ff204b03a905c535") # GET /users/1 returns { "_id": "4fd89a42ff204b03a905c535", "name": "Tobias" }
+user.save # PUT /users/4fd89a42ff204b03a905c535
 ```
 
 ### Inheritance
@@ -634,14 +649,14 @@ It is possible to use different APIs for different models. Instead of calling `H
 
 ```ruby
 # config/initializers/her.rb
-$my_api = Her::API.new
-$my_api.setup :url => "https://my_api.example.com" do |connection|
+MY_API = Her::API.new
+MY_API.setup url: "https://my-api.example.com" do |connection|
   connection.use Her::Middleware::DefaultParseJSON
   connection.use Faraday::Adapter::NetHttp
 end
 
-$other_api = Her::API.new
-$other_api.setup :url => "https://other_api.example.com" do |connection|
+OTHER_API = Her::API.new
+OTHER_API.setup url: "https://other-api.example.com" do |connection|
   connection.use Her::Middleware::DefaultParseJSON
   connection.use Faraday::Adapter::NetHttp
 end
@@ -652,28 +667,28 @@ You can then define which API a model will use:
 ```ruby
 class User
   include Her::Model
-  uses_api $my_api
+  use_api MY_API
 end
 
 class Category
   include Her::Model
-  uses_api $other_api
+  use_api OTHER_API
 end
 
 User.all
-# GET https://my_api.example.com/users
+# GET https://my-api.example.com/users
 
 Category.all
-# GET https://other_api.example.com/categories
+# GET https://other-api.example.com/categories
 ```
 
 ### SSL
 
-When initializing `Her::API`, you can pass any parameter supported by `Faraday.new`. So [to use HTTPS](https://github.com/technoweenie/faraday/wiki/Setting-up-SSL-certificates), you can use Faraday’s `:ssl` option.
+When initializing `Her::API`, you can pass any parameter supported by `Faraday.new`. So [to use HTTPS](https://github.com/lostisland/faraday/wiki/Setting-up-SSL-certificates), you can use Faraday’s `:ssl` option.
 
 ```ruby
-ssl_options = { :ca_path => "/usr/lib/ssl/certs" }
-Her::API.setup :url => "https://api.example.com", :ssl => ssl_options do |connection|
+ssl_options = { ca_path: "/usr/lib/ssl/certs" }
+Her::API.setup url: "https://api.example.com", ssl: ssl_options do |connection|
   connection.use Her::Middleware::DefaultParseJSON
   connection.use Faraday::Adapter::NetHttp
 end
@@ -704,11 +719,11 @@ In order to test them, we’ll have to stub the remote API requests. With [RSpec
 RSpec.configure do |config|
   config.include(Module.new do
     def stub_api_for(klass)
-      klass.uses_api (api = Her::API.new)
+      klass.use_api (api = Her::API.new)
 
       # Here, you would customize this for your own API (URL, middleware, etc)
       # like you have done in your application’s initializer
-      api.setup :url => "http://api.example.com" do |connection|
+      api.setup url: "http://api.example.com" do |connection|
         connection.use Her::Middleware::FirstLevelParseJSON
         connection.adapter(:test) { |s| yield(s) }
       end
@@ -724,7 +739,7 @@ Then, in your tests, we can specify what (fake) HTTP requests will return:
 describe User do
   before do
     stub_api_for(User) do |stub|
-      stub.get("/users/popular") { |env| [200, {}, [{ :id => 1, :name => "Tobias Fünke" }, { :id => 2, :name => "Lindsay Fünke" }].to_json] }
+      stub.get("/users/popular") { |env| [200, {}, [{ id: 1, name: "Tobias Fünke" }, { id: 2, name: "Lindsay Fünke" }].to_json] }
     end
   end
 
@@ -744,7 +759,7 @@ describe Post do
   describe :recent do
     before do
       stub_api_for(Post) do |stub|
-        stub.get("/posts/recent") { |env| [200, {}, [{ :id => 1 }, { :id => 2 }].to_json] }
+        stub.get("/posts/recent") { |env| [200, {}, [{ id: 1 }, { id: 2 }].to_json] }
       end
     end
 
@@ -756,7 +771,7 @@ describe Post do
   describe :archived do
     before do
       stub_api_for(Post) do |stub|
-        stub.get("/posts/archived") { |env| [200, {}, [{ :id => 1 }, { :id => 2 }].to_json] }
+        stub.get("/posts/archived") { |env| [200, {}, [{ id: 1 }, { id: 2 }].to_json] }
       end
     end
 

data/UPGRADE.md

@@ -2,6 +2,27 @@
 
 Here is a list of backward-incompatible changes that were introduced while Her is pre-1.0. After reaching 1.0, it will follow the [Semantic Versioning](http://semver.org/) system.
 
+## 0.6
+
+* Associations have been refactored so that calling the association name method doesn’t immediately load or fetch the data.
+
+        class User
+          include Her::Model
+          has_many :comments
+        end
+
+        # This doesn’t fetch the data yet
+        comments = User.find(1).comments
+
+        # This actually fetches the data
+        puts comments.inspect
+
+        # This is no longer possible
+        comments = User.find(1).comments(:approved => 1)
+
+        # To pass additional parameters to the HTTP request, we now have to do this
+        comments = User.find(1).comments.where(:approved => 1)
+
 ## 0.5.4
 
 * Her does not support Ruby 1.8.7 anymore. You should upgrade to 1.9.2, 1.9.3 or 2.0.0.

data/lib/her/model.rb

@@ -1,6 +1,7 @@
 require "her/model/base"
 require "her/model/http"
 require "her/model/attributes"
+require "her/model/relation"
 require "her/model/orm"
 require "her/model/parse"
 require "her/model/associations"
@@ -44,7 +45,7 @@ module Her
     # Class methods
     included do
       # Assign the default API
-      uses_api Her::API.default_api
+      use_api Her::API.default_api
 
       # Define the default primary key
       primary_key :id