rscribd 0.0.5 → 0.1.0

data/History.txt

@@ -1,3 +1,15 @@
+=== 0.1.0 / 2008-10-1
+
+* Changed Scribd::Document.find method to take an ActiveRecord-style scope
+  variable (which can be :all, :first, etc.) as its first parameter. Options are
+  now specified as the second parameter.
+* Scribd::Document.find can also be used with a single integer to find a
+  document by ID.
+* Scribd::Document.find now takes offset and limit parameters (for scopes that
+  return arrays of documents).
+* Added a Scribd::Document#download_url method.
+* Should no longer raise an exception when logging in.
+
 === 0.0.5 / 2008-09-25
 
 * Updated RScribd to work with server-side API changes.

data/README.txt

@@ -1,13 +1,13 @@
 = rscribd
 
-* 0.0.5 (Sep 25, 2007)
+* 0.1.0 (Oct 1, 2008)
 
 == DESCRIPTION:
 
 This gem provides a simple and powerful library for the Scribd API, allowing you
 to write Ruby applications or Ruby on Rails websites that upload, convert,
 display, search, and control documents in many formats. For more information on
-the Scribd platform, visit http://www.scribd.com/platform
+the Scribd platform, visit http://www.scribd.com/publisher
 
 == FEATURES:
 
@@ -25,7 +25,7 @@ storage system to store your documents in accessible manner. Scribd's ad system
 will help you monetize your documents easily.
 
 First, you'll need to get a Scribd API account. Visit
-http://www.scribd.com/platform to apply for a platform account.
+http://www.scribd.com/publisher/api to apply for a platform account.
 
 On the Platform site you will be given an API key and secret. The API object
 will need these to authenticate you:

data/Rakefile

@@ -3,7 +3,7 @@
 require 'rubygems'
 require 'hoe'
 
-Hoe.new('rscribd', '0.0.5') do |p|
+Hoe.new('rscribd', '0.1.0') do |p|
   p.rubyforge_name = 'rscribd'
   p.author = 'Jared Friedman'
   p.email = 'api@scribd.com'

data/lib/scribddoc.rb

@@ -1,4 +1,4 @@
-require "uri"
+require 'uri'
 
 module Scribd
   
@@ -25,8 +25,9 @@ module Scribd
   #
   # Aside from these two attributes, you can set other attributes that affect
   # how the file is displayed on Scribd. See the API documentation online for a
-  # list of attributes, at http://www.scribd.com/platform/documentation?method_name=docs.search&subtab=api
-  # (consult the "Result explanation" section).
+  # list of attributes, at
+  # http://www.scribd.com/publisher/api?method_name=docs.search (consult the
+  # "Result explanation" section).
   #
   # These attributes can be accessed or changed directly
   # (<tt>doc.title = 'Title'</tt>). You must save a document after changing its
@@ -53,6 +54,7 @@ module Scribd
     
     def initialize(options={})
       super
+      @download_urls = Hash.new
       if options[:xml] then
         load_attributes(options[:xml])
         @attributes[:owner] = options[:owner]
@@ -164,27 +166,56 @@ module Scribd
       docs_by_user.each { |user, doc_list| API.instance.send_request 'docs.changeSettings', options.merge(:doc_ids => doc_list.collect { |doc| doc.id }.join(','), :session_key => user.session_key) }
     end
     
-    # Searches for documents matching a query. This method is called with a hash
-    # of options to documents by their content. You must at a minimum supply a
-    # +query+ option, with a string that will become the full-text search query.
-    # For a list of other supported options, please see the online API
-    # documentation at http://www.scribd.com/platform/documentation?method_name=docs.search&subtab=api
+    # === Finding by query
+    #
+    # This method is called with a scope and a hash of options to documents by
+    # their content. You must at a minimum supply a +query+ option, with a
+    # string that will become the full-text search query. For a list of other
+    # supported options, please see the online API documentation at
+    # http://www.scribd.com/publisher/api?method_name=docs.search
+    #
+    # The scope can be any value given for the +scope+ parameter in the above
+    # website, or <tt>:first</tt> to return the first result only (not an array
+    # of results).
+    #
+    # The +num_results+ option has been aliased as +limit+, and the +num_start+
+    # option has been aliased as +offset+.
     #
     # Documents returned from this method will have their +owner+ attributes set
     # to nil.
+    #
+    #  Scribd::Document.find(:all, :query => 'cats and dogs', :limit => 10)
+    #
+    # === Finding by ID
+    #
+    # Passing in simply a numerical ID loads the document with that ID. You can
+    # pass additional options as defined at
+    # httphttp://www.scribd.com/publisher/api?method_name=docs.getSettings
+    #
+    #  Scribd::Document.find(108196)
+    #
+    # For now only documents that belong to the current user can be accessed in
+    # this manner.
     
-    def self.find(options)
-      raise ArgumentError, "The find method takes a hash of options" unless options.kind_of? Hash
-      raise ArgumentError, "You must specify the query option" unless options[:query]
+    def self.find(scope, options={})
+      doc_id = scope if scope.kind_of?(Integer)
+      raise ArgumentError, "You must specify a query or document ID" unless options[:query] or doc_id
       
