tchak-restbooks 0.1.1

data/README

@@ -0,0 +1,26 @@
+INSTALL :
+
+gem install tchak-restbooks
+
+HOWTO :
+
+require "restbooks"
+
+client = RestBooks::Client.new( :log => 'stdout' )
+Or
+client = RestBooks::Client.new( { :user => 'toto', :password => 'secret' } )
+
+m_books = client.books.all
+m_authors = client.authors.all( { :letter => 'A' } )
+m_authors = client.authors.all( { :page => 2 } )
+
+m_author = client.authors.top.first
+m_book = client.authors.books( my_author )
+p m_book.title
+p m_book.description
+
+m_comments = client.books.comments( my_book )
+m_comments.each do |comment|
+  p comment.title
+  p comment.body
+end

data/lib/authors.rb

@@ -0,0 +1,100 @@
+# 
+#  authors.rb
+#  restbooks
+#  
+#  Created by Paul Chavard on 2009-09-12.
+#  Copyright 2009
+#
+#  This file is part of RestBooks.
+#
+#  RestBooks 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.
+#  
+#  RestBooks 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 RestBooks.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+module RestBooks
+  class Authors
+    include RestBooks::Api
+
+    # Endpoint: /authors
+    #  Formats: Atom
+    #  Description: List all authors (20 items)
+    #  Parameters:
+    #     * letter: display the authors with ... as the first letter of their name
+    #     * born: authors born in ...
+    #     * death: author who dies in ...
+    #     * lang: language of the author
+    #     * order: normally from A to Z, use desc to reverse order
+    def all( options={} )
+      create_url( "/authors", options, ORDERED_AUTHOR_PARAMETERS )
+      return do_request( :author )
+    end
+
+    # Endpoint: /authors/top
+    #  Formats: Atom
+    #  Description: List top authors (20 items)
+    #  Parameters:
+    #     * letter: display the authors with ... as the first letter of their name
+    #     * born: authors born in ...
+    #     * death: author who dies in ...
+    #     * lang: language of the author
+    #     * range: normally overall, week will display the most popular for the previous week and month for the last 4 weeks
+    def top( options={} )
+      create_url( "/authors/top", options, RANGED_AUTHOR_PARAMETERS )
+      return do_request( :author )
+    end
+
+    # Endpoint: /authors/recent
+    #  Formats: Atom
+    #  Description: List recent authors (20 items)
+    #  Parameters:
+    #     * letter: display the authors with ... as the first letter of their name
+    #     * born: authors born in ...
+    #     * death: author who dies in ...
+    #     * lang: language of the author
+    def recent( options={} )
+      create_url( "/authors/recent", options, AUTHOR_PARAMETERS )
+      return do_request( :author )
+    end
+
+    # Endpoint: /author/:id/books
+    #  Formats: Atom
+    #  Description: List all books for an author (id)
+    #  Parameters: Same as /books
+    def books( author_id, options={} )
+      author_id = author_id.id if author_id.kind_of? RestBooks::Models::Author
+      create_url( "/author/#{author_id}/books", options, ORDERED_BOOK_PARAMETERS )
+      return do_request( :book )
+    end
+
+    # Endpoint: /author/:id/books/top
+    #  Formats: Atom
+    #  Description: List top books for an author (id)
+    #  Parameters: Same as /books/top
+    def top_books( author_id, options={} )
+      author_id = author_id.id if author_id.kind_of? RestBooks::Models::Author
+      create_url( "/author/#{author_id}/books/top", options, RANGED_BOOK_PARAMETERS )
+      return do_request( :book )
+    end
+
+    # Endpoint: /author/:id/books/recent
+    #  Formats: Atom, RSS
+    #  Description: List recent books for an author (id)
+    #  Parameters: Same as /books/recent
+    def recent_books( author_id, options={} )
+      author_id = author_id.id if author_id.kind_of? RestBooks::Models::Author
+      create_url( "/author/#{author_id}/books/recent", options, BOOK_PARAMETERS )
+      return do_request( :book )
+    end
+
+  end
+end

data/lib/books.rb

