robust_excel_ole 0.2.0.8 → 0.2.1

data/README.rdoc

@@ -1,24 +1,24 @@
 = RobustExcelOle
 
-robust_excel_ole wraps the win32ole, and uses the Excel operations with ruby.
+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 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.
 
-This is work in progress.
-
-Notice some features in robust_excel_ole that are not compatible with wrap_excel:
-* +save_as+ instead of +save+.
+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,
   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.
+* +save_as+ instead of +save+.
+
+This is work in progress.
 
 == Requirements
 
-* Ruby 1.9.2 or higher (platform is windows)
-* also works with Ruby 1.8.6
+* Ruby 1.8.6 or higher
 
 == Install
 
@@ -42,13 +42,12 @@ The semantics is similar to, e.g.,  File.open.
 
 Options are the following:
 
-[:reuse]         boolean (default: true). use an already open Excel-application 
-[:read_only]     boolean (default: false). open in read-only mode  
-[:displayalerts] boolean (default: false). allow display alerts in Excel   
-[:visible]       boolean (default: false). make visibe in Excel                  
+[:reuse]         use an already open Excel-application (default: true) 
+[:read_only]     open in read-only mode (default: false)  
 [:if_unsaved]    :raise (default), :accept, :forget, :new_app, :excel
-[:if_blocking_other]  :raise (default), :forget, :save_and_close, :close_or_raise, :new_app
-                         
+[:if_obstructed]  :raise (default), :forget, :save, :close_if_unsaved, :new_app
+[:displayalerts] allow display alerts in Excel (default: false)
+[:visible]       make visibe in Excel (default: false)                           
 
 The option :if_unsaved  : 
 
@@ -60,15 +59,17 @@ If an unsaved book with the same name is open, then
 [:new_app] Open the new book in a new Excel application
 [:excel]   Give control to Excel.
 
-The option :if_blocking_other :
+The option :if_obstructed :
+
 If a book with same name in a different path is open, then
                  
 [:raise]   Raise an exception. Don't open the book.
 [:forget]  Close the old book, open the new book.
