isbndb 1.5.3

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/ACKNOWLEDGEMENTS

@@ -0,0 +1 @@
+Special thanks to Terje Tjervaag (https://github.com/terje) for giving up the gem name 'isbndb'!

data/Gemfile

@@ -0,0 +1,11 @@
+source "http://rubygems.org"
+
+gem 'libxml-ruby', '>= 1.1.4'
+
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "shoulda", ">= 0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+  gem "rcov", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,22 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    git (1.2.5)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    libxml-ruby (1.1.4)
+    rake (0.8.7)
+    rcov (0.9.9)
+    shoulda (2.11.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  jeweler (~> 1.5.2)
+  libxml-ruby (>= 1.1.4)
+  rcov
+  shoulda

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Seth Vargo
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,180 @@
+Ruby ISBNdb
+===========
+About
+-----
+Ruby ISBNdb is a simple, Ruby library that connects to [ISBNdb.com's Web Service](http://isbndb.com) and API. Ruby ISBNdb is written to mimic the ease of ActiveRecord and other ORM programs, without all the added hassles. It's still in beta phases, but it is almost fully functional for the basic search features of ISBNdb.
+
+Why it's awesome
+----------------
+Ruby ISBNdb now uses [libxml-ruby](http://libxml.rubyforge.org/) - the fastest Ruby parser available for XML. Other parsers rely on REXML or hpricot, which are [show to be significantly slower](http://railstips.org/blog/archives/2008/08/11/parsing-xml-with-ruby/). libxml has been shown to have the fastest HTTP request AND fastest XML-parser to date!
+
+Instead of dealing with complicated hashes and arrays, Ruby ISBNdb populates a `ResultSet` filled with `Result` objects that behave as one would expect. Simply call `@book.title` or `@author.name`! Once a `Result` object is built, it's persistent too! That means that the XML-DOM returned by ISBNdb is parsed exactly once for each request, instead of every method call like similar versions of this gem.
+
+Version 1.5.0 now supports API-key management! The new APIKeySet supports auto-rollover - whenever one key is used up, it will automatically try the next key in the set. Once it runs out of keys, it will raise an ISBNdb::AccessKeyError. See the docs below for sample usage!
+
+Ruby ISBNdb is under active development! More features will be coming soon!
+
+Installation
+------------
+Finally got it packaged as a gem!
+
+    gem install isbndb
+
+Alternatively, you can download the source from here and `require 'lib/isbndb'`
+
+**Special Thanks** to:
+
+&nbsp;&nbsp;[Terje Tjervaag](https://github.com/terje)<br />
+&nbsp;&nbsp;[http://thedailyt.com](http://thedailyt.com)
+
+for giving up the `isbndb` gem! Thank you!
+
+Basic Setup
+-----------
+Simply create a query instance variable and you're on your way:
+
+    # will auto-rollover to API-KEY-2 when API-KEY-1 meets max requests
+    @query = ISBNdb::Query.new(["API-KEY-1", "API-KEY-2", "API-KEY-3"])
+
+ActiveRecord-like Usage
+-----------------------
+Another reason why you'll love Ruby ISBNdb is it's similarity to ActiveRecord. In fact, it's *based* on ActiveRecord, so it should look similar. It's best to lead by example, so here are a few ways to search for books, authors, etc:
+
+    @query.find_book_by_isbn("978-0-9776-1663-3")
+    @query.find_books_by_title("Agile Development")
+    @query.find_author_by_name("Seth Vargo")
+    @query.find_publisher_by_name("Pearson")
+
+Advanced Usage
+--------------
+Additionally, you can also use a more advanced syntax for complete control:
+
+    @query.find(:collection => 'books', :where => { :isbn => '978-0-9776-1663-3' })
+    @query.find(:collection => 'books', :where => { :author => 'Seth Vargo' }, :results => 'prices')
+    
+Options for `:collection` include **books**, **subjects**, **categories**, **authors**, and **publishers**.
+		
+If you are unfamiliar with some of these options, have a look at the [ISBNdb API](http://isbndb.com/docs/api/)
+
+Processing Results
+------------------
+A `ResultSet` is nothing more than an enhanced array of `Result` objects. The easiest way to process results from Ruby ISBNdb is most easily done using the `.each` method.
+
+    results = @query.find_books_by_title("Agile Development")
+    results.each do |result|
+      puts "title: #{result.title}"
+      puts "isbn10: #{result.isbn}"
+      puts "authors: #{result.authors_text}"
+    end
+    
+**Note**: calling a method on a `Result` object that is `empty?`, `blank?`, or `nil?` will *always* return `nil`. This was a calculated decision so that developers can do the following:
+
+    puts "title: #{result.title}" unless result.title.nil?
+  
+versus
+
+    puts "title: #{result.title}" unless result.title.nil? || result.title.blank? || result.title.empty?
+
+because ISBNdb.com API is generally inconsistent with respect to returning empty strings, whitespace characters, or nothing at all.
+
+**Note**: XML-keys to method names are inversely mapped. CamelCased XML keys and attributes (like BookData or TitleLong) are converted to lowercase under_scored methods (like book_data or title_long). ALL XML keys and attributes are mapped in this way.
+
+Pagination
+----------
+Ruby ISBNdb now include pagination! Pagination is based on the `ResultSet` object. The `ResultSet` object contains the methods `go_to_page`, `next_page`, and `prev_page`... Their function should not require too much explanation. Here's a basic example:
+
+    results = @query.find_books_by_title("ruby")
+    results.next_page.each do |result|
+      puts "title: #{result.title}"
+    end
+    
+A more realistic example - getting **all** books of a certain title:
+
+    results = @query.find_books_by_title("ruby")
+    while results
+      results.each do |result|
+        puts "title: #{title}"
+      end
+      
+      results = results.next_page
+    end
+    
+It seems incredibly unlikely that a developer would ever use `prev_page`, but it's still there if you need it.
+
+Because there may be cases where a developer may need a specific page, the `go_to_page` method also exists. Consider an example where you batch-process books into your own database (which is probably against Copyright laws, but you don't seem to care...):
+
+    results = @query.find_books_by_title("ruby")
+    results = results.go_to_page(50) # where 50 is the page number you want
+
+**Note**: `go_to_page`, `next_page` and `prev_page` return `nil` if the `ResultSet` is out of `Result` objects. If you try something like `results.next_page.next_page`, you could get a whiny nil. Think `LinkedLists` when working with `go_to_page`, `next_page` and `prev_page`.
+
+**BIGGER NOTE**: `go_to_page`, `next_page` and `prev_page` BOTH make a subsequent call to the API, using up one of your 500 daily request limits. Please keep this in mind!
+
+Advanced Key Management
+-----------------------
+With version 1.5.0, a new AccessKeySet allows for easy key management! It's controlled through the main @query.
+
+    @access_key_set = @query.access_key_set
+
+    @access_key_set.current_key                 # gets the current key
+    @access_key_set.next_key                    # gets the next key
+    @access_key_set.next_key!                   # advance the pointer (equivalent to @access_key_set.current_key = @access_key_set.next_key)
+    @access_key_set.prev_key                    # gets the previous key
+    @access_key_set.prev_key!                   # advance the pointer (equivalent to @access_key_set.current_key = @access_key_set.prev_key)
+    @access_key_set.use_key('abc123foobar')     # use and existing key (or add it if doesn't exist)
+
+All methods will return `nil` (except `use_key`) whenever the key does not exist.
+
+Statistics
+----------
+Ruby ISBNdb now supports basic statistics (from the server):
+
+    @query.keystats # => {:requests => 50, :granted => 49}
+    @query.keystats[:granted] # => 49
+    
+**Note**: Ironically, this information also comes from the server, so it counts as a request...
+
+Exceptions
+----------
+Ruby ISBNdb could raise the following possible exceptions:
+
+    ISBNdb::AccessKeyError
+    ISBNdb::InvalidURIError
+    
+You will most likely encounter `ISBNdb::AccessKeyError` when you have reached your 500-request daily limit. `ISBNdb::InvalidURIError` usually occurs when using magic finder methods with typographical errors.
+
+A Real-Life Example
+-------------------
+Here is a real-life example of how to use Ruby ISBNdb. Imagine a Rails application that recommends books. You have written a model, `Book`, that has a variety of methods. One of those class methods, `similar`, returns a list of book isbn values that are similar to the current book. Here's how one may do that:
+
+    # books_controller.rb
+    def simliar
+      @book = Book.find(params[:id])
+      @query = ISBNdb::Query.new(['API-KEY-1', 'API-KEY-2'])
+      @isbns = @book.similar # returns an array like [1234567890, 0987654321, 3729402827...]
+      
+      @isbns.each do |isbn|
+        begin
+          (@books ||= []) << @query.find_book_by_isbn(isbn).first
+        rescue ISBNdb::AccessKeyError
+          SomeMailer.send_limit_email.deliver!
+        end
+      end
+    end
+
+    # similar.html.erb
+    <h1>The following books are recommeded for you:</h1>
+    <% @books.each do |book| %>
+      <div class="book">
+        <h2><%= book.title_long %></h2>
+        <p><strong>authors</strong>: <%= book.authors_text %></p>
+      </div>
+    <% end %>
+
+Know Bugs and Limitations
+-------------------------
+- Result sets that return multiple sub-lists (like prices, pricehistory, and authors) are only populated with the *last* result
+
+Change Log
+----------
+2011-3-11 - Officially changed from ruby_isbndb to isbndb with special thanks to [Terje Tjervaag](https://github.com/terje) for giving up the gem name :)

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "isbndb"
+  gem.homepage = "http://github.com/svargo/isbndb"
+  gem.license = "MIT"
+  gem.summary = "This gem provides an easy solution for connecting to ISBNdb.com's API"
+  gem.description = "Ruby ISBNdb is a amazingly fast and accurate gem that reads ISBNdb.com's XML API and gives you incredible flexibilty with the results! The gem uses libxml-ruby, the fastest XML parser for Ruby, so you get blazing fast results every time. Additionally, the newest version of the gem also features caching, so developers minimize API-key usage."
+  gem.email = "seth.vargo@gmail.com"
+  gem.authors = ["Seth Vargo"]
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "ruby_isbndb #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.5.3

data/lib/isbndb.rb

@@ -0,0 +1,115 @@
+# require dependencies
+require 'libxml'
+
+# private sub-classes
+require 'isbndb/access_key_set'
+require 'isbndb/exceptions'
+require 'isbndb/result_set'
+require 'isbndb/result'
+
+module ISBNdb
+  # The Query object is the most important class of the ISBNdb Module. It is the only public
+  # class, and handles the processing power.
+  class Query
+    DEFAULT_COLLECTION = :books
+    DEFAULT_RESULTS = :details
+    BASE_URL = "http://isbndb.com/api"
+  
+    # Access methods of the access_key_set instance variable. This allows developers to manually
+    # advance, add, remove, and manage keys. See the AccessKeySet class for more information.
+    attr_reader :access_key_set
+  
+    # This method sets an array of access_keys to use for making requests to the ISBNdb API.
+    def initialize(access_keys)
+      @access_key_set = ISBNdb::AccessKeySet.new(access_keys)
+    end
+  
+    # This is the generic find method. It accepts a hash of parameters including :collection,
+    # :where clauses, and :results to show. It builds the corresponding URI and sends that URI
+    # off to the ResultSet for processing.
+    def find(params = {})
+      raise "No parameters specified! You must specify at least one parameter!" unless params[:where]
+      
+      collection = params[:collection] ||= DEFAULT_COLLECTION
+      results = params[:results] ||= DEFAULT_RESULTS
+      results = [results].flatten
+      
+      # build the search clause
+      searches = []
+      params[:where].each_with_index do |(key,val), i|
+        searches << "index#{i+1}=#{key.to_s.strip}"
+        searches << "value#{i+1}=#{val.to_s.strip}"
+      end
+    
+      # make the request
+      make_request(collection, results, searches)
+    end
+    
+    # This method returns keystats about your API key, including the number of requests
+    # and the number of granted requets. Be advised that this request actually counts 
+    # as a request to the server, so use with caution.
+    def keystats
+      uri = "#{BASE_URL}/books.xml?access_key=#{@access_key_set.current_key}&results=keystats"
+      keystats = {}
+      LibXML::XML::Parser.file(uri).parse.find('KeyStats').first.attributes.each { |attribute| keystats[attribute.name.to_sym] = attribute.value.to_i unless attribute.name == 'access_key' }
+      return keystats
+    end
+    
+    # Method missing allows for dynamic finders, similar to that of ActiveRecord. See
+    # the README for more information on using magic finders.
+    def method_missing(m, *args, &block)
+      m = m.to_s.downcase
+      
+      if m.match(/find_(.+)_by_(.+)/)
+        split = m.split('_', 4)
+        collection, search_strs = pluralize(split[1].downcase), [split.last]
+        
+        # check and see if we are searching multiple fields
+        search_strs = search_strs.first.split('_and_') if(search_strs.first.match(/_and_/))
+        raise "Wrong Number of Arguments (#{args.size} for #{search_strs.size})" if args.size != search_strs.size
+      
+        # create the searches hash
+        searches = {}
+        search_strs.each_with_index { |str, i| searches[str.strip.to_sym] = args[i].strip }
+      
+        return find(:collection => collection, :where => searches)
+      end
+      
+      super
+    end
+    
+    # Pretty print the Query object with the access key.
+    def to_s
+      "#<ISBNdb::Query, @access_key=#{@access_key_set.current_key}>"
+    end
+    
+    private
+    # Make the request to the ResultSet. If the request fails because of an ISBNdb::AccessKeyError
+    # the system will automatically rollover to the next AccessKey in the AccessKeySet. If one exists,
+    # a new request is attempted. If not, the ISBNdb::AccessKeyError persists and can be caught by your
+    # application logic.
+    def make_request(collection, results, searches)
+      begin
+        uri = "#{BASE_URL}/#{collection}.xml?access_key=#{@access_key_set.current_key}&results=#{results.join(',')}&#{searches.join('&')}"
+        ISBNdb::ResultSet.new(uri, singularize(collection).capitalize)
+      rescue ISBNdb::AccessKeyError
+        puts "Access Key Error (#{@access_key_set.current_key}) - You probably reached your limit! Trying the next key."
+        @access_key_set.next_key!
+        retry unless @access_key_set.current_key.nil?
+        raise ISBNdb::AccessKeyError
+      end
+    end
+    
+    def pluralize(str)
+      return 'categories' if str == 'category'
+      return "#{str}s" unless str.split(//).last == 's'
+      str
+    end
+    
+    def singularize(str)
+      return 'category' if str == 'categories'
+      return str[0, str.length-1] if str.split(//).last == 's'
+      str
+    end
+  end
+end

data/lib/isbndb/access_key_set.rb

@@ -0,0 +1,53 @@
+module ISBNdb
+  
+  private
+  # The AccessKeySet is a simple class used to manage access keys. It is used primarily
+  # by the ruby_isbndb class to automatically advance access keys when necessary.
+  class AccessKeySet
+    # Create the @access_keys array and then verify that the keys are valid keys.
+    def initialize(access_keys)
+      @access_keys = [access_keys].flatten
+    end
+    
+    # Get the current key. It returns a string of the access key.
+    def current_key
+      @access_keys[@current_index ||= 0]
+    end
+    
+    # Move the key pointer forward.
+    def next_key!
+      @current_index += 1
+    end
+    
+    # Get the next key.
+    def next_key
+      @access_keys[@current_index+1]
+    end
+    
+    # Move the key pointer back.
+    def prev_key!
+      @current_index -= 1
+    end
+    
+    # Get the previous key.
+    def prev_key
+      @access_keys[@current_index-1]
+    end
+    
+    # Tell Ruby ISBNdb to use a specified key. If the key does not exist, it is 
+    # added to the set and set as the current key.
+    def use_key(key)
+      @current_index = @access_keys.index(key) || @access_keys.push(key).index(key)
+    end
+    
+    # Remove the given access key from the AccessKeySet.
+    def remove_key(key)
+      @access_keys.delete(key)
+    end
+    
+    # Pretty print the AccessKeySet
+    def to_s
+      "#<AccessKeySet @keys=<#{@access_keys.collect{ |key| key }.join(',')}>>"
+    end
+  end
+end

data/lib/isbndb/exceptions.rb

@@ -0,0 +1,4 @@
+module ISBNdb
+  class AccessKeyError < StandardError; end
+  class InvalidURIError < StandardError; end
+end

data/lib/isbndb/result.rb

@@ -0,0 +1,64 @@
+module ISBNdb
+  
+  private
+  # The Result object is a true testament of metaprogramming. Almost every method of the Result
+  # is dynamically generated through the build_result() method. All attribtues of the XML are
+  # parsed, translated, and populated as instance methods on the Result object. This allows for
+  # easy Ruby-like access (@book.title), without hardcoding every single possible return value
+  # from the ISBNdb API
+  class Result
+    # Initialize simply calls build_result. Because the method definition is recusive, it must
+    # be moved into a separate helper.
+    def initialize(top_node)
+      build_result(top_node)
+    end
+    
+    # Because a result may or may not contain a specified key, we always return nil for 
+    # consistency. This allows developers to easily check for .nil? instead of checking for
+    # a miriad of exceptions throughout their code.
+    def method_missing(m, *args, &block)
+      nil
+    end
+    
+    # Pretty preint the Result including the number of singleton methods that exist. If
+    # you want the ACTUAL singleton methods, call @result.singleton_methods.
+    def to_s
+      "#<Result @singleton_methods=#{@singleton_methods.size}>"
+    end
+    
+    private
+    # This is the `magical` method. It essentially parses each attribute of the XML as well as
+    # the content of each XML node, dynamically sends a method to the instance with that attribute's
+    # or content's value. Not to be outdone, it recursively iterates over all children too!
+    def build_result(top_node)
+      top_node.attributes.each do |attribute|
+        singleton.send(:define_method, formatted_method_name(attribute.name)) { attribute.value } unless attribute.value.strip.empty?
+      end
+      
+      if top_node.children?
+        top_node.children.each { |child| build_result(child) }
+      else
+        singleton.send(:define_method, formatted_method_name(top_node.parent.name)) { top_node.content.strip.chomp(',') } unless top_node.content.strip.empty?
+      end
+    end
+    
+    # This helper function reduces code redundancy and maintains consistency by formatting
+    # all method names the same. All method names are stripped of any trailing whitespaces,
+    # converted from CamelCase to under_score, and converted to a symbol 
+    def formatted_method_name(name)
+      camel_to_underscore(name.strip).to_sym
+    end
+    
+    # This helper function converts CamelCase to under_score using a nice little regex :).
+    def camel_to_underscore(str)
+      str.gsub(/(.)([A-Z])/,'\1_\2').downcase
+    end
+    
+    # We need a singleton reference to the current _instance_ so that we can dynamically define
+    # methods. This is just a simple helper that returns the singleton class of the current
+    # object instance.
+    def singleton
+      class << self; self end
+    end
+  end
+end

data/lib/isbndb/result_set.rb

@@ -0,0 +1,86 @@
+module ISBNdb
+  
+  private
+  # The ResultSet is a collection of Result objects with helper methods for pagination. It
+  # allows for easy paginating through multiple pages of results as well as jumping to a
+  # specific results page.
+  class ResultSet
+    include Enumerable
+    
+    # This method creates instance variables for @uri, @collection, and @current_page. It then
+    # attempts to parse the XML at the gieven URI. If it cannot parse the URI for any reason,
+    # it will raise an ISBNdb::InvalidURIError. Next, the results are checked for an any error
+    # messages. An ISBNdb::AccessKeyError will be raised if the results contain any errors.
+    # Finally, this method then actually builds the ResultSet.
+    def initialize(uri, collection, current_page = 1)
+      @uri = uri
+      @collection = collection
+      @current_page = current_page
+      @xml = parse_xml
+      
+      check_results
+      build_results
+    end
+    
+    # Because ResultSet extends Enumerable, we need to define the each method. This allows users
+    # to call methods like .first, .last, [5], and .each on the ResultSet, making it behave like
+    # a primitive array.
+    def each(&block)
+      @results.each &block
+    end
+    
+    # Jump to a specific page. This method will return nil if the specified page does not exist.
+    def go_to_page(page)
+      get_total_pages unless @total_pages
+      return nil if page < 1 || page > @total_pages
+      ISBNdb::ResultSet.new("#{@uri}&page_number=#{page}", @collection, page)
+    end
+    
+    # Go to the next page. This method will return nil if a next page does not exist.
+    def next_page
+      go_to_page(@current_page+1)
+    end
+    
+    # Go to the previous page. This method will return nil if a previous page does not exist.
+    def prev_page
+     go_to_page(@current_page-1)
+    end
+    
+    # Pretty prints the Result set information.
+    def to_s
+      "#<ResultSet @collection=#{@collection}, total_results=#{@results.size}>"
+    end
+    
+    private
+    # Try and parses and returns the XML from the given URI. If the parsing fails for any reason, this method
+    # raises ISBNdb::InvalidURIError. 
+    def parse_xml
+      begin
+        LibXML::XML::Parser.file(@uri).parse
+      rescue
+        raise ISBNdb::InvalidURIError
+      end
+    end
+    
+    # Check the results for an error message. If one exists, raise an ISBNdb::AccessKeyError for now. 
+    # Currently the API does not differentiate between an overloaded API key and an invalid one
+    # (it returns the same exact response), so there only exists one exception for now...
+    def check_results
+      raise ISBNdb::AccessKeyError unless @xml.find("ErrorMessage").first.nil?
+    end
+    
+    # Iterate over #{@collection}List/#{@collection}Data (ex. BookList/BookData) and build a result with
+    # each child. This method works because the API always returns #{@collection}List followed by a subset
+    # of #{@collection}Data. These results are all pushed into the @results array for accessing.
+    def build_results
+      @xml.find("#{@collection}List/#{@collection}Data").collect { |node| (@results ||= []) << Result.new(node) }
+    end
+    
+    # This helper method is mainly designed for use with the go_to_page(page) method. It parses the XML
+    # and returns the total number of pages that exist for this result set.
+    def get_total_pages
+      list = @xml.find("#{@collection}List").first.attributes
+      @total_pages = (list['total_results'].to_f/list['page_size'].to_f).ceil
+    end
+  end
+end

data/test/helper.rb

@@ -0,0 +1,23 @@
+require 'rubygems'
+# Set up gems listed in the Gemfile.
+gemfile = File.expand_path('../../Gemfile', __FILE__)
+begin
+  ENV['BUNDLE_GEMFILE'] = gemfile
+  require 'bundler'
+  Bundler.setup
+rescue Bundler::GemNotFound => e
+  STDERR.puts e.message
+  STDERR.puts "Try running `bundle install`."
+  exit!
+end if File.exist?(gemfile)
+
+
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'isbndb'
+
+class Test::Unit::TestCase
+end

data/test/test_isbndb.rb

@@ -0,0 +1,64 @@
+require 'helper'
+
+class TestISBNdb < Test::Unit::TestCase
+  context "ISBNdb" do
+    setup do
+      @query = ISBNdb::Query.new('KXWFXJIK')
+    end    
+    
+    should "fetch a book by ISBN" do
+      @book = @query.find_book_by_isbn('1934356549').first
+      assert_equal '1934356549', @book.isbn
+    end
+    
+    should "fetch a book by ISBN13" do
+      @book = @query.find_book_by_isbn('9781934356548').first
+      assert_equal '9781934356548', @book.isbn13
+    end
+    
+    should 'fetch books by title' do
+      @books = @query.find_books_by_title('ruby')
+      @books.each do |book|
+        assert (book.title || "").downcase.include?('ruby') || (book.title_long || "").downcase.include?('ruby'), "#{book.title} did not contain 'ruby'"
+      end
+    end
+    
+    should 'get next_page and prev_page' do
+      @books = @query.find_books_by_title('ruby')
+      next_page = @books.next_page
+      assert_equal @books.first.title, next_page.prev_page.first.title, 'Failed to get next_page'
+    end
+    
+    should 'get keystats' do
+      assert @query.keystats.is_a?(Hash), "#{@query.keystats} was not a Hash"
+      assert @query.keystats[:requests] >= @query.keystats[:granted], "Number of requests (#{@query.keystats[:requests]}) was not greater than number of granted requests (#{@query.keystats[:granted]})"
+      assert @query.keystats[:requests] > 0 && @query.keystats[:requests] < 500, 'Requests were not between 0 and 500'
+    end
+    
+    should 'test access_key_set' do
+      @query = ISBNdb::Query.new(['API-KEY-1', 'API-KEY-2', 'API-KEY-3'])
+      @access_key_set = @query.access_key_set
+      assert_equal 'API-KEY-1', @access_key_set.current_key
+      assert_equal 'API-KEY-2', @access_key_set.next_key
+      @access_key_set.next_key!
+      assert_equal 'API-KEY-1', @access_key_set.prev_key
+      @access_key_set.use_key('A-NEW-KEY')
+      assert_equal 'A-NEW-KEY', @access_key_set.current_key
+      @access_key_set.use_key('API-KEY-3')
+      assert_equal 'API-KEY-3', @access_key_set.current_key
+    end
+    
+    should 'raise exception for an invalid access key' do
+      @invalid = ISBNdb::Query.new(['abc123foobar', '123anotherinvalidkey'])
+      assert_raise ISBNdb::AccessKeyError, "#{@invalid} did not raise AccessKeyError" do
+        @invalid.find_book_by_isbn('1934356549')
+      end
+    end
+    
+    should 'raise exception for an invalid uri' do
+      assert_raise ISBNdb::InvalidURIError, "@query.find_invalid_by_unknown did not raise InvalidURIError" do
+        @query.find_invalid_by_unknown('foobar')
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification 
+name: isbndb
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 1.5.3
+platform: ruby
+authors: 
+- Seth Vargo
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-03-11 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: libxml-ruby
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.1.4
+  type: :runtime
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: jeweler
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.5.2
+  type: :development
+  prerelease: false
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id005
+description: Ruby ISBNdb is a amazingly fast and accurate gem that reads ISBNdb.com's XML API and gives you incredible flexibilty with the results! The gem uses libxml-ruby, the fastest XML parser for Ruby, so you get blazing fast results every time. Additionally, the newest version of the gem also features caching, so developers minimize API-key usage.
+email: seth.vargo@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.markdown
+files: 
+- .document
+- ACKNOWLEDGEMENTS
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.markdown
+- Rakefile
+- VERSION
+- lib/isbndb.rb
+- lib/isbndb/access_key_set.rb
+- lib/isbndb/exceptions.rb
+- lib/isbndb/result.rb
+- lib/isbndb/result_set.rb
+- test/helper.rb
+- test/test_isbndb.rb
+has_rdoc: true
+homepage: http://github.com/svargo/isbndb
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: -3720609337190641477
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.1
+signing_key: 
+specification_version: 3
+summary: This gem provides an easy solution for connecting to ISBNdb.com's API
+test_files: 
+- test/helper.rb
+- test/test_isbndb.rb