rscribd 1.1.0 → 1.2.0

data/.gitignore

@@ -2,3 +2,4 @@ doc
 pkg
 .idea
 .DS_Store
+.yardoc

data/History.txt

@@ -1,3 +1,13 @@
+=== 1.2.0 / 2010-5-13
+
+* Added support for collections.
+* Added support for iPaper Secure.
+* Added support for categories.
+* Added support for the docs.uploadThumb API method.
+* Added support for the user.autoSignInUrl API method.
+* Simplified the finder methods for Users and Documents.
+* Switched from RDoc to YARD for gem documentation.
+
 === 1.1.0 / 2010-3-16
 
 * Switched from Hoe to Jeweler.

data/{README.txt → README}

@@ -1,22 +1,22 @@
-= rscribd
+h1. rscribd
 
-* 1.1.0 (March 16, 2010)
+* 1.2.0 (May 13, 2010)
 
-== DESCRIPTION:
+h2. 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
+the Scribd platform, visit the Developer web page on Scribd.
 
-== FEATURES:
+h2. 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
 
-== SYNOPSIS:
+h2. SYNOPSIS:
 
 This API allows you to use Scribd's Flash viewer on your website. You'll be able
 to take advantage of Scribd's scalable document conversion system to convert
@@ -24,41 +24,42 @@ your documents into platform-independent formats. You can leverage Scribd's
 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/developers/api to apply for a platform account.
+First, you'll need to get a Scribd API account. Visit Scribd to apply for a
+developer account.
 
 On the Platform site you will be given an API key and secret. The API object
 will need these to authenticate you:
 
-  require 'rscribd'
-  Scribd::API.instance.key = 'your API key'
-  Scribd::API.instance.secret = 'your API secret'
+<pre><code>
+require 'rscribd'
+Scribd::API.instance.key = 'your API key'
+Scribd::API.instance.secret = 'your API secret'
+</code></pre>
 
 Next, log into the Scribd website:
 
-  Scribd::User.login 'username', 'password'
+<pre><code>Scribd::User.login 'username', 'password'</code></pre>
 
 You are now ready to use Scribd to manage your documents. For instance, to
 upload a document:
 
