robust_excel_ole 1.31 → 1.32

data/docs/README_save_close.rdoc

@@ -6,7 +6,7 @@
 
 Imagine, you have opened a workbook with
 
-  workbook = Workbook.open('spec/data/workbook.xls', :visible => true)
+  workbook = Workbook.open('spec/data/workbook.xls', visible: true)
 
 and have modified it.
 
@@ -33,13 +33,13 @@ If a workbook with the file name already exists, then
   
 For example, you want to save a workbook and overwrite the file if it exists before, then use
 
-  workbook.save_as('another_workbook.xls', :if_exists => :overwrite) 
+  workbook.save_as('another_workbook.xls', if_exists: :overwrite) 
 
 If a workbook blocks the workbook that should be saved, then the former one can be saved and closed before.
 
   workbook = Workbook.open('spec/data/workbook.xls')
   workbook2 = Workbook.open('spec/data/another_workbook.xls')
-  workbook2.save_as('dir/workbook.xls', :if_exists => :overwrite, :if_obstructed => :save)  
+  workbook2.save_as('dir/workbook.xls', if_exists: :overwrite, if_obstructed: :save)  
 
 === Closing a workbook.
 

data/docs/README_sheet.rdoc

@@ -6,7 +6,7 @@ Worksheets are represented by Worksheet objects.
 
 Assume you have opened a workbook
 
-  workbook = Workbook.open('spec/data/workbook.xls', :visible => true)
+  workbook = Workbook.open('spec/data/workbook.xls', visible: true)
 
 === Accessing a worksheet.
 
@@ -53,11 +53,11 @@ You can add (append) an empty worksheet using
 
 Additionally you can name it.
 
-  workbook.add_empty_sheet(:as => 'sheet_name')
+  workbook.add_empty_sheet(as: 'sheet_name')
 
 You can specify the position of the added empty worksheet.
 
-  workbook.add_empty_sheet(:as => 'new_name', :before => another_sheet)
+  workbook.add_empty_sheet(as: 'new_name', before: another_sheet)
 
 You can copy a worksheet and add it.
 
@@ -65,31 +65,36 @@ You can copy a worksheet and add it.
 
 Additionally you can specify a name and a position.
 
-  workbook.copy_sheet(sheet, :as => 'new_name', :after => another_sheet)
+  workbook.copy_sheet(sheet, as: 'new_name', after: another_sheet)
 
 If you want to copy a worksheet, if a worksheet +sheet+ is given, and add an empty worksheet, if no worksheet is given, then use
 
   workbook.add_or_copy_sheet
 
-  workbook.add_or_copy_sheet(sheet, :as => 'new_name', :after => another_sheet)  
+  workbook.add_or_copy_sheet(sheet, as: 'new_name', after: another_sheet)  
 
 Note, that running in jruby, due to some restrictions of jruby, there is a workaround when adding or copy a worksheet at the end (appending): the last worksheet is being copied and deleted afterwards, in order to serve as a dummy worksheet. This may cause a different behaviour.
 
 === Accessing rows and columns
 
-The methods Worksheet#each, Worksheet#each_row and Worksheet#each_column enable to access each cell, row and column, respectively.
+The methods Worksheet#each returns an enumerator traversing the rows (more specific: the row values) in the used range of the worksheet.  The methods +each_row+ and +each_column traverse the values in the rows and columns, respectively, using an optional offset.
+The methods +each_cell+ enables to access the values of each cell.
 
-  worksheet.each do |cell|
-    # do something with cell
-    # read every row, every column
+  worksheet.each do |row_values|
+    # do something with the row_values
+  end
+
+  worksheet.each_row(2) do |row|
+    # do something with row beginning with 2nd row
   end
 
-  worksheet.each_row do |row|
-    # do something with row
+  worksheet.each_column(3) do |column|
+    # do something with column beginning with 3rd column
   end
 
-  worksheet.each_column do |column|
-    # do something with column
+  worksheet.each_cell do |cell|
+    # do something with cell
+    # read every row, every column
   end
 
 The method Worksheet#values yields a 2-dimensional array that contains the values in each row, e.g.