@@ -0,0 +1,124 @@
+# 
+#  books.rb
+#  restbooks
+#  
+#  Created by Paul Chavard on 2009-09-12.
+#  Copyright 2009
+#
+#  This file is part of RestBooks.
+#
+#  RestBooks 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.
+#  
+#  RestBooks 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 RestBooks.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+module RestBooks
+  class Books
+    include RestBooks::Api
+    
+    # Endpoint: /books
+    #  Formats: Atom
+    #  Description: List all books (20 items)
+    #  Parameters:
+    #     * letter: display the books with ... as the first letter of their name
+    #     * year: book released in ...
+    #     * lang: language of the book
+    #     * order: normally from A to Z, use desc to reverse order or year to sort them by release date
+    def all( options={} )
+      create_url( "/books", options, ORDERED_BOOK_PARAMETERS )
+      return do_request( :book )
+    end
+
+    # Endpoint: /books/top
+    #  Formats: Atom
+    #  Description: List top books (20 items)
+    #  Parameters:
+    #     * letter: display the books with ... as the first letter of their name
+    #     * year: book released in ...
+    #     * lang: language of the book
+    #     * range: normally overall, week will display the most popular for the previous week and month for the last 4 weeks
+    def top( options={} )
+      create_url( "/books/top", options, RANGED_BOOK_PARAMETERS )
+      return do_request( :book )
+    end
+
+    # Endpoint: /books/recent
+    #  Formats: Atom, RSS
+    #  Description: List recent books (20 items)
+    #  Parameters:
+    #     * letter: display the books with ... as the first letter of their name
+    #     * year: book released in ...
+    #     * lang: language of the book
+    def recent( options={} )
+      create_url( "/books/recent", options, BOOK_PARAMETERS )
+      return do_request( :book )
+    end
+
+    # Endpoint: /books/search
+    #  Formats: Atom
+    #  Description: Search for a book
+    #  Parameters:
+    #     * query: you can use advanced queries too (for example "type:Horror AND Lovecraft")
+    def search( query, options={} )
+      options[:query] = query
+      create_url( "/books/search", options, [:query] )
+      return do_request( :book )
+    end
+
+    # Endpoint: /book/:id/similar
+    #  Formats: Atom
+    #  Description: List similar books for a given book
+    #  Parameters: none
+    def similar( book_id, options={} )
+      book_id = book_id.id if book_id.kind_of? RestBooks::Models::Book
+      create_url( "/book/#{book_id}/similar", options, [:page] )
+      return do_request( :book )
+    end
+
+    # Endpoint: /book/:id/lists
+    #  Formats: Atom
+    #  Description: View in which list a book is included
+    #  Parameters:
+    #     * order: normally the order is based on the number of favorites, use asc or desc to switch this to alphabetical order
+    def lists
+      book_id = book_id.id if book_id.kind_of? RestBooks::Models::Book
+      create_url( "/book/#{book_id}/lists", options, LIST_PARAMETERS )
+      return do_request( :list )
+    end
+    
+    # Endpoint: /book/:id/comments
+    #  Formats: Atom
+    def comments( book_id, options={} )
+      book_id = book_id.id if book_id.kind_of? RestBooks::Models::Book
+      create_url( "/book/#{book_id}/comments", options, [:page] )
+      return do_request( :comment )
+    end
+
+    # Endpoint: /book/:id/comments
+    #  Formats: Atom, EPub, Mobipocket, PDF, png
+    #  Description: Get the book, information or cover
+    #  Parameters:
+    #     * size: for png cover you can use smaller
+    def get( book_id, options={} )
+      book_id = book_id.id if book_id.kind_of? RestBooks::Models::Book
+      options.delete(:size) if options[:format] != :png
+      create_url( "/book/#{book_id}", options, [:size] )
+      if @uri.format.to_sym == :atom
+        return do_request( :book )
+      elsif [ :epub, :mobi, :pdf, :atom, :png ].include?( @uri.format.to_sym )
+        responce = RestClient::Request.execute(:method => :get, :url => @uri.to_s, :headers => {}, :raw_response => true)
+        return { :content_type => responce.headers[:content_type], :path => responce.file.path }
+      end
+    end
+
+  end
+end

data/lib/categories.rb