-  doc = Scribd::Document.upload(:file => 'your-file.pdf')
+<pre><code>doc = Scribd::Document.upload(:file => 'your-file.pdf')</code></pre>
 
 For more information, please see the documentation for the Scribd::API,
 Scribd::User, and Scribd::Document classes. (You can also check out the docs for
 the other classes for a more in-depth look at this gem's features).
 
-== REQUIREMENTS:
+h2. REQUIREMENTS:
 
 * A Scribd API account
-* mime-types gem
+* Ruby 1.8 or newer, with RubyGems 1.3 or newer.
 
-== INSTALL:
+h2. INSTALL:
 
-* The client library is a RubyGem called *rscribd*. To install, type:
+* The client library is a RubyGem called *rscribd*. To install, type
+  @sudo gem install rscribd@.
 
-  sudo gem install rscribd
-
-== LICENSE:
+h2. LICENSE:
 
 (The MIT License)
 

data/Rakefile

@@ -1,5 +1,6 @@
 require 'rubygems'
 require 'spec/rake/spectask'
+require 'yard'
 
 begin
   require 'jeweler'
@@ -10,17 +11,35 @@ begin
     gemspec.email = "api@scribd.com"
     gemspec.homepage = "http://www.scribd.com/developers"
     gemspec.authors = [ "Tim Morgan", "Jared Friedman", "Mike Watts" ]
+    gemspec.rubyforge_project = "rscribd"
     
     gemspec.add_dependency 'mime-types'
     gemspec.add_development_dependency "rspec"
+    gemspec.add_development_dependency "yard"
+  end
+  Jeweler::RubyforgeTasks.new do |rubyforge|
+    rubyforge.doc_task = "rdoc"
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError
   puts "Jeweler not available. Install it with: gem install jeweler"
 end
 
+task :default => :spec
+
 desc "Verify gem specs"
 Spec::Rake::SpecTask.new do |t|
   t.spec_files = FileList['spec/*.rb']
   t.spec_opts = [ '-cfs' ]
 end
+
+desc 'Generate YARD documentation.'
+YARD::Rake::YardocTask.new(:doc) do |rdoc|
+  rdoc.options << '-o' << 'doc'
+  rdoc.options << "--title" << "RScribd Documentation".inspect
+  rdoc.options << '--charset' << 'utf-8'
+  rdoc.options << '-r' << 'README'
+  rdoc.options << '--protected' << '--no-private'
+  rdoc.options << '--markup' << 'textile'
+  rdoc.files << "lib/**/*.rb"
+end

data/VERSION

@@ -1 +1 @@
-1.1.0
+1.2.0

data/lib/rscribd.rb

@@ -1,38 +1,17 @@
 #!/usr/bin/env ruby
 
-module Scribd # :nodoc:
-end
-
-class Symbol
-  def to_proc
-    Proc.new { |*args| args.shift.__send__(self, *args) }
-  end unless method_defined?(:to_proc)
-end
-
-class Hash #:nodoc:
-   # Taken from Rails, with appreciation to DHH
-   def stringify_keys
-     inject({}) do |options, (key, value)|
-       options[key.to_s] = value
-       options
-     end
-   end unless method_defined?(:stringify_keys)
-end
+# Container module for all classes in the RScribd gem.
 
-class Array #:nodoc:
-  def to_hsh
-    h = Hash.new
-    each { |k, v| h[k] = v }
-    h
-  end
+module Scribd
 end
 
-# The reason these files have such terrible names is so they don't conflict with
-# files in Rails's app/models directory; Rails seems to prefer loading those
-# when require is called.
-require 'scribdmultiparthack'
-require 'scribderrors'
-require 'scribdapi'
-require 'scribdresource'
-require 'scribddoc'
-require 'scribduser'
+require 'support/extensions'
+require 'support/multipart_hack'
+require 'scribd/errors'
+require 'scribd/api'
+require 'scribd/resource'
+require 'scribd/category'
+require 'scribd/collection'
+require 'scribd/document'
+require 'scribd/user'
+require 'scribd/security'

data/lib/{scribdapi.rb → scribd/api.rb}

@@ -6,74 +6,87 @@ module Scribd
   
   # This class acts as the top-level interface between Scribd and your
   # application. Before you can begin using the Scribd API, you must specify for
-  # this object your API key and API secret. They are available on your
-  # Platform home page.
+  # this object your API key and API secret. They are available on your account
+  # settings page.
   #
   # This class is a singleton. Its only instance is accessed using the
-  # +instance+ class method.
+  # @instance@ class method.
   #
   # To begin, first specify your API key and secret:
   #
-  #  Scribd::API.instance.key = 'your API key here'
-  #  Scribd::API.instance.secret = 'your API secret here'
+  # <pre><code>
+  # Scribd::API.instance.key = 'your API key here'
+  # Scribd::API.instance.secret = 'your API secret here'
+  # </code></pre>
   #
-  # (If you set the +SCRIBD_API_KEY+ and +SCRIBD_API_SECRET+ Ruby environment
+  # (If you set the @SCRIBD_API_KEY@ and @SCRIBD_API_SECRET@ Ruby environment
   # variables before loading the gem, these values will be set automatically for
   # you.)
   #
   # Next, you should log in to Scribd, or create a new account through the gem.
   #
-  #  user = Scribd::User.login 'login', 'password'
+  # <pre><code>user = Scribd::User.login 'login', 'password'</code></pre>
   #
-  # You are now free to use the Scribd::User or Scribd::Document classes to work
-  # with Scribd documents or your user account.
+  # You are now free to use the {Scribd::User} or {Scribd::Document} classes to
+  # work with Scribd documents or your user account.
   #
-  # If you need the Scribd::User instance for the currently logged in user at a
-  # later point in time, you can retrieve it using the +user+ attribute:
+  # If you need the {User} instance for the currently logged in user at a later
+  # point in time, you can retrieve it using the @user@ attribute:
   #
-  #  user = Scribd::API.instance.user
+  # <pre><code>user = Scribd::API.instance.user</code></pre>
   #
   # In addition, you can save and restore sessions by simply storing this user
   # instance and assigning it to the API at a later time. For example, to
   # restore the session retrieved in the previous example:
   #
-  #  Scribd::API.instance.user = user
+  # <pre><code>Scribd::API.instance.user = user</code></pre>
   #
   # In addition to working with Scribd users, you can also work with your own
   # website's user accounts. To do this, set the Scribd API user to a string
   # containing a unique identifier for that user (perhaps a login name or a user
   # ID):
   #
-  #  Scribd::API.instance.user = my_user_object.mangled_user_id
+  # <pre><code>Scribd::API.instance.user = my_user_object.mangled_user_id</code></pre>
   #
-  # A "phantom" Scribd user will be set up with that ID, so you any documents
-  # you upload will be associated with that account.
+  # A "phantom" Scribd user will be set up with that ID, so any documents you
+  # upload will be associated with that account.
   #
   # For more hints on what you can do with the Scribd API, please see the
-  # Scribd::Document class.
+  # {Document} class.
   
   class API
     include Singleton
-    
-    HOST = 'api.scribd.com' #:nodoc:
-    PORT = 80 #:nodoc:
-    REQUEST_PATH = '/api' #:nodoc:
-    TRIES = 3 #:nodoc:
-    
-    attr_accessor :key # The API key you were given when you created a Platform account.
-    attr_accessor :secret # The API secret used to validate your key (also provided with your account).
-    attr_accessor :user # The currently logged in user.
-    attr_accessor :asynchronous # If true, requests are processed asynchronously. If false, requests are blocking.
-    attr_accessor :debug # If true, extended debugging information is printed
-    
-    def initialize #:nodoc:
+
+    # @private
+    HOST = 'api.scribd.com'
+    # @private
+    PORT = 80
+    # @private
+    REQUEST_PATH = '/api'
+    # @private
+    TRIES = 3
+
+    # @return [String] The API key you were given when you created a Platform account.
+    attr_accessor :key
+    # @return [String] The API secret used to validate your key (also provided with your account).
+    attr_accessor :secret
+    # @return [Scribd::User] The currently logged in user.
+    attr_accessor :user
+    # @return [true, false] If true, requests are processed asynchronously. If false, requests are blocking.
+    attr_accessor :asynchronous
+    # @return [true, false] If true, extended debugging information is printed
+    attr_accessor :debug
+
+    # @private
+    def initialize
       @asychronous = false
       @key = ENV['SCRIBD_API_KEY']
       @secret = ENV['SCRIBD_API_SECRET']
       @user = User.new
     end
-    
-    def send_request(method, fields={}) #:nodoc:
+
+    # @private
+    def send_request(method, fields={})
       raise NotReadyError unless @key and @secret
       # See if method is given
       raise ArgumentError, "Method should be given" if method.nil? || method.empty?
@@ -161,7 +174,7 @@ module Scribd
     # TODO: It would probably be better if we wrapped the fault
     # in something more meaningful. At the very least, a broad
     # division of errors, such as retryable and fatal. 
-    def error(el) #:nodoc:
+    def error(el)
       att = el.attributes
       fe = XMLRPC::FaultException.new(att['code'].to_i, att['msg'])
       $stderr.puts "ERR: #{fe.faultString} (#{fe.faultCode})"
@@ -177,7 +190,7 @@ module Scribd
     # Raises:
     #   ArgumentError if the value is nil, or empty.
     #
-    def check_not_empty(name, value) #:nodoc:
+    def check_not_empty(name, value)
       check_given(name, value)
       raise ArgumentError, "#{name} must not be empty" if value.to_s.empty?
     end
@@ -191,7 +204,7 @@ module Scribd
     # Raises:
     #   ArgumentError if the value is nil.
     #
-    def check_given(name, value) #:nodoc:
+    def check_given(name, value)
       raise ArgumentError, "#{name} must be given" if value.nil?
     end
     

data/lib/scribd/category.rb

@@ -0,0 +1,112 @@
+module Scribd
+  
+  # A category on Scribd. Categories group together {Document Documents} about
+  # similar topics. Categories are represented as a two-way tree, with each
+  # category having both a {#parent} and an array of {#children}.
+  #
+  # You can choose to load categories with or without their children using the
+  # {.all} method. If you load categories with their children, each parent will
+  # have its {#children} attribute set. Otherwise, calling {#children} on a
+  # category will induce another network call.
+  
+  class Category < Resource
+    # @return [Scribd::Category] The parent of this category.
+    # @return [nil] If this is a top-level category.
+    attr_reader :parent
+    
+    # @private
+    def initialize(options)
+      super
+      @children_preloaded = false
+      if options[:xml] then
+        children_xml = options[:xml].get_elements('subcategories').first
+        if children_xml and not children_xml.children.empty?
+          @children = Array.new
+          children_xml.get_elements('subcategory').each do |child_xml|
+            children << Category.new(:xml => child_xml, :parent => self)
+          end
+          @children_preloaded = true
+        end
+        options[:xml].delete(children_xml) if children_xml
+        
+        load_attributes(options[:xml])
+        @parent = options[:parent]
+        @saved = true
+        @created = true
+      else
+        raise "Categories cannot be created, only retrieved."
+      end
+    end
+    
+    # @return [true, false] True if this @Category@ has its children preloaded.
+    # @see #children
+    
+    def children_preloaded?
+      @children_preloaded
+    end
+    
+    # Returns an array of top-level categories. These categories will have their
+    # {#children} attributes set if @include_children@ is @true@.
+    #
+    # @param [true, false] include_children If @true@, child categories will be
+    # loaded for each top-level category. If @false@, only top-level categories
+    # will be loaded.
+    # @return [Array<Scribd::Category>] All top-level categories. If
+    # @include_children@ is @true@, each of these categories will have its
+    # @children@ attribute pre-loaded.
+    
+    def self.all(include_children=false)
+      response = include_children ? API.instance.send_request('docs.getCategories', :with_subcategories => true) : API.instance.send_request('docs.getCategories')
+      categories = Array.new
+      response.get_elements('/rsp/result_set/result').each do |res|
+        categories << Category.new(:xml => res)
+      end
+      return categories
+    end
+    
+    # Returns a list of the categories whose parent is this category.
+    #
+    # *If the receiver has preloaded its children* (in other words, it came from
+    # a call to {.all .all(true)}), this method makes no network call.
+    #
+    # *If the receiver has not preloaded its children* (in other words, it came
+    # from a call to {.all .all(false)}), _each_ invocation of this method will
+    # make a new network call.
+    #
+    # @return [Array<Scribd::Category>] The child categories of this category.
+    
+    def children
+      return @children if @children
+      response = API.instance.send_request('docs.getCategories', :category_id => self.id)
+      children = Array.new
+      response.get_elements('/rsp/result_set/result').each do |res|
+        children << Category.new(:xml => res)
+      end
+      return children
+    end
+    
+    # Returns documents found by the Scribd browser with given options, all
+    # categorized under this category. The browser provides documents suitable
+    # for a browse page.
+    #
+    # This method is called with a hash of options. For a list of supported
+    # options, please see the online API documentation.
+    #
+    # Documents returned from this method will have their @owner@ attributes set
+    # to @nil@ (i.e., they are read-only).
+    #
+    # @param [Hash] options Options to pass to the API find method.
+    # @return [Array<Scribd::Document>] An array of documents found.
+    # @example
+    #   category.browse(:sort => 'views', :category_id => 1, :limit => 10)
+    
+    def browse(options={})
+      response = API.instance.send_request('docs.browse', options.merge(:category_id => self.id))
+      documents = []
+      response.elements['/rsp/result_set'].elements.each do |doc|
+        documents << Document.new(:xml => doc)
+      end
+      return documents
+    end
+  end
+end