robust_excel_ole 1.1.3 → 1.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9bc4f05390e7e89a7d95a262e280e94dff090063
-  data.tar.gz: db6443cf724e5f58acbe8607ab427fc1734afa08
+  metadata.gz: 8c842707a42ecf41966021d1c4b46de412d598a5
+  data.tar.gz: 2ac4026904e8fab21e087bdeaae0b123d14d41cc
 SHA512:
-  metadata.gz: f789655b7ae560eecf54132d0470e2441b04d902b95c72c3fb165987e02ef7395235e4f0e3723519928a5df86897b6f6f7340adebb0dde9f66e7aeda493588ad
-  data.tar.gz: 7b4110169af5c687a5be28535b8c0359f95f4c30217df5d8d90f26e5a5c54dc28153bf4b8e0bfa9411961a44cc064118cbc681df68b95061a337b61efd247e27
+  metadata.gz: 93acf54dc229f58aa5e1cb5b1ad59f0d28fa77e513af12adc52e1bf5daaeae2920d3206637a196cc7dd78d2b40c5feb2bbfb2599e88d70ac273396dd5545bf9e
+  data.tar.gz: 468faa1ad3c10feeb8316fc9de2d827ba1be7444108af0c0f9cd0d7d89ba33538e87e9af5e9ae694a11ca25bef2b2ccafbd475880a753923417a011bc85baaa0

data/.gitignore

