robust_excel_ole 1.30 → 1.35

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 468109a0884d48ed77c70d9681d0067453aadfbd7294c6b152fb6457141bb98d
-  data.tar.gz: 2527cdd343eefb7325c077204203e1893d8e32f00830a8a6591669aba7ad43ec
+  metadata.gz: 80365f36774968b6f55052177932c00dbe57b7fb3bee76762474a0b21637440b
+  data.tar.gz: a352fd270609529688869edf581bc2d1c20eee9c0b9b8ec61198dcfafc82fd2b
 SHA512:
-  metadata.gz: 5637d87926eef9515335fb075add5cf4810cf97229c762f2b182fbdad42cae99f128c6a2ee253acbf29362c49005d579944e283e875aff4785df5220a6f0bff6
-  data.tar.gz: 59f015190d12c0a0b3c7e8016e6dd81da74ae5b760e166d0044a5b04dab5d0fb0b8fa295d13f66a30861a71867c921c2352119957b0543caeb467ecd881b3223
+  metadata.gz: 5246534fa3c3767e9fe4c8081d37aac6d54070238b6008d1ea289792cc3fa2bbf3b855b36eab4959b16103af6e5f8a83d7d326dc82923ff25c82ab8b9f61ae1e
+  data.tar.gz: '070856a21a1786fa7f9fd3de02edaa6bf661e936329c02afb78e9d5ddbd8623b95a49ec1f22be64e4d205c47e4c7e7c2bf964a00d2928a2d4dbe4a6640bf3a40'

data/Changelog

@@ -1,6 +1,32 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+## [1.33] 2021-01-06
+
+## [1.32] 2021-23-04
+
+### Added
+  - Excel#each  
+  - ListObject#each, value, rows_number, position, ==
+  - ListObject#[] extended with options
+  - ListRow#to_h, to_a, values=, keys_values, ==  
+  - RangeOwners#names
+  - Worksheet#each_cell
+
+### Changed  
+  - Worksheet#[]: returning range values given address or defined name (instead of returning a cell when giving address)
+  - Worksheet#each traversing row values instead of cells
+  - Excel#excels_number renamed to #instance_count
+  - Excel#known_excels_number renamed to #known_instance_count
+  - Excel#known_excel_instance renamed to #known_running_instance
+  - Excel#known_excel_instances renamed to #known_running_instances
+  - RangeOwners#rename_range renamed to #rename_name
+  
+## [1.31] 2021-14-01
+
+### Added
+  - Worksheet#table
+
 ## [1.30] 2020-18-11
 
 ## [1.29] 2020-05-11
@@ -187,7 +213,7 @@ All notable changes to this project will be documented in this file.
 ## [1.1.4] - 2018-10-6
 
 ### Added
-  - Book#open: for the options: simplifiaction: :force can be left out
+  - Book#open: for the options: simplifiction: :force can be left out
   - Excel#for_this_instance
   - Excel#for_all_workbooks
   - Book#for_this_workbooks

data/README.rdoc

@@ -105,7 +105,7 @@ Then we'll save the workbook.
 
   workbook.save
 
-=== More features when opening, modifying, creating, saving and closing workbooks
+=== Unobtrusively opening workbooks
 
 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.
 
@@ -121,9 +121,11 @@ RobustExcelOle allows unobtrusively reading and modifying workbooks, i.e. access
     # do something
   end
 
-We can also create a new, empty workbook. 
+=== More featrues about creating, opening, saving and closing workbooks 
 
-  Workbook.create('spec/data/new_workbook.xls', :visible => true)
+We can create a new, empty workbook. 
+
+  Workbook.create('spec/data/new_workbook.xls', visible: true)
 
 Moreover, we can open the workbook using a block, similar to, e.g., +File.open+. 
 
@@ -133,15 +135,15 @@ Moreover, we can open the workbook using a block, similar to, e.g., +File.open+.
 
 Once we have a workbook, we can set some options, e.g.
 
-  workbook.for_this_workbook(:visible => true, :read_only => false)
+  workbook.for_this_workbook(visible: true, read_only: false)
 
 We can also open the workbook and provide the options in one step, e.g.
 
-  workbook = Workbook.open('spec/data/workbook.xls', :visible => true)
+  workbook = Workbook.open('spec/data/workbook.xls', visible: true)
 
 or, using abbreviations,
 
-  workbook = Workbook.open('spec/data/workbook.xls', :v => true)
+  workbook = Workbook.open('spec/data/workbook.xls', v: true)
 
 Note that +Workbook.open+ can also connect to workbooks which were not opened via RobustExcelOle (but had been opened before by some user).
 
@@ -157,11 +159,11 @@ or save the workbook under a different name.
 
 Finally we can close the workbook
 
-  workbook.save
+  workbook.close
 
 or save and close the workbook in one step.
 
