robust_excel_ole 0.2.3 → 0.3.0

data/README.rdoc

@@ -6,12 +6,14 @@ robust_excel_ole wraps the win32ole library, and allows to perform various opera
 
 robust_excel_ole started as a simple fork from tomiacannondale's wrap_excel adapted to Ruby 1.8.6.
 The functionality of wrap_excel is optimised and extended by new features.
-Most noticable extension is that books are opened in a Excel application if it is already running, instead of opening Excel whenever a book is opened.
+Most notable extensions include:
+* books can be opened in already running Excel instances (instead of opening a new Excel whenever a book is opened)
+* a book management system stores all books that have been open. This book store is being used, e.g., for reopening a book that has been closed before. It provides transperency identity, i.e., equal Excel books correspond to equal Book objects of RobustExcelOle.
 
-Thus some features in robust_excel_ole that are not compatible with wrap_excel:
-* +open+ uses by default a running Excel application instead of creating a new one,
+Some features in robust_excel_ole that are not compatible with wrap_excel:
+* +open+ uses by default a running Excel instance instead of creating a new one,
   and opens a book by default in writable mode instead of read_only 
-* +close+ closes the workbook instead of closing all workbooks and the Excel application.
+* +close+ closes the workbook instead of closing all workbooks and the Excel instance.
 * +save_as+ instead of +save+.
 
 This is work in progress.
@@ -26,37 +28,56 @@ This is work in progress.
 
 == Usage
 
-=== Open a book.
+=== Including robust_excel_ole.
+
+  include RobustExcelOle
+
+=== Opening a book.
 
 Example:
 
-  book = RobustExcelOle::Book.open('simple.xls')
+  book = Book.open('simple.xls')
 
 Open a book with a block. 
 The semantics is similar to, e.g.,  File.open.
 
-  RobustExcelOle::Book.open('./sample.xls') do |book|
+  Book.open('simple.xls') do |book|
     # do something
   end
 
 Options are the following:
 
-+:read_only+::       open in read-only mode (default: +false+)  
-+:if_unsaved+::      +:raise+ (default), +:accept+, +:forget+, +:new_app+, +:alert+
-+:if_obstructed+::   :raise (default), +:forget+, +:save+, +:close_if_unsaved+, +:new_app+
-+:reuse+::           use an already open Excel-application (default: +true+) 
-+:excel+::           an Excel appication (default: +nil+)
++:default_excel+::   open in the Excel instance used before if the book was once open (default: +reuse+)
++:force_excel+::     open in a new or given Excel instance (defaut: +:new+)
++:if_unsaved+::      specify behaviour if the book was unsaved (default: +raise+)
++:if_obstructed+::   specidy behaviour if the book is blocked by another book (default: +raise+)
++:read_only+::       open in read-only mode (default: +false+) 
 +:displayalerts+::   allow display alerts in Excel (default: +false+)
 +:visible+::         make visibe in Excel (default: +false+)
 
+The option +:defaut_excel+  :
+
+If the book was open before, then open it in the Excel instance used before. If the book cannot be reopened, then
+
++:reuse+:: Connect to a running Excel, if it exists, open a new Excel otherwise.
++:new+:: Open in a new Excel.
+[instance]:: Open in a given Excel instance.
+
+The option +:force_excel  :
+
+No matter if the book was open before,
+
++:new+:: Open in a new Excel.
+[instance]:: Open in a given Excel instance.
+
 The option +:if_unsaved+  : 
 
 If an unsaved book with the same name is open, then
 
 +:raise+::   Raise an exeption. Don't open the book.
 +:accept+::  Let the unsaved book open.
-+:forget+::  Close the unsaved book, open the new book.
-+:new_app+:: Open the new book in a new Excel application
++:forget+::  Discard any changes and reopen the book.
++:new_excel+:: Open the new book in a new Excel instance
 +:alert+::   Give control to Excel.
 
 The option +:if_obstructed+ :