@@ -8,3 +8,4 @@ vendor/bundle
 doc/*
 *.sublime-workspace
 .yardoc
+TodoList.md

data/Changelog

@@ -1,7 +1,15 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## [1.1.3] - 2018-10-6
+## [1.1.4] - 2018-10-6
+
+### Added
+  - Excel#for_this_instance
+  - Excel#for_all_workbooks
+  - Book#for_this_workbooks
+  - Book#reopen : wirth options
+
+## [1.1.3] - 2018-13-5
 
 ## [1.1.2] - 2018-10-5
 

data/README.rdoc

@@ -4,7 +4,7 @@ This ruby gem automates reading, modifying, and writing Excel files. It is desig
 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 supports Excel 2010.
+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.
@@ -19,287 +19,240 @@ It implements a management system and keeps track of Excel files and Excel insta
 
 == Usage
 
+RobustExcelOle can be used either for scripts
+
   require 'robust_excel_ole'
   include RobustExcelOle
 
-or call the console 
-
-  reo.bat
-
-== Description  
-
-In the following, some features of RobustExcelOle are depicted.
-
-RobustExcelOle enables opening and processing Excel files (or 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 and make it visible.
-
-  book1 = Workbook.open('workbook.xls', :visible => true)
-
-Now we want to open another workbook in a different Excel instance.
-
-  book2 = Workbook.open('workbook2.xls', :force => {:excel => :new}, :visible => true)
-
-We can also create a third Excel instance and open another workbook in this instance.
-
-  excel1 = Excel.create
-  book3 = Workbook.open('workbook3.xls', :force => {:excel => excel1}, :visible => true)
-
-Another feature that RobustExcelOle povides is reopening workbooks after closing them.
-
-  book1.close
-  book1.reopen
-
-A workbook is opened by default in the Excel instance where it was open before most recently.
-
-   book1.close
-   book1 = Workbook.open('workbook.xls') 
-
-If this Excel instance is damaged or closed, then options control whether the workbook shall be opened in the current (active), a new or a given Excel instance.
+or as a console 
 
-  book1 = Workbook.open('workbook.xls', :default => {:excel => :new})
+  reo
 
-The workbook can also be forced to be opened in the current, new or given Excel instance, no matter if and where it was opened before, e.g.
+The call of the console will include RobustExcelOle for you.
 
-  book2 = Workbook.open('workbook.xls', :force => {:excel => excel1})
+The following examples can be used for both scripts and console. You can try them directly.
 
-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.
-
-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:
-
-  book = Workbook.open('workbook.xls', :if_unsaved => :accept)
+== Description  
 
-Similarly, if the user has opened a workbook that has the same name but a different path, the conflict is solved via an option.
+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. 
 
-  book1 = Workbook.open('path1/workbook.xls')
-    ...
-  book2 = Workbook.open('workbook.xls', :if_obstructed => :forget)
+First we open a workbook.
 
-There are twelve options that control opening workbooks. 
+  workbook = Workbook.open 'spec/data/workbook.xls'
 
-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. 
+We can also open the workbook using a block, similar to, e.g., +File.open+. 
 
-  Workbook.for_modifying('workbook.xls') do |book|
-    # do something
-  end
-
-  Workbook.for_reading('workbook.xls') do |book|
+  Workbook.open('spec/data/workbook.xls') do |workbook|
     # do something
   end
 
-=== The Workbook objects and identity transparency
+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.
 
-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 transparency.
-Identity transparency 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.
+For example, we can make the workbook visible, using
 
-Here are some more details about opening, closing, reading, writing and modifying Excel files.
+  workbook.visible = true
 
-=== Opening and closing workbooks
-
-Let's have a look at an example. Suppose, we want to open a workbook.
-
-  book = Workbook.open('workbook.xls')
-
-We could do this in a block as well. The semantics is similar to, e.g.,  +File.open+.
-
-  Workbook.open('workbook.xls') do |book|
-    # do something with book
-  end
+or
 
-Now let's make the workbook visible.
+  workbook.for_this_workbook(:visible => true)
 
-  book.visible = true
+You can also open a workbook and make it visible in one step.
 
-We can do this in one step as well.
+  workbook = Workbook.open('spec/data/workbook.xls', :visible => true)
 
-  book = Workbook.open('workbook.xls', :visible => true)
+or
 
-Now we want to open another workbook in a new Excel instance.
+  workbook = Workbook.open('spec/data/workbook.xls', :v => true)
 
-  book2 = Workbook.open('another_workbook.xls', :force => {:excel => :new}, :visible => true)
+Then we read the value of a cell.
 
-Then we open a third workbook in the second Excel instance. 
+  value = workbook['firstcell']
+  # => "foo"
 
-  book3 = Workbook.open('different_workbook.xls', :force => {:excel => book2.excel})
+Now we write a new value in this cell.
 
-We close the second workbook.
+  workbook['firstcell'] = "new"
 
-  book2.close
+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]
 
-Reopening this workbook is done by
+Then we save the workbook.
 
-  book2.reopen
+  workbook.save
 
-=== Reading and modifying workbooks
+We can also save the workbook under a different name.
 
-We can get the value of a named range.
+  workbook.save_as('spec/data/new_workbook.xls')
 
-  book2["new"]   # => foo
+Finally we close the workbook.
 
-or
+  workbook.close
 
-  book2.nameval("new")  # => "foo"
+We could also have saved and closed the workbook in one step.
 
-Now we assign a new value to this range.
+  workbook.close(:if_unsaved => :save)
 
-  book2["new"] = "bar"
+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]
 
-or, with coloring the cell,
+One special feature of RobustExcelOle is that it enables reopening workbooks.
 
-  book2.set_nameval("new", "bar", :color => 4)
+  workbook.reopen
 
-Then we access the first worksheet by
+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. 
 
-  sheet1 = book2.sheet(1)
+=== Using Excel instances
 
-or 
+You can start a new Excel instance with
 
-  sheet1 = book2.sheet('Sheet1')
+  excel1 = Excel.create
 
 or
-  
-  sheet1 = book2.first_sheet
 
-We can read the first three cells of the first row
+  excel1 = Excel.new(:reuse => false)
 
-  sheet1.row_range(1, 1..3).values   # => ["foo","workbook","sheet1"]
+You can also have an Excel object by connecting to the already running Excel instance.
 
-and the third column
+  excel2 = Excel.current
 
-  sheet1.col_range(3).values   # => ["sheet1", 2.0, 4.0]
+or 
 
-Then we read first cell
+  excel2 = Excel.new(:reuse => true)  
 
-  sheet1[1,1].value    # => "foo"
+We close the Excel instance using
 
-or
+  excel1.close
 
-  sheet1.row_range(1)[0].value    # => "foo"
+Closed Excel instances can be reopened.
 
-Then we modify it
+  excel1.recreate(:reopen_workbooks => true, :visible => true)
 
-  sheet1[1,1] = "hello"
+Closing all Excel instances is done by
 
-We get the value of a range
+  Excel.close_all(:if_unsaved => :forget)
 
-  sheet1.nameval("firstcell")    # => "hello"
+For hard terminating all Excel processes you can use
 
-and set the value, while coloring the cell
+  Excel.kill_all
 
-  sheet1.set_nameval("firstcell", "foo", :color => 4)
+For more details about creating Excel instances see README_excel[https://github.com/Thomas008/robust_excel_ole/blob/master/README_excel_rdoc]
 
-We get the value of a range of a locally defined name.
+=== Opening workbooks in several Excel instances
 
-  sheet1.rangeval("firstcell")     # => "foo"
+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. 
 
-or
+For example, suppose you want to open a workbook.
 
-  sheet1.rangeval("A1")    # => "foo"
+  workbook1 = Workbook.open('spec/data/workbook.xls')
 
-Then we set the value of this range.
+Now we want to open another workbook in a different Excel instance.
 
-  sheet1.set_rangeval("firstcell", "bar")
+  workbook2 = Workbook.open('spec/data/different_workbook.xls', :excel => :new)
 
-We can copy the first worksheet, name it and add it before the third worksheet.
+We can also create a third Excel instance and open another workbook in this instance.
 
-  book2.add_or_copy_sheet(sheet1, :as => "copied_name, :before => book2.last_sheet)
+  excel1 = Excel.create
+  book3 = Workbook.open('spec/data/another_workbook.xls', :excel => excel1)
 
-=== Saving (writing) workbooks
+A workbook is opened by default in the Excel instance where it was open before most recently.
 
-Simple save is done by
+   book1.close
+   book1 = Workbook.open('spec/data/workbook.xls') 
 
-  book2.save
+If this Excel instance is damaged or closed, then options control whether the workbook shall be opened in the current (active), a new or a given Excel instance.
 
-We could save the workbook under a different name, and overwrite, if a file with the same name exists.
+  workbook1 = Workbook.open('spec/data/workbook.xls', :default => {:excel => :new})
 
-  book2.save_as('example_workbook.xls', :if_exists => :overwrite)
+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.
 
-Then we close this workbook.
+  workbook2 = Workbook.open('spec/data/workbook.xls', :excel => excel1)
 
-  book2.close
+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.
 
-Simple saving and closing can be also done in one step by
+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.
 
-  book2.close(:if_unsaved => :save)
+  workbook = Workbook.open('workbook.xls', :if_unsaved => :accept)
 
-When you want discolor all cells that have been colored when modifying them, then use
-  
-  book2.save(:discoloring => true)
+Similarly, if the user has opened a workbook that has the same name but a different path, the conflict is solved via an option.
 
-or
+  workbook1 = Workbook.open('spec/data/workbook.xls')
+  # do something
+  workbook2 = Workbook.open('spec/data/more/workbook.xls', :if_obstructed => :forget)
 
-  book2.save_as('example_workbook.xls', :if_exists => :overwrite, :discoloring => true)
+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. 
 
-=== Operating on Excel instances.
+  Workbook.for_modifying('workbook.xls') do |book|
+    # do something
+  end
 
-Suppose we want to create an Excel object by connecting to the already running Excel instance.
+  Workbook.for_reading('workbook.xls') do |book|
+    # do something
+  end
 
-  excel1 = Excel.current
+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]
 
-or 
+=== Processing worksheets
 
-  excel1 = Excel.new(:reuse => true)  
+Assime you have opened a workbook
+ 
+ workbook = Workbook.open('spec/data/workbook.xls')
 
-Now we want to start a new, visible Excel instance.
+You access the first worksheet by
 
-  excel2 = Excel.create(:visible => true)
+  sheet = workbook.sheet(1)
 
 or 
 
-  excel2 = Excel.new(:reuse => false, :visible => true)  
+  sheet = workbook.sheet('Sheet1')
 
-We open a workbook in this Excel instance.
+or
+  
+  sheet = workbook.first_sheet
 
-  book4 = Workbook.open('more_data/workbook', {:force => {:excel => excel2}})
+You can read and change the worksheet name.
 
-We close the Excel instance by
+  sheet.name
+  # => "Sheet1"
 
-  excel1.close
+  sheet.name = "new_sheet"
 
-Closed Excel instances can be reopened.
+You can read the first three cells of the first row
 
-  excel1.recreate(:reopen_workbooks => true, :visible => true)
+  sheet.row_range(1, 1..3).values   # => ["foo","workbook","sheet1"]
 
-We can get the value of a range in an Excel instance by
+and the third column
 
-  excel2["firstcell"] => "foo"
-  
-or
+  sheet.col_range(3).values   # => ["sheet1", 2.0, 4.0]
 
-  excel2.nameval("firstcell") = "foo"
+You can read the first cell, using
 
-and set the value of this range by using
+  sheet[1,1].value    # => "foo"
 
-  excel2["firstcell"] = "bar"
+or
 
-or, with coloring the cell,
+  sheet.row_range(1)[0].value    # => "foo"
 
-  excel2.set_nameval("firstcell", "bar", :color => 4)
+Then we modify it
 
-We get and set the value of a range with a locally defined named by
+  sheet[1,1] = "hello"
 
-  excel2.rangeval("firstcell")
+You can get the value of a named range 
 
-and set its value by
+  sheet["firstcell"]    # => "hello"
 
-  excel2.set_rangeval("firstcell, "bar")
+and set another value to that range.
 
-Closing all Excel instances is done by
+  sheet["firstcell"] = "new_value"
 
-  Excel.close_all(:if_unsaved => :forget)
+You can copy the first worksheet, name it and add it before the third worksheet.
 
-Hard terminating all Excel processes is done by
+  workbook.add_or_copy_sheet(sheet, :as => "copied_name, :before => workbook.last_sheet)
 
-  Excel.kill_all
+For more details about processing worksheets see {README_sheet}[https://github.com/Thomas008/robust_excel_ole/blob/master/README_sheet.rdoc]
 
 === Development
 
-The tests of RobustExcelOle are optimised with help of the rcov tool.  
-
-=== More details
-
-{README_detail.rdoc}[https://github.com/Thomas008/robust_excel_ole/blob/master/README_detail.rdoc]
+For some details about developing RobustExcelOle see
+{README_development}[https://github.com/Thomas008/robust_excel_ole/blob/master/README_development.rdoc]
 
 === Want to do more things