data/examples/example_ruby_library.rb

@@ -14,8 +14,8 @@ workbook.each do |worksheet|
   puts "Reading: #{worksheet.name}"
   num_rows = 0
 
-  worksheet.each do |row|
-    row_cells = row.map{ |cell| cell.value }
+  worksheet.each do |row_values|
+    a = row_values.map{ |cell| cell }
     num_rows += 1
 
     # uncomment to print out row values

data/examples/introductory_examples/example_range.rb

@@ -67,12 +67,12 @@ value = book["name"]
 puts 'value of range "name": #{value}'
 # renaming a range
 puts 'renaming range from "name" to "new_name"'
-book.rename_range("name", "new_name")
+book.rename_name("name", "new_name")
 # deleting the name of a range
 puts 'deleting name "new_name"'
 book.delete_name("new_name")
 # reading the value of a cell
-cell_value = sheet[1,1].Value
+cell_value = sheet[1,1]
 puts "value of 1st cell: #{cell_value}"
 # writing the value of a cell
 puts 'writing the value "bar" into 1st cell'

data/examples/modifying_sheets/example_access_sheets_and_cells.rb

@@ -15,22 +15,22 @@ begin
   File.delete simple_save_file rescue nil
   book = Workbook.open(simple_file, :visible => true)      # open a book
   sheet = book.sheet(1)                    # access a sheet via integer 
-  cell = sheet[1,1]                  # access the first cell
+  cell = sheet.range([1,1])                  # access the first cell
   puts "1st cell: #{cell.Value}"     # put the value of the first cell
   sheet[1,1] = "complex"             # write a value into a cell
-  puts "new cell: #{sheet[1,1].Value}"
+  puts "new cell: #{sheet[1,1]}"
   puts "all cells:"
-  sheet.each do |cell|               # access all cells
+  sheet.each_cell do |cell|               # access all cells
     puts "#{cell.Value}"             #   for each row: for every column: put the value of the cells
   end
   
   sheet_enum = proc do |enum_method|     # put each cell, each row or each column 
     i = 0
     sheet.send(enum_method) do |item|
-      i = i + 1
+      i += 1
       item_name = 
         case enum_method
-        when :each        then "cell"
+        when :each_cell   then "cell"
         when :each_row    then "row"
         when :each_column then "column"
         end 
@@ -38,7 +38,7 @@ begin
     end
   end
 
-  sheet_enum[:each]        # put cells
+  sheet_enum[:each_cell]   # put cells
   sheet_enum[:each_row]    # put rows
   sheet_enum[:each_column] # put columns
 

data/examples/modifying_sheets/example_add_names.rb

@@ -38,7 +38,7 @@ begin
       colnr = idx+1
       puts "colnr: #{colnr}"
       sheet[1,colnr] = nam
-      puts "sheet[1,colnr]: #{sheet[1,colnr].Value}"
+      puts "sheet[1,colnr]: #{sheet[1,colnr]}"
       sheet.add_name(nam,[nil,colnr])
       puts "sheet.Range().Address: #{sheet.Range(nam).Address}"
     end

data/examples/modifying_sheets/example_concating.rb

@@ -20,7 +20,7 @@ begin
 
   Workbook.unobtrusively(extended_file_name) do |book|
     book.each do |sheet|
-      sheet.each do |cell|
+      sheet.each_cell do |cell|
         name = cell.Name.Name rescue nil
         if name
           cell.Value = cell.Value.to_s + cell.Offset(0,1).Value.to_s

data/examples/modifying_sheets/example_copying.rb

@@ -26,13 +26,13 @@ begin
     book.each do |sheet|
       new_sheet = book.add_sheet 
       contains_named_cells = false
-      sheet.each do |cell|
+      sheet.each_cell do |cell|
         full_name = cell.Name.Name rescue nil
         if full_name
           sheet_name, short_name = full_name.split("!") 
           cell_name = short_name ? short_name : sheet_name
           contains_named_cells = true
-          new_sheet[cell.Row, cell.Column].Value = cell.Value
+          new_sheet[cell.Row, cell.Column] = cell.Value
           new_sheet.add_name(cell_name, [cell.Row,cell.Column])
         end
       end

