robust_excel_ole 1.1.4 → 1.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8c842707a42ecf41966021d1c4b46de412d598a5
-  data.tar.gz: 2ac4026904e8fab21e087bdeaae0b123d14d41cc
+  metadata.gz: 94e2b8cc2f0306a63e377d70378a04063e6b5cf2
+  data.tar.gz: 6d4c94aa56956a25ba723746bf05e23320aa36bb
 SHA512:
-  metadata.gz: 93acf54dc229f58aa5e1cb5b1ad59f0d28fa77e513af12adc52e1bf5daaeae2920d3206637a196cc7dd78d2b40c5feb2bbfb2599e88d70ac273396dd5545bf9e
-  data.tar.gz: 468faa1ad3c10feeb8316fc9de2d827ba1be7444108af0c0f9cd0d7d89ba33538e87e9af5e9ae694a11ca25bef2b2ccafbd475880a753923417a011bc85baaa0
+  metadata.gz: f46997852585e4560db9ccb679a0dccc11a6128b59022b374d8393771531ae2aab2973fa10d0f342f882181dcaaca2cdf4af7151ed918446bdebdb5f57faf8dc
+  data.tar.gz: 99d74fe8c6c16ab52c40c6d5362cba29a07539acf695fbc546619b8fb18086b860258005ccd63429c19655aaf6212096c5d1d76924c4ff85be565cf7dc88e34a

data/Changelog

@@ -1,9 +1,22 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+## [1.1.5] - 2018-10-7
+
+### Added
+  - Book#unobtrusively: 
+    option :writable
+
+### Changed
+  - Book#unobtrusively:
+    option :rw_change_excel instead :readonly_excel
+
+### Added
+
 ## [1.1.4] - 2018-10-6
 
 ### Added
+  - Book#open: for the options: simplifiaction: :force can be left out
   - Excel#for_this_instance
   - Excel#for_all_workbooks
   - Book#for_this_workbooks

data/README.rdoc

@@ -1,22 +1,26 @@
 = RobustExcelOle
 
-This ruby gem automates reading, modifying, and writing Excel files. It is designed to support several kinds of concurrency of both simultaneously running Excel instances and simultanously happening user interactions.
+This library automates reading, modifying, and writing Excel workbooks. It is designed to support several kinds of concurrency of both simultaneously running Excel instances and simultanously happening user interactions.
 RobustExcelOle deals with various cases of Excel and user behaviour,
 and implements workarounds for some Excel bugs.
 The gem provides convenient methods for common tasks, and facilitates referenced libraries.
-It can be used for any recent Excel Office version, and is tested for Excel 2010.
 
-RobustExcelOle works by sending VBA methods via Win32OLE.
-It implements a management system and keeps track of Excel files and Excel instances.
+RobustExcelOle works by sending VBA methods via Win32OLE. It keeps track of Excel workbooks and Excel instances.
 
 == Requirements
 
 * Ruby 1.8.6 or higher
 
-== Install
+== Installation
+
+You can install the gem by running the command
 
   gem install robust_excel_ole
 
+or by using bundler and putting the following line in your Gemfile.
+
+  gem 'robust_excel_ole'
+
 == Usage
 
 RobustExcelOle can be used either for scripts
@@ -30,79 +34,110 @@ or as a console
 
 The call of the console will include RobustExcelOle for you.
 
-The following examples can be used for both scripts and console. You can try them directly.
+The following examples can be used for both scripts and console. If you are in the path of the gem and start the console, you can just put these examples.
 
 == Description  
 
-RobustExcelOle enables opening and processing Excel files (or workbooks). In the following example, we want to open a workbook, modify a cell, save and close the workbook. 
+In the following example, we want to open a workbook, modify a cell, save and close the workbook. 
 
-First we open a workbook.
+Let's open a workbook.
 
   workbook = Workbook.open 'spec/data/workbook.xls'
 
-We can also open the workbook using a block, similar to, e.g., +File.open+. 
+Now we have a Workbook object that wraps a win32ole object. That is, you can send any win32ole (VBA) method to it. For example, you can determine the name and the saved-status of the workbook.
 
-  Workbook.open('spec/data/workbook.xls') do |workbook|
-    # do something
-  end
+  workbook.Name 
+  # => "workbook.xls"
+
+  workbook.Visible
+  # => false
 
