robust_excel_ole 0.5.1 → 0.6

data/Changelog

@@ -1,10 +1,23 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+## [0.6] - 2016-03-08
+
+## [0.5.2] - 2016-17-07
+
+### Changed
+- Book: open: option :update_links
+- Book: open: options :default_excel, :force_excel => :current instead of :reuse
+  (:active, :reuse as alias)
+- Book: open: options: deleted :displayalerts
+- Excel: create, current: with options :visible, :displayalerts
+- Excel: create, current, new: new options-value :displayalerts => :if_visible
+
 ## [0.5.1] - 2016-18-06
 
 ### Added
 - Book#open :force_excel => :active
+- Excel#workbooks_visible
 
 ### Changed
 - Book: open: :default_excel, :force_excel => :active, (:reuse as alias), bug fix in :default

data/README.rdoc

@@ -2,13 +2,14 @@
 
 robust_excel_ole helps to automate modifying and reading Excel files.
 This is done by sending VBA methods via Win32OLE.
-Moreover, robust_excel_ole implements a management system of Excel files and Excel instances and keeps track of all workbooks.
+Moreover, robust_excel_ole implements a management system and keeps track of Excel files and Excel instances
 
 Goals:
 - support both fully automated operations as well as simultaneous user interactions during the automation
-- be able to cope with all cases of Excel (and user) behaviour, encapsulate errors
+- robust Excel AUtomation: be able to deal with all cases of Excel (and user) behaviour, encapsulate errors
 - provide convenient methods for frequent (common) tasks
 - support the use of simultaneously running Excel instances
+- comprehensive wrapping of Excel using Win32OLE
 - allow the presence of referenced libraries and provide some support for that
 - support EXCEL 2010, EXCEL 2007
 
@@ -41,9 +42,9 @@ The semantics is similar to, e.g.,  +File.open+.
 Options are 
   
   +:default_excel+, +:force_excel+, +:if_absent+, +:if_unsaved+, +:if_obstructed+, 
-  +:read_only+, +:check_compatibility, +:visible+, +:displayalerts+. 
+  +:read_only+, +:visible+, +:check_compatibility, and +:update_links+. 
 
-Valid values for +:default_excel+ are +:active+ (or +:reuse+), +:new+ or some Excel instance, for +:force_excel+ : +:active (or +:reuse+), +:new+ or some Excel instance, for +:if_unsaved+ : +:raise+, +:accept+, +:forget+, +:alert+ and +:new_excel+, for +:if_obstructed+ : +:raise+, +:save+, +:close_if_saved+, +:forget+, +:alert+ and +:new_excel+ , for +:if_absent+ : +:raise+ and +:create+.
+Valid values for +:default_excel+ are +:current+ (or +:active+, or +:reuse+), +:new+ or some Excel instance, for +:force_excel+ : +:current+ (or +:active+, or +:reuse+), +:new+ or some Excel instance, for +:if_unsaved+ : +:raise+, +:accept+, +:forget+, +:alert+ and +:new_excel+, for +:if_obstructed+ : +:raise+, +:save+, +:close_if_saved+, +:forget+, +:alert+ and +:new_excel+ , for +:if_absent+ : +:raise+ and +:create+. The others are Boolean.
 
 Here are a few examples:
 
@@ -65,7 +66,7 @@ Opening a workbook in a given Excel instance, no matter if the workbook was open
 
   book = Book.open('workbook.xls', :force_excel => excel1)
 
-Opening a workbook in a new Excel instance and make it visible.
+Opening a workbook in a new Excel instance and make the window of the workbook visible.
 
   book = Book.open('workbook.xls', :force_excel => :new, :visible => true)
 
@@ -137,11 +138,11 @@ If a workbook is blocking the workbook that should be saved, then the former one
 
 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 workbook is opened or closed, saved or unsaved, readonly or writable. 
 
-Some options determine the Excel instance in which a closed workbook is opened. The options +:active+ (or +:reuse+) (default) indicates that the closed workbook is opened in the Excel instance where the workbooks is opened, if such an Excel instance exists, otherwise that another Excel instance is reused. The option +:hidden+ provokes that the closed workbook is opened in a separate Excel instance that is not visible and has no DisplayAlerts. Any following closed workbook 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 workbook.
+Some options determine the Excel instance in which a closed workbook is opened. The option +:current+ (or +:active+, or +:reuse+) (default) indicates that the closed workbook is opened in the Excel instance where the workbooks is opened, if such an Excel instance exists, otherwise that another Excel instance is reused. The option +:hidden+ provokes that the closed workbook is opened in a separate Excel instance that is not visible and has no DisplayAlerts. Any following closed workbook 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 workbook.
 