data/examples/modifying_sheets/example_listobjects.rb

@@ -0,0 +1,86 @@
+# example_ranges.rb: 
+# access row and column ranges of a sheet. 
+
+require_relative '../../lib/robust_excel_ole'
+require_relative '../../spec/helpers/create_temporary_dir'
+require "fileutils"
+
+include RobustExcelOle
+
+using StringRefinement
+
+Excel.close_all
+begin
+  dir = create_tmpdir
+  table_file = dir + 'workbook_listobjects.xlsx'
+  book = Workbook.open(table_file, :visible => true)      # open a workbook
+  sheet = book.sheet(3)              # access a worksheet via the name
+  table = sheet.table(1)             # access a list object (table)
+
+  puts "table: #{table}"
+
+  listrow1 = table[2]                # access the second list row of the table
+
+  puts "listrow1: #{listrow1}"
+
+  values1 = listrow1.values             # access the values of this listrow
+  puts "values: #{values1}"
+
+  listrow2 = table[{"Number" => 3, "Person" => "Angel"}]  # acess a list row via a given key hash
+
+  puts "listrow2: #{listrow2}"
+
+  values2 = listrow2.values
+  puts "values: #{values2}"
+
+  listrows3 = table[{"Number" => 3}, limit: 2]  # access maximal 2 listrows matching the key
+
+  puts "listrows3: #{listrows3}"
+  puts "values:"
+  listrows3.map{|l| puts l.values}
+
+  puts "deleting the values of the second row"   # deleting the contents of the second row
+  table.delete_row_values(2)
+
+  puts "deleting empty rows"   
+  table.delete_empty_rows              # deleting empty rows
+
+  puts "sorting table:"
+  table.sort("Number")                 # sort table
+
+  puts "find all cells:"               # find all cells containing a given value
+  cells = table.find_cells(40)
+  puts "cells: #{cells}"
+
+  # create a new table
+  table2 = Table.new(sheet, "table_name", [20,1], 3, ["Verkäufer", "Straße", "area in m²"])
+  puts "table2: #{table2}"
+
+  table_row1 = table[1]         
+  puts "list_row1 of second table: #{table_row1}"
+  
+  table_row1.verkaeufer = "John"
+  value3 = table_row1.verkaeufer
+  puts "value of verkaeufer: #{value3}"
+
+  value4 = table_row1.Verkaeufer
+  puts "value of verkaeufer: #{value4}"
+
+  table_row1.strasse = 42
+  value5 = table_row1.strasse
+  puts "value of strasse: #{value5}"
+
+  table_row1.area_in_m2 = 400
+  value6 = table_row1.area_in_m2
+  puts "value of area in m2: #{value6}"
+
+  sleep 5
+ 
+  book.close(:if_unsaved => :forget)
+  
+ensure
+  Excel.close_all
+  rm_tmp(dir)
+end
+
+  

data/examples/modifying_sheets/example_naming.rb

@@ -27,7 +27,7 @@ begin
 
   Workbook.unobtrusively(extended_file_name) do |book|     
     book.each do |sheet|
-      sheet.each do |cell_orig|
+      sheet.each_cell do |cell_orig|
         contents = cell_orig.Value
         sheet.add_name(contents, [cell_orig.Row, cell_orig.Column]) if contents && contents.is_a?(String)
       end

data/examples/modifying_sheets/example_ranges.rb

@@ -24,7 +24,7 @@ begin
   
   i = 0
   row_r.values.each do |value|          # access the values of the first row 
-    i = i + 1
+    i += 1
     puts "cell #{i} of the range of the 1st row: #{value}"
   end
  

data/examples/open_save_close/example_control_to_excel.rb

@@ -14,7 +14,7 @@ begin
   book = Workbook.open(file_name, :visible => true)          # open a book
   sleep 1
   sheet = book.sheet(1)                                                        # access a worksheet
-  sheet[1,1] = sheet[1,1].Value == "simple" ? "complex" : "simple"       # change a cell
+  sheet[1,1] = sheet[1,1] == "simple" ? "complex" : "simple"       # change a cell
   sleep 1
   begin
     new_book = Workbook.open(file_name, :visible => true, :if_unsaved => :alert) # open another workbook with the same file name 

