robust_excel_ole 1.14 → 1.18.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b63b8ec97e714c16c5b4e3f1bb60f7e160aba0469ad14d47b766fa1778919c1f
-  data.tar.gz: 1e0af619c00875ae92782cfa25a091335de3e1235723be9c2ecef2924b4f3cf9
+  metadata.gz: c966421c6f926cf0b4eec9b0c294a5a8544dcc129d24b5f7bbe34ced993baea9
+  data.tar.gz: 0e410b3f9a975a62dd671835eed6dcc06403acd0fc448e69019619ffc48cd8ed
 SHA512:
-  metadata.gz: 54d8101340e7a2c82af0a761998a466a931df0dc5eaf0bd5117a513f89ebf3e38fa6e27dd04af909f0d8cf8125117b126c8df7d642843c993862f6af2966afbd
-  data.tar.gz: 9f92d1018a35b7d018b7b3c3f7f3bb71383b7cb3914429a7986fe097a3ea9e8ac7ae77c011adff4075d4b56946c08ae8d9fdb9c69a51abb65b6109ea4f66cd00
+  metadata.gz: 670204220b0507239c8a4d31dd57085361bd60275a47bc228c5182bedb07e416ae1a414b65d73a416bfc826270445e450bf8aa841e6230829fa8072e6385aa93
+  data.tar.gz: 5cebdfb964bd8c87288059f6da7479bd8612482efddb7ce7f3d4818d51b911ce091b4b8ae576dd60d427c17db1a6a49eace85607112ad986aef2d32f5aa19ff0

data/Changelog

@@ -1,11 +1,44 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## [1.14]
+## [1.18] 2020-30-4
+
+### Added
+  - Workbook#worksheets, worksheets_count
+  - Worksheet#each_value
+  - Range#value, value=
+
+### Changed
+  - Range#initialize: optional paramter worksheet
+
+## [1.17]
+
+### Added
+  - Excel#active_workbook
+
+### Changed
+  - Excel#namevalue, set_namevalue, namevalue_glob, set_namevalue_glob are being removed
+
+## [1.16]
+
+### Added
+   - RangeOwners#set_namevalue, set_namevalue_glob, Worksheet#set_cellval: 
+     optional parameter for color 
+   
+### Changed   
+   - Workbook#color_if_modified removed   
+
+## [1.15]
+
+### Added
+   - Workbook#unobtrusively, Workbook#for_reading, Workbook#for_modifying
 
 ### Changed
    - Workbook.unobtrusively: removed parameter :rw_change_excel
    
+## [1.14]
+
+  - no interface change
 
 ## [1.13]
 

data/README.rdoc

@@ -14,10 +14,27 @@ Library references are supported.
 RobustExcelOle works by sending VBA methods via Win32OLE. 
 Therefore, it runs on Windows only.
 
+== Feature list
+
+- opening and processing workbooks across various Excel instances
+- reading and writing workbooks (cells and ranges)
+- reopening and unobtrusively opening workbooks
+- convenient methods for standard tasks (like opening, reading, writing, closing, saving workbooks, naming, adding, and copying ranges and worksheets)
+- dealing with various cases of Excel and user behaviour, e.g. managing conflicts when opening workbooks (e.g. blocking or unsaved workbooks),
+  even with simultanously happening user interactions
+- workarounds for Excel bugs and JRuby bugs
+- various workbook formats, e.g. .xlsx, .xls, .xlsm are supported
+- library references are supported
+- console for convenient usage
+
+== What's new?
+
+  - removing methods to operate on ranges directly from an Excel instance. However, you can use the method Excel.active_workbook to do so.
+  See ChangeLogs.
 
 == Requirements
 
-  Ruby 2.1 or higher. Most functions run on Ruby 1.8.6, too.
+  Ruby 2.1 or higher.
 
 == Installation
 
@@ -61,14 +78,11 @@ Let's open a workbook.
 Now we have a Workbook object that wraps a WIN32OLE object. That is, you can send any WIN32OLE (VBA) method to it. See 
 https://docs.microsoft.com/en-us/office/vba/api/excel.workbook#methods.
 
-For example, you can determine the name and whether the workbook is visible.
+For example, you can determine the name of the workbook.
 
   workbook.Name 
   # => "workbook.xls"
 
-  workbook.Visible
-  # => false
-
 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.
 
 First we want to make the workbook visible.
@@ -92,7 +106,7 @@ Then we'll save the workbook.
 
 === More features when opening, modifying, creating, saving and closing 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 (the Workbook object remembers its properties).
+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.unobtrusively('spec/data/workbook.xls') do |workbook|
     # do something

data/docs/README_excel.rdoc

