robust_excel_ole 0.3.0 → 0.3.1

data/README_detail.rdoc

@@ -0,0 +1,510 @@
+= RobustExcelOle
+
+robust_excel_ole processes Excel files, allows to perform all win32ole operations, 
+convenient methods for opening, saving and closing, and implements an Excel file management system.
+
+This is work in progress.
+
+== Requirements
+
+* Ruby 1.8.6 or higher
+
+== Install
+
+  gem install robust_excel_ole
+
+== Usage
+
+  include RobustExcelOle
+
+=== Opening a book.
+
+Example:
+
+  book = Book.open('simple.xls')
+
+Open 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:
+
++: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: +new_excel+)
++:if_obstructed+::   specidy behaviour if the book is blocked by another book (default: +new_excel+)
++: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+::  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+ :
+
+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+::           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.
+
+The values :displayalerts and :visible are reached to the class Excel that controls opening and closing Excel instances.
+
+=== Closing a book.
+
+Simple close.
+
+  book.close
+
+The option is : +:if_unsaved+ . It can have one of the following values:
+
++:save+ (default), +:raise+, +:forget+, +:alert+
+
+The option specifies: If the book is unsaved, then
+
++:save+::   Save the book before closing it.
++:raise+::  Raise an exception. Don't close the book.
++:forget+:: Close the book. 
++:alert+::  Give control to Excel.
+
+
+=== Saving a book.
+
+Simple save.
+
+  book.save
+
+Saving a book with a file name.
+
+  book.save_as('another_simple.xls')
+
+Options are the following:
+
++:if_exists+:: +:raise+ (default), +:overwrite+, +:alert+
+
+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 instance, then raise an exception.
++:alert+::     Give the control to Excel.
+  
+
+=== Unobtrusively modifying a book
+
+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 the following:
+
++:read_only+:: Open the book unobtrusively for reading only  (default: false)
++:use_this+::  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
+                                    in a new excel instance, otherwise
+
++:visible+::   Make the book visible in the Excel (default: false)
++:keep_open+:: Let the book open after modification (default: false)
+
+  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)
+
+=== Alive.
+
+Checking whether the referenced Excel workbook responds to methods.
+
+  if book.alive? then sheet = book[0] end
+
+=== Make an Excel visible or invisible, and enable and disable DisplayAlerts.
+
+Make an Excel visible
+
+  book.excel.visible = true
+
+Enable DisplayAlerts.
+
+  book.excel.displayalerts = true
+
+Options: +true+ -> enable DisplayAlerts , +false+ -> Disable DisplayAlerts
+
+
+=== Accessing a sheet.
+
+A sheet object can be accessed with a Book#[] method via an integer number.
+
+  sheet = book[0]
+
+Accessing a sheet object with the sheet name.
+
+  sheet = book['Sheet1']
+
+Accessing sheet objects using the methods Book#each.
+
+  book.each do |sheet|               
+    # do something with sheet
+  end
+
+=== Accessing a row or a column.
+
+A sheet object is enumerable. Use the methods Sheet#each_column, Sheet#each_row or Sheet#each.
+
+  sheet.each do |cell|
+    # do something with cell
+    # read every row every column
+  end
+
+  sheet.each_row do |row|
+    # do something with row
+  end
+
+  sheet.each_column do |column|
+    # do something with column
+  end
+
+=== Accessing a cell.
+
+Reading a cell from a sheet object.
+
+  sheet[0, 0]  => first cell.
+
+Reading a cell from a range object.
+
+  row_range[0]  => first cell in row_range
+  column_range[1] => second cell in column_range
+
+Reading the value of a cell.
+
+  cell = sheet[0,0]
+  cell.value  => value of the cell.
+
+Writing a cell
+
+  sheet[0,0] = "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  
+
+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
+
+
+=== Adding a sheet.
+
+Adding a new sheet.
+
+  book.add_sheet
+
+Adding a new sheet with a name.
+
+  book.add_sheet(:as => 'new_sheet')
+
+Adding a new sheet with a name before another sheet.
+
+  book.add_sheet(:as => 'new_sheet2', :before => 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
+
+Including robust_excel_ole.
+
+  include RobustExcelOle
+
+=== Example 1 
+
+Opening a book.
+
+  book = Book.open('simple.xls')
+
+Accessing a sheet via its name.
+
+  sheet = book['Sheet1']
+  
+Changing the first cell.
+
+  sheet[0,0] = "new"
+  
+Saving the book.
+
+  book.save
+
+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)
+
+Closing the book.
+
+  book.close  
+
+=== Example 2
+
+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
+
+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.
+
+  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])
+
+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 = Book.open('simple.xls', :if_unsaved => :new_excel)
+
+Accessing a sheet and change a cell.
+
+  sheet = new_book[0]
+  sheet[1,1] = "another"
+
+Opening another book with the same name in the running Excel. The book that contains unsaved changes will be closed before. 
+
+  third_book = Book.open('simple.xls', :if_unsaved => :forget)
+
+Adding a sheet.
+
+  third_book.add_sheet
+
+Closing the book without saving it.
+
+  third_book.close(:if_unsaved => :forget)
+
+Closing the first book and saving it before.
+
+  book.close(:if_unsaved => :save)
+
+=== Example 4
+
+Opening a book.
+
+  book1 = Book.open('simple.xls')
+
+Opening a book with the same name in a different path. Close the old book.
+
+  book2 = Book.open('more/simple.xls', :if_obstructed => :forget)
+
+Changing its cell.
+
+  sheet = book2[0]
+  sheet[0,0] = "new"
+
+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)
+
+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)
+
+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
+
+
+=== 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
+
+This is work in progress. Please contact us and to report issues and feature requests to github Issues. 
+https://github.com/Thomas008/robust_excel_ole/issues
+
+== Collaborate
+
+Please pull request on github.
+
+== Author
+
+thomas mailto:Thomas.Raths@gmx.net
+
+== License
+
+MIT License. For more imformation, please see LICENSE.

