google_drive 0.3.11 → 1.0.0.pre1

data/lib/google_drive_v1/spreadsheet.rb

@@ -0,0 +1,248 @@
+# Author: Hiroshi Ichikawa <http://gimite.net/>
+# The license of this source is "New BSD Licence"
+
+require "time"
+
+require "google_drive_v1/util"
+require "google_drive_v1/error"
+require "google_drive_v1/worksheet"
+require "google_drive_v1/table"
+require "google_drive_v1/acl"
+require "google_drive_v1/file"
+
+
+module GoogleDriveV1
+    
+    # A spreadsheet.
+    #
+    # Use methods in GoogleDriveV1::Session to get GoogleDriveV1::Spreadsheet object.
+    class Spreadsheet < GoogleDriveV1::File
+
+        include(Util)
+        
+        SUPPORTED_EXPORT_FORMAT = Set.new(["xls", "csv", "pdf", "ods", "tsv", "html"])
+
+        def initialize(session, worksheets_feed_url, title = nil) #:nodoc:
+          super(session, nil)
+          @worksheets_feed_url = worksheets_feed_url
+          @title = title
+        end
+
+        # URL of worksheet-based feed of the spreadsheet.
+        attr_reader(:worksheets_feed_url)
+
+        # Title of the spreadsheet.
+        #
+        # Set <tt>params[:reload]</tt> to true to force reloading the title.
+        def title(params = {})
+          if !@title || params[:reload]
+            @title = spreadsheet_feed_entry_internal(params).css("title").text
+          end
+          return @title
+        end
+
+        # Key of the spreadsheet.
+        def key
+          if !(@worksheets_feed_url =~
+              %r{^https?://spreadsheets.google.com/feeds/worksheets/(.*)/private/.*$})
+            raise(GoogleDriveV1::Error,
+              "Worksheets feed URL is in unknown format: #{@worksheets_feed_url}")
+          end
+          return $1
+        end
+        
+        # Spreadsheet feed URL of the spreadsheet.
+        def spreadsheet_feed_url
+          return "https://spreadsheets.google.com/feeds/spreadsheets/private/full/#{self.key}"
+        end
+        
+        # URL which you can open the spreadsheet in a Web browser with.
+        #
+        # e.g. "http://spreadsheets.google.com/ccc?key=pz7XtlQC-PYx-jrVMJErTcg"
+        def human_url
+          # Uses Document feed because Spreadsheet feed returns wrong URL for Apps account.
+          return self.document_feed_entry_internal.css("link[rel='alternate']")[0]["href"]
+        end
+
+        # DEPRECATED: Table and Record feeds are deprecated and they will not be available after
+        # March 2012.
+        #
+        # Tables feed URL of the spreadsheet.
+        def tables_feed_url
+          warn(
+              "DEPRECATED: Google Spreadsheet Table and Record feeds are deprecated and they " +
+              "will not be available after March 2012.")
+          return "https://spreadsheets.google.com/feeds/#{self.key}/tables"
+        end
+
+        # URL of feed used in document list feed API.
+        def document_feed_url
+          return "https://docs.google.com/feeds/documents/private/full/spreadsheet%3A#{self.key}"
+        end
+
+        # <entry> element of spreadsheet feed as Nokogiri::XML::Element.
+        #
+        # Set <tt>params[:reload]</tt> to true to force reloading the feed.
+        def spreadsheet_feed_entry(params = {})
+          warn(
+              "WARNING: GoogleDriveV1::Spreadsheet\#spreadsheet_feed_entry is deprecated and will be removed " +
+              "in the next version.")
+          return spreadsheet_feed_entry_internal(params)
+        end
+        
+        def spreadsheet_feed_entry_internal(params = {}) #:nodoc
+          if !@spreadsheet_feed_entry || params[:reload]
+            @spreadsheet_feed_entry =
+                @session.request(:get, self.spreadsheet_feed_url).css("entry")[0]
+          end
+          return @spreadsheet_feed_entry
+        end
+        
+        # <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::Spreadsheet\#document_feed_entry is deprecated and will be removed " +
+              "in the next version.")
+          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
+        
+        # Creates copy of this spreadsheet with the given title.
+        def duplicate(new_title = nil)
+          new_title ||= (self.title ? "Copy of " + self.title : "Untitled")
+          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(self.document_feed_url)}</id>
+              <title>#{h(new_title)}</title>
+            </entry>
+          EOS
+          doc = @session.request(
+              :post, DOCS_BASE_URL, :data => xml, :header => header, :auth => :writely)
+          ss_url = doc.css(
+              "link[rel='http://schemas.google.com/spreadsheets/2006#worksheetsfeed']")[0]["href"]
+          return Spreadsheet.new(@session, ss_url, new_title)
+        end
+
+        # Exports the spreadsheet in +format+ and returns it as String.
+        #
+        # +format+ can be either "csv" or "pdf".
+        # In format such as "csv", only the worksheet specified with +worksheet_index+ is
+        # exported.
+        def export_as_string(format, worksheet_index = nil)
+          if ["xls", "ods", "tsv", "html"].include?(format)
+            warn("WARNING: Export with format '%s' is deprecated, and will not work in the next version." % format)
+          end
+          gid_param = worksheet_index ? "&gid=#{worksheet_index}" : ""
+          format_string = "&format=#{format}"
+          if self.human_url.match("edit")
+            url = self.human_url.gsub(/edit/, "export") + gid_param + format_string
+          else
+            url =
+              "https://spreadsheets.google.com/feeds/download/spreadsheets/Export" +
+              "?key=#{key}&exportFormat=#{format}#{gid_param}"
+          end
+          return @session.request(:get, url, :response_type => :raw)
+        end
+        
+        # Exports the spreadsheet in +format+ as a local file.
+        #
+        # +format+ can be either "xls", "csv", "pdf", "ods", "tsv" or "html".
+        # If +format+ is nil, it is guessed from the file name.
+        # In format such as "csv", only the worksheet specified with +worksheet_index+ is exported.
+        #
+        # e.g.
+        #   spreadsheet.export_as_file("hoge.ods")
+        #   spreadsheet.export_as_file("hoge.csv", nil, 0)
+        def export_as_file(local_path, format = nil, worksheet_index = nil)
+          if !format
+            format = ::File.extname(local_path).gsub(/^\./, "")
+            if !SUPPORTED_EXPORT_FORMAT.include?(format)
+              raise(ArgumentError,
+                  ("Cannot guess format from the file name: %s\n" +
+                   "Specify format argument explicitly.") %
+                  local_path)
+            end
+          end
+          open(local_path, "wb") do |f|
+            f.write(export_as_string(format, worksheet_index))
+          end
+        end
+        
+        def download_to_io(io, params = {})
+          # General downloading API doesn't work for spreadsheets because it requires a different
+          # authorization token, and it has a bug that it downloads PDF when text/html is
+          # requested.
+          raise(NotImplementedError,
+              "Use export_as_file or export_as_string instead for GoogleDriveV1::Spreadsheet.")
+        end
+        
+        # Returns worksheets of the spreadsheet as array of GoogleDriveV1::Worksheet.
+        def worksheets
+          doc = @session.request(:get, @worksheets_feed_url)
+          if doc.root.name != "feed"
+            raise(GoogleDriveV1::Error,
+                "%s doesn't look like a worksheets feed URL because its root is not <feed>." %
+                @worksheets_feed_url)
+          end
+          result = []
+          doc.css("entry").each() do |entry|
+            title = entry.css("title").text
+            updated = Time.parse(entry.css("updated").text)
+            url = entry.css(
+              "link[rel='http://schemas.google.com/spreadsheets/2006#cellsfeed']")[0]["href"]
+            result.push(Worksheet.new(@session, self, url, title, updated))
+          end
+          return result.freeze()
+        end
+        
+        # Returns a GoogleDriveV1::Worksheet with the given title in the spreadsheet.
+        #
+        # Returns nil if not found. Returns the first one when multiple worksheets with the
+        # title are found.
+        def worksheet_by_title(title)
+          return self.worksheets.find(){ |ws| ws.title == title }
+        end
+
+        # Adds a new worksheet to the spreadsheet. Returns added GoogleDriveV1::Worksheet.
+        def add_worksheet(title, max_rows = 100, max_cols = 20)
+          xml = <<-"EOS"
+            <entry xmlns='http://www.w3.org/2005/Atom'
+                   xmlns:gs='http://schemas.google.com/spreadsheets/2006'>
+              <title>#{h(title)}</title>
+              <gs:rowCount>#{h(max_rows)}</gs:rowCount>
+              <gs:colCount>#{h(max_cols)}</gs:colCount>
+            </entry>
+          EOS
+          doc = @session.request(:post, @worksheets_feed_url, :data => xml)
+          url = doc.css(
+            "link[rel='http://schemas.google.com/spreadsheets/2006#cellsfeed']")[0]["href"]
+          return Worksheet.new(@session, self, url, title)
+        end
+
+        # DEPRECATED: Table and Record feeds are deprecated and they will not be available after
+        # March 2012.
+        #
+        # Returns list of tables in the spreadsheet.
+        def tables
+          warn(
+              "DEPRECATED: Google Spreadsheet Table and Record feeds are deprecated and they " +
+              "will not be available after March 2012.")
+          doc = @session.request(:get, self.tables_feed_url)
+          return doc.css("entry").map(){ |e| Table.new(@session, e) }.freeze()
+        end
+        
+        def inspect
+          fields = {:worksheets_feed_url => self.worksheets_feed_url}
+          fields[:title] = @title if @title
+          return "\#<%p %s>" % [self.class, fields.map(){ |k, v| "%s=%p" % [k, v] }.join(", ")]
+        end
+        
+    end
+    
+end