-Further options are +:read_only+, +:readonly_excel+, and +:keep_open. The option +:readonly_excel+ chooses whether a book that is opened in read only mode. If the workbook is opened as read only, then the option +:readonly_excel+ determines whether to close the workbook and open it as writable in the Excel instance where it was open so far, or to open it as writable in another running Excel instance, if such an instance exists, or to open it in a new Excel instance. Moreover, there are the options +:visible+, +:displayalerts+ and +:check_compatiblity.
+Further options are +:read_only+, +:readonly_excel+, and +:keep_open. The option +:readonly_excel+ chooses whether a book that is opened in read only mode. If the workbook is opened as read only, then the option +:readonly_excel+ determines whether to close the workbook and open it as writable in the Excel instance where it was open so far, or to open it as writable in another running Excel instance, if such an instance exists, or to open it in a new Excel instance. Moreover, there are the options +:visible+, and +:check_compatiblity.
 
-  Book.unobtrusively('workbook.xls', :active, :read_only => false, :keep_open => false) do |book|
+  Book.unobtrusively('workbook.xls', :current, :read_only => false, :keep_open => false) do |book|
     # some modification
     sheet = book[0]
     sheet[1,1] = "c" 
@@ -188,17 +189,17 @@ Bring the window of a workbook to the foreground, make it available for keyboard
   book.activate
 
 
-=== Making a workbook visible or invisible
+=== Making the window of the workbook visible
 
-Open a workbook and make the Excel instance visible.
+Open a workbook and make the Excel instance and the window of the workbook visible.
 
   book = Book.open('workbook.xls', :visivble => true)
 
-Make the workbook invisible.
+Make the window of the workbook invisible.
 
   book.visible = false
 
-Make the workbook visible
+Make the window of the workbook visible.
 
   book.visible = true
 
@@ -356,26 +357,74 @@ Creating a new Excel.
 
   excel1 = Excel.create
 
-Getting a running Excel instance and reusing it.
+or 
+
+  excel1 = Excel.new(:reuse => false)  
+
+Resusing a runnin Excel instance.
 
   excel2 = Excel.current
 
-Reusing a running Excel instance, making it visible and turning on displayalerts.
+or 
 
-  excel2 = Excel.new(:reuse => true, :visible => true, :displayalerts => true).
+  excel2 = Excel.new(:reuse => true)  
+
+Options are +:reuse+ (+true+, +false+), +:visible+ (+true+, +false+) and +:displayalerts+ (+true+, +false+, +:if_visible+).  
 
 Promoting an Excel instance represented as WIN32OLE object to an Excel object
 
-  excel = Excel.new(:reuse => win32ole_object)
+  excel = Excel.new(win32ole_object)
+
+=== Making a Excel visible or invisible
+
+Creating a new Excel and making it visible.
+
+  excel1 = Excel.create(:visible => true)
+
+or
+
+  excel1 = Excel.new(:reuse => false, :visible => true)  
+
+Reusing a Excel and making it invisible.
+
+  excel2 = Excel.current(:reuse => false, :visible => false)  
+
+or 
+
+  excel2 = Excel.new(:reuse => false, :visible => false)
+
+=== Enabling or disabling DisplayAlerts
+
+Enabling DisplayAlerts.
+
+  excel3 = Excel.new(:reuse => true, :displayalerts => true)
+
+Disabling DisplayAlerts.
+  
+  excel3 = Excel.current(:reuse => true, :displayalerts => false)
+
+Enabling DisplayAlerts whenever the Excel instance is visible.
+
+  excel3 = Excel.current(:reuse => true, :displayalerts => :if_visible)
+
+=== Making all workbooks visible or invisible
+
+Making all workbooks visible.
+
+  excel1.workbooks_visible true  
+
+Making all workbooks invisible.
+
+  excel1.workbooks_visible false   
 
 === Closing an Excel
 
   excel = Excel.current
   excel.close
 
-The options are +:if_unsaved+ and +:hard+ . Example:
+The options are +:if_unsaved+ and +:hard+ . Values for :if_unsaved+ are +:raise+, +:save+, +:forget+ and +:keep_open+.
 
-Closing the Excel instance, saving unsaved wrkbooks and terminating the Excel process
+Closing the Excel instance, saving unsaved workbooks and terminating the Excel process hard.
 
   excel.close(:if_unsaved => :save, :hard => true)
 