@@ -0,0 +1,68 @@
+# 
+#  categories.rb
+#  restbooks
+#  
+#  Created by Paul Chavard on 2009-09-12.
+#  Copyright 2009
+#
+#  This file is part of RestBooks.
+#
+#  RestBooks 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.
+#  
+#  RestBooks 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 RestBooks.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+module RestBooks
+  class Categories
+    include RestBooks::Api
+    
+    # Endpoint: /types
+    #  Formats: Atom
+    #  Description: View the categories, use pagination
+    #  Parameters:
+    #    * order: normally based on the number of favorites, use comments to order them by most discussed lists
+    def all( options={} )
+      create_url( "/types", options, LIST_PARAMETERS )
+      return do_request( :category )
+    end
+    
+    # Endpoint: /type/:id/books
+    #  Formats: Atom
+    #  Description: List all books from given category, use pagination
+    def books( category_id, options={} )
+      category_id = category_id.id if category_id.kind_of? RestBooks::Models::Category
+      create_url( "/type/#{category_id}/books", options, ORDERED_BOOK_PARAMETERS )
+      return do_request( :book )
+    end
+    
+    # Endpoint: /type/:id/books/top
+    #  Formats: Atom
+    #  Description: List top books for a category (id)
+    #  Parameters: Same as /books/top
+    def top_books( category_id, options={} )
+      category_id = category_id.id if category_id.kind_of? RestBooks::Models::Category
+      create_url( "/type/#{category_id}/books/top", options, RANGED_BOOK_PARAMETERS )
+      return do_request( :book )
+    end
+
+    # Endpoint: /type/:id/books/recent
+    #  Formats: Atom, RSS
+    #  Description: List recent books for a category (id)
+    #  Parameters: Same as /books/recent
+    def recent_books( category_id, options={} )
+      category_id = category_id.id if category_id.kind_of? RestBooks::Models::Category
+      fcreate_url( "/type/#{category_id}/books/recent", options, BOOK_PARAMETERS )
+      return do_request( :book )
+    end
+
+  end
+end

data/lib/extend/uri.rb

@@ -0,0 +1,30 @@
+# 
+#  uri.rb
+#  restbooks
+#  
+#  Created by Paul Chavard on 2009-09-12.
+#  Copyright 2009
+#
+#  This file is part of RestBooks.
+#
+#  RestBooks 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.
+#  
+#  RestBooks 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 RestBooks.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+module URI
+  class Generic
+    def format
+      return self.path.split('.').last
+    end
+  end
+end

data/lib/lists.rb

@@ -0,0 +1,49 @@
+# 
+#  lists.rb
+#  restbooks
+#  
+#  Created by Paul Chavard on 2009-09-12.
+#  Copyright 2009
+#
+#  This file is part of RestBooks.
+#
+#  RestBooks 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.
+#  
+#  RestBooks 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 RestBooks.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+module RestBooks
+  class Lists
+    include RestBooks::Api
+    
+    # Endpoint: /lists
+    #  Formats: Atom
+    #  Description: View the lists, use pagination
+    #  Parameters:
+    #    * favorites: normally, only the lists with at least 2 favorites are displayed. You can change the minimum value using this parameter.
+    #    * order: normally based on the number of favorites, use comments to order them by most discussed lists
+    def all( options={} )
+      create_url( "/lists", options, LIST_PARAMETERS )
+      return do_request( :list )
+    end
+    
+    # Endpoint: /list/:id
+    #  Formats: Atom
+    #  Description: View the books on the lists, use pagination
+    def books( list_id, options={} )
+      list_id = list_id.id if list_id.kind_of? RestBooks::Models::List
+      create_url( "/list/#{list_id}", options, LIST_PARAMETERS )
+      return do_request( :book )
+    end
+
+  end
+end

data/lib/mixins/api.rb

