isbndb 1.5.5 → 2.0.0

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+config/isbndb.yml

data/.rspec

@@ -0,0 +1 @@
+--color

data/.rvmrc

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+
+# This is an RVM Project .rvmrc file, used to automatically load the ruby
+# development environment upon cd'ing into the directory
+
+# First we specify our desired <ruby>[@<gemset>], the @gemset name is optional,
+# Only full ruby name is supported here, for short names use:
+#     echo "rvm use 1.9.3" > .rvmrc
+environment_id="ruby-1.9.3-p194@isbndb"
+
+# Uncomment the following lines if you want to verify rvm version per project
+# rvmrc_rvm_version="1.13.6 (master)" # 1.10.1 seams as a safe start
+# eval "$(echo ${rvm_version}.${rvmrc_rvm_version} | awk -F. '{print "[[ "$1*65536+$2*256+$3" -ge "$4*65536+$5*256+$6" ]]"}' )" || {
+#   echo "This .rvmrc file requires at least RVM ${rvmrc_rvm_version}, aborting loading."
+#   return 1
+# }
+
+# First we attempt to load the desired environment directly from the environment
+# file. This is very fast and efficient compared to running through the entire
+# CLI and selector. If you want feedback on which environment was used then
+# insert the word 'use' after --create as this triggers verbose mode.
+if [[ -d "${rvm_path:-$HOME/.rvm}/environments"
+  && -s "${rvm_path:-$HOME/.rvm}/environments/$environment_id" ]]
+then
+  \. "${rvm_path:-$HOME/.rvm}/environments/$environment_id"
+  [[ -s "${rvm_path:-$HOME/.rvm}/hooks/after_use" ]] &&
+    \. "${rvm_path:-$HOME/.rvm}/hooks/after_use" || true
+else
+  # If the environment file has not yet been created, use the RVM CLI to select.
+  rvm --create  "$environment_id" || {
+    echo "Failed to create RVM environment '${environment_id}'."
+    return 1
+  }
+fi
+
+# If you use bundler, this might be useful to you:
+# if [[ -s Gemfile ]] && {
+#   ! builtin command -v bundle >/dev/null ||
+#   builtin command -v bundle | GREP_OPTIONS= \grep $rvm_path/bin/bundle >/dev/null
+# }
+# then
+#   printf "%b" "The rubygem 'bundler' is not installed. Installing it now.\n"
+#   gem install bundler
+# fi
+# if [[ -s Gemfile ]] && builtin command -v bundle >/dev/null
+# then
+#   bundle install | GREP_OPTIONS= \grep -vE '^Using|Your bundle is complete'
+# fi

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3
+before_script: "cp config/isbndb.example.yml config/isbndb.yml"
+script: "bundle exec rake test:ci --trace"

data/Gemfile

@@ -1,15 +1,3 @@
-source "http://rubygems.org"
+source :rubygems
 
-gem 'activesupport'
-gem 'i18n'
-gem 'rake'
-gem 'rdoc'
-gem 'libxml-ruby', '>= 1.1.4'
-
-# Include everything needed to run rake, tests, features, etc.
-group :development do
-  gem 'shoulda', '>= 0'
-  gem 'bundler'
-  gem 'jeweler'
-  gem 'rcov', '>= 0'
-end
+gemspec

data/Gemfile.lock

@@ -1,29 +1,49 @@
+PATH
+  remote: .
+  specs:
+    isbndb (2.0.0)
+      httparty (~> 0.8.3)
+      rake (~> 0.9.2.2)
+
 GEM
   remote: http://rubygems.org/
   specs:
-    activesupport (3.0.9)
-    git (1.2.5)
-    i18n (0.6.0)
-    jeweler (1.6.2)
-      bundler (~> 1.0)
-      git (>= 1.2.5)
-      rake
-    libxml-ruby (2.0.6)
-    rake (0.9.2)
-    rcov (0.9.9)
-    rdoc (3.6.1)
-    shoulda (2.11.3)
+    addressable (2.2.8)
+    crack (0.3.1)
+    diff-lcs (1.1.3)
+    httparty (0.8.3)
+      multi_json (~> 1.0)
+      multi_xml
+    multi_json (1.3.6)
+    multi_xml (0.5.1)
+    rake (0.9.2.2)
+    rspec (2.10.0)
+      rspec-core (~> 2.10.0)
+      rspec-expectations (~> 2.10.0)
+      rspec-mocks (~> 2.10.0)
+    rspec-core (2.10.1)
+    rspec-expectations (2.10.0)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.10.1)
+    shoulda (3.0.1)
+      shoulda-context (~> 1.0.0)
+      shoulda-matchers (~> 1.0.0)
+    shoulda-context (1.0.0)
+    shoulda-matchers (1.0.0)
+    simplecov (0.6.4)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.5.3)
+    simplecov-html (0.5.3)
+    webmock (1.8.7)
+      addressable (>= 2.2.7)
+      crack (>= 0.1.7)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  activesupport
-  bundler
-  i18n
-  jeweler
-  libxml-ruby (>= 1.1.4)
-  rake
-  rcov
-  rdoc
-  shoulda
+  isbndb!
+  rspec (~> 2.10.0)
+  shoulda (~> 3.0.1)
+  simplecov (~> 0.6.4)
+  webmock (~> 1.8.7)

