gazette 0.1.2 → 0.2.0

data/README.md

@@ -1,6 +1,6 @@
 # Gazette
 
-Gazette is a Ruby gem to interact with the [Instapaper API](http://www.instapaper.com/api).  It offers complete functionality with all API features, including authentication and adding URLs to read later.  Gazette operates over HTTP and HTTPS, and uses (Instapaper-preferred) HTTP basic authentication.
+Gazette is a Ruby gem to interact with the [Instapaper API](http://www.instapaper.com/api).  It implements all API features, including authentication and adding URLs to read later.  Gazette operates over HTTP and HTTPS, and uses (Instapaper-preferred) HTTP basic authentication.
 
 * [Github](http://github.com/Fluxx/gazette) - Browse source code, README, etc.
 * [Yardoc](http://rubydoc.info/github/Fluxx/gazette/master/frames) - Documentation.
@@ -16,45 +16,47 @@ At your favorite shell:
 
 ## Usage
 
-All interaction with the Instapaper API is done with an instance of `Gazette::Client` object.  The constructor requires one argument, the user's Instapaper email or username.  The 2nd argument is an optional hash, which can contain a `:password => "user_pass"` and/or `:https => true` if you would like to use HTTPS
+All interaction with the Instapaper API is done with an instance of `Gazette::Client`.  The constructor requires one argument: the user's Instapaper email or username.  The second argument is an optional hash, which can contain a `:password => "user_pass"` to pass the user's password, and/or `:https => true` if you would like to communicate with the Instapaper API over HTTPS.
 
     @client = Gazette::Client.new("user@eample.com", :password => "seeecrets")
-    => #<Gazette::Client:0x101f41cb0 @password=nil, @https=false, @username="user@eample.com", @options={}> 
     
 By default Gazette communicates with the Instapaper API over good 'ol HTTP.  You are strongly encouraged to use HTTPS if at all possible.
     
-    
 ### Authentication
 
-With a client in hand, you can call `@client.authenticate` to authenticate the user's credentials. Per the API documentation, authentication is totally optional.  It may be useful if you want to verify the credentials provided by a user, but is not a required step before adding URLs.
+With a `@client` in hand, you can call `@client.authenticate` to authenticate the user's credentials. Per the API documentation, authentication is a totally optional.  It may be useful if you want to verify the credentials provided by a user, but is not a required step before adding URLs.
 
     >> @client.authenticate
-    => #<Gazette::Response::Success:0x101f37260 @instapaper_title=nil, @content_location=nil>
-    
-### Responses
-    
-All valid responses to the Instapaper API return a `Gazette::Response::Success` object.  All invalid response *raise* one of the following exceptions:
-
-* `Gazette::Response::InvalidCredentials` - Invalid user credentials.
-* `Gazette::Response::ServerError` - API encountered an error. Please try again later.
-* `Gazette::Response::UnknownError` - Some other unknown error.  File a bug...maybe.
-
-Thus, for proper error checking, please `rescue` any/all of the above exceptions.
 
 ### Adding URLs
 
-To add URLs to the client's Instapaper account, call `@client.add(url)`:
+To add URLs to the client's Instapaper account, call `@client.add(url_string)`:
 
     >> @client.add("http://patmaddox.com/blog/2010/5/9/a-response-to-unit-and-functional-tests-are-as-useful-as-100.html", :title => "How do you write 100% correct code?", :selection => "How do you guarantee an application's correctness?")
-    => #<Gazette::Response::Success:0x101f17a00 @instapaper_title="\"How do you write 100% correct code?\"", @content_location="http://patmaddox.com/blog/2010/5/9/a-response-to-unit-and-functional-tests-are-as-useful-as-100.html">
     
-The `#add` method takes only one required parameter, a string of the URL you want to add.  The 2nd parameter is an optional hash, which can contain any of the following.  See the [Instapaper API documentation](http://www.instapaper.com/api) for details:
+The `#add` method's first parameter, a string of the URL you want to add, is required.  The 2nd parameter is an optional hash, which can contain any of the following.  See the [Instapaper API documentation](http://www.instapaper.com/api) for details:
 
 * `:title => "string"`
 * `:selection => "string"`
-* `:redirect => :close` which attempts to close the window after a short delay.
-* `:jsonp => "string"`
+* `:redirect => :close` - Response body contains HTML which displays a "Saved!" message with and attempts to close the browser window after a short delay.
+* `:jsonp => "string"` - Response body contains JSON response with the specified callback function.
+
+### Responses
+    
+If a successful API call was made, Gazette returns an instance of `Gazette::Response::Success`.  Responses have the following instance methods to retrieve
+values returned by the Instapaper API:
+
+* `#content_location` Saved URL of the newly created item.
+* `#instapaper_title` Saved title of the newly created item.
+* `#body` Body of the response from the API request.  Useful when the `:redirect` or `:jsonp` option is used in a `@client.add` call (see above).
+
+Invalid responses from the API cause Gazette to *raise* a new exception.  All exceptions are subclasses of `Gazette::Response::Error`:
+
+* `Gazette::Response::InvalidCredentials` - Invalid user credentials.
+* `Gazette::Response::ServerError` - API encountered an error. Please try again later.
+* `Gazette::Response::UnknownError` - Some other unknown error.  File a bug...maybe.
 
+Thus, for proper error checking, please `rescue Gazette::Response::Error` and/or the other specific exceptions.
 
 ## Note on Patches/Pull Requests
  

data/VERSION

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

data/gazette.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{gazette}
-  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 = ["Jeff Pollard"]
-  s.date = %q{2010-10-22}
+  s.date = %q{2010-12-03}
   s.description = %q{Simple Ruby wrapper gem to interact with the Instapaper API.  Supports authenticate and add API methods, as well as https, jsonp and all other features of the API.}
   s.email = %q{jeff.pollard@gmail.com}
   s.extra_rdoc_files = [
@@ -29,9 +29,12 @@ Gem::Specification.new do |s|
      "lib/gazette/api.rb",
      "lib/gazette/client.rb",
      "lib/gazette/response.rb",
+     "lib/gazette/response/error.rb",
+     "lib/gazette/response/success.rb",
      "spec/client/add_spec.rb",
      "spec/client/authenticate_spec.rb",
      "spec/client/client_spec.rb",
+     "spec/response/error_spec.rb",
      "spec/response/success_spec.rb",
      "spec/spec.opts",
      "spec/spec_helper.rb",
@@ -46,6 +49,7 @@ Gem::Specification.new do |s|
     "spec/client/add_spec.rb",
      "spec/client/authenticate_spec.rb",
      "spec/client/client_spec.rb",
+     "spec/response/error_spec.rb",
      "spec/response/success_spec.rb",
      "spec/spec_helper.rb"
   ]

data/lib/gazette.rb

@@ -2,4 +2,6 @@ $LOAD_PATH.unshift(File.dirname(__FILE__))
 
 require "gazette/api"
 require "gazette/client"
-require "gazette/response"
+require "gazette/response"
+require "gazette/response/success"
+require "gazette/response/error"

data/lib/gazette/response.rb

@@ -2,38 +2,6 @@ module Gazette
   # Container class for response from the Instapaper API.
   # @author Jeff Pollard
   class Response
-    # Successful response from the Instapaper API
-    # @author Jeff Pollard
-    class Success < Response
-      
-      # Final saved URL of the content returned from the Instapaper API.
-      attr_reader :content_location
-      
-      # Saved title of the content returned from the Instapaper API.
-      attr_reader :instapaper_title
-      
-      # Create a new Success object out of a net/http response.
-      def initialize(response)
-        unless response.is_a?(Net::HTTPResponse)
-          # Require a net/http response object
-          raise ArgumentError.new("Argument must be a Net::HTTPResponse object") 
-        end
-        
-        # Build our ivars from the headers
-        @content_location = response.header['Content-Location']
-        @instapaper_title = response.header['X-Instapaper-Title']
-      end
-    end
-    
-    # Response raised of the Instapaper returned a response indicating invalid user
-    # credentials.
-    class InvalidCredentials < Exception; end
-    
-    # Retponse raised if the Instapaper returned a server error (500).
-    class ServerError < Exception; end
-    
-    # Response returned if there was some other type of unknown error.
-    class UnknownError < Exception; end
         
   end
 end

data/lib/gazette/response/error.rb

@@ -0,0 +1,18 @@
+module Gazette
+  class Response
+    
+    # Superclass for all Gazette::Errors
+    class Error < Exception; end
+    
+    # Response raised of the Instapaper returned a response indicating invalid user
+    # credentials.
+    class InvalidCredentials < Error; end
+    
+    # Retponse raised if the Instapaper returned a server error (500).
+    class ServerError < Error; end
+    
+    # Response returned if there was some other type of unknown error.
+    class UnknownError < Error; end
+        
+  end
+end

data/lib/gazette/response/success.rb

@@ -0,0 +1,32 @@
+module Gazette
+  class Response
+    
+    # Successful response from the Instapaper API
+    # @author Jeff Pollard
+    class Success < Response
+      
+      # Final saved URL of the content returned from the Instapaper API.
+      attr_reader :content_location
+      
+      # Saved title of the content returned from the Instapaper API.
+      attr_reader :instapaper_title
+      
+      # The body returned by the Instapaper API
+      attr_reader :body
+      
+      # Create a new Success object out of a net/http response.
+      def initialize(response)
+        unless response.is_a?(Net::HTTPResponse)
+          # Require a net/http response object
+          raise ArgumentError.new("Argument must be a Net::HTTPResponse object") 
+        end
+        
+        # Build our ivars from the response and headers
+        @body = response.body
+        @content_location = response.header['Content-Location']
+        @instapaper_title = response.header['X-Instapaper-Title']
+      end
+    end
+    
+  end
+end

data/spec/response/error_spec.rb

@@ -0,0 +1,11 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+describe Gazette::Response::Error do
+
+  it "is the superclass of InvalidCredentials, ServerError and UnknownError errors" do
+    Gazette::Response::InvalidCredentials.superclass.should == Gazette::Response::Error
+    Gazette::Response::ServerError.superclass.should == Gazette::Response::Error
+    Gazette::Response::UnknownError.superclass.should == Gazette::Response::Error
+  end
+  
+end

data/spec/response/success_spec.rb

@@ -2,7 +2,7 @@ require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
 
 describe Gazette::Response::Success do
   before(:each) do
-    @response = mock("response", :is_a? => true, :header => {})
+    @response = mock("response", :is_a? => true, :header => {}, :body => "200")
   end
   
   it "raises an argument error unless the first argument is a Net::HTTPResponse object" do
@@ -20,6 +20,10 @@ describe Gazette::Response::Success do
     Gazette::Response::Success.new(@response).instapaper_title.should be_nil
   end
   
+  it "has an body attribute" do
+    Gazette::Response::Success.new(@response).body.should == "200"
+  end
+  
   it "sets content_location if the 'Content-Location' header is present" do
     @response.stub!(:header).and_return({'Content-Location' => 'http://www.example.com/'})
     Gazette::Response::Success.new(@response).content_location.should == 'http://www.example.com/'
@@ -29,5 +33,5 @@ describe Gazette::Response::Success do
     @response.stub!(:header).and_return({'X-Instapaper-Title' => 'nonse'})
     Gazette::Response::Success.new(@response).instapaper_title.should == 'nonse'
   end
-    
+      
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
   - 2
-  version: 0.1.2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Jeff Pollard
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-22 00:00:00 -07:00
+date: 2010-12-03 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -65,9 +65,12 @@ files:
 - lib/gazette/api.rb
 - lib/gazette/client.rb
 - lib/gazette/response.rb
+- lib/gazette/response/error.rb
+- lib/gazette/response/success.rb
 - spec/client/add_spec.rb
 - spec/client/authenticate_spec.rb
 - spec/client/client_spec.rb
+- spec/response/error_spec.rb
 - spec/response/success_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
@@ -106,5 +109,6 @@ test_files:
 - spec/client/add_spec.rb
 - spec/client/authenticate_spec.rb
 - spec/client/client_spec.rb
+- spec/response/error_spec.rb
 - spec/response/success_spec.rb
 - spec/spec_helper.rb