rscribd 1.1.0 → 1.2.0

data/lib/{scribderrors.rb → scribd/errors.rb}

@@ -11,9 +11,9 @@ module Scribd
   # Raised when trying to perform an action that isn't allowed for the current
   # active user. Note that this exception is thrown only if the error originates
   # locally. If the request must go out to the Scribd server before the
-  # privilege error occurs, a Scribd::ResponseError will be thrown. Unless a
+  # privilege error occurs, a {Scribd::ResponseError} will be thrown. Unless a
   # method's documentation indicates otherwise, assume that the error will
-  # originate remotely and a Scribd::ResponseError will be thrown.
+  # originate remotely and a {Scribd::ResponseError} will be thrown.
   
   class PrivilegeError < StandardError; end
   
@@ -22,11 +22,10 @@ module Scribd
   # their descriptions for each API method.
   
   class ResponseError < RuntimeError
-    # The error code.
+    # @return [Fixnum, String] The error code.
     attr_reader :code
     
-    # Initializes the error with a given code.
-    
+    # @private
     def initialize(code)
       @code = code
     end

data/lib/{scribdresource.rb → scribd/resource.rb}

@@ -1,36 +1,44 @@
 module Scribd
   
   # Describes a remote object that the Scribd API lets you interact with. All
-  # such objects are modeled after the <tt>ActiveRecord</tt> ORM approach.
+  # such objects are modeled after the Active Record ORM approach.
   #
-  # The Resource superclass is never directly used; you will interact with
-  # actual Scribd entities like Document and User, which inherit functionality
-  # from this superclass.
+  # The @Resource@ superclass is never directly used; you will interact with
+  # actual Scribd entities like {Document} and {User}, which inherit
+  # functionality from this superclass.
   #
   # Objects have one or more attributes (also called fields) that can be
   # accessed directly through synonymous methods. For instance, if your resource
-  # has an attribute +title+, you can get and set the title like so:
+  # has an attribute @title@, you can get and set the title like so:
   #
-  #  obj.title #=> "Title"
-  #  obj.title = "New Title"
+  # <pre><code>
+  #   obj.title #=> "Title"
+  #   obj.title = "New Title"
+  # </code></pre>
   #
-  # The specific attributes that a Document or a User or any other resource has
-  # are not stored locally. They are downloaded remotely whenever a resource is
-  # loaded from the remote server. Thus, you can modify any attribute you want,
-  # though it may or may not have any effect:
+  # The specific attributes that a {Document} or a {User} or any other resource
+  # has are not saved locally. They are downloaded remotely whenever a resource
+  # is loaded from the remote server. Thus, you can modify any attribute you
+  # want, though it may or may not have any effect:
   #
-  #  doc = Scribd::Document.find(:text => 'foo').first
-  #  doc.self_destruct_in = 5.seconds #=> Does not produce error
-  #  doc.save #=> Has no effect, since that attribute doesn't exist. Your document does not explode.
+  # <pre><code>
+  #   doc = Scribd::Document.find(:text => 'foo').first
+  #   doc.self_destruct_in = 5.seconds #=> Does not produce error
+  #   doc.save #=> Has no effect, since that attribute doesn't exist. Your document does not explode.
+  # </code></pre>
   #
   # As shown above, when you make changes to an attribute, these changes are not
   # immediately reflected remotely. They are only stored locally until such time
   # as save is called. When you call save, the remote object is updated to
   # reflect the changes you made in its API instance.
+  #
+  # @abstract
   
   class Resource
     
     # Initializes instance variables.
+    #
+    # @param [Hash] options Initial attributes for the new object.
     
     def initialize(options={})
       @saved = false
@@ -39,8 +47,11 @@ module Scribd
     end
     
     # Creates a new instance with the given attributes, saves it immediately,
-    # and returns it. You should call its created? method if you need to verify
-    # that the object was saved successfully.
+    # and returns it. You should call its {#created?} method if you need to
+    # verify that the object was saved successfully.
+    #
+    # @param [Hash] options Initial attributes for the new object.
+    # @return [Scribd::Resource] The new object.
     
     def self.create(options={})
       obj = new(options)