-  workbook.close(:if_unsaved => :save)
+  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]
@@ -175,7 +177,7 @@ We can start a new Excel instance with
 
 or
 
-  excel1 = Excel.new(:reuse => false)
+  excel1 = Excel.new(reuse: false)
 
 We can also obtain an Excel object by connecting to the already running Excel instance.
 
@@ -183,19 +185,15 @@ We can also obtain an Excel object by connecting to the already running Excel in
 
 or 
 
-  excel2 = Excel.new(:reuse => true)  
+  excel2 = Excel.new(reuse: true)  
 
 We close the Excel instance using
 
   excel1.close
 
-Closed Excel instances can be reopened.
-
-  excel1.recreate(:reopen_workbooks => true, :visible => true)
-
 Closing all Excel instances is done by
 
-  Excel.close_all(:if_unsaved => :forget)
+  Excel.close_all(if_unsaved: :forget)
 
 For hard terminating all Excel processes we can use
 
@@ -214,39 +212,34 @@ For example, suppose we want to open a workbook.
 
 Now we want to open another workbook in a different Excel instance.
 
-  workbook2 = Workbook.open('spec/data/different_workbook.xls', :excel => :new)
-
-We can also create a third Excel instance and open another workbook in this instance.
-
-  excel1 = Excel.create
-  workbook3 = Workbook.open('spec/data/another_workbook.xls', :excel => excel1)
+  workbook2 = Workbook.open('spec/data/different_workbook.xls', excel: :new)
 
 A workbook is opened by default in the Excel instance where it was open before most recently.
 
    workbook1.close
    workbook1 = Workbook.open('spec/data/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.
+If the 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.
 
-  workbook1 = Workbook.open('spec/data/workbook.xls', :default => {:excel => :new})
+  workbook1 = Workbook.open('spec/data/workbook.xls', default: {excel: new})
 
 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)
+  workbook2 = Workbook.open('spec/data/workbook.xls', excel: new)
 
 === Managing conflicts with unsaved and blocking workbooks
 
-RobustExcelOle enables 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.
+RobustExcelOle enables processing workbooks, while 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 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 (forgotten) before opening the workbook, e.g.
 
-  workbook = Workbook.open('workbook.xls', :if_unsaved => :accept)
+  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 can be solved via an option.
 
   workbook1 = Workbook.open('spec/data/workbook.xls')
   # do something
-  workbook2 = Workbook.open('spec/data/more/workbook.xls', :if_blocked => :forget)
+  workbook2 = Workbook.open('spec/data/more/workbook.xls', if_blocked: :forget)
 
 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]
 
@@ -260,14 +253,6 @@ We access the first worksheet by
 
   worksheet = workbook.sheet(1)
 
-or 
-
-  worksheet = workbook.sheet('Sheet1')
-
-or
-  
-  worksheet = workbook.first_sheet
-
 We can read and change the worksheet name.
 
   worksheet.name
@@ -277,7 +262,7 @@ We can read and change the worksheet name.
 
 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)
+  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]
 
@@ -287,62 +272,77 @@ We can define a rectangular range by providing the top left and the bottum down
 
   worksheet.range([1..3,1..4])
 
-We can read the first three cells of the first row
+We can read and modify the first cell, e.g.
 
-  worksheet.row_range(1, 1..3).values   # => ["foo","workbook","sheet1"]
+  worksheet[1,1]    
+  # => "foo"
+  worksheet[1,1] = "hello"
+
+We get the value of a named range 
 
-and the third column
+  worksheet["firstcell"]    # => "hello"
 
-  worksheet.col_range(3).values   # => ["sheet1", 2.0, 4.0]
+and set another value to that range.
 
-We can read the first cell, using
+  worksheet["firstcell"] = "new_value"
 
-  worksheet[1,1].value    # => "foo"
+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]
 
-or
+=== List Objects (Tables)
 
-  worksheet.row_range(1)[0].value    # => "foo"
+We can define a list object (or table) from scratch
 
-Then we modify it.
+  table = ListObject.new(worksheet, "table 1", [1,1], 3, ["Person","AmountSales"])
 
-  worksheet[1,1] = "hello"
+or get a given list object in a worksheet given its table number or name.
 
-We get the value of a named range 
+  table = worksheet.table(1) 
 
-  worksheet["firstcell"]    # => "hello"
+A list row can be accessed by providing either the row number or a key, i.e. hash of column name - value pairs, e.g.
 
-and set another value to that range.
+  row1 = table[1]
 
-  worksheet["firstcell"] = "new_value"
+  row1 = table[{"Number": 1, "Person": "John"}]
 
-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]
+You can get all or a maximal number of list rows matching the key.
 
+  rows = table[{"Number": 1}, limit: nil]
+  rows = table[{"Number": 1}, limit: 2]
 
