google-spreadsheet-ruby 0.1.8 → 0.2.1

data/lib/google_spreadsheet/spreadsheet.rb

@@ -0,0 +1,298 @@
+# Author: Hiroshi Ichikawa <http://gimite.net/>
+# The license of this source is "New BSD Licence"
+
+require "google_spreadsheet/util"
+require "google_spreadsheet/error"
+require "google_spreadsheet/worksheet"
+require "google_spreadsheet/table"
+require "google_spreadsheet/acl"
+
+
+module GoogleSpreadsheet
+    
+    # A spreadsheet.
+    #
+    # Use methods in GoogleSpreadsheet::Session to get GoogleSpreadsheet::Spreadsheet object.
+    class Spreadsheet
+
+        include(Util)
+        
+        SUPPORTED_EXPORT_FORMAT = Set.new(["xls", "csv", "pdf", "ods", "tsv", "html"])
+
+        def initialize(session, worksheets_feed_url, title = nil) #:nodoc:
+          @session = session
+          @worksheets_feed_url = worksheets_feed_url
+          @title = title
+          @acl = nil
+        end
+
+        # URL of worksheet-based feed of the spreadsheet.
+        attr_reader(:worksheets_feed_url)
+
+        # Title of the spreadsheet.
+        #
+        # Set params[:reload] to true to force reloading the title.
+        def title(params = {})
+          if !@title || params[:reload]
+            @title = spreadsheet_feed_entry(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(GoogleSpreadsheet::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.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
+
+        # ACL feed URL of the spreadsheet.
+        def acl_feed_url
+          orig_acl_feed_url = document_feed_entry.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 "https://docs.google.com/feeds/default/private/full/#{$1}/acl"
+            else
+              raise(GoogleSpreadsheet::Error,
+                "ACL feed URL is in unknown format: #{orig_acl_feed_url}")
+          end
+        end
+
+        # <entry> element of spreadsheet feed as Nokogiri::XML::Element.
+        #
+        # Set params[:reload] to true to force reloading the feed.
+        def spreadsheet_feed_entry(params = {})
+          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 params[:reload] to true to force reloading the feed.
+        def document_feed_entry(params = {})
+          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")
+          post_url = "https://docs.google.com/feeds/default/private/full/"
+          header = {"GData-Version" => "3.0", "Content-Type" => "application/atom+xml"}
+          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, post_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
+
+        # If +permanent+ is +false+, moves the spreadsheet to the trash.
+        # If +permanent+ is +true+, deletes the spreadsheet permanently.
+        def delete(permanent = false)
+          @session.request(:delete,
+            self.document_feed_url + (permanent ? "?delete=true" : ""),
+            :auth => :writely, :header => {"If-Match" => "*"})
+        end
+
+        # Renames title of the spreadsheet.
+        def rename(title)
+          doc = @session.request(:get, self.document_feed_url, :auth => :writely)
+          edit_url = doc.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:category
+                scheme="http://schemas.google.com/g/2005#kind"
+                term="http://schemas.google.com/docs/2007#spreadsheet" label="spreadsheet"/>
+              <atom:title>#{h(title)}</atom:title>
+            </atom:entry>
+          EOS
+
+          @session.request(:put, edit_url, :data => xml, :auth => :writely)
+        end
+        
+        alias title= rename
+        
+        # Exports the spreadsheet in +format+ and returns it as String.
+        #
+        # +format+ can be either "xls", "csv", "pdf", "ods", "tsv" or "html".
+        # In format such as "csv", only the worksheet specified with +worksheet_index+ is
+        # exported.
+        def export_as_string(format, worksheet_index = nil)
+          gid_param = worksheet_index ? "&gid=#{worksheet_index}" : ""
+          url =
+              "https://spreadsheets.google.com/feeds/download/spreadsheets/Export" +
+              "?key=#{key}&exportFormat=#{format}#{gid_param}"
+          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
+        
+        # Returns worksheets of the spreadsheet as array of GoogleSpreadsheet::Worksheet.
+        def worksheets
+          doc = @session.request(:get, @worksheets_feed_url)
+          if doc.root.name != "feed"
+            raise(GoogleSpreadsheet::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
+            url = entry.css(
+              "link[rel='http://schemas.google.com/spreadsheets/2006#cellsfeed']")[0]["href"]
+            result.push(Worksheet.new(@session, self, url, title))
+          end
+          return result.freeze()
+        end
+        
+        # Returns a GoogleSpreadsheet::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 GoogleSpreadsheet::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
+
+        # Returns GoogleSpreadsheet::Acl object for the spreadsheet.
+        #
+        # With the object, you can see and modify people who can access the spreadsheet.
+        # Modifications take effect immediately.
+        #
+        # Set params[:reload] to true to force reloading the title.
+        #
+        # e.g.
+        #   # Dumps people who have access:
+        #   for entry in spreadsheet.acl
+        #     p [entry.scope_type, entry.scope, entry.role]
+        #     # => e.g. ["user", "example1@gmail.com", "owner"]
+        #   end
+        #   
+        #   # Shares the spreadsheet with new people:
+        #   # NOTE: This sends email to the new people.
+        #   spreadsheet.acl.push(
+        #       {:scope_type => "user", :scope => "example2@gmail.com", :role => "reader"})
+        #   spreadsheet.acl.push(
+        #       {:scope_type => "user", :scope => "example3@gmail.com", :role => "writer"})
+        #   
+        #   # Changes the role of a person:
+        #   spreadsheet.acl[1].role = "writer"
+        #   
+        #   # Deletes an ACL entry:
+        #   spreadsheet.acl.delete(spreadsheet.acl[1])
+
+        def acl(params = {})
+          if !@acl || params[:reload]
+            @acl = Acl.new(@session, self.acl_feed_url)
+          end
+          return @acl
+        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_spreadsheet/table.rb

@@ -0,0 +1,60 @@
+# Author: Hiroshi Ichikawa <http://gimite.net/>
+# The license of this source is "New BSD Licence"
+
+require "google_spreadsheet/util"
+require "google_spreadsheet/error"
+require "google_spreadsheet/record"
+
+
+module GoogleSpreadsheet
+
+    # DEPRECATED: Table and Record feeds are deprecated and they will not be available after
+    # March 2012.
+    #
+    # Use GoogleSpreadsheet::Worksheet#add_table to create table.
+    # Use GoogleSpreadsheet::Worksheet#tables to get GoogleSpreadsheet::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_spreadsheet/util.rb

@@ -0,0 +1,30 @@
+# Author: Hiroshi Ichikawa <http://gimite.net/>
+# The license of this source is "New BSD Licence"
+
+require "cgi"
+
+
+module GoogleSpreadsheet
+    
+    module Util #:nodoc:
+        
+      module_function
+        
+        def encode_query(params)
+          return params.map(){ |k, v| CGI.escape(k) + "=" + CGI.escape(v) }.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
+        
+        def h(str)
+          return CGI.escapeHTML(str.to_s())
+        end
+        
+    end
+    
+end

data/lib/google_spreadsheet/worksheet.rb

@@ -0,0 +1,445 @@
+# Author: Hiroshi Ichikawa <http://gimite.net/>
+# The license of this source is "New BSD Licence"
+
+require "set"
+
+require "google_spreadsheet/util"
+require "google_spreadsheet/error"
+require "google_spreadsheet/table"
+require "google_spreadsheet/list"
+
+
+module GoogleSpreadsheet
+
+    # A worksheet (i.e. a tab) in a spreadsheet.
+    # Use GoogleSpreadsheet::Spreadsheet#worksheets to get GoogleSpreadsheet::Worksheet object.
+    class Worksheet
+
+        include(Util)
+
+        def initialize(session, spreadsheet, cells_feed_url, title = nil) #:nodoc:
+          
+          @session = session
+          @spreadsheet = spreadsheet
+          @cells_feed_url = cells_feed_url
+          @title = title
+
+          @cells = nil
+          @input_values = nil
+          @modified = Set.new()
+          @list = nil
+          
+        end
+
+        # URL of cell-based feed of the worksheet.
+        attr_reader(:cells_feed_url)
+
+        # URL of worksheet feed URL of the worksheet.
+        def worksheet_feed_url
+          # I don't know good way to get worksheet feed URL from cells feed URL.
+          # Probably it would be cleaner to keep worksheet feed URL and get cells feed URL
+          # from it.
+          if !(@cells_feed_url =~
+              %r{^https?://spreadsheets.google.com/feeds/cells/(.*)/(.*)/private/full((\?.*)?)$})
+            raise(GoogleSpreadsheet::Error,
+              "Cells feed URL is in unknown format: #{@cells_feed_url}")
+          end
+          return "https://spreadsheets.google.com/feeds/worksheets/#{$1}/private/full/#{$2}#{$3}"
+        end
+
+        # GoogleSpreadsheet::Spreadsheet which this worksheet belongs to.
+        def spreadsheet
+          if !@spreadsheet
+            if !(@cells_feed_url =~
+                %r{^https?://spreadsheets.google.com/feeds/cells/(.*)/(.*)/private/full(\?.*)?$})
+              raise(GoogleSpreadsheet::Error,
+                "Cells feed URL is in unknown format: #{@cells_feed_url}")
+            end
+            @spreadsheet = @session.spreadsheet_by_key($1)
+          end
+          return @spreadsheet
+        end
+
+        # Returns content of the cell as String. Arguments must be either
+        # (row number, column number) or cell name. Top-left cell is [1, 1].
+        #
+        # e.g.
+        #   worksheet[2, 1]  #=> "hoge"
+        #   worksheet["A2"]  #=> "hoge"
+        def [](*args)
+          (row, col) = parse_cell_args(args)
+          return self.cells[[row, col]] || ""
+        end
+
+        # Updates content of the cell.
+        # Arguments in the bracket must be either (row number, column number) or cell name. 
+        # Note that update is not sent to the server until you call save().
+        # Top-left cell is [1, 1].
+        #
+        # e.g.
+        #   worksheet[2, 1] = "hoge"
+        #   worksheet["A2"] = "hoge"
+        #   worksheet[1, 3] = "=A1+B1"
+        def []=(*args)
+          (row, col) = parse_cell_args(args[0...-1])
+          value = args[-1].to_s()
+          reload() if !@cells
+          @cells[[row, col]] = value
+          @input_values[[row, col]] = value
+          @modified.add([row, col])
+          self.max_rows = row if row > @max_rows
+          self.max_cols = col if col > @max_cols
+        end
+
+        # Updates cells in a rectangle area by a two-dimensional Array.
+        # +top_row+ and +left_col+ specifies the top-left corner of the area.
+        #
+        # e.g.
+        #   worksheet.update_cells(2, 3, [["1", "2"], ["3", "4"]])
+        def update_cells(top_row, left_col, darray)
+          darray.each_with_index() do |array, y|
+            array.each_with_index() do |value, x|
+              self[top_row + y, left_col + x] = value
+            end
+          end
+        end
+
+        # Returns the value or the formula of the cell. Arguments must be either
+        # (row number, column number) or cell name. Top-left cell is [1, 1].
+        #
+        # If user input "=A1+B1" to cell [1, 3]:
+        #   worksheet[1, 3]              #=> "3" for example
+        #   worksheet.input_value(1, 3)  #=> "=RC[-2]+RC[-1]"
+        def input_value(*args)
+          (row, col) = parse_cell_args(args)
+          reload() if !@cells
+          return @input_values[[row, col]] || ""
+        end
+
+        # Row number of the bottom-most non-empty row.
+        def num_rows
+          reload() if !@cells
+          return @input_values.select(){ |(r, c), v| !v.empty? }.map(){ |(r, c), v| r }.max || 0
+        end
+
+        # Column number of the right-most non-empty column.
+        def num_cols
+          reload() if !@cells
+          return @input_values.select(){ |(r, c), v| !v.empty? }.map(){ |(r, c), v| c }.max || 0
+        end
+
+        # Number of rows including empty rows.
+        def max_rows
+          reload() if !@cells
+          return @max_rows
+        end
+
+        # Updates number of rows.
+        # Note that update is not sent to the server until you call save().
+        def max_rows=(rows)
+          reload() if !@cells
+          @max_rows = rows
+          @meta_modified = true
+        end
+
+        # Number of columns including empty columns.
+        def max_cols
+          reload() if !@cells
+          return @max_cols
+        end
+
+        # Updates number of columns.
+        # Note that update is not sent to the server until you call save().
+        def max_cols=(cols)
+          reload() if !@cells
+          @max_cols = cols
+          @meta_modified = true
+        end
+
+        # Title of the worksheet (shown as tab label in Web interface).
+        def title
+          reload() if !@title
+          return @title
+        end
+
+        # Updates title of the worksheet.
+        # Note that update is not sent to the server until you call save().
+        def title=(title)
+          reload() if !@cells
+          @title = title
+          @meta_modified = true
+        end
+
+        def cells #:nodoc:
+          reload() if !@cells
+          return @cells
+        end
+
+        # An array of spreadsheet rows. Each row contains an array of
+        # columns. Note that resulting array is 0-origin so
+        # worksheet.rows[0][0] == worksheet[1, 1].
+        def rows(skip = 0)
+          nc = self.num_cols
+          result = ((1 + skip)..self.num_rows).map() do |row|
+            (1..nc).map(){ |col| self[row, col] }.freeze()
+          end
+          return result.freeze()
+        end
+
+        # Reloads content of the worksheets from the server.
+        # Note that changes you made by []= etc. is discarded if you haven't called save().
+        def reload()
+          
+          doc = @session.request(:get, @cells_feed_url)
+          @max_rows = doc.css("gs|rowCount").text.to_i()
+          @max_cols = doc.css("gs|colCount").text.to_i()
+          @title = doc.css("feed > title")[0].text
+
+          @cells = {}
+          @input_values = {}
+          doc.css("feed > entry").each() do |entry|
+            cell = entry.css("gs|cell")[0]
+            row = cell["row"].to_i()
+            col = cell["col"].to_i()
+            @cells[[row, col]] = cell.inner_text
+            @input_values[[row, col]] = cell["inputValue"]
+          end
+          @modified.clear()
+          @meta_modified = false
+          return true
+          
+        end
+
+        # Saves your changes made by []=, etc. to the server.
+        def save()
+          
+          sent = false
+
+          if @meta_modified
+
+            ws_doc = @session.request(:get, self.worksheet_feed_url)
+            edit_url = ws_doc.css("link[rel='edit']")[0]["href"]
+            xml = <<-"EOS"
+              <entry xmlns='http://www.w3.org/2005/Atom'
+                     xmlns:gs='http://schemas.google.com/spreadsheets/2006'>
+                <title>#{h(self.title)}</title>
+                <gs:rowCount>#{h(self.max_rows)}</gs:rowCount>
+                <gs:colCount>#{h(self.max_cols)}</gs:colCount>
+              </entry>
+            EOS
+
+            @session.request(:put, edit_url, :data => xml)
+
+            @meta_modified = false
+            sent = true
+
+          end
+
+          if !@modified.empty?
+
+            # Gets id and edit URL for each cell.
+            # Note that return-empty=true is required to get those info for empty cells.
+            cell_entries = {}
+            rows = @modified.map(){ |r, c| r }
+            cols = @modified.map(){ |r, c| c }
+            url = concat_url(@cells_feed_url,
+                "?return-empty=true&min-row=#{rows.min}&max-row=#{rows.max}" +
+                "&min-col=#{cols.min}&max-col=#{cols.max}")
+            doc = @session.request(:get, url)
+
+            doc.css("entry").each() do |entry|
+              row = entry.css("gs|cell")[0]["row"].to_i()
+              col = entry.css("gs|cell")[0]["col"].to_i()
+              cell_entries[[row, col]] = entry
+            end
+
+            # Updates cell values using batch operation.
+            # If the data is large, we split it into multiple operations, otherwise batch may fail.
+            @modified.each_slice(250) do |chunk|
+
+              xml = <<-EOS
+                <feed xmlns="http://www.w3.org/2005/Atom"
+                      xmlns:batch="http://schemas.google.com/gdata/batch"
+                      xmlns:gs="http://schemas.google.com/spreadsheets/2006">
+                  <id>#{h(@cells_feed_url)}</id>
+              EOS
+              for row, col in chunk
+                value = @cells[[row, col]]
+                entry = cell_entries[[row, col]]
+                id = entry.css("id").text
+                edit_url = entry.css("link[rel='edit']")[0]["href"]
+                xml << <<-EOS
+                  <entry>
+                    <batch:id>#{h(row)},#{h(col)}</batch:id>
+                    <batch:operation type="update"/>
+                    <id>#{h(id)}</id>
+                    <link rel="edit" type="application/atom+xml"
+                      href="#{h(edit_url)}"/>
+                    <gs:cell row="#{h(row)}" col="#{h(col)}" inputValue="#{h(value)}"/>
+                  </entry>
+                EOS
+              end
+              xml << <<-"EOS"
+                </feed>
+              EOS
+
+              batch_url = concat_url(@cells_feed_url, "/batch")
+              result = @session.request(:post, batch_url, :data => xml)
+              result.css("atom|entry").each() do |entry|
+                interrupted = entry.css("batch|interrupted")[0]
+                if interrupted
+                  raise(GoogleSpreadsheet::Error, "Update has failed: %s" %
+                    interrupted["reason"])
+                end
+                if !(entry.css("batch|status").first["code"] =~ /^2/)
+                  raise(GoogleSpreadsheet::Error, "Updating cell %s has failed: %s" %
+                    [entry.css("atom|id").text, entry.css("batch|status")[0]["reason"]])
+                end
+              end
+
+            end
+
+            @modified.clear()
+            sent = true
+
+          end
+          
+          return sent
+          
+        end
+
+        # Calls save() and reload().
+        def synchronize()
+          save()
+          reload()
+        end
+
+        # Deletes this worksheet. Deletion takes effect right away without calling save().
+        def delete()
+          ws_doc = @session.request(:get, self.worksheet_feed_url)
+          edit_url = ws_doc.css("link[rel='edit']")[0]["href"]
+          @session.request(:delete, edit_url)
+        end
+
+        # Returns true if you have changes made by []= which haven't been saved.
+        def dirty?
+          return !@modified.empty?
+        end
+
+        # DEPRECATED: Table and Record feeds are deprecated and they will not be available after
+        # March 2012.
+        #
+        # Creates table for the worksheet and returns GoogleSpreadsheet::Table.
+        # See this document for details:
+        # http://code.google.com/intl/en/apis/spreadsheets/docs/3.0/developers_guide_protocol.html#TableFeeds
+        def add_table(table_title, summary, columns, options)
+          
+          warn(
+              "DEPRECATED: Google Spreadsheet Table and Record feeds are deprecated and they " +
+              "will not be available after March 2012.")
+          default_options = { :header_row => 1, :num_rows => 0, :start_row => 2}
+          options = default_options.merge(options)
+
+          column_xml = ""
+          columns.each() do |index, name|
+            column_xml += "<gs:column index='#{h(index)}' name='#{h(name)}'/>\n"
+          end
+
+          xml = <<-"EOS"
+            <entry xmlns="http://www.w3.org/2005/Atom"
+              xmlns:gs="http://schemas.google.com/spreadsheets/2006">
+              <title type='text'>#{h(table_title)}</title>
+              <summary type='text'>#{h(summary)}</summary>
+              <gs:worksheet name='#{h(self.title)}' />
+              <gs:header row='#{options[:header_row]}' />
+              <gs:data numRows='#{options[:num_rows]}' startRow='#{options[:start_row]}'>
+                #{column_xml}
+              </gs:data>
+            </entry>
+          EOS
+
+          result = @session.request(:post, self.spreadsheet.tables_feed_url, :data => xml)
+          return Table.new(@session, result)
+          
+        end
+
+        # DEPRECATED: Table and Record feeds are deprecated and they will not be available after
+        # March 2012.
+        #
+        # Returns list of tables for the workwheet.
+        def tables
+          warn(
+              "DEPRECATED: Google Spreadsheet Table and Record feeds are deprecated and they " +
+              "will not be available after March 2012.")
+          return self.spreadsheet.tables.select(){ |t| t.worksheet_title == self.title }
+        end
+
+        # List feed URL of the worksheet.
+        def list_feed_url
+          # Gets the worksheets metafeed.
+          entry = @session.request(:get, self.worksheet_feed_url)
+
+          # Gets the URL of list-based feed for the given spreadsheet.
+          return entry.css(
+            "link[rel='http://schemas.google.com/spreadsheets/2006#listfeed']")[0]["href"]
+        end
+        
+        # Provides access to cells using column names, assuming the first row contains column
+        # names. Returned object is GoogleSpreadsheet::List which you can use mostly as
+        # Array of Hash.
+        #
+        # e.g. Assuming the first row is ["x", "y"]:
+        #   worksheet.list[0]["x"]  #=> "1"  # i.e. worksheet[2, 1]
+        #   worksheet.list[0]["y"]  #=> "2"  # i.e. worksheet[2, 2]
+        #   worksheet.list[1]["x"] = "3"     # i.e. worksheet[3, 1] = "3"
+        #   worksheet.list[1]["y"] = "4"     # i.e. worksheet[3, 2] = "4"
+        #   worksheet.list.push({"x" => "5", "y" => "6"})
+        #
+        # Note that update is not sent to the server until you call save().
+        def list
+          return @list ||= List.new(self)
+        end
+        
+        # Returns a [row, col] pair for a cell name string.
+        # e.g.
+        #   worksheet.cell_name_to_row_col("C2")  #=> [2, 3]
+        def cell_name_to_row_col(cell_name)
+          if !cell_name.is_a?(String)
+            raise(ArgumentError, "Cell name must be a string: %p" % cell_name)
+          end
+          if !(cell_name.upcase =~ /^([A-Z]+)(\d+)$/)
+            raise(ArgumentError,
+                "Cell name must be only letters followed by digits with no spaces in between: %p" %
+                    cell_name)
+          end
+          col = 0
+          $1.each_byte() do |b|
+            # 0x41: "A"
+            col = col * 26 + (b - 0x41 + 1)
+          end
+          row = $2.to_i()
+          return [row, col]
+        end
+
+        def inspect
+          fields = {:worksheet_feed_url => self.worksheet_feed_url}
+          fields[:title] = @title if @title
+          return "\#<%p %s>" % [self.class, fields.map(){ |k, v| "%s=%p" % [k, v] }.join(", ")]
+        end
+        
+      private
+
+        def parse_cell_args(args)
+          if args.size == 1 && args[0].is_a?(String)
+            return cell_name_to_row_col(args[0])
+          elsif args.size == 2 && args[0].is_a?(Integer) && args[1].is_a?(Integer)
+            return args
+          else
+            raise(ArgumentError,
+                "Arguments must be either one String or two Integer's, but are %p" % args)
+          end
+        end
+        
+    end
+    
+end