robust_excel_ole 0.3.4 → 0.3.5

data/README.rdoc

@@ -71,13 +71,13 @@ Closing the workbook and saving it before if it has unsaved changes.
 
   book.close(:if_unsaved => :save)
 
-=== Reopening workbooks.
+=== Reopening a workbook.
 
-A special feature of robust_excel_ole is that it allows tog reopen books after closing them.
+A special feature of robust_excel_ole is that it allows to reopen books after closing them.
 
   book = Book.open('workbook.xls')
   book.close
-  reopened_book = Book.open('workbook.xls')
+  book.reopen
 
 The closed book is now alive again, i.e. is open and responds to Excel methods.
 
@@ -85,8 +85,6 @@ This feature is achieved by providing identity transperence and by storing the f
 Identity transperence means that the same Book objects refer to the same Excel files, and vice versa.
 In other words, a Book objects is a proxy of an Excel file.
 
-  reopened_book === book
-  => true
 
 === Saving a workbook.
 
@@ -107,21 +105,23 @@ Saving a workbook and overwriting the file if it exists before.
 
 The method +unobtrusively+ enables the user to read or modify a workbook, no matter if it is open in some Excel instance, if it is saved or unsaved, and if it is writable or not. When opening a workbook unobtrusively, its status remains unchanged. This status includes, whether the book is opened or closed, saved or unsaved, readonly or writable. 
 
-Options are +:if_closed+, +:read_only+, +:use_readonly_excel+, and +:keep_open.
+One option chooses the Excel instance in which a closed book is opened. The options +:reuse (default) indicates that the closed book is opened in the Excel instance of the book, if it exists, or that another Excel instance is reused. The option +:hidden+ provokes that the closed book is opened in a separate Excel instance that is not visible and has no DisplayAlerts. Any following closed book would be opened in this Excel instance as well when using this option. Moreover, an Excel instance can be given directly where to open the closed book.
 
-The option +:if_closed+ => +:hidden+ provokes that a closed book is opened unobtrusively in a separate Excel instance that is not visible and has no DisplayAlerts. Any following closed book would be opened in this Excel instance as well when using this option.
+Further options are +:read_only+, +:readonly_excel+, and +:keep_open. The option +:readonly_excel+ chooses whether a book that is opened as ReadOnly and that shall be modified shall be opned as writable in the Excel instance where it was open so far, or if it shall be opened as writable in another running Excel instance, if such an Excel exists, or opened in a new Excel instance.
 
-  Book.unobtrusively('workbook.xls', :if_closed => :hidden) do |book|
+  Book.unobtrusively('workbook.xls', :reuse, :read_only => false, :keep_open => false) do |book|
     # some modification
     sheet = book[0]
-    sheet[0,0] = "c" 
+    sheet[1,1] = "c" 
   end
   
-=== Value of a named cell or range
+The methods +for_reading+ and +for_modifying+ indicate unobtrusively reading or modifying.
 
-Returning the value of a cell or range that has a with a defined name.
-
-  book.nvalue(name)
+  Book.for_modifying('workbook.xls') do |book|
+    # some modification
+    sheet = book[0]
+    sheet[1,1] = "c" 
+  end
 
 === Checking whether the workbook is alive.
 
@@ -129,6 +129,26 @@ This method finds out whether the Excel workbook that is referenced by the Book
 
   if book.alive? then sheet = book[0] end
 
+=== Setting and getting the contents of a range.
+
+Setting:
+
+  book["name"] = "value"
+
+or
+
+  book.set_nvalue("name") = "value"
+
+Getting:
+
+  book["name"] 
+  => "value"
+
+or
+
+  book.nvalue("name")
+  => "value"
+
 === Making an Excel visible or invisible, and enable and disable DisplayAlerts.
 
 Make an Excel visible
@@ -177,7 +197,7 @@ A sheet object is enumerable. Use the methods Sheet#each_column, Sheet#each_row
 
 Reading a cell from a sheet object.
 
-  sheet[0, 0]  => first cell.
+  sheet[1, 1]  => first cell (first row, first column).
 
 Reading a cell from a range object.
 
@@ -188,26 +208,48 @@ Methods to a cell are just delegated. Example:
 
 Reading the value of a cell.
 
