rscribd 0.0.2 → 0.0.3

data/lib/resource.rb

@@ -0,0 +1,158 @@
+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.
+  #
+  # 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:
+  #
+  #  obj.title #=> "Title"
+  #  obj.title = "New Title"
+  #
+  # 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:
+  #
+  #  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.
+  #
+  # 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.
+  
+  class Resource
+    
+    # Initializes instance variables.
+    
+    def initialize(options={})
+      @saved = false
+      @created = false
+      @attributes = Hash.new
+    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.
+    
+    def self.create(options={})
+      obj = new(options)
+      obj.save
+      obj
+    end
+    
+    # Throws NotImplementedError by default.
+    
+    def save
+      raise NotImplementedError, "Cannot save #{self.class.to_s} objects"
+    end
+    
+    # Throws NotImplementedError by default.
+    
+    def self.find(options)
+      raise NotImplementedError, "Cannot find #{self.class.to_s} objects"
+    end
+    
+    # Throws NotImplementedError by default.
+    
+    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.
+    
+    def saved?
+      @saved
+    end
+    
+    # Returns true if this document has been created remotely, and corresponds
+    # to a document 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.
+    
+    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.
+    
+    def read_attributes(attributes)
+      raise ArgumentError, "Attributes must be listed in an Enumeration" unless attributes.kind_of? Enumeration
+      raise ArgumentError, "All attributes must respond to to_sym" unless attributes.all? { |a| a.respond_to? :to_sym }
+      keys = attributes.map(&:to_sym)
+      values = @attributes.values_at keys
+      keys.zip(values).to_hsh
+    end
+    
+    # Assigns values to attributes. Takes a hash that specifies the
+    # attribute-value pairs to update. Does not perform a save. Non-writeable
+    # attributes are ignored.
+    
+    def write_attributes(values)
+      raise ArgumentError, "Values must be specified through a hash of attributes" unless values.kind_of? Hash
+      raise ArgumentError, "All attributes must respond to to_sym" unless values.keys.all? { |a| a.respond_to? :to_sym }
+      @attributes.update values.map { |k,v| [ k.to_sym, v ] }.to_hsh
+    end
+    
+    # Gets or sets attributes for the resource. Any named attribute can be
+    # 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
+    #
+    # 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
+        @attributes[$1.to_sym] = args[0]
+      else
+        @attributes[meth]
+      end
+    end
+    
+    # Pretty-print for debugging output of Scribd resources.
+    
+    def inspect #:nodoc:
+      "#<#{self.class.to_s} #{@attributes.select { |k, v| not v.nil? }.collect { |k,v| k.to_s + '=' + v.to_s }.join(', ')}>"
+    end
+    
+    private
+    
+    def load_attributes(xml)
+      @attributes.clear
+      xml.each_element do |element|
+        @attributes[element.name.to_sym] = if element.attributes['type'] == 'integer' then
+          element.text.to_i
+        elsif element.attributes['type'] == 'float' then
+          element.text.to_f
+        elsif element.attributes['type'] == 'symbol' then
+          element.text.to_sym
+        else
+          element.text
+        end
+      end
+    end
+  end
+end

data/lib/rscribd.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+
+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
+
+class Array #:nodoc:
+  def to_hsh
+    h = Hash.new
+    each { |k, v| h[k] = v }
+    h
+  end
+end
+
+require 'multipart'
+require 'exceptions'
+require 'api'
+require 'resource'
+require 'doc'
+require 'user'

data/lib/user.rb