-      options[:scope] ||= 'all'
-      
-      response = API.instance.send_request('docs.search', options)
-      documents = []
-      response.elements['/rsp/result_set'].elements.each do |doc|
-        documents << Document.new(:xml => doc)
+      if doc_id then
+        options[:doc_id] = doc_id
+        response = API.instance.send_request('docs.getSettings', options)
+        return Document.new(:xml => response.elements['/rsp'])
+      else
+        options[:scope] = scope == :first ? 'all' : scope.to_s
+        options[:num_results] = options[:limit]
+        options[:num_start] = options[:offset]
+        response = API.instance.send_request('docs.search', options)
+        documents = []
+        response.elements['/rsp/result_set'].elements.each do |doc|
+          documents << Document.new(:xml => doc)
+        end
+        return scope == :first ? documents.first : documents
       end
-      return documents
     end
     
     # Synonym for create.
@@ -200,7 +231,7 @@ module Scribd
     #
     # The conversion status is returned as a string. For a full list of
     # conversion statuses, see the online API documentation at
-    # http://www.scribd.com/platform/documentation?method_name=docs.getConversionStatus&subtab=api
+    # http://www.scribd.com/publisher/api?method_name=docs.getConversionStatus
     #
     # Unlike other properties of a document, this is retrieved from the server
     # every time it's queried.
@@ -229,5 +260,19 @@ module Scribd
     def owner=(newuser) #:nodoc:
       saved? ? raise(NotImplementedError, "Cannot change a document's owner once the document has been saved") : super
     end
+    
+    # Retrieves a document's download URL. You can provide a format for the
+    # download. Valid formats are listed at
+    # http://www.scribd.com/publisher/api?method_name=docs.getDownloadUrl
+    #
+    # If you do not provide a format, the link will be for the document's
+    # original format.
+    
+    def download_url(format='original')
+      @download_urls[format] ||= begin
+        response = API.instance.send_request('docs.getDownloadUrl', :doc_id => self.id, :doc_type => format)
+        response.elements['/rsp/download_link'].cdatas.first.to_s
+      end
+    end
   end
 end

data/lib/scribdresource.rb

@@ -143,7 +143,12 @@ module Scribd
     def load_attributes(xml)
       @attributes.clear
       xml.each_element do |element|
-        text = element.text.chomp.strip.empty? ? element.cdatas.first.value : element.text
+        text = if element.text.nil? or element.text.chomp.strip.empty? then
+          element.cdatas ? element.cdatas.first.value : nil
+        else
+          element.text
+        end
+        
         @attributes[element.name.to_sym] = if element.attributes['type'] == 'integer' then
           text.to_i
         elsif element.attributes['type'] == 'float' then

data/lib/scribduser.rb

@@ -18,7 +18,7 @@ module Scribd
   #  user = Scribd::API.instance.user
   #
   # For information on a user's attributes, please consult the online API
-  # documentation at http://www.scribd.com/platform/documentation?method_name=user.login&subtab=api
+  # documentation at http://www.scribd.com/publisher/api?method_name=user.login
   #
   # You can create a new account with the signup (a.k.a. create) method:
   #
@@ -69,7 +69,7 @@ module Scribd
     # Scribd::Document instances returned through this method have more
     # attributes than those returned by the Scribd::Document.find method. The
     # additional attributes are documented online at
-    # http://www.scribd.com/platform/documentation?method_name=docs.getSettings&subtab=api
+    # http://www.scribd.com/publisher/api?method_name=docs.getSettings
     
     def documents
       response = API.instance.send_request('docs.getList', { :session_key => @attributes[:session_key] })

data/sample/02_user.rb

@@ -32,7 +32,7 @@ begin
     end
   end
 
-  results = Scribd::Document.find(:query => 'checklist') # Search over the user's docs for the string 'cat'
+  results = Scribd::Document.find(:all, :query => 'checklist') # Search over the user's docs for the string 'checklist'
   puts "Search through docs turned up #{results.size} results:"
   for doc in results
     puts "#{doc.title}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rscribd
 version: !ruby/object:Gem::Version 
-  version: 0.0.5
+  version: 0.1.0
 platform: ruby
 authors: 
 - Jared Friedman
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-09-25 00:00:00 -07:00
+date: 2008-10-01 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -32,7 +32,7 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 1.7.0
     version: 
-description: "== DESCRIPTION:  This gem provides a simple and powerful library for the Scribd API, allowing you to write Ruby applications or Ruby on Rails websites that upload, convert, display, search, and control documents in many formats. For more information on the Scribd platform, visit http://www.scribd.com/platform  == FEATURES:  * Upload your documents to Scribd's servers and access them using the gem * Upload local files or from remote web sites * Search, tag, and organize documents * Associate documents with your users' accounts"
+description: "== DESCRIPTION:  This gem provides a simple and powerful library for the Scribd API, allowing you to write Ruby applications or Ruby on Rails websites that upload, convert, display, search, and control documents in many formats. For more information on the Scribd platform, visit http://www.scribd.com/publisher  == FEATURES:  * Upload your documents to Scribd's servers and access them using the gem * Upload local files or from remote web sites * Search, tag, and organize documents * Associate documents with your users' accounts"
 email: api@scribd.com
 executables: []