-[:save_and_close]  Save the old book, close it, open the new book
-[:close_or_raise] Close the old book and open the new book, if the old book is saved, raise an exception otherwise
+[: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.
 
+The values :displayalerts and :visible are reached to the class ExcelApp that controls opening and closing of Excel applications.
 
 Examples:
 
@@ -93,6 +94,34 @@ Let the unsaved book open, when opening a book and a book with the same name is
 
   new_book = RobustExcelOle::Book.open('./sample.xls', :if_unsaved => accept)
 
+=== Close a book.
+
+Example:
+
+  book.close
+
+Options are the following:
+
+[:if_unsaved]  :raise (default), :save, :forget, :excel  
+               if the book is unsaved
+
+:raise 
+
+Raise an exception. Don't close the book.                  
+                 
+:save            
+
+Save the book before closing it.                  
+                 
+:forget          
+
+Close the book. 
+    
+:excel           
+
+Give control to Excel.
+
+
 === Save a book.
 
 Simple save:
@@ -123,60 +152,17 @@ Overwrite a book with the same name.
 
   book.save('./another_sample.xls', :if_exists => :overwrite)  
 
-=== == (equal)
+=== == 
 
 Check whether two referenced Excel workbooks are identical.
 
-Example.
-
-  if (book == new_book) then
-    puts "the workbooks are identical"
-  end
-
 === alive?
 
 Check whether the referenced Excel workbook responds to methods.
 
-Example:
-
-  if book.alive? then 
-    puts "the book is alive"
-  end
-
 === filename
 
-Get the file name of the book.
-
-Example:
-
-  book.filename
-
-=== Close a book.
-
-Example:
-
-  book.close
-
-Options are the following:
-
-[:if_unsaved]  :raise (default), :save, :forget, :excel  
-               if the book is unsaved
-                 
-:raise 
-
-Raise an exception. Don't close the book.                  
-                 
-:save            
-
-Save the book before closing it.                  
-                 
-:forget          
-
-Close the book. 
-    
-:excel           
-
-Give control to Excel.
+Return the file name of the book with the absolute path that contains slash (/) instead of back slash (\)
 
 
 

data/examples/open_save_close/example_control_to_excel.rb

@@ -0,0 +1,40 @@
+# example_gibe_control_to_excel.rb: open, close, save  with giving control to Excel 
+
+require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
+
+include RobustExcelOle
+
+ExcelApp.close_all
+begin
+  dir = 'c:/'
+  file_name = dir + 'simple.xls' 
+  book = Book.open(file_name)          # open a book
+  ExcelApp.reuse.Visible = true                              # make Excel visible 
+  sleep 1
+  sheet = book[0]                                                        # access a sheet
+  sheet[0,0] = sheet[0,0].value == "simple" ? "complex" : "simple"       # change a cell
+  sleep 1
+  begin
+    new_book = Book.open(file_name, :if_unsaved => :excel) # open another book with the same file name 
+  rescue ExcelUserCanceled => msg                          # if the user chooses not open the book,
+  	puts "#{msg.message}"                                  #   an exeptions is raised
+  end
+  puts "new book has opened" if new_book
+  ExcelApp.reuse.Visible = true
+  begin
+  	book.close(:if_unsaved => :excel)                      # close the unsaved book. 
+  rescue ExcelUserCanceled => msg                          # user is asked whether the unsaved book shall be saved
+  	puts "#{msg.message}"                                  # if the user chooses to cancel, then an expeption is raised
+  end
+  if new_book then
+  	begin
+  	  new_book.save_as(file_name, :if_exists => :excel)    # save the new book, if it was opened
+  	rescue ExcelErrorSave => msg                           # user is asked, whether the existing file shall be overwritten
+  	  puts "save_as: #{msg.message}"                       # if the user chooses "no" or "cancel", an exception is raised
+  	end 
+
+  	new_book.close                                         # close the new book, if the user chose to open it
+  end
+ensure                                                              
+  ExcelApp.close_all                                       # close ALL workbooks, quit Excel application
+end

data/examples/open_save_close/example_if_obstructed_closeifsaved.rb

@@ -0,0 +1,33 @@
+# example 10: open with :if_obstructed: :close_if_saved
+
+require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
+
+include RobustExcelOle
+
+ExcelApp.close_all
+begin
+  dir = 'C:/'
+  file_name = dir + 'simple.xls'
+  other_dir = 'C:/more_data/'
+  other_file_name = other_dir + 'simple.xls'
+  book = Book.open(file_name, :visible => true)  # open a book, make Excel visible
+  sleep 1
+  sheet = book[0]
+  first_cell = sheet[0,0].value                                   # access a sheet
+  sheet[0,0] = first_cell == "simple" ? "complex" : "simple"      # change a cell
+  sleep 1
+  begin
+    new_book = Book.open(other_file_name, :if_obstructed => :close_if_saved) # raises an exception since the file is not saved
+    rescue ExcelErrorOpen => msg                                             
+    puts "open: #{msg.message}"
+  end                                                        
+  book.save                                                           # save the unsaved book
+  new_book = Book.open(file_name, :if_obstructed => :close_if_saved)  # open the new book, close the saved book    
+  sleep 1
+  new_sheet = new_book[0]
+  new_first_cell = new_sheet[0,0].value
+  puts "the old book was saved" unless new_first_cell == first_cell 
+  new_book.close                                 # close the books                  
+ensure
+  ExcelApp.close_all                         # close all workbooks, quit Excel application
+end

data/examples/open_save_close/example_if_obstructed_forget.rb

@@ -0,0 +1,30 @@
+# example_if_obstructed_forget.rb: open with :if_obstructed: :forget, :new_app
+
+require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
+
+include RobustExcelOle
+
+ExcelApp.close_all
+begin
+  dir = 'C:/'
+  file_name = dir + 'simple.xls'
+  other_dir = 'C:/more_data/'
+  other_file_name = other_dir + 'simple.xls'
+  book = Book.open(file_name, :visible => true)  # open a book, make Excel application visible
+  sleep 3 
+  begin
+    new_book = Book.open(other_file_name)        # open a book with the same file name in a different path
+  rescue ExcelErrorOpen => msg                   # by default: raises an exception 
+  	puts "open: #{msg.message}"
+  end
+  # open a new book with the same file name in a different path. close the old book before.
+  new_book = Book.open(other_file_name, :if_obstructed => :forget) 
+  sleep 3
+  # open another book with the same file name in a different path. Use a new Excel application
+  another_book = Book.open(file_name, :if_obstructed => :new_app, :visible => true)                                         
+  sleep 3
+  new_book.close                                 # close the books                      
+  another_book.close
+ensure
+  ExcelApp.close_all                         # close all workbooks, quit Excel application
+end

data/examples/open_save_close/example_if_obstructed_save.rb

@@ -0,0 +1,31 @@
+# example_if_obstructed_save.rb:
+# open with :if_obstructed: :save
+
+require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
+
+include RobustExcelOle
+
+ExcelApp.close_all
+begin
+  dir = 'C:/'
+  file_name = dir + 'simple.xls'
+  other_dir = 'C:/more_data/'
+  other_file_name = other_dir + 'simple.xls'
+  book = Book.open(file_name, :visible => true)  # open a book, make Excel visible
+  sleep 1
+  sheet = book[0]
+  first_cell = sheet[0,0].value                                   # access a sheet
+  sheet[0,0] = first_cell == "simple" ? "complex" : "simple"      # change a cell
+  sleep 1
+  new_book = Book.open(other_file_name, :if_obstructed => :save)  # open a book with the same file name in a different path
+  sleep 1                                                         #save the old book, close it, before
+  old_book = Book.open(file_name, :if_obstructed => :forget ,:visible => true) # open the old book    
+  sleep 1
+  old_sheet = old_book[0]
+  old_first_cell = old_sheet[0,0].value
+  puts "the old book was saved" unless old_first_cell == first_cell 
+  new_book.close                                 # close the books                      
+  old_book.close
+ensure
+  ExcelApp.close_all                         # close all workbooks, quit Excel application
+end

data/examples/open_save_close/example_if_unsaved_accept.rb

@@ -0,0 +1,38 @@
+# example_ifunsaved_accept.rb: 
+# open with :if_unsaved => :accept, close with :if_unsaved => :save 
+
+require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
+
+include RobustExcelOle
+
+ExcelApp.close_all
+begin
+  dir = 'C:/'
+  file_name = dir + 'simple.xls' 
+  book = Book.open(file_name)                      # open a book 
+  sheet = book[0]                                                  # access a sheet
+  sheet[0,0] = sheet[0,0].value == "simple" ? "complex" : "simple" # change a cell
+  begin
+    new_book = Book.open(file_name)                # open another book with the same file name
+  rescue ExcelErrorOpen => msg                     # by default: raises an exception:
+    puts "open error: #{msg.message}"              # a book with the same name is already open and unsaved 
+  end
+  new_book = Book.open(file_name, :if_unsaved => :accept) # open another book with the same file name 
+                                                          # and let the unsaved book open
+  if book.alive? && new_book.alive? then                  # check whether the referenced workbooks
+  	puts "open with :if_unsaved => :accept : the two books are alive." # respond to methods
+  end
+  if book == new_book then                                # check whether the book are equal
+  	puts "both books are equal"
+  end
+  begin                                                                   
+  	book.close                                          # close the book. by default: raises an exception:
+  rescue ExcelErrorClose => msg                         #   book is unsaved
+  	puts "close error: #{msg.message}"
+  end
+  book.close(:if_unsaved => :save)                      # save the book before closing it 
+  puts "closed the book successfully with option :if_unsaved => :save"
+  new_book.close                                        # close the other book. It is already saved.
+ensure
+	  ExcelApp.close_all                                    # close workbooks, quit Excel application
+end

data/examples/open_save_close/example_if_unsaved_forget.rb

@@ -0,0 +1,34 @@
+# example_ifunsaved_forget.rb:
+# open with :if_unsaved => :forget, :new_app, close with :if_unsaved => :save 
+
+require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
+
+include RobustExcelOle
+
+ExcelApp.close_all
+begin
+  dir = 'C:/'
+  file_name = dir + 'simple.xls' 
+  book = Book.open(file_name)                      # open a book
+  ExcelApp.reuse.Visible = true        # make Excel visible 
+  sleep 1
+  sheet = book[0]                                            # access a sheet
+  first_cell = sheet[0,0].value
+  sheet[0,0] = first_cell == "simple" ? "complex" : "simple" # change a cell
+  sleep 1
+  new_book = Book.open(file_name, :if_unsaved => :forget) # open another book with the same file name 
+                                                          # and close the unsaved book without saving it
+  sheet_new_book = new_book[0]
+  if (not book.alive?) && new_book.alive? && sheet_new_book[0,0].value == first_cell then # check whether the unsaved book 
+    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[0,0] = sheet_new_book[0,0].value == "simple" ? "complex" : "simple" # change a cell
+  # open another book in a new Excel application, and make Excel visible, leaving the unsaved book open
+  another_book = Book.open(file_name, :if_unsaved => :new_app, :visible => true)  
+  sleep 3                                                                  # leaving the unsaved book open  
+  new_book.close(:if_unsaved => :forget )                                
+  another_book.close
+ensure
+	  ExcelApp.close_all                                    # close all workbooks, quit Excel application
+end

data/examples/open_save_close/example_read_only.rb

@@ -0,0 +1,27 @@
+# example_read_only: open with read_only mode. save, close 
+
+require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
+
+include RobustExcelOle
+
+ExcelApp.close_all
+begin
+  dir = 'C:/'
+  file_name = dir + 'simple.xls'
+  other_file_name = dir + 'different_simple.xls'
+  # open a book with read_only and make Excel visible
+  book = Book.open(file_name, :read_only => true, :visible => true) 
+  sheet = book[0]                                     			   # access a sheet
+  sleep 1     
+  sheet[0,0] = sheet[0,0].value == "simple" ? "complex" : "simple" # change a cell
+  sleep 1
+  begin
+    book.save                                         # simple save. 
+  rescue ExcelErrorSave => msg                        # raises an exception because book is opened in read_only mode
+    puts "save_as error: #{msg.message}"
+  end
+  book.close                                          # close the book without saving it 
+ensure
+  ExcelApp.close_all                                  # close workbooks, quit Excel application
+end
+

data/examples/open_save_close/example_reuse.rb

@@ -0,0 +1,31 @@
+# example_reuse.rb: open a book in a running Excel application and in a new one. make visible
+
+require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
+
+include RobustExcelOle
+
+ExcelApp.close_all
+begin
+  dir = 'C:/'
+  file_name1 = dir + 'simple.xls'
+  file_name2 = dir + 'different_simple.xls'
+  file_name3 = dir + 'different_simple.xls'
+  file_name4 = dir + 'book_with_blank.xls'
+  book1 = Book.open(file_name1)             # open a book in a new Excel application since no Excel is open
+  ExcelApp.reuse.Visible = true # make Excel visible
+  sleep 2
+  book2 = Book.open(file_name2)             # open a new book in the same Excel application
+  sleep 2                                   # (by default:  :reuse => true)
+  book3 = Book.open(file_name3, :reuse => false, :visible => true) # open another book in a new Excel application, 
+  sleep 2                                                          # make Excel visible
+  book4 = Book.open(file_name4, :reuse => true, :visible => true)  # open anther book, and use a running Excel application
+  sleep 2                                                          # (Excel chooses the first Excel application)        
+  book1.close                               # close the books
+  book2.close                                             
+  book3.close
+  book4.close                                         
+ensure
+  ExcelApp.close_all                       # close all workbooks, quit Excel application
+end
+
+

data/examples/open_save_close/example_simple.rb

@@ -0,0 +1,30 @@
+# example_simple.rb: open a book, simple save, save_as, close
+
+require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
+
+include RobustExcelOle
+
+ExcelApp.close_all
+begin
+  dir = 'C:/'
+  file_name = dir + 'simple.xls'
+  other_file_name = dir + 'different_simple.xls'
+  book = Book.open(file_name)                # open a book.  default:  :read_only => false
+  ExcelApp.reuse.Visible = true                  # make Excel visible
+  sheet = book[0]                                            # access a sheet
+  sleep 1     
+  sheet[0,0] = sheet[0,0].value == "simple" ? "complex" : "simple"  # change a cell
+  sleep 1
+  book.save                                                  # simple save
+  begin
+  	book.save_as(other_file_name)                            # save_as :  default :if_exists => :raise 
+  rescue ExcelErrorSave => msg
+  	puts "save_as error: #{msg.message}"
+  end
+  book.save_as(other_file_name, :if_exists => :overwrite)    # save_as with :if_exists => :overwrite
+  puts "save_as: saved successfully with option :if_exists => :overwrite"
+  book.close                                                 # close the book
+ensure
+	  ExcelApp.close_all                                         # close workbooks, quit Excel application
+end		
+