robust_excel_ole 1.14 → 1.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b63b8ec97e714c16c5b4e3f1bb60f7e160aba0469ad14d47b766fa1778919c1f
-  data.tar.gz: 1e0af619c00875ae92782cfa25a091335de3e1235723be9c2ecef2924b4f3cf9
+  metadata.gz: 4c75264c3aa717667b2c38799b6fad4043f45a307d9d434b8e3d4a00ca0eff35
+  data.tar.gz: dbb9ba06291ab9f9efdb616d5b0f34d9f425166fc5a90accba4efed3b0afb99e
 SHA512:
-  metadata.gz: 54d8101340e7a2c82af0a761998a466a931df0dc5eaf0bd5117a513f89ebf3e38fa6e27dd04af909f0d8cf8125117b126c8df7d642843c993862f6af2966afbd
-  data.tar.gz: 9f92d1018a35b7d018b7b3c3f7f3bb71383b7cb3914429a7986fe097a3ea9e8ac7ae77c011adff4075d4b56946c08ae8d9fdb9c69a51abb65b6109ea4f66cd00
+  metadata.gz: e171843b4c4fa899a2db7ee69f21656dfc005396cd3f372977a9e520ff47b019642ddb188af41870bf79216508195609389743ffdb100c8c7975450d4334da1b
+  data.tar.gz: 5cb5bfe60497f110077d27746e90d15ad455e94a2a289762372407361f26cc7163e2ea211720782c99e4b00abb48be954a2507ae855faf0b0cc069408b1e73f6

data/Changelog

@@ -1,11 +1,17 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## [1.14]
+## [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

@@ -61,14 +61,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 +89,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)
 

data/docs/README_open.rdoc

@@ -145,18 +145,18 @@ The closed workbook is now alive again, i.e. is open and responds to Excel metho
 === Promoting 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+:
+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.
 
@@ -169,7 +169,7 @@ You can supply options, e.g. +:visible+.
 
 === 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.
 
@@ -179,32 +179,41 @@ The method +unobtrusively+ enables the user to read or modify a workbook, no mat
 
 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 +227,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/lib/robust_excel_ole/cell.rb

@@ -19,7 +19,7 @@ module RobustExcelOle
     # @private
     def method_missing(name, *args) 
       #if name.to_s[0,1] =~ /[A-Z]/
-      if JRUBY_BUG_ERRORMESSAGE
+      if ::JRUBY_BUG_ERRORMESSAGE
         begin
           @cell.send(name, *args)
         rescue Java::OrgRacobCom::ComFailException 

data/lib/robust_excel_ole/excel.rb

@@ -3,6 +3,8 @@
 require 'weakref'
 require 'Win32API'
 
+
+
 def ka
   Excel.kill_all
 end
@@ -16,19 +18,14 @@ module RobustExcelOle
 
   class Excel < RangeOwners
     attr_accessor :ole_excel
-    #attr_accessor :created
-    attr_accessor :workbook
-
-    # setter methods are implemented below
-    attr_reader :visible
-    attr_reader :displayalerts
-    attr_reader :calculation
-    attr_reader :screenupdating
+    attr_reader :properties
 
     alias ole_object ole_excel
 
     @@hwnd2excel = {}
 
+    PROPERTIES = [:visible, :displayalerts, :calculation, :screenupdating]
+
     # creates a new Excel instance
     # @param [Hash] options the options
     # @option options [Variant] :displayalerts
@@ -96,10 +93,7 @@ module RobustExcelOle
         unless reused || connected
           options = { :displayalerts => :if_visible, :visible => false, :screenupdating => true }.merge(options)
         end
-        result.visible = options[:visible] unless options[:visible].nil? 
-        result.displayalerts = options[:displayalerts] unless options[:displayalerts].nil?
-        result.calculation = options[:calculation] unless options[:calculation].nil?
-        result.screenupdating = options[:screenupdating] unless options[:screenupdating].nil?
+        result.set_options(options)        
       end
       result
     end    
@@ -118,13 +112,11 @@ module RobustExcelOle
     def recreate(opts = {})
       unless alive?
         opts = {
-          :visible => @visible || false,
-          :displayalerts => @displayalerts || :if_visible
+          :visible => @properties[:visible] || false,
+          :displayalerts => @properties[:displayalerts] || :if_visible
         }.merge(opts)
         @ole_excel = WIN32OLE.new('Excel.Application')
-        self.visible = opts[:visible]
-        self.displayalerts = opts[:displayalerts]
-        self.calculation = opts[:calculation]
+        set_options(opts)
         if opts[:reopen_workbooks]
           books = workbook_class.books
           books.each do |book|
@@ -399,7 +391,7 @@ module RobustExcelOle
     # if this Excel instance is being closed, then Excel creates a new Excel instance
     # @private
     def self.current_ole_excel   