-Now we have a Workbook object that wraps a win32ole object. That is, you can send any win32ole (VBA) method to it. For some common tasks and for considering various cases of Excel and user behaviour, more convenient methods are implemented.
+For some common tasks and for considering various complex cases of Excel and user behaviour, more convenient methods are implemented. For example, RobustExcelOle provides methods for reading and writing the contents of ranges, for opening, saving, closing, reopening and unobtrusively opening workbooks, and for setting options.
 
-For example, we can make the workbook visible, using
+First we want to make the workbook visible.
 
   workbook.visible = true
 
-or
+This method makes both the Excel instance and the window of the Workbook-win32ole-object visible.
 
-  workbook.for_this_workbook(:visible => true)
+Let's read the value of a named cell.
 
-You can also open a workbook and make it visible in one step.
+  value = workbook['firstcell']
+  # => "foo"
 
-  workbook = Workbook.open('spec/data/workbook.xls', :visible => true)
+Now we want to write a new value into this cell.
 
-or
+  workbook['firstcell'] = "new"
 
-  workbook = Workbook.open('spec/data/workbook.xls', :v => true)
+Then we'll save the workbook.
 
-Then we read the value of a cell.
+  workbook.save
 
-  value = workbook['firstcell']
-  # => "foo"
+Finally we want to close the workbook.
 
-Now we write a new value in this cell.
+  workbook.close
 
-  workbook['firstcell'] = "new"
+One special feature of RobustExcelOle is that it enables reopening workbooks.
 
-For more details about reading and writing contents of cells and ranges see {README_ranges}[https://github.com/Thomas008/robust_excel_ole/blob/master/README_ranges.rdoc]
+  workbook.reopen
 
-Then we save the workbook.
+The workbook is now open again and ready for applying further operations, e.g.
 
+  workbook['firstcell'] = "another_value"
   workbook.save
+  workbook.close
 
-We can also save the workbook under a different name.
+RobustExcelOle allows unobtrusively reading and modifying workbooks, i.e. accessing workbooks without changing their "status". The status comprises whether the workbook is open or closed, saved or unsaved, read-only or writable, visible or invisible, whether the calculation mode is manual or automatic, and checking compatibility is done or not done (the Workbook object remembers its properties).
 
-  workbook.save_as('spec/data/new_workbook.xls')
+  Workbook.for_modifying('spec/data/workbook.xls') do |workbook|
+    # do something
+  end
 
-Finally we close the workbook.
+  Workbook.for_reading('spec/data/workbook.xls') do |workbook|
+    # do something
+  end
 
-  workbook.close
+=== More features when opening, modifying, saving and closing workbooks
 
-We could also have saved and closed the workbook in one step.
+We can open the workbook using a block, similar to, e.g., +File.open+. 
 
-  workbook.close(:if_unsaved => :save)
+  Workbook.open('spec/data/workbook.xls') do |workbook|
+    # do something
+  end
 
-For more details about saving and closing workbooks see
-{README_save_close}[https://github.com/Thomas008/robust_excel_ole/blob/master/README_save_close.rdoc]
+Once we have a workbook, we can set some options, e.g.
 
-One special feature of RobustExcelOle is that it enables reopening workbooks.
+  workbook.for_this_workbook(:visible => true, :read_only => false)
 
-  workbook.reopen
+We can also open the workbook and provide the options in one step, e.g.
+
+  workbook = Workbook.open('spec/data/workbook.xls', :visible => true)
+
+or, using abbreviations,
+
+  workbook = Workbook.open('spec/data/workbook.xls', :v => true)
+
+For more details about opening workbooks see {README_open}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_open.rdoc]
+ 
+We can do a simple save
+
+  workbook.save
+
+or save the workbook under a different name.
+
+  workbook.save_as('spec/data/new_workbook.xls')
+
+Finally we can save and close the workbook in one step.
+
+  workbook.close(:if_unsaved => :save)
+
+For more details about saving and closing workbooks see
+{README_save_close}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_save_close.rdoc]
 