-  cell = sheet[0,0]
+  cell = sheet[1,1]
   cell.Value  => value of the cell.
 
 Writing a cell
 
-  sheet[0,0] = "new_value"
-
+  sheet[1,1] = "new_value"
 
 === Accessing a range of a row or column. 
 
 Accessing a range of a row.
 
-  sheet.row_range(0)  => first row
-  sheet.row_range(0, 0..2 )  => first three cells of the first row  
+  sheet.row_range(1)  => first row
+  sheet.row_range(1, 1..3 )  => first three cells of the first row  
 
 Accessing a range of a column.
 
-  sheet.col_range(2)  => third column
-  sheet.col_range(2, 0..1)  => first two cells of the third column
+  sheet.col_range(3)  => third column
+  sheet.col_range(3, 1..2)  => first two cells of the third column
+
+=== Naming a cell
+
+Naming or renaming a cell range given its address.
+
+  book.add_name(1,1,"name")
+
+=== Reading and modifying a Value of a named range
+
+Returning the value of a range, e.g. a cell, that has a with a defined name.
+
+  book.nvalue(name)
 
+or 
+
+  book[name]
+
+Setting the value of a range, e.g. a cell, that has a with a defined name.
+
+  book.set_nvalue(name,value)
+
+or 
+
+  book[name] = value
 
 === Adding a sheet.
 
@@ -282,6 +324,11 @@ Turning on and off in a block.
     book = Book.open('workbook.xls')
   end
 
+=== Closing an Excel
+
+  excel = Excel.current
+  excel.close
+
 === Closing all Excel instances.
 
   Excel.close_all
@@ -398,7 +445,7 @@ Opening a book with the same name in a different path. Close the old book.
 Changing its cell.
 
   sheet = book2[0]
-  sheet[0,0] = "new"
+  sheet[1,1] = "new"
 
 Opening a book with the same name in a different path. The old book that was modified will be saved and closed before.
 
@@ -422,22 +469,22 @@ Opening a book.
 Printing its first cell.
 
   sheet = book[0]
-  p "1st cell: #{sheet[0,0].value}"
+  p "1st cell: #{sheet[1,1].Value}"
 
 Unobtrusively modify the book.
 
   Book.unobtrusively('workbook.xls') do |book|
     sheet = book[0]
-    sheet[0,0] = 'simple'
+    sheet[1,1] = 'simple'
   end
 
 The book is modified, but its status is unchanged.
 
   new_sheet = book[0]
-  not (new_sheet[0,0].value == sheet[0,0].value) 
+  not (new_sheet[1,1].Value == sheet[1,1].Value) 
   => true
 
-  book.Saved 
+  book.saved 
   => true
 
 

data/README_detail.rdoc

@@ -110,6 +110,20 @@ The option specifies: If the workbook is unsaved, then
 +:forget+:: Close the workbook. 
 +:alert+::  Give control to Excel.
 
+=== Reopening a workbook.
+
+A special feature of robust_excel_ole is that it allows to reopen books after closing them.
+
+  book = Book.open('workbook.xls')
+  book.close
+  book.reopen
+
+The closed book is now alive again, i.e. is open and responds to Excel methods.
+
+This feature is achieved by providing identity transperence and by storing the file name.
+Identity transperence means that the same Book objects refer to the same Excel files, and vice versa.
+In other words, a Book objects is a proxy of an Excel file.
+
 
 === Saving a workbook.
 
@@ -138,37 +152,59 @@ If a book with the file name already exists, then
 
 The method +unobtrusively+ enables the user to read or modify a workbook, no matter if it is open in some Excel instance, if it is saved or unsaved, and if it is writable or not. When opening a workbook unobtrusively, its status remains unchanged. This status includes, whether the book is opened or closed, saved or unsaved, readonly or writable. 
 
-Options are +:if_closed+, +:read_only+, +:use_readonly_excel+, and +:keep_open.
-
-The option +:if_closed+ => +:hidden+ provokes that a closed book is opened unobtrusively in a separate Excel instance that is not visible and has no DisplayAlerts. Any following closed book would be opened in this Excel instance as well when using this option.
+One option chooses the Excel instance in which a closed book is opened. The options +:reuse (default) indicates that the closed book is opened in the Excel instance of the book, if it exists, or that another Excel instance is reused. The option +:hidden+ provokes that the closed book is opened in a separate Excel instance that is not visible and has no DisplayAlerts. Any following closed book would be opened in this Excel instance as well when using this option. Moreover, an Excel instance can be given directly where to open the closed book.
 
 Options are the following:
 