@@ -26,7 +26,7 @@ Options of the methods +create+ and +new+ are +:reuse+ (+true+, +false+), +:visi
 
 The option +:calculation+ specifies, whether the calculation mode is being forced to be manual (:manual), automatic (+:automatic+) or is not being forced (+nil+).
 
-You can also promote an Excel instance represented as WIN32OLE object to an Excel object.
+You can also type-lift an Excel instance represented as WIN32OLE object to an Excel object.
 
   excel = Excel.new(win32ole_object, :visible => true)
 
@@ -124,6 +124,12 @@ or, with a block,
 
   excel.each_workbook(:visible => true) {|w| puts w}
 
+=== Accessing the active workbook
+
+You can operate on the active workbook with help of the method Workbook#active_workbook, e.g.
+
+  workbook = excel.active_workbook
+
 === Bringing an Excel instance to the foreground
 
   excel1.focus

data/docs/README_open.rdoc

@@ -142,21 +142,22 @@ 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.
 
-=== Promoting WIN32OLE objects to RobustExcelOle objects
+=== Type-lifting WIN32OLE objects to RobustExcelOle objects
 
-Promoting means here: enriching a given object of a certain class by properties and methods of another class. 
-The method +General.to_reo+ enables promoting WIN32OLE objects to RobustExcelOle objects such that the attributes and methods of RobustExcelOle can be applied to these objects. For example, assume we have a WIN32OLE workbook +win32ole_workbook+:
+Type-lifting means here: enriching a given object of a certain class by properties and methods of another class. 
+The method +General.to_reo+ enables type-lifting WIN32OLE objects to RobustExcelOle objects, in the sense that the attributes and methods of RobustExcelOle can be applied to these objects. For example, assume we have a WIN32OLE workbook +win32ole_workbook+:
 
   win32ole_workbook.to_class
   => WIN32OLE
 
-This object can be promoted to a RobustExcelOle workbook.
+This object can be type-lifted to a RobustExcelOle workbook.
 
   workbook = win32ole_workbook.to_reo
+
   workbook.to_class
   => RobustExcelOle::Workbook
 
-Similarly, Excel, Worksheet, and Range WIN32OLE objects can be promoted to corresponding RobustExcelOle objects. 
+Similarly, Excel, Worksheet, and Range WIN32OLE objects can be type-lifted to corresponding RobustExcelOle objects. 
 
 The method +to_reo+ uses the method +new+. You can apply the method +new+ directly.
 
@@ -166,45 +167,69 @@ You can supply options, e.g. +:visible+.
 
    workbook = Workbook.new(win32ole_workbook, :visible => true) 
 
+You can also supply a workbook and options, e.g.
+
+   new_workbook = Workbook.new(workbook, :visible => true)
 
 === Identity transperence ===
 
-A RobustExcelOle Workbook object is a proxy of an Excel WIN32OLE 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 identical Workbook objects refer to identical Excel workbooks, and vice versa. Identity transperence ensures that, no matter how a Workbook object was created - by filename or by promoting an Excel workbook - two Workbook objects are identical, if and only if the Excel workbooks, they are referring to, are identical. 
+A RobustExcelOle Workbook object is a proxy of an Excel WIN32OLE 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 identical Workbook objects refer to identical Excel workbooks, and vice versa. Identity transperence ensures that, no matter how a Workbook object was created - by filename or by type-lifting an Excel workbook - two Workbook objects are identical, if and only if the Excel workbooks, they are referring to, are identical. 
 
 Similarly, each Excel, Worksheet and a Range object in RobustExcelOle is a proxy of a corresponding Excel, Worksheet and a Range object in WIN32OLE. For these objects identity transperence holds as well.
 
+=== Opening workbooks given a network path and a hostname share path ===
+
+RobustExcelOle allows opening workbooks via a network path starting with a drive letter different from the default drive (mostly 'C'), e.g. 
+
+  workbook = Workbook.open('N:/data workbook.xls')
+
+Likewise the corresponding hostname share path can be used, starting with '//', e.g.
+
+  workbook = Workbook.open("//DESKTOP-A5D5GJ5/spec/data/workbook.xls")
+
+where 'DESKTOP-A5D5GJ5' shall be the hostname, and 'data' be the share.
+
 === 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. 
 
 Options are the following:
 
-+: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
-               
++:if_closed+:: the Excel instance in which to open the workbook, if it was closed (default: +:current+). (Note: this option works workbooks opened via RobustExcelOle only.)
+
 +:read_only+:: Whether the workbook shall be forced to be open in ReadOnly mode
 +:writable+::  Whether changes in the workbook shall be saved
 
-+: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)
++:keep_open+:: Whether the workbook shall be open after unobtrusively opening (default: false)
 
+There are the class method and the instance method of +unobtrusively+. Here is an example of the class method:
 
   Workbook.unobtrusively('spec/data/workbook.xls') do |book|
     # some modification
