robust_excel_ole 0.3.0 → 0.3.1

data/README.rdoc

@@ -1,20 +1,8 @@
 = RobustExcelOle
 
-robust_excel_ole wraps the win32ole library, and allows to perform various operations in Excel with ruby.
-
-== Description
-
-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 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.
-
-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 instance.
-* +save_as+ instead of +save+.
+robust_excel_ole processes Excel files, allows to perform all win32ole operations, 
+provides convenient methods for opening, saving, closing, and modifying Excel files,
+and implements an Excel file management system.
 
 This is work in progress.
 
@@ -28,115 +16,84 @@ This is work in progress.
 
 == Usage
 
-=== Including robust_excel_ole.
+=== Opening a book.
 
   include RobustExcelOle
 
-=== Opening a book.
-
 Example:
 
   book = Book.open('simple.xls')
 
-Open a book with a block. 
+Opening a book with a block. 
 The semantics is similar to, e.g.,  File.open.
 
   Book.open('simple.xls') do |book|
     # do something
   end
 
-Options are the following:
+Options are +default_excel+, +force_excel+, +if_unsaved+, +if_obstructed+, +read_only+, +visible+, +displayalerts+. 
 
-+: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+)
+Here are a few examples:
 
-The option +:defaut_excel+  :
+Opening another book in a new Excel instance and make it visible.
 
-If the book was open before, then open it in the Excel instance used before. If the book cannot be reopened, then
+  second_book = Book.open('simple.xls', :force_excel => :new, :visible => true)
 
-+: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.
+Opening a book with the same name in a different path. 
+The option +:if_unsaved => :forget+ causes the old book to close such that it does not block the new book anymore.
 
-The option +:force_excel  :
+  third_book = Book.open('more/simple.xls', :if_obstructed => :forget)
 
-No matter if the book was open before,
+Opening another book with the same file name in the running Excel. With the option +:if_unsaved => :accept+  the book remains open if it contains unsaved changes.
 
-+:new+:: Open in a new Excel.
-[instance]:: Open in a given Excel instance.
+  forth_book = Book.open('simple.xls', :if_unsaved => :accept)
 
-The option +:if_unsaved+  : 
 
-If an unsaved book with the same name is open, then
+=== Closing a book.
 
-+:raise+::   Raise an exeption. Don't open the book.
-+:accept+::  Let the unsaved book open.
-+:forget+::  Discard any changes and reopen the book.
-+:new_excel+:: Open the new book in a new Excel instance
-+:alert+::   Give control to Excel.
+  book.close
 
-The option +:if_obstructed+ :
+The option is : +:if_unsaved+. Example:
 
-If a book with same name in a different path is open, then
+Closing the book and saving it before if it has unsaved changes.
 
-+:raise+::          Raise an exception. Don't open the book.
-+: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_excel+::        Open the new book in a new Excel instance.
+  book.close(:if_unsaved => :save)
 
-The values :displayalerts and :visible are reached to the class Excel that controls opening and closing Excel instances.
 
-=== Closing a book.
+=== Reopening books.
 
-Simple close.
+The books can be reopened after closing them. Example:
 
+  book = Book.open('simple.xls')
   book.close
+  reopened_book = Book.open('simple.xls')
 
-The option is : +:if_unsaved+ . It can have one of the following values:
-
-+:if_unsaved+,  +:raise+ (default), +:save+, +:forget+, +:alert+
-
-The option specifies: If the book is unsaved, then
+robust_excel_ole provides transperency identity. That is the same Book objects refer to the same Excel files, and vice versa.
 
-+:raise+::  Raise an exception. Don't close the book.
-+:save+::   Save the book before closing it.
-+:forget+:: Close the book. 
-+:alert+::  Give control to Excel.
+  reopened_book == book
+  => true
 
 
 === Saving a book.
 
-Simple save.
-
   book.save
 
 Saving a book with a file name.
 
   book.save_as('another_simple.xls')
 
-Options are the following:
+The option is +:if_exists+. Example:
 
-+:if_exists+:: +:raise+ (default), +:overwrite+, +:alert+
+Saving a book and overwriting the file if it exists before.
 
-The option +:if_exists+ :
+  book.save_as('another_simple.xls', :if_exists => :overwrite)
 
-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 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.
+Sometimes the user wants to read and possibly modify a book, no matter if it is open in some Excel instance or not, is saved or unsaved. The method +unobtrusively+ provides this service. When modifying a book unobtrusively, its status remains unchanged. This status includes, wheter the book is opened or closed, saved or unsaved, readonly or writable. If the books were closed and the Excel instance are still running, then the book is opened in the Excel instance where it was opened most recently or in a new Excel. This is relevant if the book has references to other books.
 
+Options are +:if_readonly+, +:use_this+, +:keep_open+, +:visible+ 
 
   Book.unobtrusively('simple.xls') do |book|
     # some modification
@@ -150,49 +107,21 @@ 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.
-
-  if book1 == book2 then puts "Both referenced Excel workbooks are identical." 
-
-=== Alive.
+=== Alive?.
 
 Checking whether the referenced Excel workbook responds to methods.
 
-  if book.alive? then puts "book is responding."
-
-=== File name. 
-
-Getting the file name of the book with the absolute path that contains slash (/) instead of back slash (\).
-
-  book.filename
+  if book.alive? then sheet = book[0] end
 
-=== Make a book visible or invisible in Excel.
+=== Making an Excel visible or invisible, and enable and disable DisplayAlerts.
 
-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"
+Make an Excel visible
 
-=== Enable and disable DisplayAlerts in Excel.
+  book.excel.visible = true
 
 Enable DisplayAlerts.
 
-  book.displayalerts = true
-
-Options: +true+ -> enable DisplayAlerts , +false+ -> Disable DisplayAlerts
-
-
-Check whether DisplayAlerts is enabled.
-  
-  if book.displayalerts then p "DisplayAlerts enabled"
-
+  book.excel.displayalerts = true
 
 
 === Accessing a sheet.
@@ -298,7 +227,7 @@ Getting a running Excel instance and reusing it.
 
 Reusing a running Excel instance, making it visible and turning on displayalerts.
 
-   excel2 = Excel.new(:reuse => true, :visible => true, displayalerts => true).
+   excel2 = Excel.new(:reuse => true, :visible => true, :displayalerts => true).
 
 Reusing a certain running Excel instance.
 
@@ -310,7 +239,6 @@ Making Excel visible.
 
   excel = Excel.create
   excel.visible = true
-  puts "visible" if excel.visible
 
 Making Excel invisible
 
@@ -322,7 +250,6 @@ Turning DisplayAlerts on.
 
   excel = Excel.create
   excel.displayalerts = true
-  puts "allows displayalerts" if excel.displayalerts
 
 Turning DisplayAlerts off.
 
@@ -343,10 +270,6 @@ Turning on and off in a block.
 
 === Examples
 
-Including robust_excel_ole.
-
-  include RobustExcelOle
-
 === Example 1 
 
 Opening a book.
@@ -502,9 +425,23 @@ The book is modified, but its status is unchanged.
   => true
 
 
+=== Development
+
+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 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.
+
+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 instance.
+* +save_as+ instead of +save+.
+
+
 === Want to do more things
 
-All RobustExcelOle objects include the win32ole instance. 
 If you want to do something that not provide a function, you can use win32ole methods.
 
 == Support