@@ -67,21 +88,21 @@ If a book with same name in a different path is open, then
 +:forget+::         Close the old book, open the new book.
 +:save+::           Save the old book, close it, open the new book
 +:close_if_saved+:: Close the old book and open the new book, if the old book is saved, raise an exception otherwise
-+:new_app+::        Open the new book in a new Excel application.
++:new_excel+::        Open the new book in a new Excel instance.
 
-The values :displayalerts and :visible are reached to the class Excel that controls opening and closing of Excel applications.
+The values :displayalerts and :visible are reached to the class Excel that controls opening and closing Excel instances.
 
-=== Close a book.
+=== Closing a book.
 
 Simple close.
 
   book.close
 
-Options are the following:
+The option is : +:if_unsaved+ . It can have one of the following values:
 
 +:if_unsaved+,  +:raise+ (default), +:save+, +:forget+, +:alert+
 
-If the book is unsaved, then
+The option specifies: If the book is unsaved, then
 
 +:raise+::  Raise an exception. Don't close the book.
 +:save+::   Save the book before closing it.
@@ -89,15 +110,15 @@ If the book is unsaved, then
 +:alert+::  Give control to Excel.
 
 
-=== Save a book.
+=== Saving a book.
 
 Simple save.
 
   book.save
 
-Save a book with a file name.
+Saving a book with a file name.
 
-  book.save_as('./another_sample.xls')
+  book.save_as('another_simple.xls')
 
 Options are the following:
 
@@ -108,41 +129,89 @@ The option +:if_exists+ :
 If a book with the file name already exists, then
 
 +:raise+::     Raise an exeption. Don't write the file.
-+:overwrite+:: Delete the existing file and write the file. If the book is open in an Excel application, then raise an exception.
++:overwrite+:: Delete the existing file and write the file. If the book is open in an Excel instance, then raise an exception.
 +:alert+::     Give the control to Excel.
   
 
-=== == 
+=== Unobtrusively modifying a book
+
+When modifying the book unobtrusively, the status of the book remains unchanged. The status includes, wheter the book is opened or closed, saved or unsaved, readonly or writable.
+
+
+  Book.unobtrusively('simple.xls') do |book|
+    # some modification
+    sheet = book[0]
+    sheet[0,0] = "c" 
+  end
+  
+=== Value of a named cell or range
+
+Returning the value of a cell or range that has a with a defined name.
+
+  book.nvalue(name)
+
+=== Identity.
+
+Checking whether two referenced Excel workbooks are identical.
 
-Check whether two referenced Excel workbooks are identical.
+  if book1 == book2 then puts "Both referenced Excel workbooks are identical." 
 
-=== alive?
+=== Alive.
 
-Check whether the referenced Excel workbook responds to methods.
+Checking whether the referenced Excel workbook responds to methods.
 
-=== filename
+  if book.alive? then puts "book is responding."
 
-Return the file name of the book with the absolute path that contains slash (/) instead of back slash (\)
+=== File name. 
 
+Getting the file name of the book with the absolute path that contains slash (/) instead of back slash (\).
 
+  book.filename
+
+=== Make a book visible or invisible in Excel.
+
+Make the book visible.
+
+  book.visible = true
+
+Options: +true+ -> make visible , +false+ -> make invisible
+
+Check whether the book is visible.
+  
+  if book.visible then p "visible"
 
-=== Access a sheet.
+=== Enable and disable DisplayAlerts in Excel.
+
+Enable DisplayAlerts.
+
+  book.displayalerts = true
+
+Options: +true+ -> enable DisplayAlerts , +false+ -> Disable DisplayAlerts
+
+
+Check whether DisplayAlerts is enabled.
+  
+  if book.displayalerts then p "DisplayAlerts enabled"
+
+
+
+=== Accessing a sheet.
 
 A sheet object can be accessed with a Book#[] method via an integer number.
 
   sheet = book[0]
 
-Access a sheet object with the sheet name.
+Accessing a sheet object with the sheet name.
 
   sheet = book['Sheet1']
 
-Access sheet objects using the methods Book#each.
+Accessing sheet objects using the methods Book#each.
 
   book.each do |sheet|               
     # do something with sheet
   end
 