data/examples/open_save_close/example_if_obstructed_closeifsaved.rb

@@ -15,7 +15,7 @@ begin
   book = Workbook.open(file_name, :visible => true)  # open a workbook, make Excel visible
   sleep 1
   sheet = book.sheet(1)
-  first_cell = sheet[1,1].Value                                   # access a worksheet
+  first_cell = sheet[1,1]                                   # access a worksheet
   sheet[1,1] = first_cell == "simple" ? "complex" : "simple"      # change a cell
   sleep 1
   begin

data/examples/open_save_close/example_if_obstructed_save.rb

@@ -15,7 +15,7 @@ begin
   book = Workbook.open(file_name, :visible => true)  # open a workbook, make Excel visible
   sleep 1
   sheet = book.sheet(1)
-  first_cell = sheet[1,1].Value                                   # access a worksheet
+  first_cell = sheet[1,1]                                        # access a worksheet
   sheet[1,1] = first_cell == "simple" ? "complex" : "simple"      # change a cell
   sleep 1
   new_book = Workbook.open(other_file_name, :if_obstructed => :save)  # open a workbook with the same file name in a different path
@@ -23,11 +23,11 @@ begin
   old_book = Workbook.open(file_name, :if_obstructed => :forget ,:visible => true) # open the old book    
   sleep 1
   old_sheet = old_book.sheet(1)
-  old_first_cell = old_sheet[1,1].Value
+  old_first_cell = old_sheet[1,1]
   puts "the old book was saved" unless old_first_cell == first_cell 
   new_book.close                                 # close the workbooks                      
   old_book.close
 ensure
   Excel.kill_all                         # close all workbooks, quit Excel application
-  rm_tmp(dir)
+  #rm_tmp(dir)
 end

data/examples/open_save_close/example_if_unsaved_accept.rb

@@ -13,7 +13,7 @@ begin
   file_name = dir + 'workbook.xls' 
   book = Workbook.open(file_name, :visible => true)                      # open a workbook 
   sheet = book.sheet(1)                                                  # access a worksheet
-  sheet[1,1] = sheet[1,1].Value == "simple" ? "complex" : "simple" # change a cell
+  sheet[1,1] = sheet[1,1] == "simple" ? "complex" : "simple" # change a cell
   begin
     new_book = Workbook.open(file_name)             # open another workbook with the same file name
   rescue WorkbookNotSaved => msg                    # by default: raises an exception:

data/examples/open_save_close/example_if_unsaved_forget.rb

@@ -15,7 +15,7 @@ begin
   puts "file_name: #{file_name}"
   sleep 1
   sheet = book.sheet(1)                                      # access a worksheet
-  first_cell = sheet[1,1].Value
+  first_cell = sheet[1,1]
   sheet[1,1] = first_cell == "simple" ? "complex" : "simple" # change a cell
   sleep 1
   puts "new_book: before"
@@ -24,11 +24,11 @@ begin
                                                           # and close the unsaved workbook without saving it
   puts "new_book: after"
   sheet_new_book = new_book.sheet(1)
-  if (not book.alive?) && new_book.alive? && sheet_new_book[1,1].Value == first_cell then # check whether the unsaved workbook 
+  if (not book.alive?) && new_book.alive? && sheet_new_book[1,1] == first_cell then # check whether the unsaved workbook 
     puts "open with :if_unsaved => :forget : the unsaved book is closed and not saved."     # is closed and was not saved
   end
   sleep 1
-  sheet_new_book[1,1] = sheet_new_book[1,1].Value == "simple" ? "complex" : "simple" # change a cell
+  sheet_new_book[1,1] = sheet_new_book[1,1] == "simple" ? "complex" : "simple" # change a cell
   # open another workbook in a new Excel application, and make Excel visible, leaving the unsaved workbook open
   another_book = Workbook.open(file_name, :if_unsaved => :new_excel, :visible => true)  
   sleep 3                                                                  # leaving the unsaved workbook open  