data/lib/google_drive_v1/table.rb

@@ -0,0 +1,60 @@
+# 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/record"
+
+
+module GoogleDriveV1
+
+    # DEPRECATED: Table and Record feeds are deprecated and they will not be available after
+    # March 2012.
+    #
+    # Use GoogleDriveV1::Worksheet#add_table to create table.
+    # Use GoogleDriveV1::Worksheet#tables to get GoogleDriveV1::Table objects.
+    class Table
+
+        include(Util)
+
+        def initialize(session, entry) #:nodoc:
+          @columns = {}
+          @worksheet_title = entry.css("gs|worksheet")[0]["name"]
+          @records_url = entry.css("content")[0]["src"]
+          @edit_url = entry.css("link[rel='edit']")[0]["href"]
+          @session = session
+        end
+
+        # Title of the worksheet the table belongs to.
+        attr_reader(:worksheet_title)
+
+        # Adds a record.
+        def add_record(values)
+          fields = ""
+          values.each() do |name, value|
+            fields += "<gs:field name='#{h(name)}'>#{h(value)}</gs:field>"
+          end
+          xml =<<-EOS
+            <entry
+                xmlns="http://www.w3.org/2005/Atom"
+                xmlns:gs="http://schemas.google.com/spreadsheets/2006">
+              #{fields}
+            </entry>
+          EOS
+          @session.request(:post, @records_url, :data => xml)
+        end
+
+        # Returns records in the table.
+        def records
+          doc = @session.request(:get, @records_url)
+          return doc.css("entry").map(){ |e| Record.new(@session, e) }
+        end
+
+        # Deletes this table. Deletion takes effect right away without calling save().
+        def delete
+          @session.request(:delete, @edit_url, :header => {"If-Match" => "*"})
+        end
+
+    end
+    
+end