@@ -48,49 +59,56 @@ module Scribd
       obj
     end
     
-    # Throws NotImplementedError by default.
-    
+    # @abstract This method is implemented by subclasses.
+
     def save
       raise NotImplementedError, "Cannot save #{self.class.to_s} objects"
     end
     
-    # Throws NotImplementedError by default.
-    
+    # @abstract This method is implemented by subclasses.
+
     def self.find(options)
       raise NotImplementedError, "Cannot find #{self.class.to_s} objects"
     end
     
-    # Throws NotImplementedError by default.
+    # @abstract This method is implemented by subclasses.
     
     def destroy
       raise NotImplementedError, "Cannot destroy #{self.class.to_s} objects"
     end
     
-    # Returns true if this document's attributes have been updated remotely, and
-    # thus their local values reflect the remote values.
+    # @return [true, false] Whether this resource's attributes have been updated
+    # remotely, and thus their local values reflect the remote values.
     
     def saved?
       @saved
     end
     
-    # Returns true if this document has been created remotely, and corresponds
-    # to a document on the Scribd website.
+    # @return [true, false] Whether this resource has been created remotely, and
+    # corresponds to something on the Scribd website.
     
     def created?
       @created
     end
     
-    # Returns the value of an attribute, referenced by string or symbol, or nil
-    # if the attribute cannot be read.
+    # Returns the value of an attribute.
+    #
+    # @param [#to_sym] attribute The attribute to read.
+    # @return [String] The value of the attribute.
+    # @return [nil] If the attribute could not be read.
+    # @raise [ArgumentError] If an invalid value for @attribute@ is given.
     
     def read_attribute(attribute)
       raise ArgumentError, "Attribute must respond to to_sym" unless attribute.respond_to? :to_sym
       @attributes[attribute.to_sym]
     end
     
-    # Returns a map of attributes to their values, given an array of attributes,
-    # referenced by string or symbol. Attributes that cannot be read are
-    # ignored.
+    # Returns a map of attributes to their values, given an array of attributes.
+    # Attributes that cannot be read are ignored.
+    #
+    # @param [Enumerable<String, Symbol>] attributes The attributes to read.
+    # @return [Hash<Symbol -> String] The attribute values.
+    # @raise [ArgumentError] If an invalid value for @attributes@ is provided.
     
     def read_attributes(attributes)
       raise ArgumentError, "Attributes must be listed in an Enumeration" unless attributes.kind_of?(Enumerable)
@@ -101,8 +119,12 @@ module Scribd
     end
     
     # Assigns values to attributes. Takes a hash that specifies the
-    # attribute-value pairs to update. Does not perform a save. Non-writeable
+    # attribute-value pairs to update. Does not perform a save. Non-writable
     # attributes are ignored.
+    #
+    # @param [Hash<#to_sym -> #to_s>] values The values to update and their new
+    # values.
+    # @raise [ArgumentError] If an invalid value for @values@ is provided.
     
     def write_attributes(values)
       raise ArgumentError, "Values must be specified through a hash of attributes" unless values.kind_of? Hash
@@ -114,15 +136,17 @@ module Scribd
     # retrieved for changed through a method call, even if it doesn't exist.
     # Such attributes will be ignored and purged when the document is saved:
     #
-    #  doc = Scribd::Document.new
-    #  doc.foobar #=> Returns nil
-    #  doc.foobar = 12
-    #  doc.foobar #=> Returns 12
-    #  doc.save
-    #  doc.foobar #=> Returns nil
+    # <pre><code>
+    # doc = Scribd::Document.new
+    # doc.foobar #=> Returns nil
+    # doc.foobar = 12
+    # doc.foobar #=> Returns 12
+    # doc.save
+    # doc.foobar #=> Returns nil
+    # </code></pre>
     #
