dewey 0.2.1 → 0.2.2

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 0.2.2 (October 27, 2010)
+
+  Changes:
+
+    - API Changes for get and put. All methods will use an options hash
+      rather than ordered options.
+    - Validation methods can accept either a string or a symbol
+    - More error-resistant handling of nil values passed to validation methods
+
 ## 0.2.1 (October 26, 2010)
 
 Additions:

data/README.md

@@ -42,7 +42,7 @@ first operation.
 ### Putting a Document
 
     document = File.new('my_document.doc')
-    resource = Dewey.put(document, 'My First Upload') # Returns the id when successful
+    resource = Dewey.put(document, :title => 'My First Upload') # Returns the id when successful
 
 ### Searching Documents
 
@@ -62,9 +62,9 @@ Upload your file
     
 Get it in various formats
 
-    original = Dewey.get(id)     # -> Tempfile
-    pdf  = Dewey.get(id, :pdf)   # -> Tempfile
-    html = Dewey.get(id, :html)  # -> Tempfile
+    original = Dewey.get(id)                #=> Tempfile
+    pdf  = Dewey.get(id, :format => :pdf)   #=> Tempfile
+    html = Dewey.get(id, :format => :html)  #=> Tempfile
     
 A tempfile is returned, so you'll have to move it
 
@@ -73,4 +73,4 @@ A tempfile is returned, so you'll have to move it
 ### Deleting a Document
 
     id = Dewey.put(File.new('my_spreadsheet.xls'))
-    result = Dewey.delete(id) # -> true
+    result = Dewey.delete(id) # -> true

data/lib/dewey/core.rb

@@ -32,37 +32,40 @@ module Dewey
       @@authenticator.authenticate!
     end
    
+    # Queries the document list for a particular title. Titles can be either 
+    # full or partial matches. Matches are returned as an array of ids.
+    #
+    # @param [String] query   The title to be matched
+    # @param [Hash]   options Search options
+    # @option options [Symbol] :exact Setting this to `true` will force an
+    #   exact match, with a maximum of one id returned
+    #
+    # @return [Array] An array of matched ids. No matches return an empty array
     def search(query, options = {})
-      authenticate! unless authenticated?
-      
       title    = query.gsub(/\s+/, '+')
       headers  = base_headers(false)
       url      = "#{GOOGLE_FEED_URL}?title=#{title}"
       url     << "&title-exact=true" if options[:exact]
       response = get_request(url, headers)
       
-      case response
-      when Net::HTTPOK
-        extract_ids(response.body)
-      else
-        nil
-      end
+      response.kind_of?(Net::HTTPOK) ? extract_ids(response.body) : []
     end
 
     # Upload a file to the account. A successful upload will return the resource
     # id, which is useful for downloading the file without doing a title search.
-    # * file  - A File reference
-    # * title - An alternative title, to be used instead of the filename
     #
-    def put(file, title = nil)
-      authenticate! unless authenticated?
-  
+    # @param [File] file    An IOStream object that responds to path, size
+    # @param [Hash] options Options for uploading the file
+    # @option options [Symbol] :title An alternative title, to be used instead
+    #                                 of the filename
+    # 
+    # @return [String, Boolean] The id if upload was successful, false otherwise
+    def put(file, options = {})
       extension = File.extname(file.path).sub('.', '')
       basename  = File.basename(file.path, ".#{extension}")
       mimetype  = Dewey::Mime.mime_type(file)
       service   = Dewey::Mime.guess_service(mimetype)
-  
-      title ||= basename
+      title     = options[:title] || basename
   
       raise DeweyException, "Invalid file type: #{extension}" unless Dewey::Validation.valid_upload_format?(extension, service)
   
@@ -75,46 +78,57 @@ module Dewey
       file.rewind
   
       response = post_request(GOOGLE_FEED_URL, file.read.to_s, headers)
-  
-      case response
-      when Net::HTTPCreated
-        extract_ids(response.body)
+ 
+      if response.kind_of?(Net::HTTPCreated)
+        extract_ids(response.body).first
       else
         false
       end
     end
 
-    # Download, or export more accurately, a file to a specified format
-    # * rid    - A resource id, for example +document:12345+
-    # * format - The output format, see *_EXPORT_FORMATS for possiblibilites
+    # Download a file. You may optionally specify a format for export.
     #
-    def get(rid, format = nil)
-      authenticate! unless authenticated?
-  
-      spreadsheet = !! rid.match(/^spreadsheet/)
-      id = rid.sub(/[a-z]+:/, '')
-  
-      url  = ''
-      url << (spreadsheet ? GOOGLE_SPREADSHEET_URL : GOOGLE_DOCUMENT_URL)
-      url << (spreadsheet ? "?key=#{id}" : "?docID=#{id}")
-      url << "&exportFormat=#{format.to_s}" unless format.nil?
-  
-      headers = base_headers
+    # @param [String] id       A resource id, for example `document:12345`
+    # @param [Hash]   options  Options for downloading the document
+    # @option options [Symbol] :format The output format
+    # 
+    # @return [Tempfile] The downloaded file
+    #
+    # @see Dewey::Validation::DOCUMENT_EXPORT_FORMATS
+    # @see Dewey::Validation::SPREADSHEET_EXPORT_FORMATS
+    # @see Dewey::Validation::PRESENTATION_EXPORT_FORMATS
+    def get(id, options = {})
+      service, id = id.split(':')
+      format = options[:format].to_s
+
+      raise DeweyException, "Invalid format: #{format}" unless Dewey::Validation.valid_export_format?(format, service)
+
+      url = ''
+      case service
+      when 'document'
+        url << GOOGLE_DOCUMENT_URL
+        url << "?docID=#{id}"
+      when 'spreadsheet'
+        url << GOOGLE_SPREADSHEET_URL
+        url << "?key=#{id}"
+      end
+
+      url << "&exportFormat=#{format}" unless format.blank?
   
-      file = Tempfile.new([rid, format].join('.'))
+      file = Tempfile.new([id, format].join('.'))
       file.binmode
   
-      open(url, headers) { |data| file.write data.read }
+      open(url, base_headers) { |data| file.write data.read }
   
       file
     end
 
-    # Deletes a document referenced either by resource id.
-    # * id - A resource id or exact file name matching a document in the account
+    # Deletes a document referenced by id.
+    #
+    # @param [String] id An id matching a document
     #
+    # @return [Boolean] `true` if delete was successful, `false` otherwise
     def delete(id)
-      authenticate! unless authenticated?
-  
       headers = base_headers(false)
       headers['If-Match'] = '*' # We don't care if others have modified
   
@@ -124,34 +138,49 @@ module Dewey
 
       response = delete_request(url, headers)
   
-      case response
-      when Net::HTTPOK
-        true
-      else
-        false
-      end
+      response.kind_of?(Net::HTTPOK)
     end
     
-    # The same as delete, except that it will raise +Dewey::DeweyException+ if
+    # The same as delete, except that it will raise `Dewey::DeweyException` if
     # the request fails.
-    #
+    # 
+    # @see #delete
     def delete!(id)
       delete(id) || raise(DeweyException, "Unable to delete document")
     end
 
-    # Convenience method for +put+, +get+, +delete+. Returns a Tempfile
-    # with in the provided type. Note that if you omit the format option it will
-    # simply upload the file and return it.
-    # * file    - The file that will be converted
-    # * options - Takes :title and :format. See +upload+ for title, and +download+ for format.
+    [:search, :put, :get, :delete].each do |method|
+      aliased = "no_auto_authenticate_#{method.to_s}".to_sym 
+      alias_method aliased, method
+      
+      self.class_eval(%Q{
+        def #{method} *args
+          authenticate! unless authenticated?
+          #{aliased}(*args)
+        end
+      })
+    end
+
+    # Convenience method for `put`, `get`, `delete`.
+    #
+    # @param [File] file The file that will be converted
+    # @param [Hash] options Options for conversion
+    # @option options [Symbol] :title  The title that the file will be stored
+    #   under. Only useful if the conversion fails.
+    # @option options [Symbol] :format Format to convert to.
     #
+    # @return [Tempfile] The converted file
+    #
+    # @see #put
+    # @see #get
+    # @see #delete
     def convert(file, options = {})
-      rid = put(file, options[:title])
-      con = get(rid, options[:format])
+      id = put(file, options[:title])
+      converted = get(id, options[:format])
   
-      delete(rid)
+      delete(id)
   
-      con
+      converted
     end
 
     protected
@@ -187,27 +216,26 @@ module Dewey
       end
     end
 
-    def base_headers(put_or_post = true) #:nodoc:
+    # A hash of default headers. Considers authentication and put/post headers.
+    #
+    # @param [Boolean] form If true the Content-Type will be set accordingly
+    # @return [Hash] Headers hash
+    def base_headers(form = true) #:nodoc:
       base = {}
       base['GData-Version'] = '3.0'
-      base['Content-Type']  = 'application/x-www-form-urlencoded'         if put_or_post
+      base['Content-Type']  = 'application/x-www-form-urlencoded'         if form
       base['Authorization'] = "GoogleLogin auth=#{@@authenticator.token}" if authenticated?
   
       base
     end
 
+    # Parse the XML returned to pull out one or more document ids.
+    #
+    # @param  [String] response An XML feed document
+    # @return [Array]  Array of document ids
     def extract_ids(response) #:nodoc:
       xml = REXML::Document.new(response)
-      ids = xml.elements.
-            collect('//id') { |e| "#{$1}:#{$2}" if e.text =~ /.*(document|spreadsheet|presentation)(?:%3A|:)([0-9a-zA-Z_-]+)$/ }.
-            reject(&:nil?)
-      
-      case ids.length
-      when 0 then nil
-      when 1 then ids.first
-      else
-        ids
-      end
+      xml.elements.collect('//id') { |e| e.text.gsub('%3A', ':') }.reject(&:blank?)
     end
   end
 end

data/lib/dewey/validation.rb

@@ -1,38 +1,63 @@
 module Dewey
   
-  DOCUMENT_EXPORT_FORMATS     = %w(txt odt pdf html rtf doc png zip)
-  PRESENTATION_EXPORT_FORMATS = %w(swf pdf png ppt)
-  SPREADSHEET_EXPORT_FORMATS  = %W(xls csv pdf ods tsv html)
+  DOCUMENT_EXPORT_FORMATS     = [:txt, :odt, :pdf, :html, :rtf, :doc, :png, :zip]
+  PRESENTATION_EXPORT_FORMATS = [:swf, :pdf, :png, :ppt]
+  SPREADSHEET_EXPORT_FORMATS  = [:xls, :csv, :pdf, :ods, :tsv, :html]
   
+  # Utility methods to check that a format is accepted for a particular service
+  #
   class Validation
-    # Determine wether or not a format is available for download.
-    #
-    # * format  - The file format to check, i.e. 'txt', 'doc', 'pdf'
-    # * service - The service that would be used. Must be document, presentation,
-    #   or spreadsheet.
-    def self.valid_upload_format?(format, service = :document)
-      case service
-      when :document     then Dewey::DOCUMENT_MIMETYPES.has_key?(format.to_sym)
-      when :presentation then Dewey::PRESENTATION_MIMETYPES.has_key?(format.to_sym)
-      when :spreadsheet  then Dewey::SPREADSHEET_MIMETYPES.has_key?(format.to_sym)
-      else
-        raise DeweyException, "Unknown service: #{service}"
+    
+    class << self
+      # Determine wether or not a format is available for download.
+      #
+      # @param [Symbol] format  The file format to check, i.e. `:txt`, `:doc`, `:pdf`
+      # @param [Symbol] service The service that would be used. Must be
+      #   `:document`, `:presentation`, or `:spreadsheet`.
+      #
+      # @return [Boolean] `true` if the format is supported, `false` otherwise
+      #
+      # @raise [DeweyException] Raised when an unknown service is given
+      def valid_upload_format?(format, service = nil)
+        format  = format.to_sym
+        service = default_service(service)
+
+        case service
+        when :document     then Dewey::DOCUMENT_MIMETYPES.has_key?(format)
+        when :presentation then Dewey::PRESENTATION_MIMETYPES.has_key?(format)
+        when :spreadsheet  then Dewey::SPREADSHEET_MIMETYPES.has_key?(format)
+        else
+          raise DeweyException, "Unknown service: #{service}"
+        end
       end
-    end
 
-    # Determine whether or not a format is available for export.
-    #
-    # * format  - The file format to check, i.e. 'txt', 'doc', 'pdf'
-    # * service - The service that would be used. Must be document, presentation,
-    #   or spreadsheet.
-    def self.valid_export_format?(format, service = :document)
-      case service
-      when :document     then Dewey::DOCUMENT_EXPORT_FORMATS.include?(format)
-      when :presentation then Dewey::PRESENTATION_EXPORT_FORMATS.include?(format)
-      when :spreadsheet  then Dewey::SPREADSHEET_EXPORT_FORMATS.include?(format)
-      else
-        raise DeweyException, "Unknown service: #{service}"
+      # Determine whether or not a format is available for export.
+      #
+      # @param [Symbol] format  The file format to check, i.e. `:txt`, `:doc`, `:pdf`
+      # @param [Symbol] service The service that would be used. Must be
+      #   `:document`, `:presentation`, or `:spreadsheet`.
+      #
+      # @return [Boolean] `true` if the format is supported, `false` otherwise
+      #
+      # @raise [DeweyException] Raised when an unknown service is given
+      def valid_export_format?(format, service = nil)
+        format  = format.to_sym
+        service = default_service(service) 
+
+        case service
+        when :document     then Dewey::DOCUMENT_EXPORT_FORMATS.include?(format)
+        when :presentation then Dewey::PRESENTATION_EXPORT_FORMATS.include?(format)
+        when :spreadsheet  then Dewey::SPREADSHEET_EXPORT_FORMATS.include?(format)
+        else
+          raise DeweyException, "Unknown service: #{service}"
+        end
+      end
+
+      protected
+
+      def default_service(service)
+        service.nil? ? :document : service.to_sym
       end
     end
   end
-end
+end

data/lib/dewey/version.rb

@@ -1,3 +1,3 @@
 module Dewey
-  VERSION = '0.2.1'
-end
+  VERSION = '0.2.2'
+end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 2
-  - 1
-  version: 0.2.1
+  - 2
+  version: 0.2.2
 platform: ruby
 authors: 
 - Parker Selbert
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-26 00:00:00 -05:00
+date: 2010-10-28 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency