mwunsch-weary 0.1.2 → 0.2.0

data/README.md

@@ -9,6 +9,73 @@ The things it do:
 + Quickly build an interface to your favorite REST API.
 + Parse XML and JSON with the [Crack](http://github.com/jnunemaker/crack) library.
 
+Browse the documentation here: [http://rdoc.info/projects/mwunsch/weary](http://rdoc.info/projects/mwunsch/weary)
+
 ## Requirements
 
-+ Crack
++ Crack >= 0.1.2
++ Nokogiri >= 1.3.1 (if you want to use the #search method)
+
+## Installation
+
+You do have Rubygems right?
+
+	sudo gem install weary
+
+## How it works
+
+Create a class and `extend Weary` to give it methods to craft a resource request:
+
+	class Foo
+		extend Weary
+		
+		declare "foo" do |resource|
+			resource.url = "http://path/to/foo"
+		end
+	end
+	
+If you instantiate this class, you'll get an instance method named `foo` that crafts a GET request to "http://path/to/foo"
+
+Besides the name of the resource, you can also give `declare_resource` a block like:
+
+	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.follows = false			# if this is set to false, the formed request will not follow redirects.
+	end
+					
+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.
+
+### 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
+		
+		on_domain "http://foo.bar/"
+		construct_url "<domain><resource>.<format>"
+		as_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.
+	

data/Rakefile

@@ -22,6 +22,7 @@ begin
     gemspec.homepage = "http://github.com/mwunsch/weary"
     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')
   end
 rescue LoadError
   puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"  

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.2.0

data/examples/repo.rb

@@ -9,11 +9,13 @@ class Repository
   on_domain "http://github.com/api/v2/"
   as_format :yaml
   
-  get "show",
-      :url => "<domain><format>/repos/show/#{@gh_user}/#{@gh_repo}"
-      
-  get "network",
-      :url => "<domain><format>/repos/show/#{@gh_user}/#{@gh_repo}/network"
+  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"
+  end
       
 end
 

data/examples/status.rb

@@ -5,9 +5,10 @@ class Status
   
   on_domain "http://twitter.com/statuses/"
   
-  get "user_timeline",
-      :requires => [:id],
-      :with => [:user_id, :screen_name, :since_id, :max_id, :count, :page]
+  get "user_timeline" do |resource|
+    resource.requires = [:id]
+    resource.with = [:user_id, :screen_name, :since_id, :max_id, :count, :page]
+  end
   
 end
 

data/lib/weary/exceptions.rb

@@ -1,3 +1,15 @@
 module Weary
-  class HTTPError < StandardError; end 
+  class HTTPError < StandardError; end
+  
+  class RedirectionError < HTTPError; end
+  class ClientError      < HTTPError; end
+  class ServerError      < HTTPError; end
+  
+  class BadRequest          < ClientError; end #400
+  class Unauthorized        < ClientError; end #401
+  class Forbidden           < ClientError; end #403
+  class NotFound            < ClientError; end #404
+  class MethodNotAllowed    < ClientError; end #405
+  class ResourceConflict    < ClientError; end #409
+  class UnprocessableEntity < ClientError; end #422  
 end

data/lib/weary/request.rb

@@ -34,7 +34,7 @@ module Weary
     def method
       @http_verb
     end
-  
+    
     def perform
       req = http.request(request)
       response = Response.new(req, @http_verb)

data/lib/weary/resource.rb

@@ -1,35 +1,30 @@
 module Weary
   class Resource
-    attr_reader :name, :with, :requires, :via, :format, :url
-    
-    def initialize(name,options={})
-      @domain = options[:domain]
-      self.name = name
-      self.via = options[:via]
-      self.with = options[:with]
-      self.requires = options[:requires]
-      self.format = options[:format]
-      self.url = options[:url]
-      @authenticates = (options[:authenticates] != false)
-      @follows = (options[:no_follow] == false)
-    end
-    
-    def name=(resource)
-      @name = resource.to_s
-    end
-    
-    def via=(verb)
-      @via = verb
-    end
-    
+    attr_reader :name
+    attr_accessor :domain, :with, :requires, :via, :format, :url, :authenticates, :follows
+    
+    def initialize(name)
+      @name = name
+      self.via = :get
+      self.authenticates = false
+      self.follows = true
+      self.with = []
+      self.requires
+    end
+        
     def with=(params)
-      if params.empty?
-        @with = nil
+      unless @requires.nil?
+        @with = params.collect {|x| x.to_sym} | @requires
       else
-        @with = params.collect {|x| x.to_sym }
+        @with = params.collect {|x| x.to_sym}
       end
     end
     
+    def requires=(params)
+      @with = @with | params.collect {|x| x.to_sym}
+      @requires = params.collect {|x| x.to_sym}
+    end
+    
     def url=(pattern)
       if pattern.index("<domain>")
         raise StandardError, "Domain flag found but the domain is not defined" if @domain.nil?
@@ -40,34 +35,23 @@ module Weary
       @url = pattern
     end
     
-    def requires=(params)
-      if (params.nil? || params.empty?)
-        @requires = nil
-      else
-        @requires = params
-      end
-    end
-    
-    def format=(type)
-      @format = type
-    end
-    
     def authenticates?
-      @authenticates
+      @authenticates == true
     end
     
     def follows_redirects?
-      @follows
+      @follows == true
     end
-    
+
     def to_hash
-      {@name.to_sym => {:via => @via,
-                       :with => @with,
-                       :requires => @requires,
-                       :no_follow => !follows_redirects?,
-                       :authenticates => authenticates?,
-                       :format => @format,
-                       :url => @url}}
+      {@name.to_sym => { :via => @via,
+                         :with => @with,
+                         :requires => @requires,
+                         :follows => follows_redirects?,
+                         :authenticates => authenticates?,
+                         :format => @format,
+                         :url => @url,
+                         :domain => @domain}}
     end
     
   end

data/lib/weary/response.rb

@@ -20,7 +20,7 @@ module Weary
     def redirected?
       @raw.is_a?(Net::HTTPRedirection)
     end
-
+    
     def success?
       (200..299).include?(@code)
     end
@@ -54,6 +54,7 @@ module Weary
       end
     end
     
+    # Parse the body with Crack parsers (if XML/HTML) or Yaml parser
     def parse
       raise StandardError, "The Response has no body. #{@method.to_s.upcase} request sent." unless @body
       handle_errors
@@ -69,6 +70,7 @@ module Weary
       end
     end
     
+    # Search the body with a CSS/XPath selector with Nokogiri
     def search(selector)
       raise ArgumentError, "Search can only be used with an XML or HTML document." unless @format != (:xml || :html)
       doc = Nokogiri.parse(@body)
@@ -79,27 +81,27 @@ module Weary
       def handle_errors
         case @code
           when 301,302
-            raise HTTPError, "#{@message} to #{@raw['location']}"
+            raise RedirectionError, "#{@message} to #{@raw['location']}"
           when 200...400
             return
           when 400
-            raise HTTPError, "Failed with #{@code}: #{@message}"
+            raise BadRequest, "Failed with #{@code}: #{@message}"
           when 401
-            raise HTTPError, "Failed with #{@code}: #{@message}"
+            raise Unauthorized, "Failed with #{@code}: #{@message}"
           when 403
-            raise HTTPError, "Failed with #{@code}: #{@message}"
+            raise Forbidden, "Failed with #{@code}: #{@message}"
           when 404
-            raise HTTPError, "Failed with #{@code}: #{@message}"
+            raise NotFound, "Failed with #{@code}: #{@message}"
           when 405
-            raise HTTPError, "Failed with #{@code}: #{@message}"
+            raise MethodNotAllowed, "Failed with #{@code}: #{@message}"
           when 409
-            raise HTTPError, "Failed with #{@code}: #{@message}"
+            raise ResourceConflict, "Failed with #{@code}: #{@message}"
           when 422
-            raise HTTPError, "Failed with #{@code}: #{@message}"
+            raise UnprocessableEntity, "Failed with #{@code}: #{@message}"
           when 401...500
-            raise HTTPError, "Failed with #{@code}: #{@message}"
+            raise ClientError, "Failed with #{@code}: #{@message}"
           when 500...600
-            raise HTTPError, "Failed with #{@code}: #{@message}"
+            raise ServerError, "Failed with #{@code}: #{@message}"
           else
             raise HTTPError, "Unknown response code: #{@code}"
         end

data/lib/weary.rb

@@ -24,8 +24,9 @@ module Weary
               :put    => [:put, :PUT, /\bput\b/i],
               :delete => [:delete, :del, :DELETE, :DEL, /\bdelete\b/i],
               :head   => [:head, :HEAD, /\bhead\b/i] }
+  UserAgents = { } # will be a collection of user agent strings            
   
-  # Weary::Query quickly performs a :get request on a URL and parses the request
+  # Weary::Query quickly performs a GET request on a URL and parses the request.
   def self.Query(url)
     req = Weary::Request.new(url, :get).perform
     req.parse
@@ -33,16 +34,29 @@ module Weary
   
   attr_reader :domain, :resources
   
+  # Sets the domain the resource is on. 
+  #
+  # If the domain is not provided and you use a URL pattern that asks for it, 
+  # an exception will be raised.
   def on_domain(domain)
     parse_domain = URI.extract(domain)
     raise ArgumentError, 'The domain must be a URL.' if parse_domain.empty?
     @domain = parse_domain[0]
+    return @domain
   end
-
+  
+  # Sets a default format to make your Requests in.
+  # Defaults to JSON.
   def as_format(format)
     @default_format = format.to_sym
   end
   
+  # 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 construct_url(pattern)
     @url_pattern = pattern.to_s
   end
@@ -53,63 +67,65 @@ module Weary
     return nil
   end
 
-  def declare_resource(resource, options={})
-    # available options:
-    # :via = get, post, etc. defaults to get
-    # :with = paramaters passed to body or query
-    # :requires = members of :with that must be in the action
-    # :authenticates = boolean; uses basic_authentication
-    # :url = a pattern
-    # :format = to set format, defaults to :json
-    # :no_follow = boolean; defaults to false. do not follow redirects
-      
-    
-    @resources ||= []
-        
-    r = Weary::Resource.new(resource, set_defaults(options))
-    declaration = r.to_hash
-    
-    @resources << declaration
-    
-    craft_methods(r)
-    return declaration
+  # 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.
+  # [<tt>requires</tt>] 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>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>)
+  def declare(name)
+    resource = prepare_resource(name,:get)
+    yield resource if block_given?
+    form_resource(resource)
+    return resource
   end
+  alias get declare
   
-  def get(resource,options={})
-    options[:via] = :get
-    declare_resource(resource,options)
+  def post(name)
+    resource = prepare_resource(name,:post)
+    yield resource if block_given?
+    form_resource(resource)
+    return resource
   end
   
-  def post(resource,options={})
-    options[:via] = :post
-    declare_resource(resource,options)
+  def put(name)
+    resource = prepare_resource(name,:put)
+    yield resource if block_given?
+    form_resource(resource)
+    return resource
   end
   
-  def put(resource,options={})
-    options[:via] = :put
-    declare_resource(resource,options)
-  end
-  
-  def delete(resource,options={})
-    options[:via] = :delete
-    declare_resource(resource,options)
+  def delete(name)
+    resource = prepare_resource(name,:delete)
+    yield resource if block_given?
+    form_resource(resource)
+    return resource
   end
 
   private
-    def set_defaults(hash)
-      hash[:domain] = @domain
-      hash[:via] ||= :get
-      hash[:with] ||= []
-      hash[:with] = hash[:with] | hash[:requires] unless hash[:requires].nil?
-      hash[:format] ||= (@default_format || :json)
-      hash[:authenticates] ||= false
-      hash[:authenticates] = false if hash[:authenticates] == "false"
-      if hash[:authenticates]
+  
+    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>")
+      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
-      hash[:url] ||= (@url_pattern || "<domain><resource>.<format>")
-      hash[:no_follow] ||= false
-      return hash
+      @resources ||= []      
+      @resources << resource.to_hash 
+      craft_methods(resource)
+      return resource.to_hash
     end
     
     def craft_methods(resource)
@@ -118,12 +134,12 @@ module Weary
           options ||= {}
           url = "#{resource.url}"
       }
-      unless resource.requires.nil?
+      unless resource.requires.empty?
         resource.requires.each do |required|
           code << %Q{raise ArgumentError, "This resource requires parameter: ':#{required}'" unless params.has_key?(:#{required}) \n}
         end
       end
-      unless resource.with.nil?
+      unless resource.with.empty?
         with = %Q{[#{resource.with.collect {|x| ":#{x}"}.join(',')}]}
         code << %Q{unnecessary = params.keys - #{with} \n}
         code << %Q{unnecessary.each { |x| params.delete(x) } \n}

data/weary.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{weary}
-  s.version = "0.1.2"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Mark Wunsch"]
-  s.date = %q{2009-06-09}
+  s.date = %q{2009-06-11}
   s.description = %q{The Weary need REST: a tiny DSL that makes the consumption of RESTful web services simple.}
   s.email = %q{mark@markwunsch.com}
   s.extra_rdoc_files = [
@@ -30,12 +30,11 @@ Gem::Specification.new do |s|
      "spec/weary_spec.rb",
      "weary.gemspec"
   ]
-  s.has_rdoc = true
   s.homepage = %q{http://github.com/mwunsch/weary}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
   s.rubyforge_project = %q{weary}
-  s.rubygems_version = %q{1.3.1}
+  s.rubygems_version = %q{1.3.4}
   s.summary = %q{A little DSL for consuming RESTful web services}
   s.test_files = [
     "spec/weary/request_spec.rb",
@@ -46,11 +45,14 @@ Gem::Specification.new do |s|
 
   if s.respond_to? :specification_version then
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 2
+    s.specification_version = 3
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<crack>, [">= 0.1.2"])
     else
+      s.add_dependency(%q<crack>, [">= 0.1.2"])
     end
   else
+    s.add_dependency(%q<crack>, [">= 0.1.2"])
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: mwunsch-weary
 version: !ruby/object:Gem::Version 
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors: 
 - Mark Wunsch
@@ -9,10 +9,19 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-06-09 00:00:00 -07:00
+date: 2009-06-11 00:00:00 -07:00
 default_executable: 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: crack
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.1.2
+    version: 
 description: "The Weary need REST: a tiny DSL that makes the consumption of RESTful web services simple."
 email: mark@markwunsch.com
 executables: []
@@ -38,7 +47,7 @@ files:
 - spec/weary/request_spec.rb
 - spec/weary_spec.rb
 - weary.gemspec
-has_rdoc: true
+has_rdoc: false
 homepage: http://github.com/mwunsch/weary
 post_install_message: 
 rdoc_options: 
@@ -62,7 +71,7 @@ requirements: []
 rubyforge_project: weary
 rubygems_version: 1.2.0
 signing_key: 
-specification_version: 2
+specification_version: 3
 summary: A little DSL for consuming RESTful web services
 test_files: 
 - spec/weary/request_spec.rb