-    worksheet = book[0]
-    worksheet[1,1] = "c" 
+    book.sheet(1)[1,1] = "c" 
   end
-  
-The methods +for_reading+ and +for_modifying+ indicate unobtrusively reading or modifying.
+
+Here is an example of the instance method:
+
+  book.unobtrusively do
+    # some modification
+    book.sheet(1)[1,1] = "c" 
+  end
+       
+The methods +for_reading+ and +for_modifying+ indicate unobtrusively reading or modifying. 
 
   Workbook.for_modifying('spec/data/workbook.xls') do |book|
     # some modification
-    worksheet = book[0]
-    worksheet[1,1] = "c" 
+    book.sheet(1)[1,1] = "c"
   end
 
+An example of the instance method would be
+
+  book.for_modifying do
+    # some modification
+    book.sheet(1)[1,1] = "c"
+  end
+  
 Note, that the methods +unobtrusively+, +for_reading+ and +for_modifying+ work not only for workbooks opened via RobustExcelOle, but connect to workbooks opened outside RobustExcelOle as well.
 
 === Retaining the saved-status
@@ -218,7 +243,7 @@ This method ensures keeping the save status of the workbook
 
 === Checking whether the workbook is alive.
 
-This method finds out whether the Excel workbook that is referenced by the Workbook object responds to methods.
+The method +alive?+ finds out whether the Excel workbook that is referenced by the Workbook object responds to methods. For example
 
   workbook.alive?
   # => true

data/docs/README_ranges.rdoc

@@ -306,9 +306,12 @@ or
 
   workbook.set_namevalue_glob("name", "new_value")
 
-The method []= colors the written cell, if you have specified the color of the changed range via the method Workbook#color before, e.g.
+You can color the range when setting the contents of a range.
+
+  workbook.set_namevalue_glob("name", "new_value", :color => 4)
+
+The method []= sets the contents of a range and colors the range via some default color.
 
-  workbook.color_if_modified = 4
   workbook["name"] = "new_value"
 
 Similarly, the contents of a named range can be read and modified in a worksheet
@@ -391,6 +394,12 @@ The methods Worksheet#each, Worksheet#each_row and Worksheet#each_column enable
     # do something with column
   end
 
+The method Worksheet#each_value accesses the values of each row.
+
+  worksheet.each_value do |row_values|
+    # do something with the row_values
+  end
+
 You access a range of a row by giving the number of the row, and optionally, the range of the cell numbers.
 
   worksheet.row_range(1)  # => first row

data/examples/example_ruby_library.rb

@@ -0,0 +1,27 @@
+#require 'robust_excel_ole'
+
+#workbook = Workbook.open './sample_excel_files/xlsx_500_rows.xlsx'
+
+require_relative '../lib/robust_excel_ole'
+
+include RobustExcelOle
+
+workbook = Workbook.open './../spec/data/workbook.xls'
+
+puts "Found #{workbook.worksheets_count} worksheets"
+
+workbook.each do |worksheet|
+  puts "Reading: #{worksheet.name}"
+  num_rows = 0
+
+  worksheet.each do |row|
+    row_cells = row.map{ |cell| cell.value }
+    num_rows += 1
+
+    # uncomment to print out row values
+    # puts row_cells.join " "
+  end
+  puts "Read #{num_rows} rows"
+end
+
+puts 'Done'

data/extconf.rb

@@ -0,0 +1,13 @@
+dummy_make_content = "make:\n" \
+                     "\t:\n" \
+                     "install:\n" \
+                     "\t:\n" \
+                     "clean:\n" \
+                     "\t:\n"
+File.write('Makefile', dummy_make_content)
+
+puts "hello"
+
+a = 2
+
+puts a

data/lib/robust_excel_ole.rb

@@ -3,10 +3,11 @@ if RUBY_PLATFORM =~ /java/
 else
   require 'win32ole'
 end
-require File.join(File.dirname(__FILE__), 'robust_excel_ole/reo_common')
-require File.join(File.dirname(__FILE__), 'robust_excel_ole/range_owners')
-require File.join(File.dirname(__FILE__), 'robust_excel_ole/address')
+require File.join(File.dirname(__FILE__), 'robust_excel_ole/base')
 require File.join(File.dirname(__FILE__), 'robust_excel_ole/general')
+require File.join(File.dirname(__FILE__), 'robust_excel_ole/vba_objects')
+require File.join(File.dirname(__FILE__), 'robust_excel_ole/range_owners')
+require File.join(File.dirname(__FILE__), 'robust_excel_ole/address_tool')
 require File.join(File.dirname(__FILE__), 'robust_excel_ole/excel')
 require File.join(File.dirname(__FILE__), 'robust_excel_ole/bookstore')
 require File.join(File.dirname(__FILE__), 'robust_excel_ole/workbook')