-      if JRUBY_BUG_CONNECT
+      if ::JRUBY_BUG_CONNECT
         result = known_excel_instance
         if result.nil?
           if excels_number > 0
@@ -545,7 +537,7 @@ module RobustExcelOle
 
     # sets DisplayAlerts in a block
     def with_displayalerts displayalerts_value
-      old_displayalerts = displayalerts
+      old_displayalerts = @properties[:displayalerts]
       self.displayalerts = displayalerts_value
       begin
         yield self
@@ -556,26 +548,29 @@ module RobustExcelOle
 
     # makes the current Excel instance visible or invisible
     def visible= visible_value
-      @ole_excel.Visible = @visible = visible_value
-      @ole_excel.DisplayAlerts = @visible if @displayalerts == :if_visible
+      return if visible_value.nil?
+      @ole_excel.Visible = @properties[:visible] = visible_value
+      @ole_excel.DisplayAlerts = @properties[:visible] if @properties[:displayalerts] == :if_visible
     end
 
     # enables DisplayAlerts in the current Excel instance
     def displayalerts= displayalerts_value
-      @displayalerts = displayalerts_value
-      @ole_excel.DisplayAlerts = @displayalerts == :if_visible ? @ole_excel.Visible : displayalerts_value
+      return if displayalerts_value.nil?
+      @properties[:displayalerts] = displayalerts_value
+      @ole_excel.DisplayAlerts = @properties[:displayalerts] == :if_visible ? @ole_excel.Visible : displayalerts_value
     end
 
     # sets ScreenUpdating
     def screenupdating= screenupdating_value
-      @ole_excel.ScreenUpdating = @screenupdating = screenupdating_value
+      return if screenupdating_value.nil?
+      @ole_excel.ScreenUpdating = @properties[:screenupdating] = screenupdating_value
     end
 
     # sets calculation mode
     # retains the saved-status of the workbooks when set to manual
     def calculation= calculation_mode
       return if calculation_mode.nil?
-      @calculation = calculation_mode
+      @properties[:calculation] = calculation_mode
       calc_mode_changable = @ole_excel.Workbooks.Count > 0 && @ole_excel.Calculation.is_a?(Integer)
       if calc_mode_changable
         retain_saved_workbooks do
@@ -615,9 +610,9 @@ module RobustExcelOle
     def Calculation= calculation_vba_mode
       case calculation_vba_mode
       when XlCalculationManual
-        @calculation = :manual
+        @properties[:calculation] = :manual
       when XlCalculationAutomatic
-        @calculation = :automatic
+        @properties[:calculation] = :automatic
       end
       @ole_excel.Calculation = calculation_vba_mode
     end
@@ -637,13 +632,22 @@ module RobustExcelOle
 
     # set options in this Excel instance
     def for_this_instance(options)
-      self.class.new(@ole_excel, options)
+      set_options(options)
+      #self.class.new(@ole_excel, options)
     end
 
-    def set_options(options)
-      for_this_instance(options)
-    end    
+    #def set_options(options)
+    #  for_this_instance(options)
+    #end  
 
+    def set_options(options)      
+      @properties ||= { }
+      PROPERTIES.each do |property|
+        method = (property.to_s + '=').to_sym
+        self.send(method, options[property]) 
+      end
+    end
+  
     # set options in all workbooks
     def for_all_workbooks(options)
       each_workbook(options)
@@ -696,6 +700,13 @@ module RobustExcelOle
       workbook.color_if_modified = old_color_if_modified
     end
 
+    # @private
+    # returns active workbook
+    def workbook
+      return @workbook unless @workbook.nil?
+      @workbook = workbook_class.new(@ole_excel.ActiveWorkbook)
+    end
+
     # @private
     def to_s            
       '#<Excel: ' + hwnd.to_s + ('not alive' unless alive?).to_s + '>'
@@ -729,7 +740,7 @@ module RobustExcelOle
     def method_missing(name, *args) 
       if name.to_s[0,1] =~ /[A-Z]/
         raise ObjectNotAlive, 'method missing: Excel not alive' unless alive?
-        if JRUBY_BUG_ERRORMESSAGE
+        if ::JRUBY_BUG_ERRORMESSAGE
           begin
             @ole_excel.send(name, *args)
           rescue Java::OrgRacobCom::ComFailException => msg

data/lib/robust_excel_ole/general.rb

@@ -3,11 +3,11 @@
 module General
 
   IS_JRUBY_PLATFORM = (RUBY_PLATFORM =~ /java/)
