her 0.0.1

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.yardoc
+doc

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/README.md

@@ -0,0 +1,36 @@
+# 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.
+
+## Installation
+
+In your Gemfile, add:
+
+    gem "her"
+
+## Usage
+
+To add the ORM to a class, you just have to include `Her::Model` in it and define which API you want it to be bound to. For example, with Rails, you would define a `config/initializers/her.rb` file with this:
+
+```ruby
+$my_api = Her::API.new
+$my_api.setup :base_uri => "https://api.example.com"
+```
+
+And then, for each of your models:
+
+```ruby
+class User
+  include Her::Model
+  uses_api $my_api
+end
+```
+
+After that, using Her is very similar to many ActiveModel-like ORMs:
+
+```ruby
+User.all     # => Fetches "https://api.example.com/users" and return an array of User objects
+User.find(1) # => Fetches "https://api.example.com/users/1" and return a User object
+```

data/Rakefile

@@ -0,0 +1,28 @@
+require "bundler"
+Bundler.require :development
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+task :default => :spec
+
+desc "Run all specs"
+RSpec::Core::RakeTask.new(:spec) do |task| # {{{
+  task.pattern = "spec/**/*_spec.rb"
+  task.rspec_opts = "--colour --format=documentation"
+end # }}}
+
+desc "Generate YARD Documentation"
+YARD::Rake::YardocTask.new do |task| # {{{
+  task.options = [
+    "-o", File.expand_path("../doc", __FILE__),
+    "--readme=README.md",
+    "--markup=markdown",
+    "--markup-provider=maruku",
+    "--no-private",
+    "--no-cache",
+    "--protected",
+    "--title=Her",
+  ]
+  task.files   = ["lib/**/*.rb"]
+end # }}}

data/her.gemspec

@@ -0,0 +1,29 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "her/version"
+
+Gem::Specification.new do |s|
+  s.name        = "her"
+  s.version     = Her::VERSION
+  s.authors     = ["Rémi Prévost"]
+  s.email       = ["remi@exomel.com"]
+  s.homepage    = "https://github.com/remiprev/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.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 "maruku"
+  s.add_development_dependency "mocha"
+  s.add_development_dependency "fakeweb"
+
+  s.add_runtime_dependency "activesupport"
+  s.add_runtime_dependency "faraday"
+  s.add_runtime_dependency "json"
+end

data/lib/her/api.rb

@@ -0,0 +1,59 @@
+module Her
+  # This class is where all HTTP requests are made. Before using Her, you must configure it
+  # so it knows where to make those requests. In Rails, this is usually done in `config/initializers/her.rb`:
+  #
+  # @example
+  #   $my_api = Her::API.new
+  #   $my_api.setup :base_uri => "https://api.example.com"
+  class API
+    # @private
+    attr_reader :base_uri, :parse_with
+
+    # Setup the API connection
+    def setup(attrs={}) # {{{
+      @base_uri = attrs[:base_uri]
+      @parse_with = lambda do |response|
+        json = JSON.parse(response.body, :symbolize_names => true)
+        {
+          :resource => json[:data],
+          :errors => json[:errors],
+          :metadata => json[:metadata],
+        }
+      end
+      @connection = Faraday.new(:url => @base_uri) do |builder|
+        builder.request  :url_encoded
+        builder.adapter  :net_http
+      end
+    end # }}}
+
+    # Define a custom parsing procedure. The procedure is passed the response object and is
+    # expected to return hash with three keys: a main resource Hash, an errors Array
+    # and a metadata Hash.
+    #
+    # @example
+    #   $my_api.parse_with do |response|
+    #     json = JSON.parse(response.body)
+    #     { :resource => json[:data], :errors => json[:errors], :metadata => json[:metdata] }
+    #   end
+    def parse_with(&block) # {{{
+      @custom_parsing_block = true
+      @parse_with = block
+    end # }}}
+
+    # Return whether a custom parsing block has been defined
+    def custom_parsing_block? # {{{
+      @custom_parsing_block
+    end # }}}
+
+    # Make an HTTP request to the API
+    def request(attrs={}) # {{{
+      # TODO Here, we would probably look for hooks that modify the request before calling the API
+      @connection.send(attrs[:method], attrs[:path])
+    end # }}}
+
+    # Parse the HTTP response
+    def parse(response) # {{{
+      @parse_with.call(response)
+    end # }}}
+  end
+end

data/lib/her/model/base.rb

@@ -0,0 +1,7 @@
+module Her
+  module Model
+    # This module includes basic functionnality to Her::Model
+    module Base
+    end
+  end
+end

data/lib/her/model/http.rb

