weary 0.5.1 → 0.6.0

data/README.md

@@ -17,21 +17,19 @@ Peruse the [Wiki](http://wiki.github.com/mwunsch/weary) to discover libraries bu
 ## Requirements
 
 + [Crack](http://github.com/jnunemaker/crack) >= 0.1.2
-+ [Nokogiri](http://github.com/tenderlove/nokogiri) >= 1.3.1 (if you want to use the #search method)
-+ [OAuth](http://github.com/mojodna/oauth) >= 0.3.5 (if you want to use OAuth)
++ [OAuth](http://github.com/mojodna/oauth) >= 0.3.5
 + [RSpec](http://rspec.info/) (for running the tests)
 
 ## Installation
 
-You do have Rubygems right?
+You do have Rubygems right? You do use [Gemcutter](http://gemcutter.org/), right?
 
-	sudo gem install weary
+	gem install weary
 	
 ## Quick Start
 	
 	# http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-users%C2%A0show
-	class TwitterUser
-		extend Weary
+	class TwitterUser < Weary::Base
 		
 		domain "http://twitter.com/users/"
 		
@@ -41,7 +39,7 @@ You do have Rubygems right?
 	end
 	
 	user = TwitterUser.new
-	me = user.show(:id => "markwunsch")
+	me = user.show(:id => "markwunsch").perform
 	puts me["name"]
 	
 Hey, that's me!	
@@ -49,10 +47,9 @@ Hey, that's me!
 
 ## How it works
 
-Create a class and `extend Weary` to give it methods to craft a resource request:
+Create a class that inherits from `Weary::Base` to give it methods to craft a resource request:
 
-	class Foo
-		extend Weary
+	class Foo < Weary::Base
 		
 		declare "foo" do |resource|
 			resource.url = "http://path/to/foo"
@@ -66,12 +63,9 @@ Besides the name of the resource, you can also give `declare_resource` a block l
 	declare "foo" do |r|
 		r.url = "path/to/foo"
 		r.via = :post 							# defaults to :get
-		r.format = :xml 						# defaults to :json
 		r.requires = [:id, :bar] 				# an array of params that the resource requires to be in the query/body
 		r.with = [:blah]						# an array of params that you can optionally send to the resource
-		r.authenticates = false					# does the method require basic authentication? defaults to false
-		r.oauth = false							# does this resource use OAuth to authorize you? it's boolean
-		r.access_token = nil					# if you're using OAuth, you should provide the user's access token.
+		r.authenticates = false					# does the method require authentication? defaults to false
 		r.follows = false						# if this is set to false, the formed request will not follow redirects.
 		r.headers = {'Accept' => 'text/html'}	# send custom headers. defaults to nil.
 	end
@@ -81,64 +75,65 @@ So this would form a method:
 	x = Foo.new
 	x.foo(:id => "mwunsch", :bar => 123)
 	
-That method would return a Weary::Response object that you could then parse or examine.
+That method would return a `Weary::Request` object. Use the `perform` method and get a `Weary::Response` that you could parse and/or examine.
 
 ### Parsing the Body
 
 Once you make your request with the fancy method that Weary created for you, you can do stuff with what it returns...which could be a good reason you're using Weary in the first place. Let's look at the above example:
 
 	x = Foo.new
-	y = x.foo(:id => "mwunsch", :bar => 123).parse
+	y = x.foo(:id => "mwunsch", :bar => 123).perform.parse
 	y["foos"]["user"]
 	
-Weary parses with Crack. If you have some XML or HTML and want to search it with XPath or CSS selectors, you can use Nokogiri magic:
+Weary parses with Crack, but you're not beholden to it. You can get the raw Request body to have your way with:
 
 	x = Foo.new
-	y = x.foo(:id => "mwunsch", :bar => 123)
-	y.search("foos > user")
+	y = x.foo(:id => "mwunsch", :bar => 123).perform
+	Nokogiri.parse(y.body)
 	
-If you try to #search a non-XMLesque document, Weary will just throw the selector away and use the #parse method.
+*note: Weary used to have Nokogiri built in, using the `#search` method, but that was dropped.*	
 
 ### Shortcuts
 
 Of course, you don't always have to use `declare`; that is a little too ambiguous. You can also use `get`, `post`, `delete`, etc. Those do the obvious.
 
-The `#requires` and `#with` methods can either be arrays of symbols, or a comma delimited list of strings.
-
 ### Forming URLs
 
 There are many ways to form URLs in Weary. You can define URLs for the entire class by typing:
 
-	class Foo
-		extend Weary
+	class Foo < Weary::Base
 		
 		domain "http://foo.bar/"
-		url "<domain><resource>.<format>"
 		format :xml
 		
 		get "show_users"
 	end
 	
-The string `<domain><resource>.<format>` helps define a simple pattern for creating URLs. These will be filled in by your resource declaration. The above `get` declaration creates a url that looks like: *http://foo.bar/show_users.xml*
-	
-If you use the `<domain>` flag but don't define a domain, an exception will be raised.
+If you don't supply a url when declaring the Resource, Weary will look to see if you've defined a domain, and will make a url for you. The above `get` declaration creates a url that looks like: *http://foo.bar/show_users.xml*
 	
 ### Weary DSL
 
 You can create some defaults for all of our resources easily:
 
-	class Foo
-		extend Weary
+	class Foo < Weary::Base
+	
+		def initialize(username,password)
+			self.credentials username,password	#basic authentication
+			self.defaults = {:user => username}	#parameters that will be passed in every request	 
+		end
 
 		domain "http://foo.bar/"
-		url "<domain><resource>.<format>"
 		format :xml
-		headers {'Accept' => 'text/html'}							# set headers
-		authenticates "basic_username","basic_password"				# basic authentication
-		with [:login, :token]										# params that should be sent with every request
-		oauth OAuth::AccessToken.new(consumer, "token", "secret")	# an access token for OAuth
+		headers {'Accept' => 'text/html'}	# set headers
 		
-		post "update"	# uses the defaults defined above!			
+		post "update" {|r| r.authenticates = true}	# uses the defaults defined above!			
 	end
 	
+Then you can do something like this:
+
+	f = Foo.new('me','secretz')
+	f.update
+	
+Which will create a POST Request for *http://foo.bar/update.xml* that will authenticate you, using basic authentication, with the username/password of "me"/"secrets" and will send the parameter `{:user => "me"}`. Easy.
+	
 There's more to discover in the Wiki.	

data/Rakefile

@@ -23,6 +23,7 @@ begin
     gemspec.description = "The Weary need REST: a tiny DSL that makes the consumption of RESTful web services simple."
     gemspec.authors = "Mark Wunsch"
     gemspec.add_dependency('crack', '>= 0.1.2')
+    gemspec.add_dependency('oauth', '>= 0.3.5')
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError

data/VERSION

@@ -1 +1 @@
-0.5.1
+0.6.0

data/examples/repo.rb

@@ -1,23 +1,20 @@
-require File.join(File.dirname(__FILE__), '..', 'lib', 'weary')
+$LOAD_PATH.unshift File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'rubygems'
+require 'weary'
 
-class Repository
-  extend Weary
+class Repository < Weary::Base
   
-  @gh_user = "mwunsch"
-  @gh_repo = "weary"
-  
-  domain "http://github.com/api/v2/"
-  format :yaml
+  def initialize(user, repo)
+    self.modify_resource(:show) do |r|
+      r.url = "http://github.com/api/v2/yaml/repos/show/#{user}/#{repo}"
+    end
+  end  
   
   get "show" do |r|
-    r.url = "<domain><format>/repos/show/#{@gh_user}/#{@gh_repo}"
-  end
-  
-  get "network" do |r|
-    r.url = "<domain><format>/repos/show/#{@gh_user}/#{@gh_repo}/network"
+    r.url = "http://github.com/api/v2/yaml/repos/show/__gh_user__/__gh_repo__"
   end
       
 end
 
-weary = Repository.new
-puts weary.show.body
+weary = Repository.new('mwunsch','weary')
+puts weary.show.perform.body

data/examples/status.rb

@@ -1,7 +1,8 @@
-require File.join(File.dirname(__FILE__), '..', 'lib', 'weary')
+$LOAD_PATH.unshift File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'rubygems'
+require 'weary'
 
-class Status
-  extend Weary
+class Status < Weary::Base
   
   domain "http://twitter.com/statuses/"
   
@@ -13,5 +14,5 @@ class Status
 end
 
 toots = Status.new
-recent_toot = toots.user_timeline(:id => "markwunsch")[0]
+recent_toot = toots.user_timeline(:id => "markwunsch").perform[0]
 puts "@" + recent_toot["user"]["screen_name"] + ": " + "\"#{recent_toot['text']}\""

data/lib/weary.rb

@@ -1,24 +1,18 @@
-$:.unshift(File.dirname(__FILE__))
-
 require 'uri'
 require 'net/http'
 require 'net/https'
 
-require 'rubygems'
 require 'crack'
+require 'oauth'
 
-gem 'nokogiri'
-gem 'oauth'
 autoload :Yaml, 'yaml'
-autoload :Nokogiri, 'nokogiri'
-autoload :OAuth, 'oauth'
 
 require 'weary/request'
 require 'weary/response'
 require 'weary/resource'
 require 'weary/exceptions'
 require 'weary/httpverb'
-
+require 'weary/base'
 
 module Weary
   
@@ -27,8 +21,39 @@ module Weary
                    :xml   => [:xml, 'xml', 'text/xml', 'application/xml'],
                    :html  => [:html, 'html', 'text/html'],
                    :yaml  => [:yaml, 'yaml', 'application/x-yaml', 'text/yaml'],
-                   :plain => [:plain, 'plain', 'text/plain'] }
-  UserAgents = { } # will be a collection of user agent strings            
+                   :plain => [:plain, 'plain', 'text/plain'] 
+  }
+  # A collection of User Agent strings that I stole from HURL (http://hurl.it)
+  UserAgents = {
+    "Firefox 1.5.0.12 - Mac" => "Mozilla/5.0 (Macintosh; U; PPC Mac OS X Mach-O; en-US; rv:1.8.0.12) Gecko/20070508 Firefox/1.5.0.12",
+    "Firefox 1.5.0.12 - Windows" => "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.0.12) Gecko/20070508 Firefox/1.5.0.12",
+    "Firefox 2.0.0.12 - Mac" => "Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.12) Gecko/20080201 Firefox/2.0.0.12",
+    "Firefox 2.0.0.12 - Windows" => "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.12) Gecko/20080201 Firefox/2.0.0.12",
+    "Firefox 3.0.4 - Mac" => "Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.5; en-US; rv:1.9.0.4) Gecko/2008102920 Firefox/3.0.4",
+    "Firefox 3.0.4 - Windows" => "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.12) Gecko/2008102920 Firefox/3.0.4",
+    "Firefox 3.5.2 - Mac" => "Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.5; en-US; rv:1.9.1.2) Gecko/20090729 Firefox/3.5.2",
+    "Firefox 3.5.2 - Windows" => "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9.1.2) Gecko/20090729 Firefox/3.5.2",
+    "Internet Explorer 5.2.3 – Mac" => "Mozilla/4.0 (compatible; MSIE 5.23; Mac_PowerPC)",
+    "Internet Explorer 5.5" => "Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 5.1)",
+    "Internet Explorer 6.0" => "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)",
+    "Internet Explorer 7.0" => "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.0)",
+    "Internet Explorer 8.0" => "Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.2; Trident/4.0)",
+    "Lynx 2.8.4rel.1 on Linux" => "Lynx/2.8.4rel.1 libwww-FM/2.14",
+    "MobileSafari 1.1.3 - iPhone" => "Mozilla/5.0 (iPhone; U; CPU like Mac OS X; en) AppleWebKit/420.1 (KHTML, like Gecko) Version/3.0 Mobile/4A93 Safari/419.3",
+    "MobileSafari 1.1.3 - iPod touch" => "Mozilla/5.0 (iPod; U; CPU like Mac OS X; en) AppleWebKit/420.1 (KHTML, like Gecko) Version/3.0 Mobile/4A93 Safari/419.3",
+    "Opera 9.25 - Mac" => "Opera/9.25 (Macintosh; Intel Mac OS X; U; en)",
+    "Opera 9.25 - Windows" => "Opera/9.25 (Windows NT 5.1; U; en)",
+    "Safari 1.2.4 - Mac" => "Mozilla/5.0 (Macintosh; U; PPC Mac OS X; en) AppleWebKit/125.5.7 (KHTML, like Gecko) Safari/125.12",
+    "Safari 1.3.2 - Mac" => "Mozilla/5.0 (Macintosh; U; PPC Mac OS X; en) AppleWebKit/312.8 (KHTML, like Gecko) Safari/312.6",
+    "Safari 2.0.4 - Mac" => "Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en) AppleWebKit/419 (KHTML, like Gecko) Safari/419.3",
+    "Safari 3.0.4 - Mac" => "Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-us) AppleWebKit/523.10.3 (KHTML, like Gecko) Version/3.0.4 Safari/523.10",
+    "Safari 3.1.2 - Mac" => "Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_5_2; en-us) AppleWebKit/525.13 (KHTML, like Gecko) Version/3.1 Safari/525.13",
+    "Safari 3.1.2 - Windows" => "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-us) AppleWebKit/525.13 (KHTML, like Gecko) Version/3.1 Safari/525.13",
+    "Safari 3.2.1 - Mac" => "Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_5_5; en-us) AppleWebKit/525.27.1 (KHTML, like Gecko) Version/3.2.1 Safari/525.27.1",
+    "Safari 3.2.1 - Windows" => "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-us) AppleWebKit/525.27.1 (KHTML, like Gecko) Version/3.2.1 Safari/525.27.1",
+    "Safari 4.0.2 - Mac" => "Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_5_7; en-us) AppleWebKit/530.19.2 (KHTML, like Gecko) Version/4.0.2 Safari/530.19",
+    "Safari 4.0.2 - Windows" => "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/530.19.2 (KHTML, like Gecko) Version/4.0.2 Safari/530.19.1"
+  }
   
   # Weary::Query quickly performs a GET request on a URL and parses the request.
   def self.Query(url)
@@ -36,226 +61,4 @@ module Weary
     req.parse
   end
   
-  attr_reader :resources
-  
-  # Sets the domain the resource is on or use it to retrieve a domain you've already set.
-  # It's a getter and a setter. It's an attribute!
-  #
-  # If the domain is not provided and you use a URL pattern that asks for it, 
-  # an exception will be raised.
-  def domain(dom=nil)
-    raise ArgumentError, 'No domain provided' if (dom.nil? && @domain.nil?)
-    if (!dom.nil?)
-      parse_domain = URI.extract(dom)
-      raise ArgumentError, 'The domain must be a URL.' if parse_domain.empty?
-      @domain = parse_domain[0]
-    end
-    return @domain
-  end
-  alias on_domain domain
-  
-  # Sets a default format to make your Requests in.
-  # Defaults to JSON.
-  def format(format) 
-    @default_format = format
-  end
-  alias as_format format
-  
-  # Construct a URL pattern for your resources to follow.
-  # You can use flags like
-  # * <domain>
-  # * <format>
-  # * <resource>
-  # To aid your construction. Defaults to "<domain><resource>.<format>"
-  def url(pattern)
-    @url_pattern = pattern.to_s
-  end
-  alias construct_url url
-
-  def authenticates(username,password)
-    @username = username
-    @password = password
-    return nil
-  end
-  alias authenticates_with authenticates
-  
-  def with(params)
-    @always_with = params
-  end
-  alias always_with with
-  
-  # Set custom Headers for your Request
-  def headers(headers)
-    @headers = headers
-  end
-  alias set_headers headers
-  
-  # Set the Access Token for OAuth. This must be an OAuth::AccessToken object.
-  # See http://github.com/mojodna/oauth/ to learn how to create Tokens
-  # Setting this will make resources use OAuth and this token by default.
-  def oauth(token)
-    raise ArgumentError, "Token needs to be an OAuth::AccessToken object" unless token.is_a?(OAuth::AccessToken)
-    @oauth = token
-  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>oauth</tt>] Boolean value; does the resource use OAuth?
-  # [<tt>access_token</tt>] Provide the Token for OAuth. Must be an OAuth::AccessToken object.
-  # [<tt>url</tt>] The url of the resource. You can use the same flags as #construct_url
-  # [<tt>format</tt>] The format you would like to request. Defaults to json
-  # [<tt>follows</tt>] Boolean; Does this follow redirects? Defaults to true
-  # [<tt>domain</tt>] Sets the domain you would like this individual resource to be on (if you include the domain flag in <tt>url</tt>)
-  # [<tt>headers</tt>] Set headers for the HTTP Request
-  def declare(name,&block)
-    build_resource(name, :get, block)
-  end
-  alias get declare
-  
-  def post(name,&block)
-    build_resource(name, :post, block)
-  end
-  
-  def put(name,&block)
-    build_resource(name, :put, block)
-  end
-  
-  def delete(name,&block)
-    build_resource(name, :delete, block)
-  end
-  
-  def build_resource(name,verb,block=nil)
-    resource = prepare_resource(name,verb)
-    block.call(resource) unless block.nil?
-    form_resource(resource)
-    return resource
-  end
-  
-  def prepare_resource(name,via)
-    preparation = Weary::Resource.new(name)
-    preparation.via = via
-    preparation.format = (@default_format || :json)
-    preparation.domain = @domain
-    preparation.url = (@url_pattern || "<domain><resource>.<format>")
-    preparation.with = @always_with unless @always_with.nil?
-    preparation.headers = @headers unless (@headers.nil? || @headers.empty?)
-    if !@oauth.nil?
-      preparation.oauth = true
-      preparation.access_token = @oauth
-    end
-    return preparation
-  end
-  
-  def form_resource(resource)
-    if resource.authenticates?
-      raise StandardError, "Can not authenticate unless username and password are defined" unless (@username && @password)
-    end
-    if resource.oauth?
-      if resource.access_token.nil?
-        raise StandardError, "Access Token is not provided" if @oauth.nil?
-        resource.access_token = @oauth
-      end
-    end
-    @resources ||= []
-    @resources << resource.to_hash 
-    craft_methods(resource)
-    return resource.to_hash
-  end
-
-  private
-    
-    def craft_methods(resource)
-      code = %Q{
-        def #{resource.name}(params={})
-          options ||= {}
-          url = "#{resource.url}"
-      }
-      if resource.with.is_a?(Hash)
-        hash_string = ""
-        resource.with.each_pair {|k,v| 
-          if k.is_a?(Symbol)
-            k_string = ":#{k}"
-          else
-            k_string = "'#{k}'"
-          end
-          hash_string << "#{k_string} => '#{v}',"
-        }
-        code << %Q{
-          params = {#{hash_string.chop}}.delete_if {|key,value| value.empty? }.merge(params)
-        }
-      end
-      unless resource.requires.nil?
-        if resource.requires.is_a?(Array)
-          resource.requires.each do |required|
-            code << %Q{  raise ArgumentError, "This resource requires parameter: ':#{required}'" unless params.has_key?(:#{required}) \n}
-          end
-        else
-          resource.requires.each_key do |required|
-            code << %Q{  raise ArgumentError, "This resource requires parameter: ':#{required}'" unless params.has_key?(:#{required}) \n}
-          end
-        end
-      end
-      unless resource.with.empty?
-        if resource.with.is_a?(Array)
-          with = %Q{[#{resource.with.collect {|x| x.is_a?(Symbol) ? ":#{x}" : "'#{x}'" }.join(',')}]}
-        else
-          with = %Q{[#{resource.with.keys.collect {|x| x.is_a?(Symbol) ? ":#{x}" : "'#{x}'"}.join(',')}]}
-        end
-        code << %Q{ 
-          unnecessary = params.keys - #{with} 
-          unnecessary.each { |x| params.delete(x) } 
-        }
-      end
-      if resource.via == (:post || :put)
-        code << %Q{options[:body] = params unless params.empty? \n}
-      else
-        code << %Q{
-          options[:query] = params unless params.empty?
-          url << "?" + options[:query].to_params unless options[:query].nil?
-        }
-      end
-      unless (resource.headers.nil? || resource.headers.empty?)
-        header_hash = ""
-        resource.headers.each_pair {|k,v|
-          header_hash << "'#{k}' => '#{v}',"
-        }
-        code << %Q{ options[:headers] = {#{header_hash.chop}} \n}
-      end
-      if resource.authenticates?
-        code << %Q{options[:basic_auth] = {:username => "#{@username}", :password => "#{@password}"} \n}
-      end
-      if resource.oauth?
-        consumer_options = ""
-        resource.access_token.consumer.options.each_pair {|k,v| 
-          if k.is_a?(Symbol)
-            k_string = ":#{k}"
-          else
-            k_string = "'#{k}'"
-          end
-          if v.is_a?(Symbol)
-            v_string = ":#{v}"
-          else
-            v_string = "'#{v}'"
-          end
-          consumer_options << "#{k_string} => #{v_string},"
-        }
-        code << %Q{ oauth_consumer = OAuth::Consumer.new("#{resource.access_token.consumer.key}","#{resource.access_token.consumer.secret}",#{consumer_options.chop}) \n}
-        code << %Q{ options[:oauth] = OAuth::AccessToken.new(oauth_consumer, "#{resource.access_token.token}", "#{resource.access_token.secret}") \n}
-      end
-      unless resource.follows_redirects?
-        code << %Q{options[:no_follow] = true \n}
-      end
-      code << %Q{
-          Weary::Request.new(url, :#{resource.via}, options).perform
-        end
-      }
-      class_eval code
-      return code
-    end
-
 end