data/lib/google_drive_v1/util.rb

@@ -0,0 +1,73 @@
+# Author: Hiroshi Ichikawa <http://gimite.net/>
+# The license of this source is "New BSD Licence"
+
+require "cgi"
+
+
+module GoogleDriveV1
+    
+    module Util #:nodoc:
+
+        # The beginning of Doc List API URL that is used in all requests (version 3).
+        DOCS_BASE_URL = "https://docs.google.com/feeds/default/private/full"
+        
+        EXT_TO_CONTENT_TYPE = {
+            ".csv" =>"text/csv",
+            ".tsv" =>"text/tab-separated-values",
+            ".tab" =>"text/tab-separated-values",
+            ".doc" =>"application/msword",
+            ".docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+            ".ods" =>"application/x-vnd.oasis.opendocument.spreadsheet",
+            ".odt" =>"application/vnd.oasis.opendocument.text",
+            ".rtf" =>"application/rtf",
+            ".sxw" =>"application/vnd.sun.xml.writer",
+            ".txt" =>"text/plain",
+            ".xls" =>"application/vnd.ms-excel",
+            ".xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+            ".pdf" =>"application/pdf",
+            ".png" =>"image/png",
+            ".ppt" =>"application/vnd.ms-powerpoint",
+            ".pps" =>"application/vnd.ms-powerpoint",
+            ".htm" =>"text/html",
+            ".html" =>"text/html",
+            ".zip" =>"application/zip",
+            ".swf" =>"application/x-shockwave-flash",
+        }
+        
+      module_function
+        
+        def encode_query(params)
+          for k, v in params
+            if ["ocr", "targetLanguage", "sourceLanguage"].include?(k.to_s())
+              warn("WARNING: Parameter '%s' is deprecated, and will not work in the next version." % k)
+            end
+          end
+          return params.map(){ |k, v| CGI.escape(k.to_s()) + "=" + CGI.escape(v.to_s()) }.join("&")
+        end
+        
+        def concat_url(url, piece)
+          (url_base, url_query) = url.split(/\?/, 2)
+          (piece_base, piece_query) = piece.split(/\?/, 2)
+          result_query = [url_query, piece_query].select(){ |s| s && !s.empty? }.join("&")
+          return (url_base || "") +
+              (piece_base || "") +
+              (result_query.empty? ? "" : "?#{result_query}")
+        end
+
+        # Returns a URL with added version parameter ("?v=3") if needed.
+        def to_v3_url(url)
+          if url =~ %r{docs.google.com/feeds/default/private/} && !(url =~ /[?&]v=3/)
+            return concat_url(url, "?v=3")
+          else
+            return url
+          end
+        end
+
+        def h(str)
+          # Should also escape "\n" to keep it in cell contents.
+          return CGI.escapeHTML(str.to_s()).gsub(/\n/, '&#x0a;')
+        end
+        
+    end
+    
+end