book_worm 0.0.3 → 0.0.4

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    book_worm (0.0.2)
+    book_worm (0.0.3)
       httparty
 
 GEM

data/README.md

@@ -0,0 +1,29 @@
+## Usage
+  gem install book_worm
+
+## Indices
+
+### Isbn
+Search on ISBN, value is set the ISBN you are interested in.
+
+#### Example
+  BookWorm.find(:isbn, "1234567890")
+
+### Title
+Keywords search on book title, long title, and latin-ized title for unicode titles.
+
+#### Example
+  BookWorm.find(:title, "Programming Ruby")
+
+### Combined
+Search index that combines titles, authors, and publisher name.
+
+### Full
+Search index that includes titles, authors, publisher name, summary, notes, awards information, etc -- practically every bit of textual information ISBNdb.com has about books.
+
+## Configuration
+
+BookWorm::Configuration.configure do |settings|
+  settings[:api_key] = "YOUR_ISBNDB_API_KEY"
+end
+

data/lib/book_worm/book.rb

@@ -1,4 +1,8 @@
 module BookWorm
+
+  # == Book
+  #
+  # Book is used to store the xml data that is returned from ISBNDB
   class Book
     attr_accessor :publisher, :authors, :isbn,
                   :isbn13, :title, :long_title,

data/lib/book_worm/configuration.rb

@@ -1,10 +1,21 @@
 module BookWorm
+
+  # == Configuration
+  #
+  # Module for storing configuration settings
   module Configuration
     extend self
 
     attr_accessor :config
     @config = {}
 
+    # Provides a method client to specify their ISBNDB API key.
+    #
+    # == Example
+    #
+    # BookWorm::Configuration.configure do |c|
+    #   c[:api_key] = YOUR_ISBNDB_API_KEY
+    # end
     def configure
       yield @config
     end

data/lib/book_worm/searchable.rb

@@ -1,5 +1,4 @@
 module BookWorm
-  require 'book_worm/configuration'
   require 'book_worm/book'
   require 'httparty'
 
@@ -7,10 +6,32 @@ module BookWorm
   format :xml
   base_uri 'http://isbndb.com'
 
+  # == Searchable
+  #
+  # A module that implements the basic finder methods for accessing the ISBNdb API
+  #
   module Searchable
 
+    # == Searchable indices
+    #
+    # These indices represent the BookWorm supported searching methods
+    #
     INDICES = [:isbn, :title, :combined, :full]
 
+    # Define convenience methods for #find and #find_all.
+    #
+    # == Example Usage
+    #
+    # BookWorm.find_by_isbn("1234567890")
+    # BookWorm.find_by_title("Programming Ruby")
+    # BookWorm.find_by_combined_index("Programming Ruby")
+    # BookWorm.find_by_full_index("Programming Ruby")
+    #
+    # BookWorm.find_all_by_isbn("1234567890")
+    # BookWorm.find_all_by_title("Programming Ruby")
+    # BookWorm.find_all_by_combined_index("Programming Ruby")
+    # BookWorm.find_all_by_full_index("Programming Ruby")
+    #
     INDICES.each do |index|
       index_name = (index.to_s =~ /full|combined/ ? "#{index}_index" : index)
 
@@ -23,6 +44,32 @@ module BookWorm
       end
     end
 
+    # Given a valid index and a value, this method returns the first match found
+    # after querying ISBNdb. The default index, :isbn, will be used
+    # in the event that you only supply one argument
+    #
+    # == Example Usage
+    #
+    # Query ISBNdb with an isbn-10
+    #   BookWorm.find(:isbn, "1234567890")
+    #   BookWorm.find("1234567890")
+    #
+    # Query ISBNdb with an isbn-13
+    #   BookWorm.find(:isbn, "1234567890123")
+    #   BookWorm.find("1234567890123")
+    #
+    # Query ISBNdb with a title
+    #   BookWorm.find(:title, "Programming Ruby")
+    #
+    # Query ISBNdb with a combined index. Search index that combines titles, authors, and
+    # publisher name.
+    #   BookWorm.find(:combined, "Programming Ruby")
+    #
+    # Query ISBNdb with a full index. A full index includes titles, authors, publisher
+    # name, summary, notes, awards information, etc -- practically every bit of textual
+    # information ISBNdb.com has about books.
+    #   BookWorm.find(:full, "Programming Ruby")
+    #
     def find(*args)
       if args.size == 1
         index = :isbn
@@ -34,6 +81,31 @@ module BookWorm
       normalize(query_isbndb(index, value))[0]
     end
 
+    # Given a valid index and a value, this method returns the all matches found
+    # after querying ISBNdb. The default index, :full, will be used
+    # in the event that you only supply one argument
+    #
+    # == Example Usage
+    #
+    # Query ISBNdb with an isbn-10
+    #   BookWorm.find_all(:isbn, "1234567890")
+    #
+    # Query ISBNdb with an isbn-13
+    #   BookWorm.find_all(:isbn, "1234567890123")
+    #
+    # Query ISBNdb with a title
+    #   BookWorm.find_all(:title, "Programming Ruby")
+    #
+    # Query ISBNdb with a combined index. Search index that combines titles, authors, and
+    # publisher name.
+    #   BookWorm.find_all(:combined, "Programming Ruby")
+    #
+    # Query ISBNdb with a full index. A full index includes titles, authors, publisher
+    # name, summary, notes, awards information, etc -- practically every bit of textual
+    # information ISBNdb.com has about books.
+    #   BookWorm.find_all(:full, "Programming Ruby")
+    #   BookWorm.find("Programming Ruby")
+    #
     def find_all(*args)
       if args.size == 1
         index = :full
@@ -47,16 +119,19 @@ module BookWorm
 
     private
 
+    # :nodoc:
     def query_base
       "/api/books.xml"
     end
 
+    # :nodoc:
     def query_isbndb(index, value)
       get(query_base, :query => { :index1 => index,
                                   :value1 => value,
                                   :access_key => Configuration.config[:api_key], })
     end
 
+    # :nodoc:
     def normalize(results)
       begin
         [results['ISBNdb']['BookList']['BookData']].flatten.collect do |book|

data/lib/book_worm/version.rb

@@ -1,3 +1,3 @@
 module BookWorm
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/lib/book_worm.rb

@@ -1,3 +1,6 @@
+# == BookWorm
+#
+# A module that interacts with the ISBN Database at isbndb.com
 module BookWorm
   require 'book_worm/configuration'
   require 'book_worm/searchable'

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 3
-  version: 0.0.3
+  - 4
+  version: 0.0.4
 platform: ruby
 authors: 
 - Tony Schneider
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-12 00:00:00 -05:00
+date: 2011-02-14 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -58,6 +58,7 @@ files:
 - .rvmrc
 - Gemfile
 - Gemfile.lock
+- README.md
 - Rakefile
 - book_worm.gemspec
 - lib/book_worm.rb