rscribd 1.1.0 → 1.2.0

data/lib/scribd/collection.rb

@@ -0,0 +1,96 @@
+module Scribd
+  
+  # A collection on Scribd is a list of {Document Documents} created and
+  # maintained by a user.
+  #
+  # @Collection@ instances and retrieved via the {User#collections} method.
+  # @Collections@ cannot be modified using the gem or the API. You can, however,
+  # {#add} and {#remove} {Document Documents} from a @Collection@.
+  
+  class Collection < Resource
+    # @private
+    DOCUMENT_MISSING_ERROR_CODE = 652
+    # @private
+    DOCUMENT_EXISTS_ERROR_CODE = 653
+    
+    # @return [Scribd::User] The user that created this collection.
+    attr_reader :owner
+    
+    # @private
+    def initialize(options={})
+      super
+      if options[:xml] then
+        load_attributes(options[:xml])
+        @owner = options[:owner]
+        @saved = true
+        @created = true
+      else
+        raise "Collections cannot be created, only retrieved."
+      end
+    end
+    
+    # Adds a {Document} to this collection.
+    #
+    # @param [Scribd::Document] document The document to add.
+    # @param [true, false] ignore_if_exists If @false@, raises an exception if
+    # the document is already in the collection.
+    # @return [Scribd::Document] The @document@ parameter.
+    # @raise [ArgumentError] If an invalid value for @document@ is provided.
+    # @raise [Scribd::ResponseError] If @ignore_if_exists@ is set to @false@ and
+    # the document already exists in the collection. See the online API
+    # documentation for more information.
+    
+    def add(document, ignore_if_exists=true)
+      raise ArgumentError, "You can only add Scribd::Documents to collections" unless document.kind_of?(Scribd::Document)
+      begin
+        API.instance.send_request 'docs.addToCollection', :collection_id => collection_id, :doc_id => document.id, :session_key => owner.session_key
+      rescue ResponseError => err
+        raise unless ignore_if_exists
+        raise if err.code.to_i != DOCUMENT_EXISTS_ERROR_CODE
+      end
+      return document
+    end
+    
+    # @see #add
+    
+    def <<(document)
+      add document
+    end
+    
+    # Removes a {Document} from this collection.
+    #
+    # @param [Scribd::Document] document The document to remove.
+    # @param [true, false] ignore_if_missing If @false@, raises an exception if
+    # the document is not in the collection.
+    # @return [Scribd::Document] The @document@ parameter.
+    # @raise [ArgumentError] If an invalid value for @document@ is provided.
+    # @raise [Scribd::ResponseError] If @ignore_if_missing@ is set to @false@
+    # and the document does not exist in the collection. See the online API
+    # documentation for more information.
+    
+    def remove(document, ignore_if_missing=true)
+      raise ArgumentError, "You can only remove Scribd::Documents from collections" unless document.kind_of?(Scribd::Document)
+      begin
+        API.instance.send_request 'docs.removeFromCollection', :collection_id => collection_id, :doc_id => document.id, :session_key => owner.session_key
+      rescue ResponseError => err
+        raise unless ignore_if_missing
+        raise if err.code.to_i != DOCUMENT_MISSING_ERROR_CODE
+      end
+      return document
+    end
+    
+    alias_method :delete, :remove
+    
+    # @return [String] The @collection_id@ attribute.
+    
+    def id
+      collection_id
+    end
+    
+    # @return [String] The @collection_name@ attribute.
+    
+    def name
+      collection_name
+    end
+  end
+end

data/lib/{scribddoc.rb → scribd/document.rb}

@@ -1,56 +1,70 @@
 require 'uri'
+require 'open-uri'
 
 module Scribd
   
   # A document as shown on the Scribd website. API programs can upload documents
-  # from files or URL's, tag them, and change their settings. An API program can
+  # from files or URLs, tag them, and change their settings. An API program can
   # access any document, but it can only modify documents owned by the logged-in
   # user.
   #
