google_drive 0.3.11 → 1.0.0.pre1

data/lib/google_drive_v1/acl_entry.rb

@@ -0,0 +1,100 @@
+# Author: Guy Boertje <https://github.com/guyboertje>
+# Author: David R. Albrecht <https://github.com/eldavido>
+# Author: Hiroshi Ichikawa <http://gimite.net/>
+# Author: Phuogn Nguyen <https://github.com/phuongnd08>
+# The license of this source is "New BSD Licence"
+
+module GoogleDriveV1
+
+    # An entry of an ACL (access control list) of a spreadsheet.
+    #
+    # Use GoogleDriveV1::Acl#[] to get GoogleDriveV1::AclEntry object.
+    #
+    # This code is based on https://github.com/guyboertje/gdata-spreadsheet-ruby .
+    class AclEntry
+
+        include(Util)
+
+        PARAM_NAMES = [:acl, :scope_type, :scope, :with_key, :role, :title, :edit_url, :etag]  #:nodoc:
+
+        # +params+ is a Hash object with keys +:scope_type+, +:scope+ and +:role+.
+        # See scope_type and role for the document of the fields.
+        def initialize(params)
+          @params = {:role => "reader"}
+          for name, value in params
+            if !name.is_a?(Symbol)
+              raise(ArgumentError, "Key must be Symbol, but is %p" % name)
+            elsif !PARAM_NAMES.include?(name)
+              raise(ArgumentError, "Invalid key: %p" % name)
+            end
+            @params[name] = value
+          end
+        end
+
+        attr_accessor(:params)  #:nodoc:
+
+        PARAM_NAMES.each() do |name|
+          define_method(name) do
+            return @params[name]
+          end
+        end
+
+        def edit_url
+          warn(
+              "WARNING: GoogleDriveV1::AclEntry\#edit_url is deprecated and will be removed in the next version.")
+          return self.edit_url_internal
+        end
+
+        def edit_url_internal #:nodoc:
+          return @params[:edit_url]
+        end
+
+        # Changes the role of the scope.
+        #
+        # e.g.
+        #   spreadsheet.acl[1].role = "writer"
+        def role=(role)
+          @params[:role] = role
+          @params[:acl].update_role(self)
+        end
+
+        def inspect
+          return "\#<%p scope_type=%p, scope=%p, with_key=%p, role=%p>" %
+              [self.class, @params[:scope_type], @params[:scope], @params[:with_key], @params[:role]]
+        end
+
+        def to_xml()  #:nodoc:
+          
+          etag_attr = self.etag ? "gd:etag='#{h(self.etag)}'" : ""
+          value_attr = self.scope ? "value='#{h(self.scope)}'" : ""
+          if self.with_key
+            role_tag = <<-EOS
+                <gAcl:withKey key='[ACL KEY]'>
+                  <gAcl:role value='#{h(self.role)}'/>
+                </gAcl:withKey>
+            EOS
+          else
+            role_tag = <<-EOS
+              <gAcl:role value='#{h(self.role)}'/>
+            EOS
+          end
+          
+          return <<-EOS
+            <entry
+                xmlns='http://www.w3.org/2005/Atom'
+                xmlns:gAcl='http://schemas.google.com/acl/2007'
+                xmlns:gd='http://schemas.google.com/g/2005'
+                #{etag_attr}>
+              <category scheme='http://schemas.google.com/g/2005#kind'
+                  term='http://schemas.google.com/acl/2007#accessRule'/>
+              #{role_tag}
+              <gAcl:scope type='#{h(self.scope_type)}' #{value_attr}/>
+            </entry>
+          EOS
+          
+        end
+
+    end
+
+end
+

data/lib/google_drive_v1/api_client_fetcher.rb

@@ -0,0 +1,47 @@
+# Author: Hiroshi Ichikawa <http://gimite.net/>
+# The license of this source is "New BSD Licence"
+
+require "net/https"
+require "uri"
+Net::HTTP.version_1_2
+
+
+module GoogleDriveV1
+
+    class ApiClientFetcher
+        
+        class Response
+
+            def initialize(client_response)
+              @client_response = client_response
+            end
+
+            def code
+              return @client_response.status.to_s()
+            end
+
+            def body
+              return @client_response.body
+            end
+
+        end
+
+        def initialize(client)
+          @client = client
+        end
+
+        attr_reader(:client)
+        
+        def request_raw(method, url, data, extra_header, auth)
+          p [method, url, data, extra_header, auth]
+          client_response = @client.execute(
+              :http_method => method,
+              :uri => url,
+              :body => data,
+              :headers => extra_header)
+          return Response.new(client_response)
+        end
+        
+    end
+    
+end

data/lib/google_drive_v1/authentication_error.rb

@@ -0,0 +1,14 @@
+# Author: Hiroshi Ichikawa <http://gimite.net/>
+# The license of this source is "New BSD Licence"
+
+require "google_drive_v1/error"
+
+
+module GoogleDriveV1
+
+    # Raised when GoogleDriveV1.login has failed.
+    class AuthenticationError < GoogleDriveV1::Error
+
+    end
+    
+end