-=== More features
+Now we can read and set the value of a cell of the table with help of methods that are underscored variants of the column names, e.g.
 
-1. The method +General.change_current_binding+ allows to change the value of self within the current binding, while preserving the local variables, without starting another repl. Assume, +object+ shall be the self, then you would put
+  row1.person = "John"
 
-  General.change_current_binding(object)
+or with help of the column name
 
-Without this method, the ruby shell 'pry' allows to change the value of 'self' in the console as well, e.g. 
+  row1["Person"] = "John"
 
-  object.pry
+We can also read all values in a row.
 
-or
+  table[1].to_a
+  # => ["John", 40]
 
-  cd object
+  table[1].to_h
+  # => {"Person": "John", "AmountSales": 40}
 
-However, this command also starts another pry repl (with another binding). Moreover, local variables in the previous binding are forgotten.
+For more details about using and processing list objects see {README_listobjects}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_listobjects.rdoc]
 
+=== More features
 
-2. The class Win32Ole is being extended such that RobustExcelOle methods can be applied to Win32Ole objects. As mentioned above, the RobustExcelOle objects are wrapper of corresponding WIN32OLE objects. With help of +update_to_reo+ the RobustExcelOle objects and their wrapped Win32Ole objects are interchangeable. One example would be
+The class WIN32OLE is being extended such that RobustExcelOle methods can be applied to WIN32OLE objects. As mentioned above, the RobustExcelOle objects are wrapper of corresponding WIN32OLE objects. So now the RobustExcelOle objects and their wrapped WIN32OLE objects are interchangeable. One example would be
 
   range.ole_range.copy([4,3])
 
-Likewise it is possible to convert ("type-lift") Win32Ole objects into the corresponding RobustExcelOle object, using General.to_reo.
+Likewise it is possible to convert ("type-lift") WIN32OLE objects into the corresponding RobustExcelOle object, using the method +to_reo+. It is a refinement of the class WIN32OLE. So you can write
+
+  using ToReoRefinement
 
   range = sheet.Names.Item("firstcell").to_reo
 
+=== Design issues
+
+We don't consider active worksheets or workbooks in our implementation, because this has been proven to be very error-prone.
+
 === Examples
 
 You can run the examples included in the directory +examples+, e.g.

data/benchmarking/creek_example.rb

@@ -10,7 +10,7 @@ start_time = Time.now
 workbook = Creek::Book.new './sample_excel_files/xlsx_500_rows.xlsx'
 
 worksheets = workbook.sheets
-puts "Found #{worksheets.count} worksheets"
+puts "Found #{worksheets.size} worksheets"
 
 worksheets.each do |worksheet|
   puts "Reading: #{worksheet.name}"

data/benchmarking/reo_example.rb

@@ -1,4 +1,4 @@
-require File.join(File.dirname(__FILE__), '../lib/robust_excel_ole')
+require_relative '../lib/robust_excel_ole'
 
 start_time = Time.now 
 

data/benchmarking/reo_example1.rb

@@ -1,5 +1,5 @@
 #require 'robust_excel_ole'
-require File.join(File.dirname(__FILE__), '../lib/robust_excel_ole')
+require_relative '../lib/robust_excel_ole'
 
 start_time = Time.now 
 

data/benchmarking/reo_example2.rb

@@ -1,4 +1,4 @@
-require File.join(File.dirname(__FILE__), '../lib/robust_excel_ole')
+require_relative '../lib/robust_excel_ole'
 
 start_time = Time.now 
 

data/benchmarking/roo_example.rb

@@ -9,7 +9,7 @@ start_time = Time.now
 workbook = Roo::Spreadsheet.open './sample_excel_files/xlsx_500_rows.xlsx'
 
 worksheets = workbook.sheets
-puts "Found #{worksheets.count} worksheets"
+puts "Found #{worksheets.size} worksheets"
 
 worksheets.each do |worksheet|
   puts "Reading: #{worksheet}"

data/benchmarking/simple_xlsx_reader_example.rb

@@ -10,7 +10,7 @@ start_time = Time.now
 workbook = SimpleXlsxReader.open './sample_excel_files/xlsx_500_rows.xlsx'
 
 worksheets = workbook.sheets
-puts "Found #{worksheets.count} worksheets"
+puts "Found #{worksheets.size} worksheets"
 
 worksheets.each do |worksheet|
   puts "Reading: #{worksheet.name}"

data/benchmarking/spreadsheet_example.rb

@@ -11,7 +11,7 @@ start_time = Time.now
 workbook = Spreadsheet.open './sample_excel_files/xls_25000_rows.xls'
 
 worksheets = workbook.worksheets
-puts "Found #{worksheets.count} worksheets"
+puts "Found #{worksheets.size} worksheets"
 
 
 worksheets.each do |worksheet|

data/docs/README_excel.rdoc