@@ -0,0 +1,39 @@
+module Her
+  module Model
+    # This module interacts with Her::API to fetch HTTP data
+    module HTTP
+      # Link a model with a Her::API object
+      def uses_api(api) # {{{
+        @her_api = api
+      end # }}}
+
+      # Defines a custom collection path for the resource
+      #
+      # @example
+      #  class User
+      #    include Her::Model
+      #    uses_api $example_api
+      #    collection_path "users"
+      #  end
+      def collection_path(path=nil) # {{{
+        return @her_collection_path unless path
+        @her_collection_path = path
+      end # }}}
+
+      # Main request wrapper around Her::API. Used to make custom request to the API.
+      # @private
+      def request(attrs={}, &block) # {{{
+        response = @her_api.request(attrs)
+        yield @her_api.parse(response)
+      end # }}}
+
+      # Make a GET request and return the parsed JSON response
+      #
+      # @example
+      #   User.get "/users/foo"
+      def get(path, attrs={}, &block) # {{{
+        request(attrs.merge(:method => :get, :path => path), &block)
+      end # }}}
+    end
+  end
+end

data/lib/her/model/orm.rb

@@ -0,0 +1,40 @@
+module Her
+  module Model
+    # This module adds ORM-like capabilities to the model
+    module ORM
+      # Initialize a new object with data received from an HTTP request
+      # @private
+      def initialize(single_data) # {{{
+        @data = single_data
+        @data = self.class.parse_relationships(@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
+      # @private
+      def method_missing(method) # {{{
+        method = method.to_s.gsub(/(\?|\!)$/, "").to_sym
+        @data.include?(method) ? @data[method] : super
+      end # }}}
+
+      # Fetch a specific resource based on an ID
+      def find(id) # {{{
+        request(:method => :get, :path => "#{@her_collection_path}/#{id}") do |parsed_data|
+          new(parsed_data[:resource])
+        end
+      end # }}}
+
+      # Fetch a collection of resources
+      def all(params={}) # {{{
+        request(:method => :get, :path => "#{@her_collection_path}") do |parsed_data|
+          Her::Model::ORM.initialize_collection(to_s.downcase.pluralize, parsed_data[:resource])
+        end
+      end # }}}
+    end
+  end
+end

data/lib/her/model/relationships.rb

@@ -0,0 +1,56 @@
+module Her
+  module Model
+    # This module adds relationships to models
+    module Relationships
+      # Return relationships
+      # @private
+      def relationships # {{{
+        @her_relationships
+      end # }}}
+
+      # Parse relationships data after initializing a new object
+      # @private
+      def parse_relationships(data) # {{{
+        @her_relationships ||= {}
+        @her_relationships.each_pair do |type, relationships|
+          relationships.each do |relationship|
+            data[relationship[:name]] = Her::Model::ORM.initialize_collection(relationship[:name], data[relationship[:name]]) if data.include?(relationship[:name])
+          end
+        end
+        data
+      end # }}}
+
+      # Define an *has_many* relationship for the resource
+      #
+      # * `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.new objects
+      # * `User.has_many :comments` creates a User.comments method to would
+      #   make an extra HTTP request if there was no "comments" key
+      def has_many(name, attrs={}) # {{{
+        @her_relationships ||= {}
+        (@her_relationships[:has_many] ||= []) << attrs.merge(:name => name)
+        collection_path = @her_collection_path
+
+        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
+        end
+      end # }}}
+
+      # Define a *belongs_to* relationship for the resource
+      #
+      # * `User.belongs_to :organzation` is used to check if the "user" JSON
+      #   resource we receive has an `organzation` key and map it to
+      #   an Organization.new object
+      #
+      # * `User.belongs_to :organzation` creates a User.organzation method
+      def belongs_to(name, attrs={}) # {{{
+        @her_relationships ||= {}
+        (@her_relationships[:belongs_to] ||= []) << attrs.merge(:name => name)
+      end # }}}
+    end
+  end
+end

data/lib/her/model.rb

@@ -0,0 +1,32 @@
+module Her
+  # This module is the main element of Her. After creating a Her::API object,
+  # include this module in your models to get a few magic methods defined in them.
+  #
+  # @example
+  #   class User
+  #     include Her::Model
+  #     uses_api $api
+  #   end
+  #
+  #   @user = User.new(:name => "Rémi")
+  module Model
+    autoload :Base,          "her/model/base"
+    autoload :HTTP,          "her/model/http"
+    autoload :ORM,           "her/model/orm"
+    autoload :Relationships, "her/model/relationships"
+
+    extend ActiveSupport::Concern
+
+    # Instance methods
+    include Her::Model::ORM
+
+    # Class methods
+    included do
+      @her_collection_path = "#{self.to_s.downcase.pluralize}"
+      extend Her::Model::Base
+      extend Her::Model::HTTP
+      extend Her::Model::ORM
+      extend Her::Model::Relationships
+    end
+  end
+end

data/lib/her/version.rb

@@ -0,0 +1,3 @@
+module Her
+  VERSION = "0.0.1"
+end

data/lib/her.rb

@@ -0,0 +1,10 @@
+require "her/version"
+require "json"
+require "faraday"
+require "active_support"
+require "active_support/inflector"
+
+module Her
+  autoload :Model, "her/model"
+  autoload :API,   "her/api"
+end

data/spec/api_spec.rb

@@ -0,0 +1,52 @@
+# encoding: utf-8
+require File.join(File.dirname(__FILE__), "spec_helper.rb")
+
+describe Her::API do
+  context "initialization" do
+    describe "#setup" do
+      it "sets a base URI" do # {{{
+        @api = Her::API.new
+        @api.setup :base_uri => "https://api.example.com"
+        @api.base_uri.should == "https://api.example.com"
+      end # }}}
+
+      it "sets a custom parsing block" do # {{{
+        @api = Her::API.new
+        @api.setup :base_uri => "https://api.example.com"
+        @api.parse_with do |response|
+          response.body
+        end
+        @api.custom_parsing_block?.should be_true
+      end # }}}
+    end
+
+    describe "#request" do
+      before do # {{{
+        @api = Her::API.new
+        @api.setup :base_uri => "https://api.example.com"
+        FakeWeb.register_uri(:get, "https://api.example.com/foo", :body => "Foo, it is.")
+      end # }}}
+
+      it "makes HTTP requests" do # {{{
+        response = @api.request(:method => :get, :path => "/foo")
+        response.body.should == "Foo, it is."
+      end # }}}
+    end
+
+    describe "#parse" 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, :name => "George Michael Bluth" }, :errors => ["This is a single error"], :metadata => { :page => 1, :per_page => 10 }}.to_json)
+      end # }}}
+
+      it "parses a request" do # {{{
+        @api.parse @api.request(:method => :get, :path => "users/1") do |parsed_data|
+          parsed_data[:resource].should == { :id => 1, :name => "George Michael Bluth" }
+          parsed_data[:errors].should == ["This is a single error"]
+          parsed_data[:metadata].should == { :page => 1, :per_page => 10 }
+        end
+      end # }}}
+    end
+  end
+end