data/lib/robust_excel_ole/{address.rb → address_tool.rb}

@@ -2,37 +2,38 @@
 
 module RobustExcelOle
 
-  class Address < REOCommon
+  class AddressTool < Base
 
-    def self.new(r1c1_letters)
-      @@row_letter = r1c1_letters[0..0]
-      @@col_letter = r1c1_letters[1..1]
+    def initialize(address_string)
+      r1c1_letters = address_string.gsub(/[0-9]/,'')
+      @row_letter = r1c1_letters[0..0]
+      @col_letter = r1c1_letters[1..1]
     end
 
     # address formats that are valid:
     #   r1c1-format: e.g. "Z3S1", "Z3S1:Z5S2", "Z[3]S1", "Z3S[-1]:Z[5]S1", "Z[3]", "S[-2]"
     #                      infinite ranges are not possible, e.g. "Z3:Z5", "S2:S5", "Z2", "S3", "Z[2]" 
-    #   int_range: e.g. [3,1], [3,"A"], [3..5,1..2], [3..5, "A".."B"], 
-    #                   [3..4, nil], [nil, 2..4], [2,nil], [nil,4]
+    #   integer_ranges-fromat: e.g. [3,1], [3,"A"], [3..5,1..2], [3..5, "A".."B"], 
+    #                               [3..4, nil], [nil, 2..4], [2,nil], [nil,4]
     #   a1-format: e.g. "A3", "A3:B5", "A:B", "3:5", "A", "3"
 
-    def self.r1c1(address)
+    def as_r1c1(address)
       transform_address(address,:r1c1)
     end
 
-    def self.a1(address)
+    def as_a1(address)
       transform_address(address,:a1)
     end
 
     # valid address formats: e.g. [3,1], [3,"A"], [3..5,1..2], [3..5, "A".."B"], 
     #                             [3..4, nil], [nil, 2..4], [2,nil], [nil,4]
-    def self.int_range(address)
+    def as_integer_ranges(address)
       transform_address(address,:int_range)
     end
 
   private
 
-    def self.transform_address(address, format)
+    def transform_address(address, format)
       address = address.is_a?(Array) ? address : [address]
       raise AddressInvalid, "address #{address.inspect} has more than two components" if address.size > 2
       begin
@@ -70,8 +71,8 @@ module RobustExcelOle
         raise AddressInvalid, "address (#{address.inspect}) format not correct"
       end
       if format==:r1c1
-        r1c1_string(@@row_letter,rows,:min) + r1c1_string(@@col_letter,columns,:min) + ":" + 
-        r1c1_string(@@row_letter,rows,:max) + r1c1_string(@@col_letter,columns,:max)
+        r1c1_string(@row_letter,rows,:min) + r1c1_string(@col_letter,columns,:min) + ":" + 
+        r1c1_string(@row_letter,rows,:max) + r1c1_string(@col_letter,columns,:max)
       elsif format==:int_range
         [rows,columns]
       else
@@ -79,8 +80,7 @@ module RobustExcelOle
       end
     end  
 
-    # @private
-    def self.r1c1_string(letter,int_range,type)
+    def r1c1_string(letter,int_range,type)
       return "" if int_range.nil? || int_range.begin.nil?
       parameter = type == :min ? int_range.begin : int_range.end
       is_relative = parameter.is_a?(Array)
@@ -88,27 +88,28 @@ module RobustExcelOle
       letter + (is_relative ? "(" : "") + parameter.to_s + (is_relative ? ")" : "")       
     end 
 
-    # @private
-    def self.analyze(comp,format)
+    def analyze(comp,format)
       row_comp, col_comp = if format==:a1 
         [comp.gsub(/[A-Z]/,''), comp.gsub(/[0-9]/,'')]
       else
-        a,b = comp.split(@@row_letter)
-        c,d = b.split(@@col_letter)
+        a,b = comp.split(@row_letter)
+        c,d = b.split(@col_letter)
         b.nil? ? ["",b] : (d.nil? ? [c,""] : [c,d])  
       end
-      def self.s2n(s)
+      def s2n(s)
         s!="" ? (s[0] == "[" ? [s.gsub(/\[|\]/,'').to_i] : (s.to_i!=0 ? s.to_i : s)) : nil
       end
       [s2n(row_comp), s2n(col_comp)]
     end
 
-
-    # @private
-    def self.str2num(str)
+    def str2num(str)
       str.tr("A-Z","0-9A-P").to_i(26) + (26**str.size-1)/25
     end
 
   end
 
+  # @private
+  class AddressInvalid < REOError                  
+  end
+
 end