-+:if_closed+::  :hidden (default) : open a closed workbooks in one separate Excel instance that is not visible and has no displayaslerts
-                <excel-instance>  : open a closed workbooks in the given Excel instance
-                :reuse            : open a closed workbooks in the Excel instance of the book, if it exists, otherwise reuse another Excel
+:reuse (default) : open a closed book in the Excel instance of the book, if it exists, otherwise reuse another Excel
+:hidden          : open a closed book in one separate Excel instance that is not visible and has no displayaslerts
+<excel-instance> : open a closed workbooks in the given Excel instance
+               
 +:read_only+:: Open the book unobtrusively for reading only  (default: false)
-+:use_readonly_excel+::  if the book is opened only as ReadOnly and shall be modified, then
-                  true:  close it and open it as writable in the excel instance where it was open so far
-                  false (default)    open it as writable in another running excel instance, if it exists, 
++:readonly_excel+::  if the book is opened only as ReadOnly and shall be modified, then
+                     true:  close it and open it as writable in the excel instance where it was open so far
+                     false (default) open it as writable in another running excel instance, if it exists, 
                                      otherwise open in a new excel instance
 +:keep_open+:: let the book open after unobtrusively opening (default: false)
 
   Book.unobtrusively('workbook.xls') do |book|
     # some modification
     sheet = book[0]
-    sheet[0,0] = "c" 
+    sheet[1,1] = "c" 
   end
   
-=== Value of a named cell or range
+The methods +for_reading+ and +for_modifying+ indicate unobtrusively reading or modifying.
 
-Returning the value of a cell or range that has a with a defined name.
+  Book.for_modifying('workbook.xls') do |book|
+    # some modification
+    sheet = book[0]
+    sheet[1,1] = "c" 
+  end
 
-  book.nvalue(name)
 
 === Checking whether the referenced Excel workbook responds to methods.
 
-  if book.alive? then sheet = book[0] end
+  book.alive?
+
+=== Setting and getting the contents of a range.
+
+Setting:
+
+  book["name"] = "value"
+
+or
+
+  book.set_nvalue("name") = "value"
+
+Getting:
+
+  book["name"] 
+  => "value"
+
+or
+
+  book.nvalue("name")
+  => "value"
 
 === Making an Excel visible or invisible, and enable and disable DisplayAlerts.
 
@@ -220,7 +256,7 @@ A sheet object is enumerable. Use the methods Sheet#each_column, Sheet#each_row
 
 Reading a cell from a sheet object.
 
-  sheet[0, 0]  => first cell.
+  sheet[1, 1]  => first cell.
 
 Reading a cell from a range object.
 
@@ -231,26 +267,49 @@ Methods to cell are just delegated as VBA methods. Example:
 
 Reading the value of a cell.
 
-  cell = sheet[0,0]
+  cell = sheet[1,1]
   cell.Value  => value of the cell.
 
 Writing a cell
 
-  sheet[0,0] = "new_value"
+  sheet[1,1] = "new_value"
 
 
 === Accessing a range of a row or column. 
 
 Accessing a range of a row.
 
-  sheet.row_range(0)  => first row
-  sheet.row_range(0, 0..2 )  => first three cells of the first row  
+  sheet.row_range(1)  => first row
+  sheet.row_range(1, 1..3 )  => first three cells of the first row  
 
 Accessing a range of a column.
 
-  sheet.col_range(2)  => third column
-  sheet.col_range(2, 0..1)  => first two cells of the third column
+  sheet.col_range(3)  => third column
+  sheet.col_range(3, 1..2)  => first two cells of the third column
+
+=== Naming a cell
 
+Naming or renaming a cell range given its address.
+
+  book.add_name(1,1,"name")
+
+=== Reading and modifying a Value of a named range
+
+Returning the value of a range, e.g. a cell, that has a with a defined name.
+
+  book.nvalue(name)
+
+or 
+
+  book[name]
+
+Setting the value of a range, e.g. a cell, that has a with a defined name.
+
+  book.set_nvalue(name,value)
+
+or 
+
+  book[name] = value
 
 === Adding a sheet.
 