data/lib/{google_drive → google_drive_v1}/basic_fetcher.rb

@@ -6,7 +6,7 @@ require "uri"
 Net::HTTP.version_1_2
 
 
-module GoogleDrive
+module GoogleDriveV1
 
     class BasicFetcher #:nodoc:
         

data/lib/{google_drive → google_drive_v1}/client_login_fetcher.rb

@@ -1,10 +1,10 @@
 # Author: Hiroshi Ichikawa <http://gimite.net/>
 # The license of this source is "New BSD Licence"
 
-require "google_drive/basic_fetcher"
+require "google_drive_v1/basic_fetcher"
 
 
-module GoogleDrive
+module GoogleDriveV1
 
     class ClientLoginFetcher < BasicFetcher #:nodoc:
         

data/lib/google_drive_v1/collection.rb

@@ -0,0 +1,167 @@
+# Author: Hiroshi Ichikawa <http://gimite.net/>
+# The license of this source is "New BSD Licence"
+
+require "google_drive_v1/util"
+require "google_drive_v1/error"
+require "google_drive_v1/spreadsheet"
+
+
+module GoogleDriveV1
+
+    # Use GoogleDriveV1::Session#root_collection, GoogleDriveV1::Collection#subcollections,
+    # or GoogleDriveV1::Session#collection_by_url to get GoogleDriveV1::Collection object.
+    class Collection < GoogleDriveV1::File
+
+        include(Util)
+        
+        ROOT_URL = "#{DOCS_BASE_URL}/folder%3Aroot"  #:nodoc:
+
+        alias collection_feed_url document_feed_url
+        
+        def contents_url
+          if self.root?
+            # The root collection doesn't have document feed.
+            return concat_url(ROOT_URL, "/contents")
+          else
+            return self.document_feed_entry_internal.css(
+                "content[type='application/atom+xml;type=feed']")[0]["src"]
+          end
+        end
+        
+        # Title of the collection.
+        #
+        # Set <tt>params[:reload]</tt> to true to force reloading the title.
+        def title(params = {})
+          if self.root?
+            # The root collection doesn't have document feed.
+            return nil
+          else
+            return super
+          end
+        end
+
+        def resource_id
+          return self.root? ? nil : super
+        end
+        
+        # Adds the given GoogleDriveV1::File to the collection.
+        def add(file)
+          header = {"GData-Version" => "3.0", "Content-Type" => "application/atom+xml;charset=utf-8"}
+          xml = <<-"EOS"
+            <entry xmlns="http://www.w3.org/2005/Atom">
+              <id>#{h(file.document_feed_url)}</id>
+            </entry>
+          EOS
+          @session.request(
+              :post, self.contents_url, :data => xml, :header => header, :auth => :writely)
+          return nil
+        end
+
+        # Creates a sub-collection with given title. Returns GoogleDriveV1::Collection object.
+        def create_subcollection(title)
+          header = {"GData-Version" => "3.0", "Content-Type" => "application/atom+xml;charset=utf-8"}
+          xml = <<-EOS
+            <entry xmlns="http://www.w3.org/2005/Atom">
+              <category scheme="http://schemas.google.com/g/2005#kind"
+                term="http://schemas.google.com/docs/2007#folder"/>
+              <title>#{h(title)}</title>
+            </entry>
+          EOS
+          doc = @session.request(
+              :post, contents_url, :data => xml, :header => header, :auth => :writely)
+          return @session.entry_element_to_file(doc)
+        end
+
+        # Removes the given GoogleDriveV1::File from the collection.
+        def remove(file)
+          url = to_v3_url("#{contents_url}/#{file.resource_id}")
+          @session.request(:delete, url, :auth => :writely, :header => {"If-Match" => "*"})
+        end
+
+        # Returns true if this is a root collection
+        def root?
+          self.document_feed_url == ROOT_URL
+        end
+
+        # Returns all the files (including spreadsheets, documents, subcollections) in the collection.
+        #
+        # You can specify query parameters described at
+        # https://developers.google.com/google-apps/documents-list/#getting_a_list_of_documents_and_files
+        #
+        # e.g.
+        #
+        #   # Gets all the files in collection, including subcollections.
+        #   collection.files
+        #   
+        #   # Gets only files with title "hoge".
+        #   collection.files("title" => "hoge", "title-exact" => "true")
+        def files(params = {})
+          return files_with_type(nil, params)
+        end
+
+        alias contents files
+
+        # Returns all the spreadsheets in the collection.
+        def spreadsheets(params = {})
+          return files_with_type("spreadsheet", params)
+        end
+        
+        # Returns all the Google Docs documents in the collection.
+        def documents(params = {})
+          return files_with_type("document", params)
+        end
+        
+        # Returns all its subcollections.
+        def subcollections(params = {})
+          return files_with_type("folder", params)
+        end
+        
+        # Returns a file (can be a spreadsheet, document, subcollection or other files) in the
+        # collection which exactly matches +title+ as GoogleDriveV1::File.
+        # Returns nil if not found. If multiple collections with the +title+ are found, returns
+        # one of them.
+        #
+        # If given an Array, does a recursive subcollection traversal.
+        def file_by_title(title)
+          return file_by_title_with_type(title, nil)
+        end
+        
+        # Returns its subcollection whose title exactly matches +title+ as GoogleDriveV1::Collection.
+        # Returns nil if not found. If multiple collections with the +title+ are found, returns
+        # one of them.
+        #
+        # If given an Array, does a recursive subcollection traversal.
+        def subcollection_by_title(title)
+          return file_by_title_with_type(title, "folder")
+        end
+        
+      protected
+
+        def file_by_title_with_type(title, type)
+          if title.is_a?(Array)
+            rel_path = title
+            if rel_path.empty?
+              return self
+            else
+              parent = subcollection_by_title(rel_path[0...-1])
+              return parent && parent.file_by_title_with_type(rel_path[-1], type)
+            end
+          else
+            return files_with_type(type, "title" => title, "title-exact" => "true")[0]
+          end
+        end
+        
+      private
+
+        def files_with_type(type, params = {})
+          contents_url = self.contents_url
+          contents_url = concat_url(contents_url, "/-/#{type}") if type
+          contents_url = concat_url(contents_url, "?" + encode_query(params))
+          header = {"GData-Version" => "3.0", "Content-Type" => "application/atom+xml;charset=utf-8"}
+          doc = @session.request(:get, contents_url, :header => header, :auth => :writely)
+          return doc.css("feed > entry").map(){ |e| @session.entry_element_to_file(e) }
+        end
+        
+    end
+    
+end