-  # To upload a new document to Scribd, you must create a new Document instance,
-  # set the +file+ attribute to the file's path, and then save the document:
+  # To upload a new document to Scribd, you must create a new {Document}
+  # instance, set the @file@ attribute to the file's path, and then save the
+  # document:
   #
-  #  doc = Scribd::Document.new
-  #  doc.file = '/path/or/URL/of/file.txt'
-  #  doc.save
+  # <pre><code>
+  # doc = Scribd::Document.new
+  # doc.file = '/path/or/URL/of/file.txt'
+  # doc.save
+  # </code></pre>
   #
   # You can do this more simply with one line of code:
   #
-  #  doc = Scribd::Document.create :file => '/path/or/URL/of/file.txt'
+  # <pre><code>doc = Scribd::Document.create :file => '/path/or/URL/of/file.txt'</code></pre>
   #
   # If you are uploading a file that does not have an extension (like ".txt"),
-  # you need to specify the +type+ attribute as well:
+  # you need to specify the @type@ attribute as well:
   #
-  #  doc = Scribd::Document.upload :file => 'CHANGELOG', :type => 'txt'
+  # <pre><code>doc = Scribd::Document.upload :file => 'CHANGELOG', :type => 'txt'</code></pre>
   #
   # 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/developers/api?method_name=docs.search (consult the
-  # "Result explanation" section).
+  # list of attributes.
   #
   # These attributes can be accessed or changed directly
-  # (<tt>doc.title = 'Title'</tt>). You must save a document after changing its
+  # (@doc.title = 'Title'@). You must save a document after changing its
   # attributes in order for those changes to take effect. Not all attributes can
   # be modified; see the API documentation online for details.
   #
-  # A document can be associated with a Scribd::User via the +owner+ attribute.
-  # This is not always the case, however. Documents retrieved from the find
-  # method will not be associated with their owners.
+  # A document can be associated with a Scribd::User via the @owner@ attribute.
+  # This is not always the case, however. {Document Documents} retrieved from
+  # the {.find} method will not be associated with their owners.
   #
-  # The +owner+ attribute is read/write, however, changes made to it only apply
+  # The @owner@ attribute is read/write, however, changes made to it only apply
   # _before_ the document is saved. Once it is saved, the owner is set in stone
   # and cannot be modified:
   #
-  #  doc = Scribd::Document.new :file => 'test.txt'
-  #  doc.user = Scribd::User.signup(:username => 'newuser', :password => 'newpass', :email => 'your@email.com')
-  #  doc.save #=> Uploads the document as "newuser", regardless of who the Scribd API user is
-  #  doc.user = Scribd::API.instance.user #=> raises NotImplementedError 
+  # <pre><code>
+  # doc = Scribd::Document.new :file => 'test.txt'
+  # doc.user = Scribd::User.signup(:username => 'newuser', :password => 'newpass', :email => 'your@email.com')
+  # doc.save #=> Uploads the document as "newuser", regardless of who the Scribd API user is
+  # doc.user = Scribd::API.instance.user #=> raises NotImplementedError
+  #</code></pre>
+  #
+  # h2. Special attributes
+  #
+  # Normally any attributes other than @file@ and @type@ are sent to and dealt
+  # by the API; however, there are a few attributes you can set on an instance
+  # that have special meaning:
+  #
+  # | @thumbnail@ | Set this to the path to, a @File@ object for, or the URL string for an image file you want to act as the document's thumbnail. Note that for URLs, the thumbnail will be downloaded to memory before being transmitted to the Scribd API server. |
   
   class Document < Resource
     
     # Creates a new, unsaved document with the given attributes. The document
     # must be saved before it will appear on the website.
+    #
+    # @param [Hash] options The document's attributes.
     
     def initialize(options={})
       super
@@ -70,23 +84,24 @@ module Scribd
     # changed attributes and saves it. Returns true if the save completed
     # successfully. Throws an exception if save fails.
     #
-    # For first-time saves, you must have specified a +file+ attribute. This can
+    # For first-time saves, you must have specified a @file@ attribute. This can
     # either be a local path to a file, or an HTTP, HTTPS, or FTP URL. In either
     # case, the file at that location will be uploaded to create the document.
     #
