weary 0.5.1 → 0.6.0

data/lib/weary/base.rb

@@ -0,0 +1,126 @@
+module Weary
+  class Base
+    @@resources = {}
+    
+    attr_accessor :defaults
+    
+    # Assign credentials to be used when authenticating to a Resource.
+    # Can be a username/password combo, or an OAuth::AccessToken
+    def credentials(username,password='')
+      if username.is_a?(OAuth::AccessToken)
+        @credentials = username
+      else
+        @credentials = {:username => username, :password => password}
+      end
+    end
+    
+    # Each Weary::Base object has its own set of Resources
+    def resources
+      @resources = Marshal.load(Marshal.dump(@@resources)) if !@resources
+      @resources
+    end
+    
+    # Make changes to a Resource given and rebuild the Request method for this object
+    def modify_resource(name)
+      yield resources[name] if block_given?
+      rebuild_method(resources[name])
+    end
+    
+    # Rebuild the Request Method for a given Resource. This only affects the current instance.
+    def rebuild_method(resource)
+      instance_eval %Q{
+        def #{resource.name}(params={})
+          resources[:#{resource.name}].build!(params, @defaults, @credentials)
+        end
+      }
+    end
+    
+    class << self
+      
+      # Getter for class-level resources
+      def resources
+        @@resources
+      end
+      
+      # Declare a resource. Use it with a block to setup the resource
+      #
+      # Methods that are understood are:
+      # [<tt>via</tt>] Get, Post, etc. Defaults to a GET request
+      # [<tt>with</tt>] An array of parameters that will be passed to the body or query of the request. If you pass a hash, it will define default <tt>values</tt> for params <tt>keys</tt>
+      # [<tt>requires</tt>] Array of members of <tt>:with</tt> that are required by the resource.
+      # [<tt>authenticates</tt>] Boolean value; does the resource require authentication?
+      # [<tt>url</tt>] The url of the resource. You can use the same flags as #construct_url
+      # [<tt>follows</tt>] Boolean; Does this follow redirects? Defaults to true
+      # [<tt>headers</tt>] Set headers for the HTTP Request
+      def get(name,&block)
+        build_resource(name, :get, block)
+      end
+      alias declare get
+      
+      # Declares a Resource to be requested via POST
+      def post(name,&block)
+        build_resource(name, :post, block)
+      end
+      
+      # Declares a Resource to be requested via PUT
+      def put(name,&block)
+        build_resource(name, :put, block)
+      end
+
+      # Declares a Resource to be requested via DELETE
+      def delete(name,&block)
+        build_resource(name, :delete, block)
+      end
+      
+      # Set custom default Headers for your Request
+      def headers(headers)
+        @headers = headers
+      end
+      
+      # Sets the domain to be used to build default url's
+      def domain(dom)
+        domain = URI.extract(dom)
+        raise ArgumentError, 'The domain must be a URL.' if domain.blank?
+        @domain = URI.parse(domain[0]).normalize.to_s
+      end
+      
+      # Sets a default format, used to build default Resource url's
+      def format(format)
+        @format = format
+      end
+      
+      # Prepare and store the Resource
+      def build_resource(name,verb,block=nil)
+        resource = prepare_resource(name,verb)
+        block.call(resource) if block
+        store_resource(resource)
+        build_method(resource)
+        resource
+      end
+      
+      # Prepare a Resource with set defaults
+      def prepare_resource(name,via = :get)
+        preparation = Weary::Resource.new(name)
+        preparation.via = via
+        preparation.headers = @headers unless @headers.blank?
+        preparation.url = "#{@domain}#{preparation.name}." + (@format || :json).to_s if @domain
+        preparation
+      end
+      
+      # Store the resource for future use
+      def store_resource(resource)
+        @@resources[resource.name.to_sym] = resource
+        resource
+      end
+      
+      # Build a method to form a Request for the given Resource
+      def build_method(resource)
+        define_method resource.name.to_sym do |*args|
+          args.blank? ? params = {} : params = args[0]
+          resource.build!(params, @defaults, @credentials)
+        end
+      end
+      
+    end
+  end
+end

data/lib/weary/request.rb

@@ -30,15 +30,11 @@ module Weary
     def perform
       req = http.request(request)
       response = Response.new(req, @http_verb)
-      unless options[:no_follow]
-        if response.redirected?
-          response.follow_redirect
-        else
-          response
-        end
-      else
-        response
+      if response.redirected?
+        return response if options[:no_follow]
+        response.follow_redirect
       end
+      response
     end
     
     private

data/lib/weary/resource.rb

@@ -1,22 +1,21 @@
 module Weary
   class Resource
-    attr_accessor :name, :domain, :with, :requires, :via, :format, :url, :authenticates, :follows, :headers, :oauth, :access_token
+    attr_reader :name, :via, :with, :requires, :url
+    attr_accessor :headers
     
     def initialize(name)
       self.name = name
       self.via = :get
       self.authenticates = false
       self.follows = true
-      self.with = []
-      self.requires = []
-      self.oauth = false
     end
     
+    # The name of the Resource. Will be a lowercase string, whitespace replaced with underscores.
     def name=(resource_name)
-      resource_name = resource_name.to_s unless resource_name.is_a?(String)
-      @name = resource_name.downcase.strip.gsub(/\s/,'_')
+      @name = resource_name.to_s.downcase.strip.gsub(/\s/,'_')
     end
     
+    # The HTTP Method used to fetch the Resource
     def via=(http_verb)
       verb = HTTPVerb.new(http_verb).normalize
       @via = if Methods.include?(verb)
@@ -26,109 +25,114 @@ module Weary
       end
     end
     
-    def format=(type)
-      type = type.downcase if type.is_a?(String)
-      @format = case type
-        when *ContentTypes[:json]
-          :json
-        when *ContentTypes[:xml]
-          :xml
-        when *ContentTypes[:html]
-          :html
-        when *ContentTypes[:yaml]
-          :yaml
-        when *ContentTypes[:plain]
-          :plain
-        else
-          raise ArgumentError, "#{type} is not a recognized format."
-      end
-    end
-        
+    # Optional params. Should be an array. Merges with requires if that is set.
     def with=(params)
-      if params.is_a?(Hash)
-        @requires.each { |key| params[key] = nil unless params.has_key?(key) }
-        @with = params
-      else
-        if @requires.nil?
-          @with = params.collect {|x| x.to_sym}
-        else
-          @with = params.collect {|x| x.to_sym} | @requires
-        end
-      end
+      @with = [params].flatten.collect {|x| x.to_sym}
+      @with = (requires | @with) if requires
     end
     
+    # Required params. Should be an array. Merges with `with` or sets `with`.
     def requires=(params)
-      if @with.is_a?(Hash)
-        params.each { |key| @with[key] = nil unless @with.has_key?(key) }
-        @requires = params.collect {|x| x.to_sym}
-      else
-        @with = @with | params.collect {|x| x.to_sym}
-        @requires = params.collect {|x| x.to_sym}
-      end
+      @requires = [params].flatten.collect {|x| x.to_sym}
+      with ? @with = (with | @requires) : (@with = @requires)
     end
     
-    def url=(pattern)
-      if pattern.index("<domain>")
-        raise StandardError, "Domain flag found but the domain is not defined" if @domain.nil?
-        pattern = pattern.gsub("<domain>", @domain)
-      end
-      pattern = pattern.gsub("<resource>", @name)
-      pattern = pattern.gsub("<format>", @format.to_s)
-      @url = pattern
+    # Sets whether the Resource requires authentication. Always sets to a boolean value.
+    def authenticates=(bool)
+      @authenticates = bool ? true : false
     end
     
-    def oauth=(bool)
-      @authenticates = false if bool
-      @oauth = if bool
-        true
-      else
-        false
-      end
+    # Does the Resource require authentication?
+    def authenticates?
+      @authenticates
     end
     
-    def authenticates=(bool)
-      @oauth = false if bool
-      @authenticates = if bool
-        true
-      else
-        false
-      end
+    # Sets whether the Resource should follow redirection. Always sets to a boolean value.
+    def follows=(bool)
+      @follows = (bool ? true : false)
     end
     
-    def authenticates?
-      @authenticates
+    # Should the resource follow redirection?
+    def follows?
+      @follows
     end
     
-    def oauth?
-      @oauth
+    # Set the Resource's URL as a URI
+    def url=(uri)
+      @url = URI.parse(uri)
     end
     
-    def access_token=(token)
-      raise ArgumentError, "Token needs to be an OAuth::AccessToken object" unless token.is_a?(OAuth::AccessToken)
-      @oauth = true
-      @access_token = token
+    # A hash representation of the Resource
+    def to_hash
+      {@name.to_sym => { :via => via,
+                         :with => with,
+                         :requires => requires,
+                         :follows => follows?,
+                         :authenticates => authenticates?,
+                         :url => url,
+                         :headers => headers}}
+    end
+    
+    # Take parameters, default params, and credentials and build a Request object for this Resource
+    def build!(params={}, defaults=nil, credentials=nil)
+      uri = @url
+      parameters = setup_parameters(params, defaults)
+      request_opts = setup_options(parameters, credentials)
+      uri.query = request_opts[:query].to_params if request_opts[:query]
+      Weary::Request.new(uri.normalize.to_s, @via, request_opts)
+    end
+    
+    # Setup the parameters to make the Request with
+    def setup_parameters(params={}, defaults=nil)
+      params = defaults ? defaults.merge(params) : params
+      find_missing_requirements(params)
+      remove_unnecessary_params(params)
     end
     
-    def follows_redirects?
-      if @follows
-        true
+    # Search the given parameters to see if they are missing any required params
+    def find_missing_requirements(params)
+      if (@requires && !@requires.empty?)
+        missing_requirements = @requires - params.keys
+        raise ArgumentError, "This resource is missing required parameters: '#{missing_requirements.inspect}'" unless missing_requirements.empty?
+      end
+    end
+    
+    # Remove params that have not been specified with #with
+    def remove_unnecessary_params(params)
+      params.delete_if {|k,v| !@with.include?(k) } if (@with && !@with.empty?)
+    end
+    
+    # Setup the options to be passed into the Request
+    def setup_options(params={}, credentials=nil)
+      options = {}
+      prepare_request_body(params, options)
+      setup_authentication(options, credentials)
+      options[:no_follow] = true if !follows?
+      options[:headers] = @headers if !@headers.blank?
+      options
+    end
+    
+    # Prepare the Request query or body depending on the HTTP method
+    def prepare_request_body(params, options={})
+      if (@via == :post || @via == :put)
+          options[:body] = params unless params.blank?
       else
-        false
+          options[:query] = params unless params.blank?
       end
+      options
     end
-
-    def to_hash
-      {@name.to_sym => { :via => @via,
-                         :with => @with,
-                         :requires => @requires,
-                         :follows => follows_redirects?,
-                         :authenticates => authenticates?,
-                         :format => @format,
-                         :url => @url,
-                         :domain => @domain,
-                         :headers => @headers,
-                         :oauth => oauth?,
-                         :access_token => @access_token}}
+    
+    # Prepare authentication credentials for the Request
+    def setup_authentication(options, credentials=nil)
+      if authenticates?
+        raise ArgumentError, "This resource requires authentication and no credentials were given." if credentials.blank?
+        if credentials.is_a?(OAuth::AccessToken)
+          options[:oauth] = credentials
+        else
+          options[:basic_auth] = credentials
+        end
+      end
+      options
     end
     
   end

data/lib/weary/response.rb

@@ -75,17 +75,6 @@ module Weary
       parse[key]
     end
     
-    # Search the body with a CSS/XPath selector with Nokogiri.
-    # If the document is not XMLish, fall back to #parse and ditch the selector.
-    def search(selector)
-      if @format == (:xml || :html)
-        doc = Nokogiri.parse(@body)
-        doc.search(selector)
-      else
-        parse
-      end
-    end
-    
     private
       def handle_errors
         case @code

data/spec/spec_helper.rb

@@ -1,7 +1,8 @@
+$LOAD_PATH.unshift File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+
 require 'rubygems'
-gem 'rspec'
 require 'spec'
-require File.join(File.dirname(__FILE__), '..', 'lib', 'weary')
+require 'weary'
 
 def get_fixture(filename)
   open(File.join(File.dirname(__FILE__), 'fixtures', "#{filename.to_s}")).read

data/spec/weary/base_spec.rb

@@ -0,0 +1,321 @@
+require File.join(File.dirname(__FILE__), '..', 'spec_helper')
+
+describe Weary::Base do
+  describe 'Class' do
+    
+    describe 'Resource Defaults' do
+      before do
+        @headers = {"User-Agent" => Weary::UserAgents["Safari 4.0.2 - Mac"]}
+      end
+      
+      it 'sets default headers' do
+        test = Class.new(Weary::Base)
+        test.headers @headers
+        test.instance_variable_get(:@headers).should == @headers
+      end
+      
+      it "sets a domain to be used in default url's" do
+        test = Class.new(Weary::Base)
+        test.domain 'http://github.com'
+        test.instance_variable_get(:@domain).should == 'http://github.com/'
+      end
+      
+      it 'panics when a domain that is not a url is given' do
+        test = Class.new(Weary::Base)
+        lambda { test.domain 'foobar' }.should raise_error
+      end
+      
+      it "sets a format to use in default url's" do
+        test = Class.new(Weary::Base)
+        test.format(:json)
+        test.instance_variable_get(:@format).should == :json
+      end
+    end
+    
+    describe 'Resource Preparation' do
+      before do
+        @headers = {"User-Agent" => Weary::UserAgents["Safari 4.0.2 - Mac"]}
+        prepTest = Class.new(Weary::Base)
+        prepTest.headers @headers
+        prepTest.domain 'http://foobar.com'
+        prepTest.format :xml
+        @t = prepTest.prepare_resource("test",:get)
+      end
+      
+      it 'prepares a Resource' do
+        @t.class.should == Weary::Resource
+      end
+      
+      it 'has a name' do
+        @t.name.should == "test"
+      end
+      
+      it 'has an http method' do
+        @t.via.should == :get
+      end
+      
+      it 'has headers' do
+        @t.headers.should == @headers
+      end
+      
+      it 'builds a default url if a domain is provided' do
+        @t.url.normalize.to_s.should == 'http://foobar.com/test.xml'
+      end
+      
+      it 'builds a default url with a json extension if no format is explicitly named' do
+        t = Class.new(Weary::Base)
+        t.domain 'http://foobar.com'
+        p = t.prepare_resource("test",:get)
+        p.url.normalize.to_s.should == 'http://foobar.com/test.json'
+      end
+      
+      it 'ignores the url if no domain is provided' do
+        t = Class.new(Weary::Base).prepare_resource("test",:get)
+        t.url.should == nil        
+      end
+            
+      it 'ignores headers if no headers are defined' do
+        t = Class.new(Weary::Base).prepare_resource("test",:get)
+        t.headers.should == nil
+      end
+    end
+    
+    describe 'Resource Storage' do
+      before do
+        @headers = {"User-Agent" => Weary::UserAgents["Safari 4.0.2 - Mac"]}
+        @restest = Class.new(Weary::Base)
+        @restest.headers @headers
+        @restest.domain 'http://foobar.com'
+        @r = @restest.prepare_resource("test",:get)
+      end
+      
+      it 'has a store for resources' do
+        @restest.class_variable_defined?(:@@resources).should == true
+      end
+      
+      it 'stores the resource for future use' do
+        @restest.store_resource(@r).should == @r
+        @restest.resources.include?(:test).should == true
+      end      
+    end
+    
+    describe 'Resource Construction' do
+      before do
+        @contest = Class.new(Weary::Base)
+        @contest.domain 'http://foobar.com'
+      end
+      
+      it 'prepares a resource to be used' do
+        r = @contest.build_resource "test", :post
+        r.name.should == "test"
+        r.via.should == :post
+      end
+      
+      it 'passes the resource into a block for further refinement' do
+        r = @contest.build_resource("test", :post, Proc.new {|res| res.via = :put })
+        r.name.should == "test"
+        r.via.should == :put
+      end
+      
+      it 'stores the resource' do
+        r = @contest.build_resource("test 2", :get)
+        @contest.resources.include?(:test_2).should == true
+      end
+      
+      it 'builds the method for the resource' do
+        r = @contest.build_resource("test 3", :get)
+        @contest.public_method_defined?(:test_3).should == true
+      end
+    end
+    
+    describe 'Resource Declaration' do
+      before do
+        @dectest = Class.new(Weary::Base)
+        @dectest.domain 'http://foobar.com'
+      end
+      
+      it 'gets a resource' do
+        r = @dectest.get "get test"
+        r.via.should == :get
+        r.name.should == "get_test"
+      end
+      
+      it 'posts a resource' do
+        r = @dectest.post "post test"
+        r.via.should == :post
+        r.name.should == "post_test"
+      end
+      
+      it 'puts a resource' do
+        r = @dectest.put "put test"
+        r.via.should == :put
+        r.name.should == "put_test"
+      end
+      
+      it 'deletes a resource' do
+        r = @dectest.delete "del test"
+        r.via.should == :delete
+        r.name.should == "del_test"
+      end
+      
+      it 'declares a resource' do
+        r = @dectest.declare "generic test"
+        r.via.should == :get
+        r.name.should == "generic_test"
+      end
+      
+      it 'stores the resource' do
+        @dectest.get "storage test"
+        @dectest.resources.include?(:storage_test).should == true
+      end
+    end
+    
+    describe 'Method Building' do
+      before do
+        @methtest = Class.new(Weary::Base)
+        @methtest.domain 'http://foobar.com'
+        
+        r = @methtest.prepare_resource("method_test",:get)
+        @methtest.build_method(r)
+        
+        a = @methtest.prepare_resource("authentication_test",:post)
+        a.authenticates = true
+        @methtest.build_method(a)
+        
+        d = @methtest.prepare_resource("params_test",:post)
+        d.requires = :id
+        d.with = [:message, :user]
+        @methtest.build_method(d)
+      end
+      
+      it 'builds a method with the name of the resource' do
+        n = @methtest.new
+        n.respond_to?(:method_test).should == true
+      end
+      
+      it 'forms a Request according to the guidelines of the Resource' do
+        n = @methtest.new
+        n.method_test.class.should == Weary::Request
+      end
+      
+      it 'passes in authentication credentials if defined' do
+        n = @methtest.new
+        cred = {:username => 'mwunsch', :password => 'secret'}
+        lambda { n.authentication_test }.should raise_error
+        n.credentials cred[:username], cred[:password]
+        n.authentication_test.options[:basic_auth].should == cred
+      end
+      
+      it 'passes in default parameters if defined' do
+        n = @methtest.new
+        defaults = {:id => 1234, :message => "Hello world"}
+        lambda { n.params_test }.should raise_error
+        n.defaults = defaults
+        n.params_test.options[:body].should == defaults
+      end
+      
+      it 'accepts parameters when given' do
+        n = @methtest.new
+        req = n.params_test :id => 1234, :message => "Hello world", :foo => "Bar"
+        req.options[:body].should == {:id => 1234, :message => "Hello world"}
+        req.options[:body].has_key?(:foo).should == false
+      end
+      
+      
+    end
+    
+  end
+  
+  describe 'Object' do
+    before do
+      @klass = Class.new(Weary::Base)
+      @klass.domain 'http://foobar.com'
+      @klass.format :xml
+      @klass.headers({"User-Agent" => Weary::UserAgents["Safari 4.0.2 - Mac"]})
+      @klass.get "thing" do |r|
+        r.requires = :id
+        r.with = [:message, :user]
+      end
+      @klass.post "important" do |r|
+        r.requires = :id
+        r.authenticates = true
+      end
+    end
+    
+    it 'has methods defined by the class' do
+      obj = @klass.new
+      obj.respond_to?(:thing).should == true
+      obj.respond_to?(:important).should == true
+    end
+    
+    it 'can set authentication credentials' do
+      obj = @klass.new
+      
+      obj.credentials "username", "password"
+      obj.instance_variable_get(:@credentials).should == {:username => "username", :password => "password"}
+      obj.important(:id => 1234).options[:basic_auth].should == obj.instance_variable_get(:@credentials)
+    end
+    
+    it 'credentials can be an OAuth access token' do
+      oauth_consumer = OAuth::Consumer.new("consumer_token","consumer_secret",{:site => 'http://foo.bar'})
+      oauth_token = OAuth::AccessToken.new(oauth_consumer, "token", "secret")
+      obj = @klass.new
+      
+      obj.credentials oauth_token
+      obj.instance_variable_get(:@credentials).class.should == OAuth::AccessToken
+      obj.important(:id => 1234).options.has_key?(:oauth).should == true
+      obj.important(:id => 1234).options.has_key?(:basic_auth).should == false
+    end
+    
+    it 'can set defaults to pass into requests' do
+      obj = @klass.new
+      
+      obj.defaults = {:user => "mwunsch", :message => "hello world"}
+      obj.defaults.should == {:user => "mwunsch", :message => "hello world"}
+      obj.thing(:id => 1234).options[:query].should == {:user => "mwunsch", :message => "hello world", :id => 1234}
+    end
+    
+    it 'has a list of resources' do
+      obj = @klass.new
+      
+      obj.resources == @klass.resources
+    end
+    
+    it 'should keep its resources separate' do
+      obj = @klass.new
+      
+      obj.resources[:foo] = 'bar'
+      obj.resources.has_key?(:foo).should == true
+      @klass.resources.has_key?(:foo).should == false
+      obj.resources.delete(:foo)
+    end
+    
+    it 'is able to rebuild its request method, like a singleton' do
+      obj1 = @klass.new
+      require 'pp'
+      
+      obj1.resources[:thing].follows = false
+      obj1.rebuild_method(obj1.resources[:thing])
+      
+      obj1.thing(:id => 1234).options[:no_follow].should == true
+      @klass.new.thing(:id => 1234).options[:no_follow].should == nil
+    end
+    
+    it 'can modify a resource without modifying the resources of its class' do
+      obj = @klass.new
+      
+      obj.modify_resource(:thing) {|r| r.url = "http://bar.foo" }
+      obj.resources[:thing].url.normalize.to_s.should == "http://bar.foo/"
+      obj.class.resources[:thing].url.normalize.to_s.should_not == "http://bar.foo/"
+    end
+    
+    it 'modifying a resource rebuilds the method' do
+      obj = @klass.new
+      
+      obj.credentials "username", "password"
+      obj.modify_resource(:important) {|r| r.follows = false }
+      obj.important(:id => 1234).options[:no_follow].should == true
+    end
+    
+  end
+end