-=== Access a row or a column.
+=== Accessing a row or a column.
 
 A sheet object is enumerable. Use the methods Sheet#each_column, Sheet#each_row or Sheet#each.
 
@@ -159,154 +228,280 @@ A sheet object is enumerable. Use the methods Sheet#each_column, Sheet#each_row
     # do something with column
   end
 
-=== Access a cell.
+=== Accessing a cell.
 
-Read a cell from a sheet object.
+Reading a cell from a sheet object.
 
   sheet[0, 0]  => first cell.
 
-Read a cell from a range object.
+Reading a cell from a range object.
 
   row_range[0]  => first cell in row_range
   column_range[1] => second cell in column_range
 
-Read the value of a cell.
+Reading the value of a cell.
 
   cell = sheet[0,0]
   cell.value  => value of the cell.
 
-Write a cell
+Writing a cell
 
   sheet[0,0] = "new_value"
 
 
-=== Access a range of a row or column. 
+=== Accessing a range of a row or column. 
 
-Access a range of a row.
+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  
 
-Access a range of a column.
+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
 
 
-=== Add a sheet
+=== Adding a sheet.
 
-Add a new sheet.
+Adding a new sheet.
 
   book.add_sheet
 
-Add a new sheet with a name.
+Adding a new sheet with a name.
 
   book.add_sheet(:as => 'new_sheet')
 
-Add a new sheet with a name before another sheet.
+Adding a new sheet with a name before another sheet.
 
   book.add_sheet(:as => 'new_sheet2', :before => another_sheet)
 
-Add a copy of a sheet with a name after another sheet.
+Adding a copy of a sheet with a name after another sheet.
 
   book.add_sheet(sheet, :as => 'sheet_copy', :after => another_sheet)
 
+=== Value of a named cell or range
+
+Returning the value of a cell or range that has a with a defined name.
+
+  sheet.nvalue(name)
+
+=== Creating and reusing an Excel instance.
+
+Creating a new Excel.
+
+  excel1 = Excel.create
+
+Getting a running Excel instance and reusing it.
+
+  excel2 = Excel.current
+
+Reusing a running Excel instance, making it visible and turning on displayalerts.
+
+   excel2 = Excel.new(:reuse => true, :visible => true, displayalerts => true).
+
+Reusing a certain running Excel instance.
+
+   excel3 = Excel.new(:excel => excel1)
+
+=== Making Excel visible or invisible
+
+Making Excel visible.
+
+  excel = Excel.create
+  excel.visible = true
+  puts "visible" if excel.visible
+
+Making Excel invisible
+
+  excel.visible = false
+
+=== Turning on or off Displayalerts.
+
+Turning DisplayAlerts on.
+
+  excel = Excel.create
+  excel.displayalerts = true
+  puts "allows displayalerts" if excel.displayalerts
+
+Turning DisplayAlerts off.
+
+  excel.displayalerts = false
+
+Turning on and off in a block.
+  
+  with_displayalerts
+
+  excel = Excel.create
+  excel.with_displayalerts true do
+    book = Book.open('simple.xls')
+  end
+
+=== Closing all Excel instances.
+
+  Excel.close_all
 
 === Examples
 
-Include robust_excel_ole.
+Including robust_excel_ole.
 
   include RobustExcelOle
 
 === Example 1 
 
-Open a book.
+Opening a book.
 
   book = Book.open('simple.xls')
 
-Access a sheet via its name.
+Accessing a sheet via its name.
 
   sheet = book['Sheet1']
   
-Change the first cell.
+Changing the first cell.
 
   sheet[0,0] = "new"
   
-Save the book.
+Saving the book.
 
   book.save
 
-Save the book with a different name, and overwrite if a file with this name exists.
+Saving the book with a different name, and overwrite if a file with this name exists.
 
   book.save_as('different_simple.xls', :if_exists => :overwrite)
 
-Close the book.
+Closing the book.
 
   book.close  
 
 === Example 2
 