@@ -0,0 +1,142 @@
+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:
+  #
+  #  user = Scribd::User.login 'login', 'pass'
+  #
+  # You can now access information about this user through direct method calls:
+  #
+  #  user.name #=> 'Real Name'
+  #
+  # If, at any time, you would like to retrieve the Scribd::User instance for
+  # the currently logged-in user, simply call:
+  #
+  #  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
+  #
+  # You can create a new account with the signup (a.k.a. create) method:
+  #
+  #  user = Scribd::User.signup :username => 'testuser', :password => 'testpassword', :email => your@email.com
+  
+  class User < Resource
+    
+    # Creates a new, unsaved user with the given attributes. You can eventually
+    # use this record to create a new Scribd account.
+    
+    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. Throws a 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 all documents owned by this user. 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:
+    #
+    #  docs = user.documents
+    #  docs.each(&:destroy)
+    #  docs #=> Still populated, because it hasn't been updated
+    #  docs = user.documents #=> Now it's empty
+    #
+    # 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
+    
+    def documents
+      response = API.instance.send_request('docs.getList', { :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
+    # Scribd::Document.find.
+    
+    def find_documents(options)
+      Document.find options.merge(:scope => 'user', :session_key => @attributes[:session_key])
+    end
+    
+    # Loads a Scribd::Document by ID. You can only load such documents if they 
+    # belong to this user.
+    
+    def find_document(document_id)
+      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. This method takes the
+    # following options:
+    #
+    # +file+:: The location of a file on disk or the URL to a file on the Web
+    # +type+:: The file's type (e.g., "txt" or "ppt"). Optional if the file has
+    #          an extension (like "file.txt").
+    #
+    # There are other options you can specify. For more information, see the
+    # Scribd::Document.save method.
+    
+    def upload(options)
+     Document.create options.merge(:owner => self)
+    end
+    
+    # Synonym for create.
+    
+    def self.signup(options={})
+      create options
+    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. Returns the Scribd::User instance for 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')[0]
+      user = User.new(:xml => xml)
+      API.instance.user = user
+      return user
+    end
+    
+    # Returns the +user_id+ attribute.
+    
+    def id
+      self.user_id
+    end
+    
+    def to_s #:nodoc:
+      @attributes[:username]
+    end
+  end
+end

data/sample/01_upload.rb

@@ -0,0 +1,47 @@
+# Example 1 - Uploading a test text file and removing it afterwards.
+
+require 'rubygems'
+require 'rscribd'
+
+# Use your API key / secret here
+api_key = ''
+api_secret = ''
+ 
+# Create a scribd object
+Scribd::API.instance.key = api_key
+Scribd::API.instance.secret = api_secret
+#Scribd::API.instance.debug = true
+
+begin
+  Scribd::User.login 'LOGIN', 'PASSWORD'
+  # Upload the document from a file
+  print "Uploading a document ... "
+
+  doc = Scribd::Document.upload(:file => 'test.txt')
+  puts "Done doc_id=#{doc.id}, doc_access_key=#{doc.access_key}"
+
+  # Poll API until conversion is complete
+  while (doc.conversion_status == 'PROCESSING')
+    puts "Document conversion is processing"
+    sleep(2) # Very important to sleep to prevent a runaway loop that will get your app blocked
+  end
+  puts "Document conversion is complete"
+
+  # Edit various options of the document
+  # Note you can also edit options before your doc is done converting
+  doc.title = 'This is a test doc!'
+  doc.description = "I'm testing out the Scribd API!"
+  doc.access = 'private'
+  doc.language = 'en'
+  doc.license = 'c'
+  doc.tags = 'test,api'
+  doc.show_ads = true
+  doc.save
+
+  # Delete the uploaded document
+  print "Deleting a document ... "
+  doc.destroy
+  puts "Done doc_id=#{doc.id}"
+rescue Scribd::ResponseError => e
+  puts "failed code=#{e.code} error='#{e.message}'"
+end

data/sample/02_user.rb

@@ -0,0 +1,44 @@
+# Example 2 - Signing in as a user, and accessing a user's files.
+
+require 'rubygems'
+require 'rscribd'
+
+# Use your API key / secret here
+api_key = ''
+api_secret = ''
+
+# Edit these to a real Scribd username/password pair
+username = ''
+password = ''
+
+# Create a scribd object
+Scribd::API.instance.key = api_key
+Scribd::API.instance.secret = api_secret
+#Scribd::API.instance.debug = true
+
+begin
+
+  # Login your Scribd API object as a particular user
+  # NOTE: Edit this to the username and password of a real Scribd user
+  user = Scribd::User.login username, password
+
+  docs = user.documents
+
+  puts "User #{user.username} has #{docs.size} docs"
+  if docs.size > 0
+    puts "User's docs:" 
+    for doc in docs
+      puts "#{doc.title}"
+    end
+  end
+
+  results = Scribd::Document.find(:query => 'checklist') # Search over the user's docs for the string 'cat'
+  puts "Search through docs turned up #{results.size} results:"
+  for doc in results
+    puts "#{doc.title}"
+  end
+  
+
+rescue Scribd::ResponseError => e
+  puts "failed code=#{e.code} error='#{e.message}'"
+end

data/sample/test.txt

@@ -1 +1 @@
-Test text file.
+This is a simple test text file to try out the neat Scribd API.

metadata

@@ -1,64 +1,87 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.9.4
-specification_version: 1
 name: rscribd
 version: !ruby/object:Gem::Version 
-  version: 0.0.2
-date: 2007-11-20 00:00:00 -08:00
-summary: Ruby interface to the Scribd API
-require_paths: 
-- lib
-email: matt.jaynes@gmail.com
-homepage: http://rubyforge.org/projects/rscribd/
-rubyforge_project: rscribd
-description: rscribd is a Ruby implementation of the Scribd API. It includes a faithful reproduction of the published API as well as method encapsulation to provide more useful object mappings. rscribd features result caching to improve performance.
-autorequire: rake
-default_executable: 
+  version: 0.0.3
+platform: ""
+authors: 
+- Jared Friedman
+autorequire: 
 bindir: bin
-has_rdoc: false
-required_ruby_version: !ruby/object:Gem::Version::Requirement 
-  requirements: 
-  - - ">"
-    - !ruby/object:Gem::Version 
-      version: 0.0.0
-  version: 
-platform: ruby
-signing_key: 
-cert_chain: 
-post_install_message: 
-authors: []
-
-files: 
-- lib/scribd/base.rb
-- lib/scribd/docs.rb
-- lib/scribd/search.rb
-- lib/scribd.rb
-- sample/01-docs_upload-text.rb
-- sample/02-docs_upload-binary.rb
-- sample/03-docs_uploadFromUrl.rb
-- sample/04-docs_changeSettings.rb
-- sample/05-docs_getConversionStatus.rb
-- sample/test.gif
-- sample/test.txt
-test_files: []
-
-rdoc_options: []
-
-extra_rdoc_files: []
-
-executables: []
-
-extensions: []
-
-requirements: []
+cert_chain: []
 
+date: 2008-02-18 00:00:00 -08:00
+default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: mime-types
   version_requirement: 
-  version_requirements: !ruby/object:Gem::Version::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement 
     requirements: 
     - - ">"
       - !ruby/object:Gem::Version 
         version: 0.0.0
     version: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.5.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.  == FEATURES/PROBLEMS:  * 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: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- sample/test.txt
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- lib/api.rb
+- lib/doc.rb
+- lib/exceptions.rb
+- lib/multipart.rb
+- lib/resource.rb
+- lib/rscribd.rb
+- lib/user.rb
+- sample/01_upload.rb
+- sample/02_user.rb
+- sample/test.txt
+has_rdoc: true
+homepage: 
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: rscribd
+rubygems_version: 0.9.5
+signing_key: 
+specification_version: 2
+summary: Ruby client library for the Scribd API
+test_files: []
+