@@ -383,11 +432,11 @@ Closing the Excel instance, saving unsaved wrkbooks and terminating the Excel pr
 
   Excel.close_all
 
-The options are +:if_unsaved+ and +:hard+ . Values for :if_unsaved+ are +raise+, +save+, and +forget+. Example:
+The options are +:if_unsaved+ and +:hard+ . Values for :if_unsaved+ are +:raise+, +:save+, and +:forget+. Example:
 
-Closing all Excel instances, not saving unsaved workbooks and terminating the Excel processes
+Closing all Excel instances, saving unsaved workbooks and terminating the Excel processes softly.
 
-  Excel.close_all(:if_unsaved => :forget, :hard => :true) 
+  Excel.close_all(:if_unsaved => :save, :hard => false) 
 
 === Terminating all Excel processes
 

data/README_detail.rdoc

@@ -42,22 +42,21 @@ The semantics is similar to, e.g., +File.open+.
 Options are the following:
 
 +:default_excel+::   open the workbook in the Excel instance where it was opened before most recently,
-if the book was opened before and this Excel instance is alive. Otherwise open it in the active (+:active+ or +:reuse+), a new (+:new+) or a given Excel instance (default: +reuse+)
-+:force_excel+::     open the workbook in the active, a new or given Excel instance 
+if the book was opened before and this Excel instance is alive. Otherwise open it in the current (+:current+, or +:active+, or +:reuse+), a new (+:new+) or a given Excel instance (default: +:current+)
++:force_excel+::     open the workbook in the current (+:current+, or +:active+, or +:reuse+), a new (+:new+) or given Excel instance 
 +:if_absent+::       specify behaviour if the workbook with the given file name does not exist if the workbook does not exist (default: +create+)
 +:if_unsaved+::      specify behaviour if the workbook was unsaved (default: +new_excel+)
 +:if_obstructed+::   specidy behaviour if the workbook is blocked by another book (default: +new_excel+)
 +:read_only+::       open in read-only mode (default: +false+) 
 +:check_compatibility:: check compatibility when saving
-+:displayalerts+::   allow display alerts in Excel (default: +false+)
-+:visible+::         make visibe in Excel (default: +false+)
++:visible+::         makes the window of the workbook visible or invisible (default: +true+)
 
 The option +:defaut_excel+  :
 
 If the workbook was open before, then open it in the Excel instance where it was open before most recently. If the workbook cannot be reopened, i.e., the book was not opened before, or the Excel is not alive anymore,
 then
 
-+:active+ (or :reuse+:): Connect to a running Excel, if it exists, otherwise open a new Excel.
++:current+ (or +:active+, or +:reuse+:): Connect to the current (the first opened) Excel instance, if it exists, otherwise open a new Excel.
 +:new+:: Open in a new Excel.
 [instance]:: Open in a given Excel instance.
 
@@ -65,6 +64,7 @@ The option +:force_excel  :
 
 No matter if the workbook was open before, or the Excel instance is alive
 
++:current+ (or +:active+, or +:reuse+): Open the current (the first opened) Excel instance
 +:new+:: Open in a new Excel instance.
 [instance]:: Open in a given Excel instance.
 
@@ -95,8 +95,6 @@ If a workbook is open and a new workbook with same name and a different path is
 +:close_if_saved+:: Close the old workbook and open the new workbook, if the old workbook is saved, otherwise raise an exception.
 +:new_excel+::      Open the new workbook in a new Excel instance.
 
-The values :displayalerts and :visible are reached to the class Excel that controls opening and closing Excel instances.
-
 Here are a few examples:
 
 Opening a workbook in the Excel instance where it was opened before most recently, if it was opened before and this Excel instance is alive. Otherwise opening it in a running Excel, if it exists, or in a new Excel.
@@ -213,11 +211,11 @@ If a workbook is blocking the workbook that should be saved, then the former one
 
 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 workbook is opened or closed, saved or unsaved, readonly or writable. 
 
-One option chooses the Excel instance in which a closed workbook is opened. The options +:active+ (or +:reuse) (default) indicates that the closed workbook is opened in the Excel instance of the workbook, if it exists, or that another Excel instance is reused. The option +:hidden+ provokes that the closed workbook is opened in a separate Excel instance that is not visible and has no DisplayAlerts. Any following closed workbook 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 workbook.
+One option chooses the Excel instance in which a closed workbook is opened. The option +:current+ (or +:active+, or +:reuse) (default) indicates that the closed workbook is opened in the Excel instance of the workbook, if it exists, or that another Excel instance is reused. The option +:hidden+ provokes that the closed workbook is opened in a separate Excel instance that is not visible and has no DisplayAlerts. Any following closed workbook 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 workbook.
 
 Options are the following:
 