-    # Because of this, no Scribd resource will ever raise NoMethodError.
-    
+    # Because of this, no Scribd resource will ever raise @NoMethodError@.
+
     def method_missing(meth, *args)
       if meth.to_s =~ /(\w+)=/ then
         raise ArgumentError, "Only one parameter can be passed to attribute=" unless args.size == 1
@@ -132,9 +156,8 @@ module Scribd
       end
     end
     
-    # Pretty-print for debugging output of Scribd resources.
-    
-    def inspect #:nodoc:
+    # @private
+    def inspect
       "#<#{self.class.to_s} #{@attributes.select { |k, v| not v.nil? }.collect { |k,v| k.to_s + '=' + v.to_s }.join(', ')}>"
     end
     

data/lib/scribd/security.rb

@@ -0,0 +1,102 @@
+module Scribd
+  
+  # Contains methods for working with iPaper Secure. For more information about
+  # iPaper Secure, see the online API documentation.
+  
+  module Security
+    
+    # Grants a user access to a {Document}. The user is referenced by his
+    # identifier (as used in the iPaper Secure embed code). If no document is
+    # provided, globally grants this user access to all documents.
+    #
+    # @param [String] user_identifier The user identifier as used in your embed
+    # code. (See the online iPaper Secure documentation.)
+    # @param [Scribd::Document, #to_i, nil] document If @nil@, globally grants
+    # this user access to all documents. Otherwise, grants this user access
+    # to one document specified by ID or {Document} instance.
+    # @raise [ArgumentError] If an invalid value for @document@ is provided.
+    # @see Scribd::Document#grant_access
+    
+    def self.grant_access(user_identifier, document=nil)
+      set_access user_identifier, true, document
+    end
+    
+    # Revokes from a user access to a {Document}. The user is referenced by his
+    # identifier (as used in the iPaper Secure embed code). If no document is
+    # provided, globally revokes access to all documents from this user.
+    #
+    # @param [String] user_identifier The user identifier as used in your embed
+    # code. (See the online iPaper Secure documentation.)
+    # @param [Scribd::Document, #to_i, nil] document If @nil@, globally revokes
+    # access to all documents from this user. Otherwise, revokes access to one
+    # document specified by ID or {Document} instance.
+    # @raise [ArgumentError] If an invalid value for @document@ is provided.
+    # @see Scribd::Document#revoke_access
+    
+    def self.revoke_access(user_identifier, document=nil)
+      set_access user_identifier, false, document
+    end
+    
+    # Sets whether a user has access to a {Document}. The user is referenced by
+    # his identifier (as used in the iPaper Secure embed code). If no document
+    # is provided, globally sets access to all documents for this user.
+    #
+    # @param [String] user_identifier The user identifier as used in your embed
+    # code. (See the online iPaper Secure documentation.)
+    # @param [true, false] access_allowed If @true@, grants access; if @false@,
+    # revokes access.
+    # @param [Scribd::Document, #to_i, nil] document If @nil@, globally sets
+    # access to all documents for this user. Otherwise, sets access to one
+    # document specified by ID or {Document} instance.
+    # @raise [ArgumentError] If an invalid value for @document@ is provided.
+    
+    def self.set_access(user_identifier, access_allowed, document=nil)
+      allow_value = (access_allowed ? 1 : 0)
+      
+      if document.nil? then
+        API.instance.send_request('security.setAccess', :user_identifier => user_identifier, :allowed => allow_value)
+        return
+      end
+      
+      API.instance.send_request('security.setAccess', :user_identifier => user_identifier, :allowed => allow_value, :doc_id => (
+        if document.kind_of?(Scribd::Document) then
+          document.id
+        elsif document.respond_to?(:to_i) then
+          document.to_i
+        else
+          raise ArgumentError, "document must be a Scribd::Document, a document ID, or nil"
+        end
+      ))
+    end
+    
+    # Returns a list of user identifiers that are allowed to access a given
+    # document. See the iPaper Secure online documentation for more information.
+    #
+    # @param [Scribd::Document, Fixnum] document Either a document instance or
+    # document ID.
+    # @return [Array<String>] An array of user identifiers.
+    # @see Scribd::Document#access_list
+    
+    def self.document_access_list(document)
+      response = API.instance.send_request('security.getDocumentAccessList', :doc_id => (document.kind_of?(Scribd::Document) ? document.id : document))
+      acl = Array.new
+      response.get_elements('/rsp/resultset/result/user_identifier').each { |tag| acl << tag.text }
+      return acl
+    end
+    
+    # Returns a list of documents that a user can view. The user is identified
+    # by his user identifier. See the iPaper Secure online documentation for
+    # more information.
+    #
+    # @param [String] user_identifier The user identifier.
+    # @return [Array<Scribd::Document>] An array of documents the user can
+    # access.
+    
+    def self.user_access_list(user_identifier)
+      response = API.instance.send_request('security.getUserAccessList', :user_identifier => user_identifier)
+      acl = Array.new
+      response.get_elements('/rsp/resultset/result').each { |tag| acl << Scribd::Document.new(:xml => tag) }
+      return acl
+    end
+  end
+end