@@ -12,7 +12,7 @@ You can create a new Excel instance by
 
 or 
 
-  excel1 = Excel.new(:reuse => false)  
+  excel1 = Excel.new(reuse: false)  
 
 In case you want to reuse an already running Excel instance, write
 
@@ -20,7 +20,7 @@ In case you want to reuse an already running Excel instance, write
 
 or 
 
-  excel2 = Excel.new(:reuse => true)  
+  excel2 = Excel.new(reuse: true)  
 
 Options of the methods +create+ and +new+ are +:reuse+ (+true+, +false+), +:visible+ (+true+, +false+), +:displayalerts+ (+true+, +false+, +:if_visible+), +:calculation+ (+:manual+, +:automatic+, +nil+) and +:screenupdating+ (+true+, +false+).
 
@@ -28,7 +28,7 @@ The option +:calculation+ specifies, whether the calculation mode is being force
 
 You can also type-lift an Excel instance represented as WIN32OLE object to an Excel object.
 
-  excel = Excel.new(win32ole_object, :visible => true)
+  excel = Excel.new(win32ole_object, visible: true)
 
 Once you have got an Excel object, you can apply all VBA methods that you would apply to a VBA Application object
 (see https://docs.microsoft.com/en-us/office/vba/api/excel.application(object)#methods).
@@ -40,17 +40,17 @@ You can set all options in a given Excel instance
 
   excel = Excel.current
 
-  excel.for_this_instance(:visible => true, :displayalerts => true, :calculation => :manual)
+  excel.set_options(visible: true, displayalerts: true, calculation: :manual)
 
 === Making an Excel visible or invisible
 
 You can create a new Excel instance and make it visible.
 
-  excel1 = Excel.create(:visible => true)
+  excel1 = Excel.create(visible: true)
 
 or
 
-  excel1 = Excel.new(:reuse => false, :visible => true)  
+  excel1 = Excel.new(reuse: false, visible: true)  
 
 or 
 
@@ -62,7 +62,7 @@ or
 
 You can enable DisplayAlerts with, e.g. 
 
-  excel1 = Excel.new(:reuse => true, :displayalerts => true)
+  excel1 = Excel.new(reuse: true, displayalerts: true)
 
 or 
 
@@ -99,30 +99,22 @@ You can do it in a block:
 
 You can set options for all workbooks of an Excel instance.
 
-  excel.for_all_workooks(:visible => true, :read_only => true)
+  excel.each_workook(visible: true, read_only: true)
 
 
-=== Showing and traversing through all workbooks
+=== Showing and traversing all workbooks
 
-You can yield an array of all Workbook objects of an Excel instance.
+The method +each+ provides an enumerator traversing all workbook objects. You can yield an array of all Workbook objects of an Excel instance, by applying +to_a+ or
 
   excel.workbooks
 
-You can access all Workbook objects by using the methods Excel#each_workbook and Excel#each_workbook_with_index. Here are some examples:
+You can access all Workbook objects supplying options by using the methods Excel#each_workbook and Excel#each_workbook_with_index. Here are some examples:
   
-  excel.each_workbook {|w| puts w.filename}
+  excel.each_workbook(displayalerts: true) {|w| puts w.filename}
 
 and
 
-  excel.each_workbook.with_index {|w,i| puts w,i }
-
-With help of these methods you can also supply options, e.g. without a block,
-
-  excel.each_workbook(:visible => true) 
-
-or, with a block,
-
-  excel.each_workbook(:visible => true) {|w| puts w}
+  excel.each_workbook.with_index(displayalerts: true) {|w,i| puts w,i }
 
 === Accessing the active workbook
 
@@ -143,7 +135,7 @@ The method +close has the option +:if_unsaved+ with the values +:raise+, +:save+
 
 For example, if you want to close an Excel instance and save unsaved workbooks, use
 
-  excel.close(:if_unsaved => :save)
+  excel.close(if_unsaved: :save)
 
 === Recreating an Excel instance    
 
@@ -154,7 +146,7 @@ Closed Excel instances can also be reopened. This includes reopening all workboo
 
 The options are +:reopen_workbooks+, +:visible+ and +:displayalerts+.
 
-  excel.recreate(:reopen_workbooks => true, :visible => true, :displayalerts => true)
+  excel.recreate(reopen_workbooks: true, visible: true, displayalerts: true)
 
 === Providing Excel instances
 
@@ -168,7 +160,7 @@ Providing all Excel instances (opened via RobustExcelOle) as objects of the clas
 
 This method has the option +:if_unsaved+ as described above. For example, if you want to close all Excel instances containing saved workbooks and raise an error for Excel instances with unsaved workbooks, use
 
-  Excel.close_all(:if_unsaved => :raise)   
+  Excel.close_all(if_unsaved: :raise)   
 
 === Terminating all Excel processes