-    # If you create a document, specify the +file+ attribute again, and then
+    # If you create a document, specify the @file@ attribute again, and then
     # save it, Scribd replaces the existing document with the file given, while
     # keeping all other properties (title, description, etc.) the same, in a
     # process called _revisioning_.
     #
-    # This method can throw a +Timeout+ exception if the connection is slow or
-    # inaccessible. A Scribd::ResponseError will be thrown if a remote problem
-    # occurs. A Scribd::PrivilegeError will be thrown if you try to upload a new
-    # revision for a document with no associated user (i.e., one retrieved from
-    # the find method).
-    #
-    # You must specify the +type+ attribute alongside the +file+ attribute if
+    # You must specify the @type@ attribute alongside the @file@ attribute if
     # the file's type cannot be determined from its name.
+    #
+    # @raise [Timeout] If the connection is slow or inaccessible.
+    # @raise [Scribd::ResponseError] If a remote problem occurs.
+    # @raise [Scribd::PrivilegeError] If you try to upload a new revision for a
+    # document with no associated user (i.e., one retrieved from the {.find}
+    # method).
+    # @return [true, false] Whether or not the upload was successful.
     
     def save
       if not created? and @attributes[:file].nil? then
@@ -100,6 +115,7 @@ module Scribd
       # Make a request form
       response = nil
       fields = @attributes.dup
+      fields.delete :thumbnail
       fields[:session_key] = fields.delete(:owner).session_key if fields[:owner]
       if file = @attributes[:file] then
         fields.delete :file
@@ -136,6 +152,24 @@ module Scribd
         load_attributes(xml)
         @created = true
       end
+
+      if thumb = fields.delete(:thumbnail) then
+        begin
+          uri = URI.parse(thumb)
+        rescue URI::InvalidURIError
+          uri = nil
+        end
+
+        file = nil
+        if uri.kind_of?(URI::HTTP) or uri.kind_of?(URI::HTTPS) or uri.kind_of?(URI::FTP) then
+          file = open(uri)
+        elsif uri.kind_of?(URI::Generic) or uri.nil? then
+          file = thumb.kind_of?(File) ? thumb : File.open(thumb, 'rb')
+        end
+
+        API.instance.send_request('docs.uploadThumb', :file => file, :doc_id => self.id)
+        file.close
+      end
       
       fields.delete :access if fields[:file] # when uploading a doc, don't send access twice
       fields.delete :file
@@ -160,6 +194,13 @@ module Scribd
     
     # Quickly updates an array of documents with the given attributes. The
     # documents can have different owners, but all of them must be modifiable.
+    #
+    # @param [Array<Scribd::Document>] docs An array of documents to update.
+    # @param [Hash] options The attributes to assign to all of those documents.
+    # @raise [ArgumentError] If an invalid value for @docs@ is given.
+    # @raise [ArgumentError] If an invalid value for @options@ is given.
+    # @raise [ArgumentError] If one or more documents cannot be modified because
+    # it has no owner (e.g., it was retrieved from a call to {.find}).
     
     def self.update_all(docs, options)
       raise ArgumentError, "docs must be an array" unless docs.kind_of? Array
@@ -170,48 +211,49 @@ module Scribd
       docs_by_user = docs.inject(Hash.new { |hash, key| hash[key] = Array.new }) { |hash, doc| hash[doc.owner] << doc; hash }
       docs_by_user.each { |user, doc_list| API.instance.send_request 'docs.changeSettings', options.merge(:doc_ids => doc_list.collect(&:id).join(','), :session_key => user.session_key) }
     end
-    
-    # === 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/developers/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+.
+
+    # @overload find(options={})
+    #   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.
     #
-    # Documents returned from this method will have their +owner+ attributes set
-    # to nil.
+    #   Documents retrieved by this method have no {User} stored in their
+    #   @owner@ attribute; in other words, they cannot be modified.
     #