data/lib/scribd/user.rb

@@ -0,0 +1,193 @@
+module Scribd
+  
+  # A user of the Scribd website. API programs can use this class to log in as a
+  # Scribd user, create new user accounts, and get information about the current
+  # user.
+  #
+  # An API program begins by logging into Scribd:
+  #
+  # <pre><code>user = Scribd::User.login 'login', 'pass'</code></pre>
+  #
+  # You can now access information about this user through direct method calls:
+  #
+  # <pre><code>user.name #=> 'Real Name'</code></pre>
+  #
+  # If, at any time, you would like to retrieve the {User} instance for the
+  # currently logged-in user, simply call:
+  #
+  # <pre><code>user = Scribd::API.instance.user</code></pre>
+  #
+  # For information on a user's attributes, please consult the online API
+  # documentation.
+  #
+  # You can create a new account with the {.signup} (a.k.a. {.create}) method:
+  #
+  # <pre><code>user = Scribd::User.signup :username => 'testuser', :password => 'testpassword', :email => your@email.com</code></pre>
+  
+  class User < Resource
+    
+    # Creates a new, unsaved user with the given attributes. You can eventually
+    # use this record to create a new Scribd account.
+    #
+    # @param [Hash] options The initial attributes for the user.
+    
+    def initialize(options={})
+      super
+      if options[:xml] then
+        load_attributes(options[:xml])
+        @saved = true
+        @created = true
+      else
+        @attributes = options
+      end
+    end
+    
+    # For new, unsaved records, creates a new Scribd user with the provided
+    # attributes, then logs in as that user. Currently modification of existing
+    # Scribd users is not supported.
+    #
+    # @raise [Scribd::ResponseError] If a remote error occurs.
+    
+    def save
+      if not created? then
+        response = API.instance.send_request('user.signup', @attributes)
+        xml = response.get_elements('/rsp')[0]
+        load_attributes(xml)
+        API.instance.user = self
+      else
+        raise NotImplementedError, "Cannot update a user once that user's been saved"
+      end
+    end
+    
+    # Returns a list of documents owned by this user. By default, the size of
+    # the returned list is capped at 1,000. Use the @:limit@ and @:offset@
+    # parameters to page through this user's documents; however, @:limit@ cannot
+    # be greater than 1,000. This list is _not_ backed by the server, so if you
+    # add or remove items from it, it will not make those changes server-side.
+    # This also has some tricky consequences when modifying a list of documents
+    # while iterating over it:
+    #
+    # <pre><code>
+    # docs = user.documents
+    # docs.each(&:destroy)
+    # docs #=> Still populated, because it hasn't been updated
+    # docs = user.documents #=> Now it's empty
+    # </code></pre>
+    #
+    # {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.
+    #
+    # @param [Hash] options Options to provide to the API find method.
+    # @return [Array<Scribd::Document>] The found documents.
+    # @see #find_documents
+    
+    def documents(options = {})
+      response = API.instance.send_request('docs.getList', options.merge(:session_key => @attributes[:session_key]))
+      documents = Array.new
+      response.elements['/rsp/resultset'].elements.each do |doc|
+        documents << Document.new(:xml => doc, :owner => self)
+      end
+      return documents
+    end
+    
+    # Finds documents owned by this user matching a given query. The parameters
+    # provided to this method are identical to those provided to {.find}.
+    #
+    # @param [Hash] options Options to pass to the API find method.
+    # @see #documents
+
+    def find_documents(options={})
+      return nil unless @attributes[:session_key]
+      Document.find options.merge(:scope => 'user', :session_key => @attributes[:session_key])
+    end
+    
+    # Loads a {Document} by ID. You can only load such documents if they belong
+    # to this user.
+    #
+    # @param [Fixnum] document_id The Scribd document ID.
+    # @return [Scribd::Document] The found document.
+    # @return [nil] If nothing was found.
+    
+    def find_document(document_id)
+      return nil unless @attributes[:session_key]
+      response = API.instance.send_request('docs.getSettings', { :doc_id => document_id, :session_key => @attributes[:session_key] })
+      Document.new :xml => response.elements['/rsp'], :owner => self
+    end
+    
+    # Uploads a document to a user's document list. See the
+    # {Scribd::Document#save} method for more information on the options hash.
+    #
+    # @param [Hash] options Options to pass to the API upload method.
+    # @raise [Scribd::NotReadyError] If the user is unsaved.
+    
+    def upload(options)
+      raise NotReadyError, "User hasn't been created yet" unless created?
+      Document.create options.merge(:owner => self)
+    end
+    
+    # Returns the collections this user has created. For information about
+    # search options, see the online API documentation. The list of collections
+    # is not memoized or cached locally.
+    #
+    # @param [Hash] options Options to pass to the API collections search
+    # method.
+    # @return [Array<Scribd::Collection>] The collections created by this user.
+    # @raise [Scribd::NotReadyError] If the user is unsaved
+    
+    def collections(options={})
+      raise NotReadyError, "User hasn't been created yet" unless created?
+      response = API.instance.send_request('docs.getCollections', options.merge(:session_key => @attributes[:session_key]))
+      collections = Array.new
+      response.elements['/rsp/resultset'].elements.each do |coll|
+        collections << Collection.new(:xml => coll, :owner => self)
+      end
+      return collections
+    end
+    
+    # Returns a URL that, when visited, will automatically sign in this user and
+    # then redirect to the provided URL.
+    #
+    # @param [String] next_url The URL to redirect to after signing in. By
+    # default the user is redirected to the home page.
+    # @return [String] An auto-sign-in URL.
+    # @raise [Scribd::NotReadyError] If the receiver is not an existing user.
+    
+    def auto_sign_in_url(next_url="")
+      raise NotReadyError, "User hasn't been created yet" unless created?
+      response = API.instance.send_request('user.getAutoSignInUrl', :session_key => @attributes[:session_key], :next_url => next_url)
+      return response.get_elements('/rsp/url').first.cdatas.first.to_s
+    end
+    
+    class << self
+      alias_method :signup, :create
+    end
+    
+    # Logs into Scribd using the given username and password. This user will be
+    # used for all subsequent Scribd API calls. You must log in before you can
+    # use protected API functions.
+    #
+    # @param [String] username The Scribd user's login.
+    # @param [String] password The Scribd user's password.
+    # @return [Scribd::User] The logged-in user.
+    
+    def self.login(username, password)
+      response = API.instance.send_request('user.login', { :username => username, :password => password })
+      xml = response.get_elements('/rsp').first
+      user = User.new(:xml => xml)
+      API.instance.user = user
+      return user
+    end
+    
+    # @return [String] The @user_id@ attribute.
+    
+    def id
+      self.user_id
+    end
+
+    # @private
+    def to_s
+      @attributes[:username]
+    end
+  end
+end