data/TodoList.md

@@ -1,27 +1,34 @@
 
 ### immediately
 
---- 2015-04-09 unobtrusively: save book only if it saved: Test
---- 2015-04-09 unobtrusively: return the block result: implementation and test
---- 2015-04-09 unobtrusively: namval: return the contents of cells or region with a given name
---- 2015-04-09 unobtrusively: visible, displayalerts
---- 2015-04-17 unobtrusively: readonly
-
+--- 2015.05-05 unobtrusively:  
+               more tests,
+--- 2015-04-27 excel.rb: implement sucht that remove attr_writer
+--- 2015-04-27 documentation: a crisp one and a detailed one, better examples
+--- 2015-04-02 set options: make it dry
+--- 2015-04-17 acceptance test from Testschmiede
 
 ### quick
 
+--- 2015-05-09 open with option :reuse_excel: 
+               choose the last opened Excel that is different to a certain Excel, if it exists,
+               open a new Excel, else
+
+### short-term
+
+--- 2015-04-17 excel managements system
 --- 2015-04-02 if_unlocked
 --- 2015-04-02 standard use cases
---- 2015-04-02 set options: make it dry
-
-### rather quick
+--- 2015-04-27 excel instances list
 
-### medium
+### mid-term
 
-### slow
+### long-term
 
 ### done
 
+--- 2015-04-17 unobtrusively: readonly
+--- 2015-04-27 tests for life cycle (weakrefs to books)
 --- 2015-04-01 examples for unobtrusively
 --- 2015-04-01 further tests for unobtrusively
 --- 2015-03-26 connnect: check test outputs
@@ -31,3 +38,6 @@
 --- 2015-01-26 unobtrusively 
 --- 2015-01-26 option keep_open
 --- 2015-01-26 separate class for book management 
+--- 2015-04-09 unobtrusively: save book only if it saved: Test
+--- 2015-04-09 unobtrusively: return the block result: implementation and test
+--- 2015-04-09 unobtrusively: namval: return the contents of cells or region with a given name

data/examples/open_save_close/example_control_to_excel.rb

@@ -12,7 +12,7 @@ begin
   dir = create_tmpdir
   file_name = dir + 'simple.xls' 
   book = Book.open(file_name)          # open a book