-Open the book in a new Excel application and make it visible.
+Opening a book.
+
+  book = Book.open('simple.xls')
+
+Opening the book in a new Excel instance and make it visible.
+
+  new_book = Book.open('simple.xls', :force_excel => :new, :visible => true)
+
+Opening the book in a given Excel instance.
+
+  another_book = Book.open('simple.xls', :force_excel => book.excel)
+
+Closing the books.
+
+  book.close
+  new_book.close
+  another_book.close
+
+Reopening the book.
+
+  reopened_book = Book.open('simple.xls')
+
+The writable book is being prefered.  
+
+  reopened_book == book
+  => true
 
-  book.open('simple.xls', :reuse => false, :visible => true)
+Opening another book.
+Since the book was not open before, reopening the book fails and the :default_excel option applies.
+According to :default_excel => :new a new Excel is created, and the book is opened there.
 
-Add a copy of the first sheet after the second sheet.
+  different_book = Book.open('different.xls', :default_excel => :new)
+  
+
+=== Example 3
+
+Opening a book.
+
+  book = Book.open('simple.xls')
+
+Adding a copy of the first sheet after the second sheet.
 
   book.add_sheet(book[0], :as => 'Sheet1_copy', :after => book[1])
 
-Open a new book with the same name in a new Excel. Leave the book that contains unsaved changes in the old Excel.
+Close the book.
+
+Opening a new book with the same name in a new Excel. Leave the book that contains unsaved changes in the old Excel.
 
-  new_book.open('simple.xls', :if_unsaved => :new_app)
+  new_book = Book.open('simple.xls', :if_unsaved => :new_excel)
 
-Access a sheet and change a cell.
+Accessing a sheet and change a cell.
 
   sheet = new_book[0]
   sheet[1,1] = "another"
 
-Open another book with the same name in the running Excel. The book that contains unsaved changes will be closed before. 
+Opening another book with the same name in the running Excel. The book that contains unsaved changes will be closed before. 
 
-  third_book.open('simple.xls', :if_unsaved => :forget)
+  third_book = Book.open('simple.xls', :if_unsaved => :forget)
 
-Add a sheet.
+Adding a sheet.
 
   third_book.add_sheet
 
-Close the book without saving it.
+Closing the book without saving it.
 
   third_book.close(:if_unsaved => :forget)
 
-Close the first book and save it before.
+Closing the first book and saving it before.
 
   book.close(:if_unsaved => :save)
 
-=== Example 3
+=== Example 4
 
-Open a book.
+Opening a book.
 
   book1 = Book.open('simple.xls')
 
-Open a book with the same name in a different path. Close the old book.
+Opening a book with the same name in a different path. Close the old book.
 
   book2 = Book.open('more/simple.xls', :if_obstructed => :forget)
 
-Change its cell.
+Changing its cell.
 
   sheet = book2[0]
   sheet[0,0] = "new"
 
-Open a book with the same name in a different path. The old book that was modified will be saved and closed before.
+Opening a book with the same name in a different path. The old book that was modified will be saved and closed before.
 
   book3 = Book.open('simple.xls', :if_obstructed => :save)
 
-Open a book with the same name in a different path. The other book will be closed, because it does not contain unsaved changes.
+Opening a book with the same name in a different path. The other book will be closed, because it does not contain unsaved changes.
 
   book4 = Book.open('more/simple.xls', :if_obstructed => :close_if_unsaved)
 
-Close the book.
+Closing the book.
 
   book4.close
 
 
+=== Example 5
+
+Opening a book.
+
+  book = Book.open('simple.xls')
+
+Printing its first cell.
+
+  sheet = book[0]
+  p "1st cell: #{sheet[0,0].value}"
+
+Unobtrusively modify the book.
+
+  Book.unobtrusively('simple.xls') do |book|
+    sheet = book[0]
+    sheet[0,0] = '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) 
+  => true
+
+  book.Saved 
+  => true
+
+
 === Want to do more things
 
 All RobustExcelOle objects include the win32ole instance.