nap 0.1 → 0.2

data/README

@@ -1,4 +1,24 @@
-Nap
----
+= Nap
 
-It be an extremely simple REST library, yo!
+It be an extremely simple REST library, yo!
+
+== Example
+
+  gem 'nap'
+  require 'rest'
+  require 'json'
+  
+  response = REST.get('http://twitter.com/statuses/friends_timeline.json', {},
+    {:username => '_evan', :password => 'buttonscat'}
+  )
+  if response.ok?
+    timeline = JSON.parse(response.body)
+    puts(timeline.map do |item|
+      "#{item['user']['name']}\n\n#{item['text']}"
+    end.join("\n\n--\n\n"))
+  elsif response.forbidden?
+    puts "Are you sure you're `_evan' and your password is the name of your cat?"
+  else
+    puts "Something went wrong (#{response.status_code})"
+    puts response.body
+  end

data/lib/rest.rb

@@ -1,20 +1,67 @@
 require 'uri'
 
+# REST is basically a convenience wrapper around Net::HTTP. It defines a simple and consistant API for doing REST-style
+# HTTP calls.
 module REST
-  def self.get(uri, headers={})
-    REST::Request.perform(:get, URI.parse(uri), nil, headers)
+  # Performs a HEAD on a resource. See REST::Request.new for a complete discussion of options.
+  #
+  #   response = REST.get('http://example.com/pigeons/12',
+  #     {'Accept' => 'text/plain'},
+  #     {:username => 'admin', :password => 'secret'}
+  #   )
+  #   if response.ok?
+  #     puts response.body
+  #   else
+  #     puts "Couldn't fetch your pigeon (#{response.status_code})"
+  #   end
+  def self.get(uri, headers={}, options={})
+    REST::Request.perform(:get, URI.parse(uri), nil, headers, options)
   end
   
-  def self.head(uri, headers={})
-    REST::Request.perform(:head, URI.parse(uri), nil, headers)
+  # Performs a HEAD on a resource. See REST::Request.new for a complete discussion of options.
+  #
+  #   response = REST.head('http://example.com/pigeons/12')
+  #   if response.ok?
+  #     puts "Your pigeon exists!"
+  #   elsif response.found?
+  #     puts "Someone moved your pigeon!"
+  #   else
+  #     puts "Couldn't fetch your pigeon (#{response.status_code})"
+  #   end  
+  def self.head(uri, headers={}, options={})
+    REST::Request.perform(:head, URI.parse(uri), nil, headers, options)
   end
   
-  def self.put(uri, body, headers={})
-    REST::Request.perform(:put, URI.parse(uri), body, headers)
+  # Performs a PUT on a resource. See REST::Request.new for a complete discussion of options.
+  #
+  #   response = REST.put('http://example.com/pigeons/12',
+  #     {'Name' => 'Homer'}.to_xml,
+  #     {'Accept' => 'application/xml, */*', 'Content-Type' => 'application/xml'}
+  #   )
+  #   if response.ok?
+  #     puts "Your pigeon was renamed to 'Homer'!"
+  #   else
+  #     puts "Couldn't rename your pigeon (#{response.status_code})"
+  #     puts XML.parse(response.body).reason
+  #   end  
+  def self.put(uri, body, headers={}, options={})
+    REST::Request.perform(:put, URI.parse(uri), body, headers, options)
   end
   
-  def self.post(uri, body, headers={})
-    REST::Request.perform(:post, URI.parse(uri), body, headers)
+  # Performs a POST on a resource. See REST::Request.new for a complete discussion of options.
+  #
+  #   response = REST.post('http://example.com/pigeons',
+  #     {'Name' => 'Bowser'}.to_xml,
+  #     {'Accept' => 'application/xml, */*', 'Content-Type' => 'application/xml'}
+  #   )
+  #   if response.created?
+  #     puts "Created a new pigeon called 'Bowser'"
+  #   else
+  #     puts "Couldn't create your pigeon (#{response.status_code})"
+  #     puts XML.parse(response.body).reason
+  #   end
+  def self.post(uri, body, headers={}, options={})
+    REST::Request.perform(:post, URI.parse(uri), body, headers, options)
   end
 end
 

data/lib/rest/request.rb

@@ -1,17 +1,46 @@
 require 'uri'
 require 'net/http'
 