-+:active (or +:reuse+:): (default) : open a closed workbook in the Excel instance of the workbook, if it exists, otherwise reuse another Excel
++:current+ (or +:active, or +:reuse+:): (default) : open a closed workbook in the Excel instance where it was opened most recently, if such an Excel instance exists, otherwise open it in the current (first opened) Excel instance
 +:hidden+::          : open a closed workbook in one separate Excel instance that is not visible and has no displayalerts
 <excel-instance> : open a closed workbooks in the given Excel instance
                
@@ -227,8 +225,7 @@ Options are the following:
                      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 workbook open after unobtrusively opening (default: false)
-+:visible+::            change the Excel into visible or invisible
-+:displayalerts+::      change the Excel into enable or disable displayalerts
++:visible+::            make the window of the workbook visible (default: false)
 +:check_compatibility+:: checks compatibility when saving
 
   Book.unobtrusively('workbook.xls') do |book|
@@ -277,23 +274,23 @@ Bring the focus to a workbook. Make it available for keyboard inputs and make th
 
   book.activate
 
-=== Making a workbook visible or invisible
+===  Make the window of the workbook visible.
 
 Open a workbook and make the Excel instance visible.
 
   book = Book.open('workbook.xls', :visivble => true)
 
-Make the workbook invisible.
+ Make the window of the workbook visible.
 
   book.visible = false
 
-Make the workbook visible
+ Makes the window of the workbook visible.
 
   book.visible = true
 
 === Making an Excel visible or invisible, and enable and disable DisplayAlerts.
 
-Make an Excel visible
+Make an Excel visible.
 
   book.excel.visible = true
 
@@ -449,40 +446,76 @@ Creating a new Excel.
 
   excel1 = Excel.create
 
-Getting a running Excel instance and reusing it.
-Connecting to the first opened Excel instance. If this Excel instance is being closed, then Excel creates a new Excel instance that has the same Hwnd
+or 
+
+  excel1 = Excel.new(:reuse => false)  
+
+Resusing a runnin Excel instance.
 
   excel2 = Excel.current
 
-Reusing a running Excel instance, making it visible and turning on displayalerts.
+or 
 
-  excel2 = Excel.new(:reuse => true, :visible => true, :displayalerts => true).
+  excel2 = Excel.new(:reuse => true)  
+
+Options are +:reuse+ (+true+, +false+), +:visible+ (+true+, +false+) and +:displayalerts+ (+true+, +false+, +:if_visible+).  
 
 Promoting an Excel instance represented as WIN32OLE object to an Excel object
 
-  excel = Excel.new(:reuse => win32ole_object)
+  excel = Excel.new(win32ole_object)
+
+=== Making a Excel visible or invisible
+
+Creating a new Excel and making it visible.
+
+  excel1 = Excel.create(:visible => true)
+
+or
+
+  excel1 = Excel.new(:reuse => false, :visible => true)  
+
+Reusing a Excel and making it invisible.
 
+  excel2 = Excel.current(:reuse => false, :visible => false)  
+
+or 
+
+  excel2 = Excel.new(:reuse => false, :visible => false)
+
+=== Enabling or disabling DisplayAlerts
+
+Enabling DisplayAlerts.
+
+  excel3 = Excel.new(:reuse => true, :displayalerts => true)
+
+Disabling DisplayAlerts.
+  
+  excel3 = Excel.current(:reuse => true, :displayalerts => false)
+
+Enabling DisplayAlerts whenever the Excel instance is visible.
+
+  excel3 = Excel.current(:reuse => true, :displayalerts => :if_visible)
 
 === Closing an Excel
 
   excel = Excel.current
   excel.close
 
-Closing the Excel instance and terminating the Excel process
+The options are +:if_unsaved+ and +:hard+ . Values for :if_unsaved+ are +:raise+, +:save+, +:forget+ and +:keep_open+.
 
-  excel.close(:hard => true)
+Closing the Excel instance, saving unsaved workbooks and terminating the Excel process hard.
+
+  excel.close(:if_unsaved => :save, :hard => true)
 
 === Closing all Excel instances.
 
   Excel.close_all
 