-    #  Scribd::Document.find(:all, :query => 'cats and dogs', :limit => 10)
+    #   @param [Hash] options Options for the search.
+    #   @option options [String] :query The search query (required).
+    #   @option options [Fixnum] :limit An alias for the @num_results@ option.
+    #   @option options [Fixnum] :offset An alias for the @num_start@ option.
+    #   @return [Array<Scribd::Document>] An array of documents found.
+    #   @example
+    #     Scribd::Document.find(:all, :query => 'cats and dogs', :limit => 10)
     #
-    # === Finding by ID
+    # @overload find(id, options={})
+    #   Passing in simply a numerical ID loads the document with that ID. You
+    #   can pass additional options as defined in the API documentation.
     #
-    # Passing in simply a numerical ID loads the document with that ID. You can
-    # pass additional options as defined at
-    # httphttp://www.scribd.com/developers/api?method_name=docs.getSettings
+    #   For now only documents that belong to the current user can be accessed
+    #   in this manner.
     #
-    #  Scribd::Document.find(108196)
+    #   @param [Fixnum] id The Scribd ID of the document to locate.
+    #   @param [Hash] options Options to pass to the API find method.
+    #   @return [Scribd::Document] The document found.
+    #   @return [nil] If nothing was found.
+    #   @example
+    #     Scribd::Document.find(108196)
     #
-    # For now only documents that belong to the current user can be accessed in
-    # this manner.
+    # @raise [ArgumentError] If neither of the two correct argument forms is
+    # provided.
     
-    def self.find(scope, options={})
-      doc_id = scope.kind_of?(Integer) ? scope : nil
-      raise ArgumentError, "You must specify a query or document ID" unless options[:query] or doc_id
+    def self.find(options={})
+      doc_id = options.kind_of?(Integer) ? options : nil
+      raise ArgumentError, "You must specify a query or document ID" unless doc_id or (options.kind_of?(Hash) and options[:query])
       
       if doc_id then
-        options[:doc_id] = doc_id
-        response = API.instance.send_request('docs.getSettings', options)
+        response = API.instance.send_request('docs.getSettings', :doc_id => doc_id)
         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)
@@ -219,55 +261,54 @@ module Scribd
         response.elements['/rsp/result_set'].elements.each do |doc|
           documents << Document.new(:xml => doc)
         end
-        return scope == :first ? documents.first : documents
+        return documents
       end
     end
 
-    # === Featured docs
+    # Returns featured documents found in a given with given options.
     #
-    # This method is called with a scope and a hash of options. For a list of
-    # supported options, please see the online API documentation at
-    # http://www.scribd.com/developers/api?method_name=docs.featured
+    # This method is called with a hash of options. For a list of supported
+    # options, please see the online API documentation.
     #
-    # The scope can be either <tt>:first</tt> to return the first result only (not an array
-    # of results) or <tt>:all</tt> to return an array. Include a +scope+ option
-    # to control the parameter described in the API documentation.
+    # Documents returned from this method will have their @owner@ attributes set
+    # to @nil@ (i.e., they are read-only).
     #
-    #  Scribd::Document.featured(:all, :scope => 'hot', :limit => 10)
-    #
-    # Documents returned from this method will have their +owner+ attributes set
-    # to nil.
+    # @param [Hash] options Options to pass to the API find method.
+    # @return [Array<Scribd::Document>] An array of documents found.
+    # @example
+    #   Scribd::Document.featured(:scope => 'hot', :limit => 10)
 
-    def self.featured(scope, options = {})
+    def self.featured(options = {})
       response = API.instance.send_request('docs.featured', options)
       documents = []
       response.elements['/rsp/result_set'].elements.each do |doc|
         documents << Document.new(:xml => doc)
       end
-      scope == :first ? documents.first : documents
+      return documents
     end
 
-    # === Browse docs
-    #
-    # This method is called with a scope and a hash of options. For a list of
-    # supported options, please see the online API documentation at
-    # http://www.scribd.com/developers/api?method_name=docs.browse
+    # Returns documents found by the Scribd browser with given options. The
+    # browser provides documents suitable for a browse page.
     #
-    # The scope can be either <tt>:first</tt> to return the first result only (not an array
-    # of results) or <tt>:all</tt> to return an array.
+    # This method is called with a hash of options. For a list of supported
+    # options, please see the online API documentation.
     #