-module REST
+module REST #:nodoc:
+  # Request holds a HTTP request
   class Request
-    attr_accessor :verb, :url, :body, :headers, :request
+    attr_accessor :verb, :url, :body, :headers, :options, :request
     
-    def initialize(verb, url, body=nil, headers={})
+    # * <tt>verb</tt>: The verb to use in the request, either :get, :head, :put, or :post
+    # * <tt>url</tt>: The URL to send the request to, must be a URI instance
+    # * <tt>body</tt>: The body to use in the request
+    # * <tt>headers</tt>: A hash of headers to add to the request
+    # * <tt>options</tt>: A hash of additional options
+    #   * <tt>username</tt>: Username to use for basic authentication
+    #   * <tt>password</tt>: Password to use for basic authentication
+    #
+    # Examples
+    #
+    #   request = REST::Request.new(:get, URI.parse('http://example.com/pigeons/1'))
+    #
+    #   request = REST::Request.new(:head, URI.parse('http://example.com/pigeons/1'))
+    #
+    #   request = REST::Request.new(:post,
+    #     URI.parse('http://example.com/pigeons'),
+    #     {'name' => 'Homr'}.to_json,
+    #     {'Accept' => 'application/json, */*', 'Content-Type' => 'application/json; charset=utf-8'}
+    #   )
+    #
+    #   request = REST::Request.new(:put,
+    #     URI.parse('http://example.com/pigeons/1'),
+    #     {'name' => 'Homer'}.to_json,
+    #     {'Accept' => 'application/json, */*', 'Content-Type' => 'application/json; charset=utf-8'},
+    #     {:username => 'Admin', :password => 'secret'}
+    #   )
+    def initialize(verb, url, body=nil, headers={}, options={})
       @verb = verb
       @url = url
       @body = body
       @headers = headers
+      @options = options
     end
     
+    # Performs the actual request and returns a REST::Response object with the response
     def perform
       case verb
       when :get
@@ -24,11 +53,21 @@ module REST
       when :post
         self.request = Net::HTTP::Post.new(url.path, headers)
         self.request.body = body
+      else
+        raise ArgumentError, "Unknown HTTP verb `#{verb}'"
       end
+      
+      if options[:username] and options[:password]
+        request.basic_auth(options[:username], options[:password])
+      end
+      
       response = Net::HTTP.new(url.host, url.port).start {|http| http.request(request) }
-      REST::Response.new(response.code, response.__send__(:instance_variable_get, '@header'), response.body)
+      REST::Response.new(response.code, response.instance_variable_get('@header'), response.body)
     end
     
+    # Shortcut for REST::Request.new(*args).perform.
+    #
+    # See new for options.
     def self.perform(*args)
       request = new(*args)
       request.perform

data/lib/rest/response.rb

@@ -1,7 +1,16 @@
-module REST
+module REST #:nodoc:
+  # Response holds a HTTP response
   class Response
+    # These codes are used to define convenience boolean accessors on the response object.
+    #
+    # Examples
+    #
+    #   REST::Response.new(200).ok? #=> true
+    #   REST::Response.new(201).ok? #=> falses
+    #   REST::Response.new(403).forbidden? #=> true
     CODES = [
       [200, :ok],
+      [201, :created],
       [301, :moved_permanently],
       [302, :found],
       [400, :bad_request],
@@ -14,6 +23,9 @@ module REST
     
     attr_accessor :body, :headers, :status_code
     
+    # * <tt>status_code</tt>: The status code of the response (ie. 200 or '404')
+    # * <tt>headers</tt>: The headers of the response
+    # * <tt>body</tt>: The body of the response
     def initialize(status_code, headers={}, body='')
       @status_code = status_code.to_i
       @headers = headers
@@ -26,6 +38,7 @@ module REST
       end
     end
     
+    # Returns _true_ when the status code is in the 2XX range. Returns false otherwise.
     def success?
       (status_code.to_s =~ /2../) ? true : false
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: nap
 version: !ruby/object:Gem::Version 
-  version: "0.1"
+  version: "0.2"
 platform: ruby
 authors: 
 - Manfred Stienstra
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-09-09 00:00:00 +02:00
+date: 2008-10-09 00:00:00 +02:00
 default_executable: 
 dependencies: []