- Closing the Excel instances and terminating the Excel processes
-
-  Excel.close_all(:hard => true) 
+The options are +:if_unsaved+ and +:hard+ . Values for :if_unsaved+ are +:raise+, +:save+, and +:forget+. Example:
 
-=== Terminating all Excel processes
+Closing all Excel instances, saving unsaved workbooks and terminating the Excel processes softly.
 
-  Excel.kill_all
+  Excel.close_all(:if_unsaved => :save, :hard => false) 
 
 === Recreating an Excel instance    
 

data/examples/edit_sheets/example_access_sheets_and_cells.rb

@@ -1,8 +1,8 @@
 # example_access_sheets_and_cells.rb: 
 # access sheets, print cells, rows, and columns of a sheet
 
-require File.join(File.dirname(__FILE__), '../../lib/general')
-require File.join(File.dirname(__FILE__), '../../spec/helpers/create_temporary_dir')
+require File.expand_path('../../lib/robust_excel_ole', File.dirname(__FILE__))
+require File.join(File.dirname(File.expand_path(__FILE__)), '../../spec/helpers/create_temporary_dir')
 require "fileutils"
 
 include RobustExcelOle

data/examples/edit_sheets/example_adding_sheets.rb

@@ -1,8 +1,8 @@
 # example_adding_sheets.rb: 
 # adding new and copied at various positions with various sheet names
 
-require File.join(File.dirname(__FILE__), '../../lib/general')
-require File.join(File.dirname(__FILE__), '../../spec/helpers/create_temporary_dir')
+require File.expand_path('../../lib/robust_excel_ole', File.dirname(__FILE__))
+require File.join(File.dirname(File.expand_path(__FILE__)), '../../spec/helpers/create_temporary_dir')
 require "fileutils"
 
 include RobustExcelOle

data/examples/edit_sheets/example_concating.rb

@@ -2,9 +2,8 @@
 # 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 'general'
-require File.join(File.dirname(__FILE__), '../../lib/general')
+require File.expand_path('../../lib/robust_excel_ole', File.dirname(__FILE__))
+require File.join(File.dirname(File.expand_path(__FILE__)), '../../spec/helpers/create_temporary_dir')
 require "fileutils"
 
 include RobustExcelOle

data/examples/edit_sheets/example_copying.rb

@@ -3,9 +3,8 @@
 # unnamed cells shall not be copied
 # if a sheet does not contain any named cell, then the sheet shall not be copied
 
-require 'rubygems'
-#require 'general'
-require File.join(File.dirname(__FILE__), '../../lib/general')
+require File.expand_path('../../lib/robust_excel_ole', File.dirname(__FILE__))
+require File.join(File.dirname(File.expand_path(__FILE__)), '../../spec/helpers/create_temporary_dir')
 require "fileutils"
 
 include RobustExcelOle

data/examples/edit_sheets/example_expanding.rb

@@ -5,9 +5,8 @@
 # the sheet's name shall be the name of the Excel name
 # in addition to that, the cell B2 shall be named "name" and get the sheet name as its value 
 
-require 'rubygems'
-#require 'general'
-require File.join(File.dirname(__FILE__), '../../lib/general')
+require File.expand_path('../../lib/robust_excel_ole', File.dirname(__FILE__))
+require File.join(File.dirname(File.expand_path(__FILE__)), '../../spec/helpers/create_temporary_dir')
 require "fileutils"
 
 include RobustExcelOle

data/examples/edit_sheets/example_naming.rb

@@ -3,9 +3,8 @@
 # the contents of each cell is copied
 # the new workbook's name is extended by the suffix "_named"
 
-require 'rubygems'
-#require 'general'
-require File.join(File.dirname(__FILE__), '../../lib/general')
+require File.expand_path('../../lib/robust_excel_ole', File.dirname(__FILE__))
+require File.join(File.dirname(File.expand_path(__FILE__)), '../../spec/helpers/create_temporary_dir')
 require "fileutils"
 
 include RobustExcelOle

data/examples/edit_sheets/example_ranges.rb

@@ -1,8 +1,8 @@
 # example_ranges.rb: 
 # access row and column ranges of a sheet. 
 
-require File.join(File.dirname(__FILE__), '../../lib/general')
-require File.join(File.dirname(__FILE__), '../../spec/helpers/create_temporary_dir')
+require File.expand_path('../../lib/robust_excel_ole', File.dirname(__FILE__))
+require File.join(File.dirname(File.expand_path(__FILE__)), '../../spec/helpers/create_temporary_dir')
 require "fileutils"
 
 include RobustExcelOle