-Technically, this feature is implemented in such way, that a Workbook object is a proxy of an Excel workbook. A Workbook object is defined by the full workbook name and the Excel instance in which it is opened. RobustExcelOle ensures identity transparency which means that the same Workbook objects refer to the same workbooks, and vice versa. 
 
 === Using Excel instances
 
-You can start a new Excel instance with
+We can start a new Excel instance with
 
   excel1 = Excel.create
 
@@ -110,7 +145,7 @@ or
 
   excel1 = Excel.new(:reuse => false)
 
-You can also have an Excel object by connecting to the already running Excel instance.
+We can also obtain an Excel object by connecting to the already running Excel instance.
 
   excel2 = Excel.current
 
@@ -130,17 +165,17 @@ Closing all Excel instances is done by
 
   Excel.close_all(:if_unsaved => :forget)
 
-For hard terminating all Excel processes you can use
+For hard terminating all Excel processes we can use
 
   Excel.kill_all
 
-For more details about creating Excel instances see README_excel[https://github.com/Thomas008/robust_excel_ole/blob/master/README_excel_rdoc]
+For more details about creating Excel instances see README_excel[https://github.com/Thomas008/robust_excel_ole/blob/master/README/README_excel_rdoc]
 
 === Opening workbooks in several Excel instances
 
 RobustExcelOle enables opening and processing workbooks in several Excel instances. Using more than one Excel process allows, e.g., running a script that operates in one Excel instance, while a user (or another script) modifies workbooks in another Excel instance. 
 
-For example, suppose you want to open a workbook.
+For example, suppose we want to open a workbook.
 
   workbook1 = Workbook.open('spec/data/workbook.xls')
 
@@ -162,41 +197,31 @@ If this Excel instance is damaged or closed, then options control whether the wo
 
   workbook1 = Workbook.open('spec/data/workbook.xls', :default => {:excel => :new})
 
-Without the option +:default+, the workbook is forced to be opened in the current, new or given Excel instance, no matter if and where it was opened before, e.g.
+Without the option +:default+, the workbook can be forced to be opened in the current, new or given Excel instance, no matter if and where it was opened before, e.g.
 
   workbook2 = Workbook.open('spec/data/workbook.xls', :excel => excel1)
 
-As a further feature, RobustExcelOle allows processing workbooks, while still supporting user's interactions: The commands enable to open, close, reopen, read, modify, write and save Excel files, without the need of the user's interaction, and even without the user noticing. Thus, while running a script containing RobustExcelOle commands, the user can open and process Excel files in any Excel instances at any time. RobustExcelOle manages the complex cases of conflicts that might occur such that the user does not need to interfere and the script can continue.
+As a further feature, RobustExcelOle allows processing workbooks, while still supporting user's interactions: The commands enable to open, close, reopen, read, modify, write and save Excel workbooks, without the need of the user's interaction, and even without the user noticing. Thus, while running a script containing RobustExcelOle commands, the user can open and process workbooks in any Excel instances at any time. RobustExcelOle manages the complex cases of conflicts that might occur such that the user does not need to interfere and the script can continue.
 
-For example, suppose you want to process a list of workbooks. RobustExcelOle allows to rapidly open, manipulate, close and save these workbooks. Now assume, the workbook "workbook.xls" is being processed, while the user has opened this workbook, has modified but not saved it yet. Excel would prompt a message and ask the user what to do. RobustExcelOle solves this conflict by using an option that states whether the changes of the user should be saved (accepted) or discarded before opening the workbook, e.g.
+For example, suppose we want to process a list of workbooks. RobustExcelOle allows to rapidly open, manipulate, close and save these workbooks. Now assume, the workbook "workbook.xls" is being processed, while the user has already opened this workbook, has modified but not saved it yet. Excel would prompt a message and ask the user what to do. RobustExcelOle solves this conflict by using an option that states whether the changes of the user should be saved (accepted) or discarded before opening the workbook, e.g.
 
   workbook = Workbook.open('workbook.xls', :if_unsaved => :accept)
 
-Similarly, if the user has opened a workbook that has the same name but a different path, the conflict is solved via an option.
+Similarly, if the user has opened a workbook that has the same name but a different path, the conflict can be solved via an option.
 
   workbook1 = Workbook.open('spec/data/workbook.xls')
   # do something
   workbook2 = Workbook.open('spec/data/more/workbook.xls', :if_obstructed => :forget)
 
-Finally, RobustExcelOle allows unobtrusively reading and modifying workbooks, i.e. accessing workbooks without changing their "status". The status comprises whether the workbook is open or closed, saved or unsaved, read-only or writable, visible or invisible, whether the calculation mode is manual or automatic, and checking compatibility is done or not done. 
-
-  Workbook.for_modifying('workbook.xls') do |book|
-    # do something
-  end
-
-  Workbook.for_reading('workbook.xls') do |book|
-    # do something
-  end
-
-For more details about opening and closing workbooks in Excel instances see {README_open}[https://github.com/Thomas008/robust_excel_ole/blob/master/README_open.rdoc]
+For more details about opening and closing workbooks in Excel instances see {README_open}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_open.rdoc]
 
-=== Processing worksheets
+=== Operating on worksheets
 
-Assime you have opened a workbook
+Assume we have opened a workbook
  
  workbook = Workbook.open('spec/data/workbook.xls')
 
-You access the first worksheet by
+We access the first worksheet by
 
   sheet = workbook.sheet(1)
 
@@ -208,14 +233,22 @@ or
   
   sheet = workbook.first_sheet
 
-You can read and change the worksheet name.
+We can read and change the worksheet name.
 
   sheet.name
   # => "Sheet1"
 
   sheet.name = "new_sheet"
 
-You can read the first three cells of the first row
+We can copy the first worksheet, name it and add it before the third worksheet.
+
+  workbook.add_or_copy_sheet(sheet, :as => "copied_name, :before => workbook.last_sheet)
+
+For more details about processing worksheets see {README_sheet}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_sheet.rdoc]
+
+=== Reading and writing ranges in worksheets
+
+We can read the first three cells of the first row
 
   sheet.row_range(1, 1..3).values   # => ["foo","workbook","sheet1"]
 
@@ -223,7 +256,7 @@ and the third column
 
   sheet.col_range(3).values   # => ["sheet1", 2.0, 4.0]
 
-You can read the first cell, using
+We can read the first cell, using
 
   sheet[1,1].value    # => "foo"
 
@@ -235,7 +268,7 @@ Then we modify it
 
   sheet[1,1] = "hello"
 
-You can get the value of a named range 
+We get the value of a named range 
 
   sheet["firstcell"]    # => "hello"
 
@@ -243,20 +276,21 @@ and set another value to that range.
 
   sheet["firstcell"] = "new_value"
 
-You can copy the first worksheet, name it and add it before the third worksheet.
+For more details about reading and writing contents of cells and ranges see {README_ranges}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_ranges.rdoc]
 
-  workbook.add_or_copy_sheet(sheet, :as => "copied_name, :before => workbook.last_sheet)
+=== Examples
+
+You can run the examples included in the directory +examples+, e.g.
 
-For more details about processing worksheets see {README_sheet}[https://github.com/Thomas008/robust_excel_ole/blob/master/README_sheet.rdoc]
+  ruby examples\open_save_close\example_unobtrusively.rb
 
-=== Development
+== Development
 
-For some details about developing RobustExcelOle see
-{README_development}[https://github.com/Thomas008/robust_excel_ole/blob/master/README_development.rdoc]
+This project RobustExcelOle is work in progress. We are happy to implement further features. So we invite you to send your pull requests. We then strive to realize them as soon as possible. If you have any feedback, or you find use cases that RobustExcelOle does not satisfy, please let us know.
 
-=== Want to do more things
+RobustExcelOle is being tested for Excel 2010. It can be used for any recent Excel Office version.
 
-If you want to do something that not provide a function, you can use win32ole methods.
+The tests of RobustExcelOle are optimised with help of the rcov tool. 
 
 == Support
 

data/{README_excel.rdoc → docs/README_excel.rdoc}

@@ -76,6 +76,8 @@ You can turn off and off DisplayAlerts in a block.
     # do something
   end
 
+Notice, that when the Excel instance is set to visible, its DisplayAlerts is set to true by default, if DisplayAlerts is not explicitely set to false.
+
 === Setting Calculation mode.
 
 You can set the calculation mode of an Excel instance to manual or automatic.

data/{README_open.rdoc → docs/README_open.rdoc}

@@ -107,6 +107,7 @@ If you want to open the workbook and make its window visible, then use
 
   book = Workbook.open('workbook.xls', :visible => true)
 
+Notice, that when the workbook is visible, the DisplayAlerts of the respective Excel instance is true, if not explicitely DisplayAlerts is set to false in this Excel instance.
 You can combine options, e.g. 
 
   Workbook.open('workbook.xls', :excel => :new, :visible => true, :default => {:excel => excel1})
@@ -139,13 +140,7 @@ A special feature of RobustExcelOle is that it allows to reopen workbooks after
 
 The closed workbook is now alive again, i.e. is open and responds to Excel methods.
 
-This feature is a result of providing identity transparence and storing the file name.
-
-=== The Workbook objects and transperence identity
-
-An Excel file (or workbook) is represented by a Workbook object. A Workbook object is defined by the full name of the workbook and the Excel instance in which it is opened. RobustExcelOle aims to ensure identity transperency.
-Identity transparence means that the same Workbook objects refer to the same Excel files, and vice versa.
-In other words, a Workbook objects is a proxy of an Excel file.
+Technically, this feature is implemented in such way, that a Workbook object is a proxy of an Excel workbook. A Workbook object is defined by the full workbook name and the Excel instance in which it is opened. RobustExcelOle ensures identity transparency which means that the same Workbook objects refer to the same workbooks, and vice versa.
 
 === Promoting a workbook to a Workbook object
 
@@ -153,22 +148,23 @@ A Workbook object can be created when giving an Excel workbook.
 
    book = Workbook.new(win32ole_workbook)
 
-
 === Unobtrusively modifying a workbook
 
 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, visible or invisible, calculation mode is automatic or manual, and checking compatibility is turned on or off. 
 
-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.  Moreover, an Excel instance can be given directly where to open the closed workbook.
-
 Options are the following:
 
-+: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
++:if_closed+:: +: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
                
-+:read_only+:: Open the workbook unobtrusively for reading only  (default: false)
-+:readonly_excel+::  if the workbook 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, otherwise open in a new excel instance
-+:keep_open+::          let the workbook open after unobtrusively opening (default: false)
++:read_only+:: Whether the workbook shall be forced to be open in ReadOnly mode (default: +false+)
++:writable+::  Whether changes in the workbook shall be saved (default: +true+)
+
++:rw_change_excel+::  Excel instance in which the workbook with the
+                      changed read-write permissions shall be opened  
+                      :current (default), :new or an Excel instance                   
+
++:keep_open+::       Whether the workbook shall be open after unobtrusively opening (default: false)
+
 
   Workbook.unobtrusively('workbook.xls') do |book|
     # some modification

data/{README_ranges.rdoc → docs/README_ranges.rdoc}

@@ -2,7 +2,7 @@
 
 == Reading and writing the contents of ranges and cells
 
-RobustExcelOle enables to read and write the contents of ranges and cells in Excel files. This can be done from a Sheet, a Book or an Excel object representing a Worksheet, Workbook, or Application object in VBA.
+RobustExcelOle enables to read and write the contents of ranges and cells in workbooks. This can be done from a Sheet, a Book or an Excel object representing a Worksheet, Workbook, or Application object in VBA.
 
 === Reading and writing the contents of a named range in a workbook.
 

data/examples/open_save_close/example_control_to_excel.rb

@@ -7,7 +7,7 @@ require "fileutils"
 
 include RobustExcelOle
 
-Excel.close_all
+Excel.kill_all
 begin
   dir = create_tmpdir
   file_name = dir + 'workbook.xls' 
@@ -19,7 +19,7 @@ begin
   sleep 1
   begin
     new_book = Book.open(file_name, :if_unsaved => :alert) # open another book with the same file name 
-  rescue ExcelUserCanceled => msg                          # if the user chooses not open the book,
+  rescue WorkbookREOError => 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
@@ -39,6 +39,6 @@ begin
   	new_book.close                                         # close the new book, if the user chose to open it
   end
 ensure                                                              
-  Excel.close_all                                       # close ALL workbooks, quit Excel application
+  Excel.kill_all                                       # close ALL workbooks, quit Excel application
   rm_tmp(dir)
 end