data/examples/open_save_close/example_if_unsaved_forget_more.rb

@@ -13,21 +13,21 @@ begin
   file_name = dir + 'workbook.xls' 
   book = Workbook.open(file_name, :visible => true)  # open a workbook
   sheet = book.sheet(1)                                            # access a worksheet
-  first_cell = sheet[1,1].Value
+  first_cell = sheet[1,1]
   sheet[1,1] = first_cell == "simple" ? "complex" : "simple" # change a cell
   sleep 1
   new_book = Workbook.open(file_name, :if_unsaved => :new_excel, :visible => true) # open another workbook with the same file name in a new Excel
   sheet_new_book = new_book.sheet(1)
-  if (not book.alive?) && new_book.alive? && sheet_new_book[1,1].Value == first_cell then # check whether the unsaved workbook 
+  if (not book.alive?) && new_book.alive? && sheet_new_book[1,1] == first_cell then # check whether the unsaved workbook 
     puts "open with :if_unsaved => :forget : the unsaved book is closed and not saved."     # is closed and was not saved
   end
   sleep 1
-  sheet_new_book[1,1] = sheet_new_book[1,1].Value == "simple" ? "complex" : "simple" # change a cell
+  sheet_new_book[1,1] = sheet_new_book[1,1] == "simple" ? "complex" : "simple" # change a cell
   # open another workbook in the running Excel application, and make Excel visible, closing the unsaved workbook
   another_book = Workbook.open(file_name, :if_unsaved => :forget, :visible => true)  
   sleep 1
   sheet_another_book = another_book.sheet(1)
-  sheet_another_book[1,1] = sheet_another_book[1,1].Value == "simple" ? "complex" : "simple" # change a cell                                                                   
+  sheet_another_book[1,1] = sheet_another_book[1,1] == "simple" ? "complex" : "simple" # change a cell                                                                   
   another_book.close(:if_unsaved => :forget )           # close the last workbook without saving it.                      
   book.close(:if_unsaved => :save)                      # close the first workbook and save it before
 ensure

data/examples/open_save_close/example_read_only.rb

@@ -14,7 +14,7 @@ begin
   book = Workbook.open(file_name, :read_only => true, :visible => true) # open a workbook with read_only and make Excel visible
   sheet = book.sheet(1)                                     			        # access a worksheet
   sleep 1     
-  sheet[1,1] = sheet[1,1].Value == "simple" ? "complex" : "simple" # change a cell
+  sheet[1,1] = sheet[1,1] == "simple" ? "complex" : "simple" # change a cell
   sleep 1
   begin
     book.save                                         # simple save. 

data/examples/open_save_close/example_simple.rb

@@ -20,7 +20,7 @@ begin
   book.excel.visible = true                                  # make current Excel visible
   sheet = book.sheet(1)                                      # access a worksheet
   sleep 1     
-  sheet[1,1] = sheet[1,1].Value == "simple" ? "complex" : "simple"  # change a cell
+  sheet[1,1] = sheet[1,1] == "simple" ? "complex" : "simple"  # change a cell
   sleep 1
   book.save                                                  # simple save
   begin

data/examples/open_save_close/example_unobtrusively.rb

@@ -12,14 +12,14 @@ begin
   simple_file = dir + 'workbook.xls'
   book = Workbook.open(simple_file, :visible => true)  # open a workbook, make Excel visible
   old_sheet = book.sheet(1)
-  p "1st cell: #{old_sheet[1,1].Value}"
+  p "1st cell: #{old_sheet[1,1]}"
   sleep 2
   Workbook.unobtrusively(simple_file) do |book|   # modify the book and keep its status unchanged
     sheet = book.sheet(1)
-    sheet[1,1] = sheet[1,1].Value == "simple" ? "complex" : "simple"
+    sheet[1,1] = sheet[1,1] == "simple" ? "complex" : "simple"
   end
   new_sheet = book.sheet(1)
-  p "1st cell: #{new_sheet[1,1].Value}"
+  p "1st cell: #{new_sheet[1,1]}"
   p "book saved" if book.Saved
   book.close                                 # close the workbook                      
 ensure