robust_excel_ole 1.27 → 1.32

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf42835b0febd0db61ca5f87c473f63256d97d2dbaaf05cbe8b97be01fc6f17e
-  data.tar.gz: 81c4e849c1aceca218207e04577e8857098c1c68482c209515a79e2ead44c5ed
+  metadata.gz: f56e6aaeeeec6c073cc4f871ea99185428523959c420e1165d199792979074c5
+  data.tar.gz: 79dd7f6ea160e0045592a3dd8ae31a5b8a162c71b6986dcbcef157eba54c93b4
 SHA512:
-  metadata.gz: 88fadf70ac1ec5fab7e133d21fe9a6e9f0ed5399fec3dd0d5198d9c639ebde470dde7f657778564c8a7b9a326fe6b0d177e3cfeca66c4f3642ca97fccfd9314e
-  data.tar.gz: 578aa3c80a722c10b2d4cdc390a45f1286775586fc58ac4c67dfe7dedb1da0939b4e79fea366bc6bf49034d9631f1b8cfaac3eb54c56b6dab3385f1811f86254
+  metadata.gz: 894959ff3e8c48c8413bbb137013cf8ad7612bb991292f1461b1df9b3371d15c16132ecf0df0dbf78403171381064cfb43d9400604bc2155214f8aa2a514ea7c
+  data.tar.gz: 508b37f27ef7c0e554b565f21263386e1b180cb5269f6a843b2da927eaa3f6eebe5a111a362d5dc96de4726a1c3648673b062b02589739eb7e5ff2a0bb7f59cc

data/Changelog

@@ -1,7 +1,41 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## [1.27] 2020-20-10
+## [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
+
+### Added
+  - Workbook.open can also take a Pathname object
+  - General#init_reo_for_win32ole
+
+## [1.28] 2020-23-10
+
+## [1.27] 2020-16-10
 
 ## [1.26] 2020-09-10
 
@@ -177,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,14 +431,20 @@ or
 However, this command also starts another pry repl (with another binding). Moreover, local variables in the previous binding are forgotten.
 
 
-2. The method +General.update_to_reo+ extends the class Win32Ole 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
+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])
 
-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/bin/jreo

@@ -15,10 +15,29 @@ Pry.config.prompt_name = "REO "
 #Pry.config.history_save = true
 #Pry.editor = 'notepad'  # 'subl', 'vi'
 
+prompt_proc1 = proc { |target_self, nest_level, pry|
+   "[#{pry.input_ring.count}] #{pry.config.prompt_name}(#{Pry.view_clip(target_self)})#{":#{nest_level}" unless nest_level.zero?}> "
+ }
+
+prompt_proc2 =  proc { |target_self, nest_level, pry|
+  "[#{pry.input_ring.count}] #{pry.config.prompt_name}(#{Pry.view_clip(target_self.inspect.gsub(/\"/, ''))})})#{":#{nest_level}" unless nest_level.zero?}* "
+ }
+
+Pry.config.prompt = if RUBY_PLATFORM =~ /java/
+  [prompt_proc1, prompt_proc2]
+else
+  Pry::Prompt.new(
+    "REO",
+    "The RobustExcelOle Prompt. Besides the standard information it puts the current object",
+    [prompt_proc1, prompt_proc2]
+    )
+end
+
 hooks = Pry::Hooks.new
 
 hooks.add_hook :when_started, :hook12 do
 puts 'REO console started'
 puts
 end
+
 Pry.start(nil, hooks: hooks)

data/bin/reo

@@ -15,10 +15,29 @@ Pry.config.prompt_name = "REO "
 #Pry.config.history_save = true
 #Pry.editor = 'notepad'  # 'subl', 'vi'
 
+prompt_proc1 = proc { |target_self, nest_level, pry|
+  "[#{pry.input_ring.count}] #{pry.config.prompt_name}(#{Pry.view_clip(target_self)})#{":#{nest_level}" unless nest_level.zero?}> "
+ }
+
+prompt_proc2 =  proc { |target_self, nest_level, pry|
+  "[#{pry.input_ring.count}] #{pry.config.prompt_name}(#{Pry.view_clip(target_self)})#{":#{nest_level}" unless nest_level.zero?}* "
+ }
+
+Pry.config.prompt = if RUBY_PLATFORM =~ /java/
+  [prompt_proc1, prompt_proc2]
+else
+  Pry::Prompt.new(
+    "REO",
+    "The RobustExcelOle Prompt. Besides the standard information it puts the current object",
+    [prompt_proc1, prompt_proc2]
+    )
+end
+
 hooks = Pry::Hooks.new
 
 hooks.add_hook :when_started, :hook12 do
 puts 'REO console started'
 puts
 end
+
 Pry.start(nil, hooks: hooks)