data/spec/model_spec.rb

@@ -0,0 +1,66 @@
+# encoding: utf-8
+require File.join(File.dirname(__FILE__), "spec_helper.rb")
+
+describe Her::Model do
+  describe Her::Model::ORM do
+    context "mapping data to Ruby objects" 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, :name => "Tobias Fünke" } }.to_json)
+        FakeWeb.register_uri(:get, "https://api.example.com/users", :body => { :data => [{ :id => 1, :name => "Tobias Fünke" }, { :id => 2, :name => "Lindsay Fünke" }] }.to_json)
+
+        Object.instance_eval { remove_const :User } if Object.const_defined?(:User)
+        class User
+          include Her::Model
+        end
+        User.uses_api @api
+      end # }}}
+
+      it "maps a single resource to a Ruby object" do # {{{
+        @user = User.find(1)
+        @user.id.should == 1
+        @user.name.should == "Tobias Fünke"
+      end # }}}
+
+      it "maps a collection of resources to an array of Ruby objects" do # {{{
+        @users = User.all
+        @users.length.should == 2
+        @users.first.name.should == "Tobias Fünke"
+      end # }}}
+    end # }}}
+  end
+
+  describe Her::Model::Relationships do
+    context "setting associations" do # {{{
+      before do # {{{
+        Object.instance_eval { remove_const :User } if Object.const_defined?(:User)
+        class User
+          include Her::Model
+        end
+      end # }}}
+
+      it "handles a single 'has_many' association" do # {{{
+        User.has_many :comments
+        User.relationships[:has_many].should == [{ :name => :comments }]
+      end # }}}
+
+      it "handles multiples 'has_many' associations" do # {{{
+        User.has_many :comments
+        User.has_many :posts
+        User.relationships[:has_many].should == [{ :name => :comments }, { :name => :posts }]
+      end # }}}
+
+      it "handles a single belongs_to association" do # {{{
+        User.belongs_to :organization
+        User.relationships[:belongs_to].should == [{ :name => :organization }]
+      end # }}}
+
+      it "handles multiples 'belongs_to' associations" do # {{{
+        User.belongs_to :organization
+        User.belongs_to :family
+        User.relationships[:belongs_to].should == [{ :name => :organization }, { :name => :family }]
+      end # }}}
+    end # }}}
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+$:.unshift File.join(File.dirname(__FILE__), *%w[.. lib])
+
+require "her"
+require "fakeweb"
+require "mocha"
+
+module Helpers
+end
+
+RSpec.configure do |c|
+  c.include Helpers
+end

metadata

@@ -0,0 +1,216 @@
+--- !ruby/object:Gem::Specification
+name: her
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Rémi Prévost
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-09 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: maruku
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: fakeweb
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Her is an ORM that maps REST resources to Ruby objects
+email:
+- remi@exomel.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- her.gemspec
+- lib/her.rb
+- lib/her/api.rb
+- lib/her/model.rb
+- lib/her/model/base.rb
+- lib/her/model/http.rb
+- lib/her/model/orm.rb
+- lib/her/model/relationships.rb
+- lib/her/version.rb
+- spec/api_spec.rb
+- spec/model_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/remiprev/her
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 1076475942848490039
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 1076475942848490039
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.18
+signing_key: 
+specification_version: 3
+summary: A simple Representational State Transfer-based Hypertext Transfer Protocol-powered
+  Object Relational Mapper. Her?
+test_files:
+- spec/api_spec.rb
+- spec/model_spec.rb
+- spec/spec_helper.rb
+has_rdoc: