google_drive 0.3.11 → 1.0.0.pre1

data/lib/google_drive/file.rb

@@ -2,6 +2,7 @@
 # The license of this source is "New BSD Licence"
 
 require "cgi"
+require "forwardable"
 require "stringio"
 
 require "google_drive/util"
@@ -14,109 +15,90 @@ module GoogleDrive
     #
     # Use GoogleDrive::Session#files or GoogleDrive::Session#file_by_title to
     # get this object.
+    #
+    # In addition to the methods below, properties defined here are also available as attributes:
+    # https://developers.google.com/drive/v2/reference/files#resource
+    #
+    # e.g.,
+    #   file.mime_type  # ==> "text/plain"
     class File
 
         include(Util)
+        extend(Forwardable)
         
-        def initialize(session, entry_or_url) #:nodoc:
+        def initialize(session, api_file) #:nodoc:
           @session = session
-          if !entry_or_url
-            # TODO Delete this after editing spreadsheet.rb.
-            @document_feed_entry = nil
-            @document_feed_url = entry_or_url
-          elsif entry_or_url.is_a?(String)
-            @document_feed_entry = nil
-            @document_feed_url = entry_or_url
-          else
-            @document_feed_entry = entry_or_url
-            # This is usually equal to the URL in <link rel="self">. But the URL in
-            # <link rel="self"> in collection feed is e.g.
-            # https://docs.google.com/feeds/default/private/full/folder%3Aroot/contents/folder%3Axxx
-            # and deletion of the URL doesn't delete the file itself.
-            # So we construct the URL here using resource ID instead.
-            @document_feed_url = "%s/%s?v=3" % [DOCS_BASE_URL, CGI.escape(self.resource_id)]
-          end
+          @api_file = api_file
           @acl = nil
+          delegate_api_methods(self, @api_file, ["title"])
         end
-        
-        # URL of feed used in document list feed API.
-        attr_reader(:document_feed_url)
-        
-        # <entry> element of document list feed as Nokogiri::XML::Element.
-        #
-        # Set <tt>params[:reload]</tt> to true to force reloading the feed.
-        def document_feed_entry(params = {})
-          warn(
-              "WARNING: GoogleDrive::file\#document_feed_entry is deprecated and will be removed " +
-              "in the next version.")
-          return self.document_feed_entry_internal(params)
-        end
 
-        def document_feed_entry_internal(params = {}) #:nodoc:
-          if !@document_feed_entry || params[:reload]
-            @document_feed_entry =
-                @session.request(:get, self.document_feed_url, :auth => :writely).css("entry")[0]
+        # Wrapped Google::APIClient::Schema::Drive::V2::File object.
+        attr_reader(:api_file)
+
+        # Reloads file metadata such as title and acl.
+        def reload_metadata()
+          api_result = @session.execute!(
+            :api_method => @session.drive.files.get,
+            :parameters => { "fileId" => self.id })
+          @api_file = api_result.data
+          if @acl
+            @acl = Acl.new(@session, self)
           end
-          return @document_feed_entry
         end
 
-        # Resource ID.
+        # Returns resource_type + ":" + id.
         def resource_id
-          return self.document_feed_entry_internal.css("gd|resourceId").text
+          return "%s:%s" % [self.resource_type, self.id]
+        end
+
+        # URL of feed used in the deprecated document list feed API.
+        def document_feed_url
+          return "https://docs.google.com/feeds/default/private/full/" + CGI.escape(self.resource_id)
+        end
+
+        # Deprecated ACL feed URL of the file.
+        def acl_feed_url
+          return self.document_feed_url + "/acl"
         end
 
         # The type of resourse. e.g. "document", "spreadsheet", "folder"
         def resource_type
-          return self.resource_id.split(/:/)[0]
+          return self.mime_type.slice(/^application\/vnd.google-apps.(.+)$/, 1) || "file"
         end
 
         # Title of the file.
