googlebooks 0.0.5 → 0.0.6

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/LICENSE

@@ -0,0 +1,15 @@
+    This file is part of GoogleBooks.
+
+    GoogleBooks is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    GoogleBooks is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with GoogleBooks.  If not, see <http://www.gnu.org/licenses/>.
+

data/README.md

@@ -0,0 +1,161 @@
+GoogleBooks
+===========
+
+GoogleBooks is a lightweight Ruby wrapper that queries the Google API to search for publications in the Google Books repository.
+
+It is inspired by the [google-book](https://github.com/papercavalier/google-book) gem which relies on the deprecated [Google GData Books API](http://code.google.com/apis/books/docs/gdata/developers_guide_protocol.html), but is updated to hook into the current Google API and expanded to provide additional methods and search options.
+
+Basic Usage
+-----------
+
+Using GoogleBooks is simple. There's just one class, `GoogleBooks`, and one method, `search`. Queries return an enumerable collection of results, each with their own set of attributes that can be individually configured.
+
+    require 'googlebooks' # unless you're using Bundler
+    
+    books = GoogleBooks.search('The Great Gatsby')
+    first_book = book.first
+    
+    first_book.author #=> 'F. Scott Fitzgerald'
+    first_book.isbn #=> '9781443411080'
+    first_book.image_link(:zoom => 6) #=> 'http://bks2.books.google.com/books?id=...'
+    
+
+Options Hash
+-----------
+
+The `search` method allows for an options hash of up to four parameters. These parameters are `page`, `count`, `order_by`, and `api_key`. Necessity of a Google API key is application dependent; further information is available in [Google's API documentation](http://code.google.com/apis/books/docs/v1/using.html).
+
+    require 'googlebooks'
+    
+    GoogleBooks.search('The Great Gatsby', {:count => 10}) 
+    #=> returns first ten results (default = 5)
+   
+    GoogleBooks.search('The Great Gatsby', {:page => 2}) 
+    #=> returns second page of results (default = 1)
+    
+    GoogleBooks.search('The Great Gatsby', {:count => 3, :page => 4, :api_key => 'THIS_IS_YOUR_API_KEY'}) 
+    #=> returns three results, beginning with the 10th overall result
+
+By default, results are returned in order of relevance. However, results also be ordered from most recently to least recently published by passing `newest` to the `order_by` key. Passing anything other than `newest` will return results by relevance. Google [does not currently support](https://groups.google.com/a/googleproductforums.com/forum/#!searchin/books/publication$20date/books/wKuq9TLGYsc/SRIk-YiiPHQJ) querying any values other than `relevance` and `newest`.
+
+    GoogleBooks.search('The Great Gatsby', {:order_by => 'newest'})
+    #=> returns results in order of most recently to least recently published
+    
+    GoogleBooks.search('The Great Gatsby')
+    GoogleBooks.search('The Great Gatsby', {:order_by => `ANYTHING ELSE`})
+    #=> both return results in order of relevance
+
+Special Keywords
+----------------
+
+There are special keywords you can specify in the search terms to search in particular fields, such as:
+
+* `intitle` *Returns results where the text following this keyword is found in the title.*
+* `inauthor` *Returns results where the text following this keyword is found in the author.*
+* `inpublisher` *Returns results where the text following this keyword is found in the publisher.*
+* `subject` *Returns results where the text following this keyword is listed in the category list of the volume.*
+* `isbn` *Returns results where the text following this keyword is the ISBN number.*
+
+Examples:
+    
+    require 'googlebooks'
+    
+    books = GoogleBooks.search('isbn:9781443411080') # yields a collection of one result
+    book = books.first # the one result
+    
+    book.title #=> 'The Great Gatsby'
+    
+Attributes
+----------
+
+By default, GoogleBooks can query the following attributes (note that not all attributes are available to all books):
+
+* `title`
+* `authors` *Returns all authors as a comma delimited string*
+* `publisher`
+* `published_date`
+* `description`
+* `isbn` *Attempts to return 13-digit first, then 10-digit, then nil*
+* `isbn_10` *Returns 10-digit form only*
+* `isbn_13` *Returns 13-digit form only*
+* `page_count`
+* `print_type`
+* `categories` *Returns all categories as a comma delimited string*
+* `average_rating`
+* `ratings_count`
+* `language`
+* `preview_link`
+* `info_link`
+* `image_link` *See details below*
+
+Sale and retail information is available on some volumes as of Google Books API v1. GoogleBooks returns a hash of these attributes (where available) under the `sale_info` attribute.
+
+    book = GoogleBooks.search(9780345508553).first # Do Androids Dream of Electric Sheep?
+   
+    book['country'] #=> 'US'
+    book['saleability'] #=> 'FOR_SALE'
+    book['isEbook'] #=> true
+    book['listPrice']['amount'] #=> 9.99
+    book['listPrice']['currencyCode'] #=> 'USD'
+    book['retailPrice']['amount'] #=> 9.99
+    book['retailPrice']['currencyCode'] #=> 'USD'
+    book['buyLink'] #=> 'http://books.google.com/books?id=jUX8N9kiCiQC&dq=9780345508553&buy=&source=gbs_api'
+   
+Note that the `sale_info` attribute is only available for some volumes and will sometimes return `nil` for nested attributes. Use with caution as GoogleBooks does not provide built-in error handling for instances of `nil`.
+
+Image Links
+-----------
+
+When possible, GoogleBooks will return links to an image of a book's cover. The size and appearance of the cover can be configured by passing an optional hash of arguments to the attribute.
+
+The size of this image is configurable by passing an numerical argument between 1-6 to the image_link attribute, which is passed to the zoom attribute in the URL query.
+
+* `:zoom` *Pass numeric value between 1-6 to the zoom attribute* (default = 1)
+
+GoogleBooks will, by default, return the image_link for an aesthetically unmodified cover. However, if you'd like Google to return an image with a "curled" corner (when available), you can pass true to this key. 
+
+* `:curl` *Pass true to return image_link of cover with curled corner* (default = false)
+
+Examples:
+    
+    book = GoogleBooks.search("The Great Gatsby").first
+    
+    # return image_link with default options
+    book.image_link # zoom=1, edge=none
+    
+    # return image_link of varying sizes
+    book.image_link # small
+    book.image_link(:zoom => 5) # thumbnail
+    book.image_link(:zoom => 2) # medium
+    book.image_link(:zoom => 3) # large
+    book.image_link(:zoom => 4) # extra large
+    
+    # return image_link with curled corners
+    book.image_link(:curl => true)
+    
+    # return thumbnail image_link with curled corners
+    book.image_link(:zoom => 5, :curl => true)
+  
+Support for distributed production servers
+------------------------------------------
+
+The current Google API for Books generally requires that the requesting server's IP address be geolocatable. [This can cause responses to be restricted](http://www.google.com/support/forum/p/booksearch-apis/thread?tid=2034bed9a98c15cb&hl=en) when requested from distributed/clustered servers such as Heroku.
+
+GoogleBooks can resolve these issues by adding an X-Forwarded-For HTTP header to each request that contains the IP address of the user. In most cases, you can pass the user's IP address as the third parameter in your search request:
+
+    # Request made from Heroku server without passing user's IP address to HTTP header
+    GoogleBooks.search("Search Query", {options_hash}) #=> returns error hash
+    
+    # Request made from Heroku server with user's IP address
+    user_ip = request.remote_ip # assuming user is accessing from a valid IP address
+    GoogleBooks.search("Search Query", {options_hash}, user_ip) #=> returns valid hash of results
+
+Doing this will, for the most part, enable you to query the Google API from apps that reside across distributed nodes.
+
+Etcetera
+--------
+
+GoogleBooks is licensed under the GNU GPL. Modify and distribute freely.
+
+Please feel free to contact the developer with any questions or suggestions. Forking and merge/pull requests are encouraged for those who would like to take part in improving this gem.
+

data/googlebooks.gemspec

@@ -16,9 +16,10 @@ Gem::Specification.new do |s|
 
   s.add_dependency('httparty')
   s.add_development_dependency('rspec')
+  s.add_development_dependency('webmock')
   
-  #s.files         = `git ls-files`.split("\n")
-  s.files         = Dir["{lib}/**/*", "googlebooks.gemspec", "Gemfile", "Rakefile"]
+  s.files         = `git ls-files`.split("\n")
+  #s.files         = Dir["{lib}/**/*", "googlebooks.gemspec", "Gemfile", "Rakefile"]
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]

data/lib/version.rb

@@ -1,3 +1,3 @@
 module GoogleBooks
-  VERSION = "0.0.5"
+  VERSION = "0.0.6"
 end

data/spec/googlebooks/book/item_spec.rb

@@ -0,0 +1,51 @@
+require 'spec_helper'
+
+module GoogleBooks
+  class Item
+    describe Item do
+      
+      example = GoogleBooks.search('isbn:9780062132345').first
+      
+      it "should append a subtitle to the title if it exists" do
+        example.title.should eq "Freakonomics: A Rogue Economist Explores the Hidden Side of Everything"
+      end
+      
+      it "should return a string authors delineated by a comma" do
+        example.authors.should eq "Steven D. Levitt, Stephen J. Dubner"
+      end
+      
+      it "should have an isbn that is 13 digits" do
+        example.isbn.should_not eq nil
+        example.isbn.should eq '9780062132345'
+        example.isbn.to_s.length.should eq 13
+      end
+      
+      it "should convert to a 10 digit isbn" do
+        example.isbn_10.should eq '0062132342'
+      end
+      
+      it "should make a 13 digit isbn duplicated from the default isbn" do
+        example.isbn_13.should eq '9780062132345'
+        example.isbn_13.should eq example.isbn
+      end
+      
+      describe "image_link" do
+        it "should have all zoom varieties and show 1 as a default" do
+          example.image_link.should include "zoom=1"
+          example.image_link(:zoom => 2).should include "zoom=2"
+          example.image_link(:zoom => 3).should include "zoom=3"
+          example.image_link(:zoom => 4).should include "zoom=4"
+          example.image_link(:zoom => 5).should include "zoom=5"
+          example.image_link(:zoom => 6).should include "zoom=6"
+          example.image_link(:zoom => 7).should include "zoom=7"
+        end
+        
+        it "should default to 'edge=none' and curl when dictated" do
+          example.image_link.should include "edge=none"
+          example.image_link(:curl => true).should include "edge=curl"
+        end
+      end
+      
+    end
+  end
+end

data/spec/googlebooks/book/response_spec.rb

@@ -0,0 +1,20 @@
+require 'spec_helper'
+
+module GoogleBooks
+  describe Response do
+
+    response = GoogleBooks.search('the great gatsby')
+
+    it "should set total results" do
+      response.total_items.should > 0
+    end
+
+    it "should return entries" do
+      response.first.should be_an Item
+    end
+
+    it "should handle an empty query" do
+      GoogleBooks.search('').to_a.should be_empty
+    end
+  end
+end

data/spec/googlebooks/googlebooks_spec.rb

@@ -0,0 +1,51 @@
+require 'spec_helper'
+
+describe GoogleBooks do
+  describe "#search" do
+    it "should escape spaces" do
+      GoogleBooks.search('the great gatsby')
+      GoogleBooks.send(:query).should include 'q=the+great+gatsby'
+    end
+
+		describe 'startIndex' do
+		  it "should default to 0 if no page is specified" do
+		  	GoogleBooks.search('the great gatsby')
+		  	GoogleBooks.send(:query).should include 'startIndex=0'
+		  end
+		  
+		  it "should calculate based on default count of 5 if no count is given" do
+		  	GoogleBooks.search("the great gatsby", :page => 4)
+		  	GoogleBooks.send(:query).should include 'startIndex=15'
+		  end
+		  
+		  it "should set based on page number and count" do
+		    GoogleBooks.search('the great gatsby', {:page => 3, :count => 12})
+		    GoogleBooks.send(:query).should include 'startIndex=24'
+		  end
+		  
+		end
+
+    it "should set the number of results per page" do
+      GoogleBooks.search('the great gatsby', :count => 20)
+      GoogleBooks.send(:query).should include 'maxResults=20'
+    end
+    
+    it "should join parameters" do
+      GoogleBooks.search('the great gatsby', :count => 20, :page => 2)
+      GoogleBooks.send(:query).should include 'startIndex=2'
+      GoogleBooks.send(:query).should include 'maxResults=20'
+      GoogleBooks.send(:query).should include 'q=the+great+gatsby'
+      GoogleBooks.send(:query).count('&').should eq 2 
+    end
+    
+    it "should return the proper number results based on the count passed in" do
+      results = GoogleBooks.search('F. Scott Fitzgerald', :count => 20)
+      results.count.should eq 20
+    end
+
+    it "should return a response" do
+      GoogleBooks.search('the great gatsby').should be_a GoogleBooks::Response
+    end
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require 'rubygems'
+require 'bundler/setup'
+require 'rspec'
+
+require 'googlebooks'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: googlebooks
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-13 00:00:00.000000000Z
+date: 2012-07-20 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
-  requirement: &74088030 !ruby/object:Gem::Requirement
+  requirement: &83731200 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *74088030
+  version_requirements: *83731200
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &74087820 !ruby/object:Gem::Requirement
+  requirement: &83730990 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,18 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *74087820
+  version_requirements: *83730990
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: &83730780 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *83730780
 description: GoogleBooks is a lightweight Ruby wrapper that queries the Google API
   to search for publications in the Google Books repository. It is inspired by the
   google-book gem which relies on the deprecated Google GData Books API, but is updated
@@ -43,13 +54,20 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/version.rb
-- lib/googlebooks.rb
-- lib/book/response.rb
-- lib/book/item.rb
-- googlebooks.gemspec
+- .gitignore
 - Gemfile
+- LICENSE
+- README.md
 - Rakefile
+- googlebooks.gemspec
+- lib/book/item.rb
+- lib/book/response.rb
+- lib/googlebooks.rb
+- lib/version.rb
+- spec/googlebooks/book/item_spec.rb
+- spec/googlebooks/book/response_spec.rb
+- spec/googlebooks/googlebooks_spec.rb
+- spec/spec_helper.rb
 homepage: https://github.com/zeantsoi/googlebooks
 licenses: []
 post_install_message: