robust_excel_ole 1.31 → 1.32

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 304ee26bf15359eec5e54ac846203b60f3d7419e54779ced816182f76f6e9b46
-  data.tar.gz: 0ea8a4d763d10b286cd29610261b815ca51308cb364483935c5c396fa31e2c67
+  metadata.gz: f56e6aaeeeec6c073cc4f871ea99185428523959c420e1165d199792979074c5
+  data.tar.gz: 79dd7f6ea160e0045592a3dd8ae31a5b8a162c71b6986dcbcef157eba54c93b4
 SHA512:
-  metadata.gz: ae94a7357c87e0069e15e279a0eb420df939840192fc2e674f8e3c1890bebdaa7c49d37e0d8a888939f8009109fc7fabf0105e7b76f6b75f168431cb58d2e0e1
-  data.tar.gz: 450ebbad0840bd557c652cc2fa9027dee4a45114a6d3b8ea0065fd5120e9b916ad26ad63a1f97088bb148f1dc07cff7fd9cdf8c9b956e6a0ee2295be4434dec2
+  metadata.gz: 894959ff3e8c48c8413bbb137013cf8ad7612bb991292f1461b1df9b3371d15c16132ecf0df0dbf78403171381064cfb43d9400604bc2155214f8aa2a514ea7c
+  data.tar.gz: 508b37f27ef7c0e554b565f21263386e1b180cb5269f6a843b2da927eaa3f6eebe5a111a362d5dc96de4726a1c3648673b062b02589739eb7e5ff2a0bb7f59cc

data/Changelog

@@ -1,6 +1,25 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+## [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
@@ -192,7 +211,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

@@ -1,3 +1,29 @@
+= News
+
+== New Interface of #[]
+
+Worksheet#[] now returns a value instead of a range, e.g.
+
+  worksheet[1,1]
+  # => "foo"
+
+Transformation: To yield the range, write range() instead of (). For example,
+
+  worksheet.range(1,1)
+
+ or
+
+  worksheet.range([1,1])
+
+This returns the range of cell with address 1,1.
+
+With this new interface, we want to be compatible with the standard syntax of other known Excel libraries, e.g. +spreadsheet+ or +axlsx+.
+
+== Using own WIN32OLE objects
+
+If you use WIN32OLE objects and define your own methods, please use upper-case method names. 
+The reason is that we extend the class WIN32OLE such that RobustExcelOle methods can be applied to WIN32OLE objects, such the RobustExcelOle objects and their wrapped WIN32OLE objects are interchangeable. We want to develop a refinement such that the name space is not being desturbed.
+
 = RobustExcelOle
 
 RobustExcelOle helps controlling Excel. 
@@ -123,7 +149,7 @@ RobustExcelOle allows unobtrusively reading and modifying workbooks, i.e. access
 
 We can also create a new, empty workbook. 
 
-  Workbook.create('spec/data/new_workbook.xls', :visible => true)
+  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 +159,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).
 
@@ -161,7 +187,7 @@ Finally we can close the workbook
 
 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 +201,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,7 +209,7 @@ 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
 
@@ -191,11 +217,11 @@ We close the Excel instance using
 
 Closed Excel instances can be reopened.
 
-  excel1.recreate(:reopen_workbooks => true, :visible => true)
+  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,12 +240,12 @@ 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)
+  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)
+  workbook3 = Workbook.open('spec/data/another_workbook.xls', excel: excel1)
 
 A workbook is opened by default in the Excel instance where it was open before most recently.
 
@@ -228,11 +254,11 @@ A workbook is opened by default in the Excel instance where it was open before m
 
 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.
 
-  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: excel1)
 
 === Managing conflicts with unsaved and blocking workbooks
 
@@ -240,13 +266,13 @@ RobustExcelOle enables processing workbooks, while still supporting user's inter
 
 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]
 
@@ -277,7 +303,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]
 
@@ -297,7 +323,7 @@ and the third column
 
 We can read the first cell, using
 
-  worksheet[1,1].value    # => "foo"
+  worksheet[1,1].    # => "foo"
 
 or
 
@@ -318,6 +344,76 @@ and set another value to that range.
 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]
 
 
+=== List Objects (Tables)
+
+We can define a list object (or table) from scratch
+
+  table = ListObject.new(worksheet, "table 1", [1,1], 3, ["Person","AmountSales"])
+
+or get a given list object in a worksheet given its table number or name.
+
+  table = worksheet.table(1) 
+
+or
+
+  table = worksheet.table("table1")
+
+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.
+
+  row1 = table[1]
+
+  row1 = table[{"Number": 1, "Person": "John"}]
+
+You can get all or a maximal number of list rows matching the key.
+
+  rows = table[{"Number": 1}, limit: 2]
+  rows = table[{"Number": 1}, limit: nil]
+
+Now we can set value of a cell of the table with help of methods that are equal to or are underscored variants of the column names, e.g.
+
+  row1.person = "John"
+
+or
+
+  row1["Person"] = "John"
+
+Similarly you can get the values. We can also read all values in a row.
+
+  table[1].to_a
+  # => ["John", 40]
+
+  table[1].to_h
+  # => {"Person": "John", "AmountSales": 40}
+
+We can set the values in a whole row.
+
+  table[1].values = ["Herber", 80]
+
+Similarly, we can read and set the values in a whole column, e.g.
+
+  table.column_values("Person")
+  # => ["John", "Peter"]
+
+and 
+
+  table.set_column_values(1, ["Herbert","Paul"])
+
+We can add and delete rows and columns, supplying optionally their name, the position and contents. 
+
+  table.add_column("column_name", 3, ["John", "Paul"])
+  table.add_row(3, ["John", 40, 2, 2004])
+
+  table.delete_column_values("column_name")
+  table[2].delete_values
+
+ Finally we can delete empty rows and columns.
+
+  table.delete_empty_rows
+  table.delete_empty_columns
+
+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
 
 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
@@ -335,7 +431,7 @@ or
 However, this command also starts another pry repl (with another binding). Moreover, local variables in the previous binding are forgotten.
 
 
-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. So the RobustExcelOle objects and their wrapped Win32Ole objects are interchangeable. One example would be
+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. So the RobustExcelOle objects and their wrapped WIN32OLE objects are interchangeable. One example would be
 
   range.ole_range.copy([4,3])
 
@@ -345,6 +441,10 @@ Likewise it is possible to convert ("type-lift") Win32Ole objects into the corre
 
   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/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