-    #  Scribd::Document.browse(:all, :sort => 'views', :category_id => 1, :limit => 10)
+    # Documents returned from this method will have their @owner@ attributes set
+    # to @nil@ (i.e., they are read-only).
     #
-    # Documents returned from this method will have their +owner+ attributes set
-    # to nil.
+    # @param [Hash] options Options to pass to the API find method.
+    # @return [Array<Scribd::Document>] An array of documents found.
+    # @example
+    #   Scribd::Document.browse(:sort => 'views', :limit => 10)
+    # @see Scribd::Category#browse
 
-    def self.browse(scope, options = {})
+    def self.browse(options = {})
       response = API.instance.send_request('docs.browse', options)
       documents = []
       response.elements['/rsp/result_set'].elements.each do |doc|
         documents << Document.new(:xml => doc)
       end
-      scope == :first ? documents.first : documents
+      return documents
     end
 
     class << self
@@ -279,20 +320,25 @@ module Scribd
     # non-blocking; you can query this method to determine whether the document
     # is ready to be displayed.
     #
-    # 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/developers/api?method_name=docs.getConversionStatus
+    # For a full list of conversion statuses, see the online API documentation.
     #
     # Unlike other properties of a document, this is retrieved from the server
     # every time it's queried.
+    #
+    # @return [String] The document's conversion status.
     
     def conversion_status
       response = API.instance.send_request('docs.getConversionStatus', :doc_id => self.id)
       response.elements['/rsp/conversion_status'].text
     end
 
-    # Returns the document read count. This is only retrieved from the server the first time it's queried.
-    # To force re-retrieval on subsequent calls include :force => true in the options parameter.
+    # Returns the document read count. This is only retrieved from the API
+    # server the first time it's queried unless @force@ is set to @true@.
+    #
+    # @param [Hash] options A hash of options.
+    # @option options [true, false] :force If true, clears the local cache for
+    # this value and re-retrieves it from the API server.
+    # @return [String] The number of reads this document has received.
 
     def reads(options = {})
       if @reads.nil? || options[:force]
@@ -302,32 +348,64 @@ module Scribd
       @reads
     end
 
-    # Deletes a document. Returns true if successful.
+    # Deletes a document.
+    #
+    # @return [true, false] Whether or not the document was successfully
+    # deleted.
     
     def destroy
       response = API.instance.send_request('docs.delete', :doc_id => self.id)
       return response.elements['/rsp'].attributes['stat'] == 'ok'
     end
     
-    # Returns the +doc_id+ attribute.
+    # Grants a user access to this document.
+    #
+    # @param [String] user_identifier The user identifier as used in your embed
+    # code.
+    # @see Scribd::Security.grant_access
     
-    def id
-      self.doc_id
+    def grant_access(user_identifier)
+      Scribd::Security.grant_access user_identifier, self
+    end
+    
+    # Revokes access to this document from a user.
+    #
+    # @param [String] user_identifier The user identifier as used in your embed
+    # code.
+    # @see Scribd::Security.revoke_access
+    
+    def revoke_access(user_identifier)
+      Scribd::Security.revoke_access user_identifier, self
+    end
+    
+    # @return [Array<String>] A list of user identifiers that have access to
+    # this document.
+    # @see Scribd::Security.document_access_list
+    
+    def access_list
+      Scribd::Security.document_access_list(self)
     end
     
-    # Ensures that the +owner+ attribute cannot be set once the document is
-    # saved.
+    # @return The @document_id@ attribute.
     
-    def owner=(newuser) #:nodoc:
+    def id
+      self.doc_id
+    end
+
+    # @private
+    def owner=(newuser)
+      # don't allow them to set the owner if the document is saved
       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/developers/api?method_name=docs.getDownloadUrl
+    # download. Valid formats are listed in the online API documentation.
     #
     # If you do not provide a format, the link will be for the document's
     # original format.
+    #
+    # @param [String] format The download format.
+    # @return [String] The download URL.
     
     def download_url(format='original')
       @download_urls[format] ||= begin