librarything-api 0.1.0 → 0.1.1

data/.gitignore

@@ -19,6 +19,7 @@ rdoc
 pkg
 doc
 .yardoc
+*.gemspec
 
 ## PROJECT::SPECIFIC
 credentials.rb

data/README.rdoc

@@ -1,6 +1,34 @@
 = librarything-api
 
-Description goes here.
+This is a Ruby wrapper for the LibraryThing API.
+
+== Accessing LibraryThing APIs
+In order to use the LT Web Services API (and this library), you need to register for a developer key on librarything.com
+
+* Sign into your LT account at http://www.librarything.com
+* Go to http://www.librarything.com/services/keys.php and fill out the form to receive a developer key
+* Documentation for the LT Web Services API can be found at http://www.librarything.com/services/webservices.php
+
+== Using the Library
+The gem uses HTTParty and Nokogiri for fetching and processing responses. Both of the gems must be installed.
+
+    $ gem install httparty nokogiri
+
+    $ irb -r rubygems
+    require 'librarything'
+    LibraryThing::DEVELOPER_KEY = 'abcdef0123456789abcdef'
+    strange = LibraryThing::Work.get(:name => 'Jonathan Strange')
+    strange['url']
+    # "http://www.librarything.com/work/1060"
+
+== To Do
+* Improve code documentation
+
+== Other LT APIs to Add
+
+* Helpers for accessing LT JSON APIs (Books, Works) (No server-side fetching allowed.)
+* Helper for generating LT Covers URLs
+* See: http://www.librarything.com/wiki/index.php/LibraryThing_APIs
 
 == Note on Patches/Pull Requests
  

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/lib/librarything/author.rb

@@ -1,6 +1,17 @@
 require File.expand_path(File.dirname(__FILE__) + "/shared_requires")
 
 module LibraryThing
+
+  # 
+  # Provides access to the LT Author API
+  # Authors can be loaded by id, authorcode, or name
+  # 
+  #   # author = LibraryThing::Author.get(:id => 216)
+  #   # author = LibraryThing::Author.get(:authorcode => 'clarkesusanna')
+  #   author = LibraryThing::Author.get(:name => 'Clarke, Susanna')
+  #   author['url]
+  #   => "http://www.librarything.com/author/216"
+  # 
   class Author < LibraryThing::Resource
     get_method 'librarything.ck.getauthor'
   end

data/lib/librarything/resource.rb

@@ -1,19 +1,28 @@
-require 'httparty'
-
 module LibraryThing
 
+  # Helper class to wrap a Nokogiri node. It includes a simplified method for accessing DOM content.
   class NodeWrapper
 
     attr_reader :node
 
+    # Creates a new wrapped XML node
     def initialize(node)
       @node = node
     end
 
+    # Returns the content of the node
     def content
       @node.content
     end
 
+    # Extracts values from the node.
+    # 
+    # * If the name matches the name of an attribute, the value of that attribute will be returned
+    # * If the name matches the name of a single child element, that element is returned.
+    # * If the matching child element only contains text data, the text data is returned.
+    # * If the matching child element is named xxxList, an array of the children of the element is returned
+    # * If there is more that one matching child element, they are returned as an array.
+    # 
     def [](name)
       # Check for attributes first. Why? It works for the LT xml (for now).
       if @node.attributes.has_key?(name)
@@ -21,12 +30,13 @@ module LibraryThing
       end
 
       # Find child elements with that name
-      children = @node.xpath("lt:#{name}")
+      children = @node.xpath("./lt:#{name}")
       if children.size == 1
         child = children.first
-      
-        # LT-specific hack to simplify access to lists. Ill-advised?
-        if child.name =~ /^[\w]*List$/
+        if self.text_element?(child)
+          return child.children.first.content
+        elsif child.name =~ /^[\w]*List$/
+          # LT-specific hack to simplify access to lists. Ill-advised?
           return wrap_children(child.children)
         else
           return NodeWrapper.new(child)
@@ -40,11 +50,18 @@ module LibraryThing
 
     protected
 