-  book.visible = true                   # make current Excel visible 
+  book.excel.visible = true                   # make current Excel visible 
   sleep 1
   sheet = book[0]                                                        # access a sheet
   sheet[0,0] = sheet[0,0].value == "simple" ? "complex" : "simple"       # change a cell

data/examples/open_save_close/example_default_excel.rb

@@ -15,7 +15,7 @@ begin
   file_name3 = dir + 'book_with_blank.xls'
   file_name4 = dir + 'merge_cells.xls'
   book1 = Book.open(file_name1)            # open a book in a new Excel instance since no Excel is open
-  book1.visible = true                      # make current Excel visible
+  book1.excel.visible = true               # make current Excel visible
   sleep 2
   book1.close                               # close the book
   sleep 2

data/examples/open_save_close/example_force_excel.rb

@@ -12,12 +12,12 @@ begin
   dir = create_tmpdir
   simple_file = dir + 'simple.xls'
   book1 = Book.open(simple_file)            # open a book in a new Excel instance since no Excel is open
-  book1.visible = true                      # make current Excel visible
+  book1.excel.visible = true                # make current Excel visible
   sleep 2
   book2 = Book.open(simple_file)             # open a new book in the same Excel instance                            
   p "book1 == book2" if book2 == book1      # the books are identical
   sleep 2       
-  book3 = Book.open(simple_file, :force_excel => :new, :visible => true) # open another book in a new Excel instance,                                                       # make Excel visible
+  book3 = Book.open(simple_file, :force_excel => :new, :visible => true) # open another book in a new Excel instance,   
   p "book3 != book1" if (not (book3 == book1))   # the books are not identical 
   sleep 2   
   new_excel = Excel.new(:reuse => false)        # create a third Excel instance

data/examples/open_save_close/example_if_unsaved_forget.rb

@@ -12,7 +12,7 @@ begin
   dir = create_tmpdir
   file_name = dir + 'simple.xls' 
   book = Book.open(file_name)                      # open a book
-  book.visible = true                              # make current Excel visible 
+  book.excel.visible = true                        # make current Excel visible 
   sleep 1
   sheet = book[0]                                            # access a sheet
   first_cell = sheet[0,0].value

data/examples/open_save_close/example_if_unsaved_forget_more.rb

@@ -12,8 +12,8 @@ begin
   dir = create_tmpdir
   file_name = dir + 'simple.xls' 
   book = Book.open(file_name)                      # open a book
-  book.visible = true                              # make current Excel visible 
-  sleep 1
+  book.excel.visible = true                        # make current Excel visible 
+  sleep
   sheet = book[0]                                            # access a sheet
   first_cell = sheet[0,0].value
   sheet[0,0] = first_cell == "simple" ? "complex" : "simple" # change a cell

data/examples/open_save_close/example_rename_cells.rb

@@ -12,7 +12,7 @@ begin
   dir = create_tmpdir
   file_name = dir + 'simple.xls'
   book = Book.open(file_name)                                # open a book.  default:  :read_only => false
-  book.visible = true                                          # make current Excel visible
+  book.excel.visible = true                                          # make current Excel visible
   sheet = book[0]
   #sheet.Names.Add("Wert","$A$1"
 

data/examples/open_save_close/example_reuse.rb

@@ -14,7 +14,7 @@ begin
   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 instance since no Excel is open
-  book1.visible = true                      # make current Excel visible
+  book1.excel.visible = true                # make current Excel visible
   sleep 2
   book2 = Book.open(file_name2)             # open a new book in the same Excel instance
   sleep 2                                   

data/examples/open_save_close/example_simple.rb

@@ -13,7 +13,7 @@ begin
   file_name = dir + 'simple.xls'
   other_file_name = dir + 'different_simple.xls'
   book = Book.open(file_name)                                # open a book.  default:  :read_only => false
-  book.visible = true                                        # make current Excel visible
+  book.excel.visible = true                                  # make current Excel visible
   sheet = book[0]                                            # access a sheet
   sleep 1     
   sheet[0,0] = sheet[0,0].value == "simple" ? "complex" : "simple"  # change a cell