@@ -331,6 +390,12 @@ Turning on and off in a block.
 
   Excel.close_all
 
+=== Closing an Excel
+
+  excel = Excel.current
+  excel.close
+
+
 === Examples
 
 Including robust_excel_ole.
@@ -349,7 +414,7 @@ Accessing a sheet via its name.
   
 Changing the first cell.
 
-  sheet[0,0] = "new"
+  sheet[1,1] = "new"
   
 Saving the book.
 
@@ -449,7 +514,7 @@ Opening a book with the same name in a different path. Close the old book.
 Changing its cell.
 
   sheet = book2[0]
-  sheet[0,0] = "new"
+  sheet[1,1] = "new"
 
 Opening a book with the same name in a different path. The old book that was modified will be saved and closed before.
 
@@ -473,22 +538,22 @@ Opening a book.
 Printing its first cell.
 
   sheet = book[0]
-  p "1st cell: #{sheet[0,0].value}"
+  p "1st cell: #{sheet[1,1].Value}"
 
 Unobtrusively modify the book.
 
   Book.unobtrusively('workbook.xls') do |book|
     sheet = book[0]
-    sheet[0,0] = 'simple'
+    sheet[1,1] = 'simple'
   end
 
 The book is modified, but its status is unchanged.
 
   new_sheet = book[0]
-  not (new_sheet[0,0].value == sheet[0,0].value) 
+  not (new_sheet[1,1].Value == sheet[1,1].Value) 
   => true
 
-  book.Saved 
+  book.saved 
   => true
 
 

data/examples/edit_sheets/example_access_sheets_and_cells.rb

@@ -15,10 +15,10 @@ begin
   File.delete simple_save_file rescue nil
   book = Book.open(simple_file)      # open a book
   sheet = book[0]                    # access a sheet via integer 
-  cell = sheet[0,0]                  # access the first cell
+  cell = sheet[1,1]                  # access the first cell
   puts "1st cell: #{cell.Value}"     # put the value of the first cell
-  sheet[0,0] = "complex"             # write a value into a cell
-  puts "new cell: #{sheet[0,0].Value}"
+  sheet[1,1] = "complex"             # write a value into a cell
+  puts "new cell: #{sheet[1,1].Value}"
   puts "all cells:"
   sheet.each do |cell|               # access all cells
     puts "#{cell.Value}"             #   for each row: for every column: put the value of the cells

data/examples/edit_sheets/example_concating.rb

@@ -1,31 +1,31 @@
-# example_concatening.rb: 
+# example_concating.rb: 
 # each named cell gets the value of cell right to it appended to its own value
 # the new workbook's name is extended by the suffix "_concat"
 
 require 'rubygems'
-require 'robust_excel_ole'
+#require 'robust_excel_ole'
+require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
 require "fileutils"
 
 include RobustExcelOle
 
 begin
-  Excel.close_all
   dir = "C:/data"
   workbook_name = 'workbook_named.xls'
-  base_name = workbook_name[0,workbook_name.rindex('.')]
-  suffix = workbook_name[workbook_name.rindex('.')+1,workbook_name.length]
+  ws = workbook_name.split(".")
+  base_name = ws[0,ws.length-1].join(".")
+  suffix = ws.last  
   file_name = dir + "/" + workbook_name
   extended_file_name = dir + "/" + base_name + "_concat" + "." + suffix
-  book_orig = Book.open(file_name)
-  book_orig.save_as(extended_file_name, :if_exists => :overwrite) 
-  book_orig.close
+  FileUtils.copy file_name, extended_file_name 
+
   Book.unobtrusively(extended_file_name) do |book|
     book.each do |sheet|
-      sheet.each do |cell_orig|
-        name = cell_orig.Name.Name rescue nil
+      sheet.each do |cell|
+        name = cell.Name.Name rescue nil
         if name
-          sheet[cell_orig.Row-1, cell_orig.Column-1].Value = cell_orig.Value.to_s + cell_orig.Offset(0,1).Value.to_s
-          sheet.Names.Add("Name" => name, "RefersTo" => "=" + cell_orig.Address) 
+          cell.Value = cell.Value.to_s + cell.Offset(0,1).Value.to_s
+          sheet.set_name(name, cell.Row, cell.Column)
         end
       end
     end