+    # Checks whether the node is an element with no attributes and a single text child
+    def text_element?(node)
+      node.element? && node.attributes.empty? && node.children.size == 1 && node.children.first.text?
+    end
+
+    # Creates and returns an array of wrapped nodes for each element in the NodeSet
     def wrap_children(children)
       children.map { |c| NodeWrapper.new(c) if c.element? }.compact
     end
   end
 
+  # Base class for fetching and parsing data from the LT WebServices APIs
   class Resource
     include HTTParty
     base_uri 'http://www.librarything.com/services/rest/1.0'
@@ -53,12 +70,15 @@ module LibraryThing
     attr_reader :document
     attr_reader :item_node
 
+    # Accepts xml from an LT API request and creates a wrapper object. If there is a problem with the format of the
+    # xml, a LibraryThing::Error will be raised.
     def initialize(xml)
       @xml = xml
       @document = self.parse_response(@xml)
       @item_node = self.find_item_node(@document)
     end
 
+    # See: LibraryThing::NodeWrapper#[](name)
     def [](name)
       @item_node[name]
     end
@@ -95,6 +115,9 @@ module LibraryThing
     end
 
     class << self
+
+      # Gets or sets the method name that will be passed to the LT web service.
+      # Generally, this will be specified in a sub-class.
       def get_method(method_name = nil)
         if method_name
           @get_method = method_name
@@ -105,6 +128,8 @@ module LibraryThing
         end
       end
 
+      # Accepts a hash of query params, and generates a request to the LT API. Returns a wrapped response object. If
+      # there is a problem with the request, a LibraryThing::Error will be raised.
       def get(query)
         raise LibraryThing::Error.new("Missing developer key. Please define LibraryThing::DEVELOPER_KEY") unless defined?(LibraryThing::DEVELOPER_KEY)
 

data/lib/librarything/work.rb

@@ -1,6 +1,21 @@
 require File.expand_path(File.dirname(__FILE__) + "/shared_requires")
 
 module LibraryThing
+
+  # 
+  # Provides access to the LT Work API
+  # Works can be loaded by id, isbn, lccn, oclc or name
+  # 
+  #   # work = LibraryThing::Work.get(:id => 1060)
+  #   # work = LibraryThing::Work.get(:isbn => '0765356155')
+  #   # work = LibraryThing::Work.get(:lccn => 'PR6103.L375J65')
+  #   # work = LibraryThing::Work.get(:oclc => '185392674')
+  #   work = LibraryThing::Work.get(:name => 'Jonathon Strange')
+  #   work['url]
+  #   => "http://www.librarything.com/work/1060"
+  # 
+  # Note: lccn amd oclc access wasn't working while I was testing. (13-Mar-2010)
+  # 
   class Work < LibraryThing::Resource
     get_method 'librarything.ck.getwork'
   end

data/spec/librarything/author_spec.rb

@@ -44,13 +44,13 @@ describe LibraryThing::Author do
     def check_author_response(author)
       author.should_not be_nil
       author['id'].should == '216'
-      author['url'].content.should == 'http://www.librarything.com/author/216'
+      author['url'].should == 'http://www.librarything.com/author/216'
 
       author_element = author['author']
       author_element.should_not be_nil
       author_element['id'].should == '216'
       author_element['authorcode'].should == 'clarkesusanna'
-      author_element['name'].content.should == 'Susanna Clarke'
+      author_element['name'].should == 'Susanna Clarke'
       
       field_list = author['commonknowledge']['fieldList']
       field_list.size.should == 8

data/spec/librarything/work_spec.rb

@@ -44,7 +44,7 @@ describe LibraryThing::Work do
     def check_work_response(work)
       work.should_not be_nil
       work['id'].should == '1060'
-      work['url'].content.should == 'http://www.librarything.com/work/1060'
+      work['url'].should == 'http://www.librarything.com/work/1060'
 
       author = work['author']
       author.should_not be_nil

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: librarything-api
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Jason Wadsworth