@@ -0,0 +1,126 @@
+# 
+#  api.rb
+#  restbooks
+#  
+#  Created by Paul Chavard on 2009-09-12.
+#  Copyright 2009
+#
+#  This file is part of RestBooks.
+#
+#  RestBooks 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.
+#  
+#  RestBooks 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 RestBooks.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+module RestBooks
+  module Api
+    
+    BOOK_PARAMETERS = [ :letter, :year, :lang, :page ]
+    AUTHOR_PARAMETERS = [ :letter, :born, :death, :lang, :page ]
+    LIST_PARAMETERS = [ :order, :page ]
+    ORDERED_BOOK_PARAMETERS = BOOK_PARAMETERS + [ :order ]
+    RANGED_BOOK_PARAMETERS = BOOK_PARAMETERS + [ :range ]
+    ORDERED_AUTHOR_PARAMETERS = AUTHOR_PARAMETERS + [ :order ]
+    RANGED_AUTHOR_PARAMETERS = AUTHOR_PARAMETERS + [ :range ]
+
+  private
+    
+    def initialize( client )
+      @user_agent = client.user_agent
+      @uri = client.uri
+      @etags = []
+    end
+    
+    def create_url( path, options, valid_keys )
+      format = :atom
+      options_str = []
+      options.each do |key,value|
+        if key == :format
+          format = options.delete( :format )
+        elsif !valid_keys.include?(key)
+          options.delete( key )
+        else
+          options_str << "#{key.to_s}=#{value}"
+        end
+      end
+      options = ( options_str.length > 0 ? options_str.join('&') : nil )
+      @uri.path = "#{path}.#{format.to_s}"
+      @uri.query = options
+    end
+    
+    def do_request( type, format = :atom )
+      etag, saved_data = get_etag( @uri.to_s )
+      if etag
+        begin
+          data = RestClient.get( @uri.to_s, { 'If-None-Match' => etag, 'User-Agent' => @user_agent } )
+          etag = data.headers[:etag]
+          save_etag( @uri.to_s, etag, data )
+        rescue RestClient::NotModified
+          data = saved_data
+        end
+      else
+        data = RestClient.get( @uri.to_s, { 'User-Agent' => @user_agent } )
+        etag = data.headers[:etag]
+        save_etag( @uri.to_s, etag, data )
+      end
+      case format
+      when :atom
+        return process_atom_responce( type, data )
+      # when :json
+      #   #return JSON.parse( data )
+      end
+    end
+    
+    def process_atom_responce( type, responce )
+      result = []
+      doc = REXML::Document.new( responce )
+      REXML::XPath.each( doc, '//entry' ) do |element|
+        result << eval( "Models::#{type.to_s.capitalize}.new( element )" )
+      end
+      return result
+    end
+    
+    def get_etag( path )
+      arr = @etags.assoc( path )
+      etag = data = nil
+      if arr
+        etag = arr[1]
+        data = arr[2]
+        if arr != @etags.first
+          @etags.delete(arr)
+          @etags.unshift( arr )
+        end
+      end
+      return etag, data
+    end
+    
+    def save_etag( path, etag, data )
+      @etags.unshift( [path,etag,data] )
+      @etags.pop if @etags.length > 99
+    end
+    
+    def update_etag( path, etag, data )
+      arr = @etags.assoc( path )
+      if arr
+        if arr == @etags.first
+          @etags[0] = [path,etag,data]
+        else
+          @etags.delete(arr)
+          @etags.unshift( [path,etag,data] )
+        end
+      else
+        @etags.unshift( [path,etag,data] )
+      end
+    end
+
+  end
+end

data/lib/mixins/model.rb

@@ -0,0 +1,46 @@
+# 
+#  model.rb
+#  restbooks
+#  
+#  Created by Paul Chavard on 2009-09-12.
+#  Copyright 2009
+#
+#  This file is part of RestBooks.
+#
+#  RestBooks 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.
+#  
+#  RestBooks 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 RestBooks.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+module RestBooks
+  module Model
+
+    # def title=( str )
+    #   @title = str
+    #   @element.elements['title'].text = str
+    # end
+
+    def to_s
+      return @element.to_s
+    end
+    
+    def to_entry
+      return @element
+    end
+
+    # def to_json
+    #   model = self.class.to_s.split('::').last.downcase.to_sym
+    #   return JSON.generate( { model => self.to_hash } )
+    # end
+
+  end
+end

data/lib/models/author.rb

@@ -0,0 +1,63 @@
+# 
+#  author.rb
+#  restbooks
+#  
+#  Created by Paul Chavard on 2009-09-12.
+#  Copyright 2009
+#
+#  This file is part of RestBooks.
+#
+#  RestBooks 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.
+#  
+#  RestBooks 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 RestBooks.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+module RestBooks
+  module Models
+    class Author
+      include RestBooks::Model
+      attr_reader :title, :id, :updated, :born, :death
+      
+      def initialize( element )
+        if element
+          @element = element
+          @element.elements.each do |tag|
+            case tag.name
+            when 'title'
+              @title = tag.text
+            when 'id'
+              @id = tag.text.split('/').last
+              @id = @id.split(':').last if @id.split(':').length > 1
+            when 'updated'
+              @updated = Date.parse( tag.text )
+            when 'content'
+              dates = tag.text.strip.split(' - ')
+              @born = dates.first
+              @death = dates.last
+            end
+          end
+        else
+          @element = REXML::Element.new( 'entry' )
+        end
+      end
+
+      def to_hash
+        return { :title => @title,
+          :id => @id,
+          :updated => @updated,
+          :born => @date,
+          :death => @subject }
+      end
+
+    end
+  end
+end