data/README.markdown

@@ -1,79 +1,90 @@
 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!
+Version 1.x
+-----------
+*ISBNdb 1.x.x has been deprecated!*. You should upgrade to the new version as soon as possible. The old documentation is still available in the [git history](https://github.com/sethvargo/isbndb/tree/75cfe76d096f92b2dfaf1c1b42d7c84ff86fcbc0). There are *significant* changes in this new version, so please test appropriately.
 
 Installation
 ------------
-Finally got it packaged as a gem!
+To get started, install the gem:
 
     gem install isbndb
 
-Alternatively, you can download the source from here and `require 'lib/isbndb'`
-
-**Special Thanks** to:
+Alternatively, you can add it to your Gemfile:
 
-&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!
+```ruby
+gem 'isbndb', '~> 2.0.0'
+```
 
 Basic Setup
 -----------
-Simply create a query instance variable and you're on your way:
+To get started, you'll need to create a `config/isbndb.yml` file in your project root. It should look like this:
+
+```yml
+access_keys:
+  - KEY_1
+  - KEY_2
+  ...
+```
 
-    # 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"])
+Where you list your access keys. This was in response to security holes in version 1.x where values were passed directly to the initializer.
+
+Now you're ready to get started:
+
+```ruby
+@query = ISBNdb::Query.find_book_by_name('Ruby')
+```
 
 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")
+```ruby
+ISBNdb::Query.find_book_by_isbn("978-0-9776-1663-3")
+ISBNdb::Query.find_books_by_title("Agile Development")
+ISBNdb::Query.find_author_by_name("Seth Vargo")
+ISBNdb::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')
-    
+```ruby
+ISBNdb::Query.find(:collection => 'books', :where => { :isbn => '978-0-9776-1663-3' })
+ISBNdb::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
-    
+```ruby
+results = ISBNdb::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?
-  
+```ruby
+puts "title: #{result.title}" unless result.title.nil?
+```
+
 versus
 
-    puts "title: #{result.title}" unless result.title.nil? || result.title.blank? || result.title.empty?
+```ruby
+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.
 
@@ -81,30 +92,36 @@ because ISBNdb.com API is generally inconsistent with respect to returning empty
 
 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:
+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:
+
+```ruby
+results = ISBNdb::Query.find_books_by_title("ruby")
+results.next_page.each do |result|
+  puts "title: #{result.title}"
+end
+```
 
-    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
-    
+```ruby
+results = ISBNdb::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
+```ruby
+results = ISBNdb::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`.
 
@@ -112,73 +129,72 @@ Because there may be cases where a developer may need a specific page, the `go_t
 
 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.
+As over version 2.0, all access key management has moved into the `config/isbndb.yml` file. ISBNdb will auto-rollover if you specify multiple keys.
 
 Statistics
 ----------
 Ruby ISBNdb now supports basic statistics (from the server):
 
-    @query.keystats # => {:requests => 50, :granted => 49}
-    @query.keystats[:granted] # => 49
-    
+```ruby
+ISBNdb::Query.keystats # => {:requests => 50, :granted => 49}
+ISBNdb::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
-    
+```ruby
+ISBNdb::AccessKeyError
+```
+
 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
+```ruby
+# 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 ||= []) << ISBNdb::Query.find_book_by_isbn(isbn).first
+    rescue ISBNdb::AccessKeyError
+      SomeMailer.send_limit_email.deliver!
     end
+  end
+end
+```
+
+```ruby
+# 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 %>
+```
 
-    # 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 %>
-    
 Testing
 -------
 [![Build Status](http://travis-ci.org/sethvargo/isbndb.png)](http://travis-ci.org/sethvargo/isbndb)
 
-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 :)
+2012-6-17 - Released v2.0
+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 :)
+
+Acknowledgments
+----------------
+Special thanks to Terje Tjervaag (https://github.com/terje) for giving up the gem name 'isbndb'!
+
+Special thanks to Lazlo (https://github.com/lazlo) for forwarding his project here!