data/lib/google_drive_v1/error.rb

@@ -0,0 +1,12 @@
+# Author: Hiroshi Ichikawa <http://gimite.net/>
+# The license of this source is "New BSD Licence"
+
+
+module GoogleDriveV1
+
+    # Raised when spreadsheets.google.com has returned error.
+    class Error < RuntimeError
+
+    end
+    
+end

data/lib/google_drive_v1/file.rb

@@ -0,0 +1,258 @@
+# Author: Hiroshi Ichikawa <http://gimite.net/>
+# The license of this source is "New BSD Licence"
+
+require "cgi"
+require "stringio"
+
+require "google_drive_v1/util"
+require "google_drive_v1/acl"
+
+
+module GoogleDriveV1
+    
+    # A file in Google Drive, including Google Docs document/spreadsheet/presentation.
+    #
+    # Use GoogleDriveV1::Session#files or GoogleDriveV1::Session#file_by_title to
+    # get this object.
+    class File
+
+        include(Util)
+        
+        def initialize(session, entry_or_url) #: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
+          @acl = nil
+        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: GoogleDriveV1::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]
+          end
+          return @document_feed_entry
+        end
+
+        # Resource ID.
+        def resource_id
+          return self.document_feed_entry_internal.css("gd|resourceId").text
+        end
+
+        # The type of resourse. e.g. "document", "spreadsheet", "folder"
+        def resource_type
+          return self.resource_id.split(/:/)[0]
+        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
+        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"]
+        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(GoogleDriveV1::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 .
+        def available_content_types
+          return self.document_feed_entry_internal.css("content").map(){ |c| c["type"] }
+        end
+        
+        # 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")
+        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
+        end
+        
+        # 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."
+        def download_to_string(params = {})
+          sio = StringIO.new()
+          download_to_io(sio, params)
+          return sio.string
+        end
+        
+        # Downloads the file and writes it 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
+          end
+          if contents.size == 1
+            url = contents[0]["src"]
+          else
+            if contents.empty?
+              raise(GoogleDriveV1::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(GoogleDriveV1::Error,
+                  ("Multiple content types are available for this file. " +
+                   "Specify one of these to content_type: %p") %
+                  [self.available_content_types])
+            end
+          end
+          # TODO Use streaming if possible.
+          body = @session.request(:get, url, :response_type => :raw, :auth => :writely)
+          io.write(body)
+        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 = {})
+          params = {:file_name => ::File.basename(path)}.merge(params)
+          open(path, "rb") do |f|
+            update_from_io(f, params)
+          end
+        end
+        
+        # Updates the file with +content+.
+        #
+        # e.g.
+        #   file.update_from_string("Good bye, world.")
+        def update_from_string(content, params = {})
+          update_from_io(StringIO.new(content), 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)
+        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" => "*"})
+        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)
+        end
+        
+        alias title= rename
+        
+        # Returns GoogleDriveV1::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
+        #     p [entry.scope_type, entry.scope, entry.role]
+        #     # => e.g. ["user", "example1@gmail.com", "owner"]
+        #   end
+        #   
+        #   # 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"})
+        #   file.acl.push(
+        #       {:scope_type => "user", :scope => "example3@gmail.com", :role => "writer"})
+        #   
+        #   # Changes the role of a person:
+        #   file.acl[1].role = "writer"
+        #   
+        #   # Deletes an ACL entry:
+        #   file.acl.delete(file.acl[1])
+        def acl(params = {})
+          if !@acl || params[:reload]
+            @acl = Acl.new(@session, self.acl_feed_url)
+          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(", ")]
+        end
+        
+    end
+    
+end