-  JRUBY_BUG_CONNECT      = IS_JRUBY_PLATFORM && true
-  JRUBY_BUG_COPYSHEETS   = IS_JRUBY_PLATFORM && true
-  JRUBY_BUG_ERRORMESSAGE = IS_JRUBY_PLATFORM && true
-  JRUBY_BUG_CONNECTEXCEL = IS_JRUBY_PLATFORM && true
-  JRUBY_BUG_RANGES       = IS_JRUBY_PLATFORM && true
+  ::JRUBY_BUG_CONNECT      = IS_JRUBY_PLATFORM && true
+  ::JRUBY_BUG_COPYSHEETS   = IS_JRUBY_PLATFORM && true
+  ::JRUBY_BUG_ERRORMESSAGE = IS_JRUBY_PLATFORM && true
+  ::JRUBY_BUG_CONNECTEXCEL = IS_JRUBY_PLATFORM && true
+  ::JRUBY_BUG_RANGES       = IS_JRUBY_PLATFORM && true
 
 
   # @private
@@ -75,7 +75,7 @@ class WIN32OLE
 
   include RobustExcelOle
   
-  # promoting WIN32OLE objects to RobustExcelOle objects
+  # type-lifting WIN32OLE objects to RobustExcelOle objects
   def to_reo
     class2method = [{Excel => :Hwnd}, {Workbook => :FullName}, {Worksheet => :Copy}, {Range => :Address}]
     class2method.each do |element|

data/lib/robust_excel_ole/range.rb

@@ -27,7 +27,7 @@ module RobustExcelOle
     # @returns [Array] the values
     def values(range = nil)
       #result = map { |x| x.Value }.flatten
-      result_unflatten = if !JRUBY_BUG_RANGES
+      result_unflatten = if !::JRUBY_BUG_RANGES
         map { |x| x.v }
       else
         self.v
@@ -44,7 +44,7 @@ module RobustExcelOle
 
     def v
       begin
-        if !JRUBY_BUG_RANGES
+        if !::JRUBY_BUG_RANGES
           self.Value
         else
           address_r1c1 = self.AddressLocal(true,true,XlR1C1)
@@ -65,7 +65,7 @@ module RobustExcelOle
 
     def v=(value)
       begin
-        if !JRUBY_BUG_RANGES
+        if !::JRUBY_BUG_RANGES
           ole_range.Value = value
         else
           address_r1c1 = ole_range.AddressLocal(true,true,XlR1C1)
@@ -240,7 +240,7 @@ module RobustExcelOle
     # @private
     def method_missing(name, *args) 
       if name.to_s[0,1] =~ /[A-Z]/
-        if JRUBY_BUG_ERRORMESSAGE
+        if ::JRUBY_BUG_ERRORMESSAGE
           begin
             @ole_range.send(name, *args)
           rescue Java::OrgRacobCom::ComFailException 

data/lib/robust_excel_ole/range_owners.rb

@@ -24,7 +24,7 @@ module RobustExcelOle
       ole_range = name_obj.RefersToRange
       value = begin
         #name_obj.RefersToRange.Value
-        if !JRUBY_BUG_RANGES       
+        if !::JRUBY_BUG_RANGES       
           ole_range.Value
         else
           values = RobustExcelOle::Range.new(ole_range).v
@@ -39,7 +39,7 @@ module RobustExcelOle
           #sheet.Evaluate(name_obj.Name).Value
           # does it result in a range?
           ole_range = sheet.Evaluate(name_obj.Name)
-          if !JRUBY_BUG_RANGES
+          if !::JRUBY_BUG_RANGES
             ole_range.Value
           else
             values = RobustExcelOle::Range.new(ole_range).v
@@ -71,7 +71,7 @@ module RobustExcelOle
         ole_range = name_object(name).RefersToRange
         workbook.color_if_modified = opts[:color] unless opts[:color].nil?
         ole_range.Interior.ColorIndex = workbook.color_if_modified unless workbook.color_if_modified.nil?
-        if !JRUBY_BUG_RANGES
+        if !::JRUBY_BUG_RANGES
           ole_range.Value = value
         else
           address_r1c1 = ole_range.AddressLocal(true,true,XlR1C1)
@@ -106,7 +106,7 @@ module RobustExcelOle
       end
       begin
         #value = ole_range.Value
-        value = if !JRUBY_BUG_RANGES
+        value = if !::JRUBY_BUG_RANGES
           ole_range.Value
         else
           values = RobustExcelOle::Range.new(ole_range).v
@@ -137,7 +137,7 @@ module RobustExcelOle
       begin
         workbook.color_if_modified = opts[:color] unless opts[:color].nil?
         ole_range.Interior.ColorIndex = workbook.color_if_modified unless workbook.color_if_modified.nil?
-        if !JRUBY_BUG_RANGES
+        if !::JRUBY_BUG_RANGES
           ole_range.Value = value
         else
           address_r1c1 = ole_range.AddressLocal(true,true,XlR1C1)

data/lib/robust_excel_ole/version.rb

@@ -1,3 +1,3 @@
 module RobustExcelOle
-  VERSION = "1.14"
+  VERSION = "1.15"
 end