morpheus 0.3.4

data/.rvmrc

@@ -0,0 +1 @@
+rvm use ree-1.8.7-2010.02@morpheus

data/Gemfile

@@ -0,0 +1,21 @@
+source "http://rubygems.org"
+
+gem 'yajl-ruby',     '~>0.8.2'
+gem 'typhoeus',      '~>0.2.4'
+gem 'activemodel',   '~>3.0.0'
+gem 'activesupport', '~>3.0.0'
+gem 'i18n',          '~>0.5.0'
+
+group :development, :test do
+  gem 'rails',         '3.0.7'
+  gem 'sqlite3',       '1.3.3'
+  gem 'rspec-rails',   '2.6.0'
+  gem 'yard',          '0.6.8'
+  gem 'jeweler',       '1.6.0'
+  gem 'rcov',          '0.9.9'
+  gem 'autotest',      '4.4.6'
+  gem 'ZenTest',       '4.6.2'
+  gem 'rocco',         '0.7.0'
+  gem 'awesome_print', '0.4.0'
+  gem 'pry',           '0.9.3'
+end

data/Gemfile.lock

@@ -0,0 +1,134 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    ZenTest (4.6.2)
+    abstract (1.0.0)
+    actionmailer (3.0.7)
+      actionpack (= 3.0.7)
+      mail (~> 2.2.15)
+    actionpack (3.0.7)
+      activemodel (= 3.0.7)
+      activesupport (= 3.0.7)
+      builder (~> 2.1.2)
+      erubis (~> 2.6.6)
+      i18n (~> 0.5.0)
+      rack (~> 1.2.1)
+      rack-mount (~> 0.6.14)
+      rack-test (~> 0.5.7)
+      tzinfo (~> 0.3.23)
+    activemodel (3.0.7)
+      activesupport (= 3.0.7)
+      builder (~> 2.1.2)
+      i18n (~> 0.5.0)
+    activerecord (3.0.7)
+      activemodel (= 3.0.7)
+      activesupport (= 3.0.7)
+      arel (~> 2.0.2)
+      tzinfo (~> 0.3.23)
+    activeresource (3.0.7)
+      activemodel (= 3.0.7)
+      activesupport (= 3.0.7)
+    activesupport (3.0.7)
+    arel (2.0.10)
+    autotest (4.4.6)
+      ZenTest (>= 4.4.1)
+    awesome_print (0.4.0)
+    builder (2.1.2)
+    coderay (1.0.4)
+    diff-lcs (1.1.3)
+    erubis (2.6.6)
+      abstract (>= 1.0.0)
+    git (1.2.5)
+    i18n (0.5.0)
+    jeweler (1.6.0)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    mail (2.2.19)
+      activesupport (>= 2.3.6)
+      i18n (>= 0.4.0)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    method_source (0.6.7)
+      ruby_parser (>= 2.3.1)
+    mime-types (1.17.2)
+    mustache (0.99.4)
+    polyglot (0.3.3)
+    pry (0.9.3)
+      coderay (>= 0.9.8)
+      method_source (>= 0.6.0)
+      ruby_parser (>= 2.0.5)
+      slop (~> 1.9.0)
+    rack (1.2.4)
+    rack-mount (0.6.14)
+      rack (>= 1.0.0)
+    rack-test (0.5.7)
+      rack (>= 1.0)
+    rails (3.0.7)
+      actionmailer (= 3.0.7)
+      actionpack (= 3.0.7)
+      activerecord (= 3.0.7)
+      activeresource (= 3.0.7)
+      activesupport (= 3.0.7)
+      bundler (~> 1.0)
+      railties (= 3.0.7)
+    railties (3.0.7)
+      actionpack (= 3.0.7)
+      activesupport (= 3.0.7)
+      rake (>= 0.8.7)
+      thor (~> 0.14.4)
+    rake (0.9.2.2)
+    rcov (0.9.9)
+    rdiscount (1.6.8)
+    rocco (0.7)
+      mustache
+      rdiscount
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.4)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+    rspec-rails (2.6.0)
+      actionpack (~> 3.0)
+      activesupport (~> 3.0)
+      railties (~> 3.0)
+      rspec (~> 2.6.0)
+    ruby_parser (2.3.1)
+      sexp_processor (~> 3.0)
+    sexp_processor (3.0.7)
+    slop (1.9.1)
+    sqlite3 (1.3.3)
+    thor (0.14.6)
+    treetop (1.4.10)
+      polyglot
+      polyglot (>= 0.3.1)
+    typhoeus (0.2.4)
+      mime-types
+      mime-types
+    tzinfo (0.3.30)
+    yajl-ruby (0.8.3)
+    yard (0.6.8)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  ZenTest (= 4.6.2)
+  activemodel (~> 3.0.0)
+  activesupport (~> 3.0.0)
+  autotest (= 4.4.6)
+  awesome_print (= 0.4.0)
+  i18n (~> 0.5.0)
+  jeweler (= 1.6.0)
+  pry (= 0.9.3)
+  rails (= 3.0.7)
+  rcov (= 0.9.9)
+  rocco (= 0.7.0)
+  rspec-rails (= 2.6.0)
+  sqlite3 (= 1.3.3)
+  typhoeus (~> 0.2.4)
+  yajl-ruby (~> 0.8.2)
+  yard (= 0.6.8)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Ryan Moran
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,44 @@
+= RESTful API Client
+Working toward a DSL that is very ActiveResource/ActiveRecord-like with some features stolen from other great libraries like DataMapper.
+
+For Example:
+
+    class Dummy < PolarisResource::Base
+      property :name
+      property :created_at
+      property :has_smarts
+
+      belongs_to :thingy
+      has_many :thingamabobs
+      has_one :doohickey
+    end
+
+    @dummy = Dummy.new(
+      :name       => "Dumb",
+      :has_smarts => false,
+      :thingy_id  => 2)                                # => #<Dummy:0x1016858d8>
+    @dummy.new_record?                                 # => true
+    @dummy.save                                        # => POST http://localhost/dummies
+
+    @dummy = Dummy.find(1)                             # => GET http:localhost/dummies/1
+    @dummy.new_record?                                 # => false
+    @dummy.name                                        # => "Dumb"
+    @dummy.name = "Dumber"                             # => "Dumber"
+    @dummy.save                                        # => PUT http://localhost/dummies/1
+    @dummy.update_attributes(:has_smarts => true)      # => PUT http://localhost/dummies/1
+
+    @dummy.thingy                                      # => GET http://localhost/thingies/2
+    @dummy.thingamabobs                                # => GET http://localhost/dummies/1/thingamabobs
+    @dummy.doohickey                                   # => GET http://localhost/dummies/1/doohickey
+
+    Dummy.all                                          # => GET http://localhost/dummies
+    Dummy.find(1,2,3)                                  # => GET http://localhost/dummies?ids=1,2,3
+    Dummy.find([1,2,3])                                # => GET http://localhost/dummies?ids=1,2,3
+
+    Dummy.where(:name => "Dumb")                       # => GET http://localhost/dummies?name=Dumb
+    Dummy.where(:name => "Dumb", :has_smarts => false) # => GET http://localhost/dummies?name=Dumb&has_smarts=false
+    Dummy.limit(1)                                     # => GET http://localhost/dummies?limit=1
+    Dummy.result_per_page = 25                         # => 25
+    Dummy.page(3)                                      # => GET http://localhost/dummies?limit=25&offset=50
+
+Design informed by Service-Oriented Design with Ruby and Rails by Paul Dix, @Amazon[http://www.amazon.com/Service-Oriented-Design-Rails-Addison-Wesley-Professional/dp/0321659368]

data/Rakefile

@@ -0,0 +1,48 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name        = "morpheus"
+  gem.homepage    = "https://github.com/RevolutionPrep/morpheus"
+  gem.license     = "MIT"
+  gem.summary     = %Q{RESTful API Client}
+  gem.description = %Q{RESTful API Client}
+  gem.email       = "ryan.moran@revolutionprep.com"
+  gem.authors     = ["Ryan Moran"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern   = 'spec/**/*_spec.rb'
+  spec.rcov_opts = "--exclude osx\/objc,gems\/,spec\/"
+  spec.rcov      = true
+end
+
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new
+
+desc "Builds the documentation using Rocco"
+task :doc do
+  system 'rocco -o doc -t doc/layout.mustache lib/*.rb lib/**/*.rb lib/**/**/*.rb'
+end

data/VERSION

@@ -0,0 +1 @@
+0.3.4

data/autotest/discover.rb

@@ -0,0 +1,7 @@
+Autotest.add_discovery do
+  'rspec2'
+end
+
+Autotest.add_hook :initialize do |autotest|
+  ['.git', 'spec/dummy/log'].each { |exception| autotest.add_exception(exception) }
+end

data/lib/ext/typhoeus.rb

@@ -0,0 +1,37 @@
+module Typhoeus
+  class Hydra
+    module ConnectOptions
+
+      def check_allow_net_connect_with_error_wrapping!(request)
+        check_allow_net_connect_without_error_wrapping!(request)
+      rescue Typhoeus::Hydra::NetConnectNotAllowedError => ex
+        raise Morpheus::NetConnectNotAllowedError.new(request), ex.message
+      end
+      private :check_allow_net_connect_with_error_wrapping!
+
+      alias_method :check_allow_net_connect_without_error_wrapping!, :check_allow_net_connect!
+      alias_method :check_allow_net_connect!, :check_allow_net_connect_with_error_wrapping!
+
+    end
+
+    def response_from_easy(easy, request)
+      Morpheus::Response.new(
+        :code                => easy.response_code,
+        :headers             => easy.response_header,
+        :body                => easy.response_body,
+        :time                => easy.total_time_taken,
+        :start_transfer_time => easy.start_transfer_time,
+        :app_connect_time    => easy.app_connect_time,
+        :pretransfer_time    => easy.pretransfer_time,
+        :connect_time        => easy.connect_time,
+        :name_lookup_time    => easy.name_lookup_time,
+        :effective_url       => easy.effective_url,
+        :curl_return_code    => easy.curl_return_code,
+        :curl_error_message  => easy.curl_error_message,
+        :request             => request
+      )
+    end
+    private :response_from_easy
+
+  end
+end

data/lib/morpheus/associations/association.rb

@@ -0,0 +1,110 @@
+# The Association class serves as the basis for associating resources.
+# Resources have an association DSL that follows that of ActiveRecord:
+#
+# has_many :automobiles
+#
+# has_one :car
+#
+# belongs_to :car_club
+# 
+# This class acts as a proxy that will allow for lazy evaluation of an
+# association. The proxy waits to make the request for the object until
+# a method on the association is called. When this happens, because the
+# method does not exist on the proxy object, method_missing will be
+# called, the target object will be loaded, and then the method will be
+# called on the loaded target.
+module Morpheus
+  module Associations
+    class Association < ActiveSupport::BasicObject
+
+      # Associations can be loaded with several options.
+      def initialize(owner, association, settings = {})
+        # @owner stores the class that the association exists on.
+        @owner = owner
+
+        # @association stores the associated class, as named in the association
+        # method (i.e. :automobile, :car, :car_club)
+        @association = association
+
+        # @target stores the loaded object. It is not typically accessed directly,
+        # but instead should be accessed through the loaded_target method.
+        @target = settings[:target]
+
+        @filters = settings[:filters] || []
+
+        @includes = []
+
+        # @options holds the chosen options for the association. Several of these
+        # options are set in the subclass' initializer.
+        @options = settings[:options] || {}
+
+        # In some cases, the association name will not match that of the class
+        # that should be instantiated when it is invoked. Here, we can specify
+        # that this association uses a specified class as its target. When the
+        # request is made for the association, this class will be used to
+        # instantiate this object or collection.
+        @options[:class_name] = settings[:options][:class_name] || @association.to_s.classify
+      end
+
+      # The proxy implements a few methods that need to be delegated to the target
+      # so that they will work as expected.
+      def id
+        loaded_target.id
+      end
+
+      def nil?
+        loaded_target.nil?
+      end
+
+      def to_param
+        loaded_target.to_param
+      end
+
+      def try(method, *args, &block)
+        loaded_target.try(method, *args, &block)
+      end
+
+      def includes(*associations)
+        associations.each do |association|
+          @includes << association unless @includes.include?(association)
+        end
+        self
+      end
+
+      # This is left to be implemented by the subclasses as it will operate
+      # differently in each case.
+      def load_target!
+      end
+
+      private
+
+      # The loaded_target method holds a cached version of the loaded target.
+      # This method is used to access the proxied object. Since a request will
+      # be made when a method is invoked on the object, and this can happen
+      # very often, we are caching the target here, so that only a single
+      # request will be made.
+      def loaded_target
+        @target ||= load_target!
+        if Array === @target && !@filters.empty?
+          @filters.uniq.inject(@target.dup) do |target, filter|
+            filter.call(target)
+          end
+        else
+          @target
+        end
+      end
+
+      # The method_missing hook will be called when methods that do not exist
+      # on the proxy object are invoked. This is the point at which the proxied
+      # object is loaded, if it has not been loaded already.
+      def method_missing(m, *args, &block)
+        if filter = @association_class.find_filter(m)
+          with_filter(filter)
+        else
+          loaded_target.send(m, *args, &block)
+        end
+      end
+
+    end
+  end
+end

data/lib/morpheus/associations/belongs_to_association.rb

@@ -0,0 +1,45 @@
+module Morpheus
+  module Associations
+    class BelongsToAssociation < Association
+
+      # The initializer calls out to the superclass' initializer, then will set the
+      # options particular to itself.
+      def initialize(owner, association, settings = {})
+        super
+
+        # The foreign key is used to generate the url for a request. The default uses
+        # the association name with an '_id' suffix as the generated key. For example,
+        # belongs_to :school, will have the foreign key :school_id.
+        @options[:foreign_key] ||= "#{@association.to_s}_id".to_sym
+
+        # The primary key defaults to :id.
+        @options[:primary_key] ||= :id
+
+        # Associations can be marked as polymorphic. These associations will use
+        # the returned type to instantiate the associated object.
+        @options[:polymorphic] = settings[:options][:polymorphic] || false
+
+        # @association_class stores the class of the association, constantized
+        # from the named association (i.e. Automobile, Car, CarClub)
+        @association_class = @options[:class_name].constantize
+      end
+
+      def with_filter(filter)
+        BelongsToAssociation.new(@owner, @association, :target => @target, :filters => @filters.dup.push(filter), :options => @options)
+      end
+
+      # When loading the target, the association will only be loaded if the foreign_key
+      # has been set. Additionally, the class used to find the record will be inferred
+      # by calling the method which is the name of the association with a '_type' suffix.
+      # Alternatively, the class name can be set by using the :class_name option.
+      def load_target!
+        if association_id = @owner.send(@options[:foreign_key])
+          polymorphic_class = @options[:polymorphic] ? @owner.send("#{@association}_type".to_sym).constantize : @options[:class_name].constantize
+          attributes = [UrlBuilder.belongs_to(polymorphic_class, association_id), nil, { :id => association_id }]
+          polymorphic_class.find(association_id)
+        end
+      end
+
+    end
+  end
+end

data/lib/morpheus/associations/has_many_association.rb

@@ -0,0 +1,70 @@
+module Morpheus
+  module Associations
+    class HasManyAssociation < Association
+
+      # The initializer calls out to the superclass' initializer and then
+      # sets the options particular to itself.
+      def initialize(owner, association, settings = {})
+        super
+
+        # The foreign key is used to generate the url for the association
+        # request when the association is transformed into a relation.
+        # The default is to use the class of the owner object with an '_id'
+        # suffix.
+        @options[:foreign_key] ||= "#{@owner.class.to_s.underscore}_id".to_sym
+
+        # The primary key is used in the generated url for the target. It
+        # defaults to :id.
+        @options[:primary_key] ||= :id
+
+        # @association_class stores the class of the association, constantized
+        # from the named association (i.e. Automobile, Car, CarClub)
+        @association_class = @options[:class_name].constantize
+      end
+
+      def with_filter(filter)
+        HasManyAssociation.new(@owner, @association, :target => @target, :filters => @filters.dup.push(filter), :options => @options)
+      end
+
+      # When loading the target, the primary key is first checked. If the
+      # key is nil, then an empty array is returned. Otherwise, the target
+      # is requested at the generated url. For a has_many :meetings
+      # association on a class called Course, the generated url might look
+      # like this: /meetings?course_id=1, where the 1 is the primary key.
+      def load_target!
+        if primary_key = @owner.send(@options[:primary_key])
+          Relation.new(@association.to_s.classify.constantize).where(@options[:foreign_key] => primary_key).all
+        else
+          []
+        end
+      end
+
+      # The where, limit, and page methods delegate to a Relation object.
+      # The association generates a relation, and then calls the very
+      # same where, limit, or page method on that relation object.
+      def where(query_attributes)
+        transform_association_into_relation.where(query_attributes)
+      end
+
+      def limit(amount)
+        transform_association_into_relation.limit(amount)
+      end
+
+      def page(page_number)
+        transform_association_into_relation.page(page_number)
+      end
+
+      def transform_association_into_relation
+        Relation.new(@association.to_s.classify.constantize).where(@options[:foreign_key] => @owner.send(@options[:primary_key]))
+      end
+      private :transform_association_into_relation
+
+      # The append operator is used to append new resources to the association.
+      def <<(one_of_many)
+        @target ||= []
+        @target << one_of_many
+      end
+
+    end
+  end
+end

data/lib/morpheus/associations/has_one_association.rb

@@ -0,0 +1,46 @@
+module Morpheus
+  module Associations
+    class HasOneAssociation < Association
+
+      # The initializer calls out to the superclass' initializer and then
+      # sets the options particular to itself.
+      def initialize(owner, association, settings = {})
+        super
+
+        # The foreign key is used to generate the url for the association
+        # request when the association is transformed into a relation.
+        # The default is to use the class of the owner object with an '_id'
+        # suffix.
+        @options[:foreign_key] ||= "#{@owner.class.to_s.underscore}_id".to_sym
+
+        # The primary key is used in the generated url for the target. It
+        # defaults to :id.
+        @options[:primary_key] ||= :id
+
+        # @association_class stores the class of the association, constantized
+        # from the named association (i.e. Automobile, Car, CarClub)
+        if @options[:class_name]
+          @association_class = @options[:class_name].constantize
+        else
+          @association_class = @association
+        end
+      end
+
+      def with_filter(filter)
+        HasOneAssociation.new(@owner, @association, :target => @target, :filters => @filters.dup.push(filter), :options => @options)
+      end
+
+      # When loading the target, the primary key is first checked. If the
+      # key is nil, then an nil is returned. Otherwise, the target
+      # is requested at the generated url. For a has_one :meeting
+      # association on a class called Course, the generated url might look
+      # like this: /meetings?course_id=1, where the 1 is the primary key.
+      def load_target!
+        if primary_key = @owner.send(@options[:primary_key])
+          Relation.new(@association_class.to_s.classify.constantize).where(@options[:foreign_key] => primary_key).limit(1).first
+        end
+      end
+
+    end
+  end
+end

data/lib/morpheus/base.rb

@@ -0,0 +1,66 @@
+# Serving as the superclass to all resources, Morpheus::Base
+# should be subclassed and extended from within your application.
+# The Base class consists of the main components one would need to
+# use the Morpheus API. The behavior of the class is contained
+# in several module 'mix-ins'. Each of these modules will be explained
+# within itself. Just know that the Base class includes these modules
+# for you.
+module Morpheus
+  class Base
+    extend  ActiveModel::Naming
+    include ActiveModel::Validations
+    include ActiveModel::Dirty
+    include ActiveModel::Serializers::JSON
+    include ActiveModel::Serializers::Xml
+
+    # These modules wrap distinct behavior that is used within the Base class.
+    # In many cases they rely upon other classes in the library to complete
+    # their functionality. The helper classes can be used stand-alone, but
+    # are most effective when used as collaborators to the mix-in behaviors.
+    include Associations
+    include Attributes
+    include Conversion
+    include Filtering
+    include Finders
+    include Introspection
+    include Persistence
+    include Reflections
+    include RequestHandling
+    include ResponseParsing
+    include UrlSupport
+
+    # Defines a default 'id' property on all instances of Morpheus::Base and subclasses
+    property :id, :integer
+
+    def initialize(new_attributes = {})
+      new_attributes = HashWithIndifferentAccess.new(new_attributes)
+      @errors = ActiveModel::Errors.new(self)
+      new_attributes.each do |attribute, value|
+        self.class.default_attributes.store(attribute.to_sym, nil) unless self.class.attribute_defined?(attribute)
+        update_attribute(attribute, value)
+      end
+    end
+
+    def ==(comparison_object)      
+      comparison_object.equal?(self) ||
+        (comparison_object.instance_of?(self.class) && comparison_object.id == id && !comparison_object.new_record?)
+    end
+
+    def self.base_class
+      self
+    end
+
+    private
+
+    def method_missing(m, *args, &block)
+      if attributes.keys.include?(m.to_s.delete('='))
+        # Defines attribute accessors when the missing method can be found in the attributes hash
+        self.class.send(:define_attribute_accessor, m)
+        send(m, *args, &block)
+      else
+        super
+      end
+    end
+
+  end
+end