-        #
-        # Set <tt>params[:reload]</tt> to true to force reloading the title.
         def title(params = {})
-          return document_feed_entry_internal(params).css("title").text
+          reload_metadata() if params[:reload]
+          return self.api_file.title
         end
         
         # URL to view/edit the file in a Web browser.
         #
         # e.g. "https://docs.google.com/file/d/xxxx/edit"
         def human_url
-          return self.document_feed_entry_internal.css("link[rel='alternate']")[0]["href"]
+          return self.alternate_link
         end
         
-        # ACL feed URL of the file.
-        def acl_feed_url
-          orig_acl_feed_url = self.document_feed_entry_internal.css(
-              "gd|feedLink[rel='http://schemas.google.com/acl/2007#accessControlList']")[0]["href"]
-          case orig_acl_feed_url
-            when %r{^https?://docs.google.com/feeds/default/private/full/.*/acl(\?.*)?$}
-              return orig_acl_feed_url
-            when %r{^https?://docs.google.com/feeds/acl/private/full/([^\?]*)(\?.*)?$}
-              # URL of old API version. Converts to v3 URL.
-              return "#{DOCS_BASE_URL}/#{$1}/acl"
-            else
-              raise(GoogleDrive::Error,
-                "ACL feed URL is in unknown format: #{orig_acl_feed_url}")
-          end
-        end
-
         # Content types you can specify in methods download_to_file, download_to_string,
         # download_to_io .
+        #
+        # This returns zero or one file type. You may be able to download the file in other formats using
+        # export_as_file, export_as_string, or export_to_io. Use export_links method to get available formats
+        # in these methods.
         def available_content_types
-          return self.document_feed_entry_internal.css("content").map(){ |c| c["type"] }
+          if self.api_file.download_url
+            return [self.api_file.mime_type]
+          else
+            return []
+          end
         end
         
-        # Downloads the file to a local file.
-        #
-        # e.g.
+        # Downloads the file to a local file. e.g.
         #   file.download_to_file("/path/to/hoge.txt")
-        #   file.download_to_file("/path/to/hoge", :content_type => "text/plain")
+        #
+        # To export the file in other formats, use export_as_file.
         def download_to_file(path, params = {})
-          params = params.dup()
-          if !params[:content_type]
-            params[:content_type] = EXT_TO_CONTENT_TYPE[::File.extname(path).downcase]
-            params[:content_type_is_hint] = true
-          end
           open(path, "wb") do |f|
             download_to_io(f, params)
           end
@@ -124,9 +106,7 @@ module GoogleDrive
         
         # Downloads the file and returns as a String.
         #
-        # e.g.
-        #   file.download_to_string()                               #=> "Hello world."
-        #   file.download_to_string(:content_type => "text/plain")  #=> "Hello world."
+        # To export the file in other formats, use export_as_string.
         def download_to_string(params = {})
           sio = StringIO.new()
           download_to_io(sio, params)
@@ -134,42 +114,73 @@ module GoogleDrive
         end
         
         # Downloads the file and writes it to +io+.
+        #
+        # To export the file in other formats, use export_to_io.
         def download_to_io(io, params = {})
-          all_contents = self.document_feed_entry_internal.css("content")
-          if params[:content_type] && (!params[:content_type_is_hint] || all_contents.size > 1)
-            contents = all_contents.select(){ |c| c["type"] == params[:content_type] }
-          else
-            contents = all_contents
+          if !self.api_file.download_url
+            raise(GoogleDrive::Error, "Downloading is not supported for this file.")
           end
-          if contents.size == 1
-            url = contents[0]["src"]
-          else
-            if contents.empty?
-              raise(GoogleDrive::Error,
-                  ("Downloading with content type %p not supported for this file. " +
-                   "Specify one of these to content_type: %p") %
-                  [params[:content_type], self.available_content_types])
-            else
-              raise(GoogleDrive::Error,
-                  ("Multiple content types are available for this file. " +
-                   "Specify one of these to content_type: %p") %
-                  [self.available_content_types])
+          # TODO Use streaming if possible.
+          api_result = @session.execute!(:uri => self.api_file.download_url)
+          io.write(api_result.body)
+        end
+
+        # Export the file to +path+ in content type +format+.
+        # If +format+ is nil, it is guessed from the file name.
+        #
+        # e.g.,
+        #   spreadsheet.export_as_file("/path/to/hoge.csv")
+        #   spreadsheet.export_as_file("/path/to/hoge", "text/csv")
+        #
+        # If you want to download the file in the original format, use download_to_file instead.
+        def export_as_file(path, format = nil)
+          if !format
+            format = EXT_TO_CONTENT_TYPE[::File.extname(path).downcase]
+            if !format
+              raise(ArgumentError,
+                  ("Cannot guess format from the file name: %s\n" +
+                   "Specify format argument explicitly.") %
+                  path)
             end
           end
-          # TODO Use streaming if possible.
-          body = @session.request(:get, url, :response_type => :raw, :auth => :writely)
-          io.write(body)
+          open(path, "wb") do |f|
+            export_to_io(f, format)
+          end
         end
         
-        # Updates the file with the content of the local file.
+        # Export the file as String in content type +format+.
         #
-        # e.g.
-        #   file.update_from_file("/path/to/hoge.txt")
-        def update_from_file(path, params = {})
-          params = {:file_name => ::File.basename(path)}.merge(params)
-          open(path, "rb") do |f|
-            update_from_io(f, params)
+        # e.g.,
+        #   spreadsheet.export_as_string("text/csv")
+        #
+        # If you want to download the file in the original format, use download_to_string instead.
+        def export_as_string(format)
+          sio = StringIO.new()
+          export_to_io(sio, format)
+          return sio.string
+        end
+
+        # Export the file to +io+ in content type +format+.
+        #
+        # If you want to download the file in the original format, use download_to_io instead.
+        def export_to_io(io, format)
+          mime_type = EXT_TO_CONTENT_TYPE["." + format] || format
+          if !self.export_links
+            raise(
+                GoogleDrive::Error,
+                "This file doesn't support exporting. You may still download the file in the " +
+                "original format using download_to_file, download_to_string or download_to_io.")
+          end
+          export_url = self.export_links[mime_type]
+          if !export_url
+            raise(
+                GoogleDrive::Error,
+                "This file doesn't support export with mime type %p. Supported mime types: %p" %
+                    [mime_type, self.export_links.to_hash().keys])
           end
+          # TODO Use streaming if possible.
+          api_result = @session.execute!(:uri => export_url)
+          io.write(api_result.body)
         end
         
         # Updates the file with +content+.
@@ -177,50 +188,84 @@ module GoogleDrive
         # e.g.
         #   file.update_from_string("Good bye, world.")
         def update_from_string(content, params = {})
-          update_from_io(StringIO.new(content), params)
+          media = new_upload_io(StringIO.new(content), params)
+          return update_from_media(media, params)
         end
         
+        # Updates the file with the content of the local file.
+        #
+        # e.g.
+        #   file.update_from_file("/path/to/hoge.txt")
+        def update_from_file(path, params = {})
+          file_name = ::File.basename(path)
+          params = {:file_name => file_name}.merge(params)
+          media = new_upload_io(path, params)
+          return update_from_media(media, params)
+        end
+
         # Reads content from +io+ and updates the file with the content.
         def update_from_io(io, params = {})
-          params = {:header => {"If-Match" => "*"}}.merge(params)
-          initial_url = self.document_feed_entry_internal.css(
-              "link[rel='http://schemas.google.com/g/2005#resumable-edit-media']")[0]["href"]
-          @document_feed_entry = @session.upload_raw(
-              :put, initial_url, io, self.title, params)
+          media = new_upload_io(io, params)
+          return update_from_media(media, params)
         end
-        
+
+        # Reads content from +media+ and updates the file with the content.
+        def update_from_media(media, params = {})
+          api_result = @session.execute!(
+              :api_method => @session.drive.files.update,
+              :media => media,
+              :parameters => {
+                "fileId" => self.id,
+                "uploadType" => "media",
+              })
+          return @session.wrap_api_file(api_result.data)
+        end
+
         # If +permanent+ is +false+, moves the file to the trash.
         # If +permanent+ is +true+, deletes the file permanently.
         def delete(permanent = false)
-          url = to_v3_url(self.document_feed_url)
-          url = concat_url(url, "?delete=true") if permanent
-          @session.request(:delete, url,
-            :auth => :writely, :header => {"If-Match" => "*"})
+          if permanent
+            @session.execute!(
+                :api_method => @session.drive.files.delete,
+                :parameters => {"fileId" => self.id})
+          else
+            @session.execute!(
+                :api_method => @session.drive.files.trash,
+                :parameters => {"fileId" => self.id})
+          end
+          return nil
         end
 
         # Renames title of the file.
         def rename(title)
-          edit_url = self.document_feed_entry_internal.css("link[rel='edit']").first["href"]
-          xml = <<-"EOS"
-            <atom:entry
-                xmlns:atom="http://www.w3.org/2005/Atom"
-                xmlns:docs="http://schemas.google.com/docs/2007">
-              <atom:title>#{h(title)}</atom:title>
-            </atom:entry>
-          EOS
-          header = {"Content-Type" => "application/atom+xml;charset=utf-8", "If-Match" => "*"}
-          @session.request(:put, edit_url, :data => xml, :auth => :writely, :header => header)
+          api_result = @session.execute!(
+              :api_method => @session.drive.files.patch,
+              :body_object => {"title" => title},
+              :parameters => {"fileId" => self.id})
+          @api_file = api_result.data
         end
         
         alias title= rename
+
+        # Creates copy of this file with the given title.
+        def copy(title)
+          copied_file = @session.drive.files.copy.request_schema.new({
+              "title" => title,
+          })
+          api_result = @session.execute!(
+              :api_method => @session.drive.files.copy,
+              :body_object => copied_file,
+              :parameters => {"fileId" => self.id})
+          return @session.wrap_api_file(api_result.data)
+        end
+
+        alias duplicate copy
         
         # Returns GoogleDrive::Acl object for the file.
         #
         # With the object, you can see and modify people who can access the file.
         # Modifications take effect immediately.
         #
-        # Set <tt>params[:reload]</tt> to true to force reloading the data.
-        #
         # e.g.
         #   # Dumps people who have access:
         #   for entry in file.acl
@@ -231,9 +276,9 @@ module GoogleDrive
         #   # Shares the file with new people:
         #   # NOTE: This sends email to the new people.
         #   file.acl.push(
-        #       {:scope_type => "user", :scope => "example2@gmail.com", :role => "reader"})
+        #       {:type => "user", :value => "example2@gmail.com", :role => "reader"})
         #   file.acl.push(
-        #       {:scope_type => "user", :scope => "example3@gmail.com", :role => "writer"})
+        #       {:type => "user", :value => "example3@gmail.com", :role => "writer"})
         #   
         #   # Changes the role of a person:
         #   file.acl[1].role = "writer"
@@ -242,15 +287,13 @@ module GoogleDrive
         #   file.acl.delete(file.acl[1])
         def acl(params = {})
           if !@acl || params[:reload]
-            @acl = Acl.new(@session, self.acl_feed_url)
+            @acl = Acl.new(@session, self)
           end
           return @acl
         end
 
         def inspect
-          fields = {:document_feed_url => self.document_feed_url}
-          fields[:title] = self.title if @document_feed_entry
-          return "\#<%p %s>" % [self.class, fields.map(){ |k, v| "%s=%p" % [k, v] }.join(", ")]
+          return "\#<%p id=%p title=%p>" % [self.class, self.id, self.title]
         end
         
     end