robust_excel_ole 1.1.5 → 1.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 94e2b8cc2f0306a63e377d70378a04063e6b5cf2
-  data.tar.gz: 6d4c94aa56956a25ba723746bf05e23320aa36bb
+  metadata.gz: eb0b1d72f09a87508b2d3f42a909b76de9230232
+  data.tar.gz: 54e2a4230a0833cb672881a49da5e105b3b74895
 SHA512:
-  metadata.gz: f46997852585e4560db9ccb679a0dccc11a6128b59022b374d8393771531ae2aab2973fa10d0f342f882181dcaaca2cdf4af7151ed918446bdebdb5f57faf8dc
-  data.tar.gz: 99d74fe8c6c16ab52c40c6d5362cba29a07539acf695fbc546619b8fb18086b860258005ccd63429c19655aaf6212096c5d1d76924c4ff85be565cf7dc88e34a
+  metadata.gz: de86c09449b9bc6c93915ef14cb898077d6243bc19012ce002a81a5d6828f8c4cb5ffaee8ed7a75c1d7ae0f8e1ad77b92dbd5d194af44393714578c2149c5a11
+  data.tar.gz: b43dfe70f03b3197d09710eeccb72fc696ae425b65b8a3ffbe36a94b0b61ce0a03e91ceb2929631aa33f22648f90362e1623d818b54b0e2fe97a5a00c971f39e

data/Changelog

@@ -1,6 +1,12 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+## [1.1.6] - 2018-20-7
+
+### Added
+  - Sheet#cellval
+  - Sheet#set_cellval
+
 ## [1.1.5] - 2018-10-7
 
 ### Added

data/README.rdoc

@@ -203,7 +203,7 @@ Without the option +:default+, the workbook can be forced to be opened in the cu
 
 As a further feature, RobustExcelOle allows 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.
 
-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 before opening the workbook, e.g.
+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)
 
@@ -264,7 +264,7 @@ or
 
   sheet.row_range(1)[0].value    # => "foo"
 
-Then we modify it
+Then we modify it.
 
   sheet[1,1] = "hello"
 

data/docs/README_excel.rdoc

@@ -69,16 +69,15 @@ and turn DisplayAlerts off with
 
   excel1.displayalerts = false
 
-You can turn off and off DisplayAlerts in a block.
+You can turn DisplayAlerts off or on within a block.
 
-  excel = Excel.create
   excel.with_displayalerts false do
     # do something
   end
 
 Notice, that when the Excel instance is set to visible, its DisplayAlerts is set to true by default, if DisplayAlerts is not explicitely set to false.
 
-=== Setting Calculation mode.
+=== Setting Calculation mode
 
 You can set the calculation mode of an Excel instance to manual or automatic.
 

data/docs/README_open.rdoc

@@ -1,6 +1,6 @@
 = RobustExcelOle
 
-=== Opening and unobtrusively modifying a workbook.
+=== Opening a workbook.
 
 If you want to open a workbook, use
   
@@ -25,9 +25,9 @@ The options are the following:
 
 +:visible+::        makes the workbook visible or invisible
 
-+:if_unsaved+::      specify behaviour if the workbook was unsaved (default: +new_excel+)
++:if_unsaved+::      specify behaviour if the workbook was unsaved (default: +:raise+)
 
-+:if_obstructed+::   specify behaviour if the workbook is blocked by another book (default: +new_excel+)
++:if_obstructed+::   specify behaviour if the workbook is blocked by another book (default: +:raise+)
 
 +:read_only+::       open in read-only mode (default: +false+)
 
@@ -37,12 +37,7 @@ The options are the following:
 
 +:if_absent+::       specify behaviour if the workbook with the given file name does not exist if the workbook does not exist (default: +create+)
 
-You can use the following abbreviations:
-
-+:f+:: +:force+
-+:d+:: +:default+
-+:e+:: +:excel+
-+:v+:: +:visible+
+You can use the following abbreviations: +:f+ for  +:force+, +:d+ for +:default+, +:e+ for +:excel+, and +:v+ for +:visible+. Finally you can leave out the option +:force+ or +:f+.
 
 The option +:excel+ :
 
@@ -100,7 +95,6 @@ For simplicity, you can also leave out the +:force+ option (but not the +:defaul
 You can also specify an Excel instance
 
   excel1 = Excel.create
-  # do something
   Workbook.open('workbook.xls', :excel => excel1)
 
 If you want to open the workbook and make its window visible, then use
@@ -156,8 +150,8 @@ 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
                
-+:read_only+:: Whether the workbook shall be forced to be open in ReadOnly mode (default: +false+)
-+:writable+::  Whether changes in the workbook shall be saved (default: +true+)
++: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  
@@ -180,6 +174,8 @@ The methods +for_reading+ and +for_modifying+ indicate unobtrusively reading or
     sheet[1,1] = "c" 
   end
 
+Remark: The methods +unobtrusively+, +for_reading+ and +for_modifying+ work only for workbooks opened via RobustExcelOle. They do not connect to workbooks opened outside RobustExcelOle.
+
 === Retaining the saved-status
 
 This method ensures keeping the save status of the workbook

data/docs/README_ranges.rdoc

@@ -2,7 +2,7 @@
 
 == Reading and writing the contents of ranges and cells
 
-RobustExcelOle enables to read and write the contents of ranges and cells in workbooks. This can be done from a Sheet, a Book or an Excel object representing a Worksheet, Workbook, or Application object in VBA.
+RobustExcelOle enables to read and write the contents of ranges and cells in workbooks. This can be done from a Sheet, a Book or an Excel object representing a Worksheet, Workbook, or Application object, respectively, in VBA.
 
 === Reading and writing the contents of a named range in a workbook.
 
@@ -10,7 +10,7 @@ Assume you have opened a workbook:
  
   book = Workbook.open('workbook.xls', :visible => true)
 
-You can get the contents of a range with a defined name with help of the method [] or nameval:
+You can get the contents of a range with a defined name with help of the method [] or +nameval+.
 
   book["name"] 
   => "value"
@@ -20,7 +20,7 @@ or
   book.nameval("name")
   => "value"
 
-Using nameval, via the option :default you can provide a value that is returned when the name cannot be found or some other error would occur.
+Using +nameval+, via the option +:default+ you can provide a value that is returned when the name cannot be found or some other error would occur.
 
   book.namval("name", :default => "default_value")
 
@@ -32,11 +32,11 @@ or
 
   book.set_nameval("name", "new_value")
 
-The method []= colors the written cell. You can specify the color of a changed range via the method set_nameval: 
+The method []= colors the written cell. You can specify the color of a changed range via the method +set_nameval+. 
   
   book.set_nameval("name", "new_value", :color => 4)
 
-Similarly, the contents of a named range can be read and modified in a worksheet 
+Similarly, the contents of a named range can be read and modified in a worksheet
 
   sheet = book.sheet(1)
 
@@ -45,7 +45,7 @@ Similarly, the contents of a named range can be read and modified in a worksheet
 
   sheet["name"] = "new_value" 
 
-or an application object:
+or an Application object.
 
   excel = book.excel
 
@@ -64,7 +64,7 @@ or
 
 === Reading and writing the contents of a range with a locally defined name
 
-The contents of locally defined ranges can be read
+The contents of locally defined ranges can be read by
 
   sheet.rangeval("name")
   => "value"
@@ -74,7 +74,7 @@ or
   excel.rangeval("name")
   => "value" 
 
-and be modified:
+and be modified by
 
   sheet.set_rangeval("name", "value")
 
@@ -88,13 +88,25 @@ Similarly to nameval, you can provide a default value that is returned when ocur
 
 === Accessing a cell
 
-You can read and write a cell from a sheet object by providing the row and the column. For example, the following lines provide and set the value of the first cell (first row, first column):
+You can read a cell from a sheet object by providing the row and the column. For example, the following lines provide the value of the first cell (first row, first column):
 
   sheet[1,1].value  
   => "foo
 
+or
+
+  sheet.cellval(1,1)
+  => "foo"
+
+Similarly, you can write a cell.
+
   sheet[1,1] = "new_value"
 
+or
+
+  sheet.set_cellval(1,1,"new_value", :color => 42)
+
+
 === Accessing rows and columns
 
 The methods Sheet#each, Sheet#each_row and Sheet#each_column enable to access each cell, row and column, respectively.

data/docs/README_sheet.rdoc

@@ -26,7 +26,7 @@ and
 
   sheet = book.last_sheet  
 
-You can access all sheet objects by using the methods Workbook#each.
+You can access all Sheet objects by using the methods Workbook#each.
 
   book.each do |sheet|               
     # do something with sheet

data/lib/robust_excel_ole/book.rb

@@ -111,24 +111,6 @@ module RobustExcelOle
       end
     end    
 
-# here is what is different and works 
-=begin
-           if book
-             if (((not options[:force][:excel]) || (forced_excel == book.excel)) &&
-                  (not (book.alive? && (not book.saved) && (not options[:if_unsaved] == :accept))))
-               book.options = options
-               book.ensure_excel(options) # unless book.excel.alive?
-               # if the ReadOnly status shall be changed, close and reopen it; save before, if it is writable
-               if book.alive? and (((not book.writable) and (not options[:read_only])) or
-                   (book.writable and options[:read_only]))
-                 book.save if book.writable  
-                 book.close(:if_unsaved => :forget)
-               end                
-               # reopens the book
-               book.ensure_workbook(file,options) unless book.alive?
-=end
-
-
     # creates a Book object by opening an Excel file given its filename workbook or 
     # by lifting a Win32OLE object representing an Excel file
     # @param [WIN32OLE] workbook a workbook
@@ -145,6 +127,8 @@ module RobustExcelOle
             book.visible = opts[:force][:visible] unless opts[:force].nil? or opts[:force][:visible].nil?
             book.excel.calculation = opts[:calculation] unless opts[:calculation].nil?
             return book 
+          else
+            super
           end
         end
       else
@@ -158,7 +142,6 @@ module RobustExcelOle
     # @param [Hash]    opts              the options
     # @option opts [Symbol] see above
     # @return [Book] a workbook
-    #def initialize(file_or_workbook, opts={ }, &block)
     def initialize(file_or_workbook, options={ }, &block)
       #options = @options = self.class.process_options(options) if options.empty?
       if file_or_workbook.is_a? WIN32OLE        
@@ -250,8 +233,6 @@ module RobustExcelOle
   public
 
     def ensure_excel(options)   # :nodoc: #
-      #if (excel && @excel.alive? && (options[:force].nil? or options[:force][:excel].nil? or 
-      #             options[:force][:excel]==@excel))
       if excel && @excel.alive?  
         @excel.created = false
         return
@@ -487,6 +468,7 @@ module RobustExcelOle
 
     # allows to read or modify a workbook such that its state remains unchanged
     # state comprises: open, saved, writable, visible, calculation mode, check compatibility 
+    # remarks: works only for workbooks opened with RobustExcelOle
     # @param [String] file        the file name
     # @param [Hash]   opts        the options
     # @option opts [Variant] :if_closed  :current (default), :new or an Excel instance
@@ -496,7 +478,6 @@ module RobustExcelOle
     #                         write permissions shall be opened  :current (default), :new or an Excel instance                   
     # @option opts [Boolean] :keep_open whether the workbook shall be kept open after unobtrusively opening 
     # @return [Book] a workbook
-    # state = [:open, :saved, :writable, :visible, :calculation, :check_compatibility]
     def self.unobtrusively(file, opts = { }, &block) 
       opts = {:if_closed => :current,
               :rw_change_excel => :current,
@@ -651,7 +632,6 @@ module RobustExcelOle
   private
 
     def discoloring
-      # self.each{|sheet| sheet.UsedRange.each{|cell| cell.Interior.ColorIndex = XlNone}}
       @modified_cells.each{|cell| cell.Interior.ColorIndex = XlNone}
     end
 

data/lib/robust_excel_ole/excel.rb

@@ -225,6 +225,8 @@ module RobustExcelOle
 
     # closes all Excel instances
     # @return [Fixnum,Fixnum] number of closed Excel instances, number of errors
+    # remark: the returned number of closed Excel instances is valid only for known Excel instances
+    # if there are unknown Excel instances (opened not via this class), then they are counted as 1
     # @param [Hash] options the options
     # @option options [Symbol]  :if_unsaved :raise, :save, :forget, or :alert
     # options:
@@ -589,21 +591,6 @@ module RobustExcelOle
       end
     end
 
-=begin
-    # make all workbooks visible or invisible
-    def workbooks_visible= visible_value
-      begin
-        @ole_excel.Workbooks.each do |ole_wb| 
-          workbook = Book.new(ole_wb)
-          workbook.visible = visible_value
-        end
-      rescue RuntimeError => msg
-        trace "RuntimeError: #{msg.message}" 
-        raise ExcelDamaged, "Excel instance not alive or damaged" if msg.message =~ /failed to get Dispatch Interface/
-      end
-    end
-=end
-
     def focus
       self.visible = true
       #if not Windows10 then 

data/lib/robust_excel_ole/reo_common.rb

@@ -8,7 +8,7 @@ File.delete REO_LOG_FILE rescue nil
 
 module RobustExcelOle
 
-  class REOError < RuntimeError                 # :nodoc: #
+  class REOError < RuntimeError                    # :nodoc: #
   end                 
 
   class ExcelREOError < REOError                   # :nodoc: #
@@ -17,6 +17,9 @@ module RobustExcelOle
   class WorkbookREOError < REOError                # :nodoc: #
   end
 
+  class SheetREOError < REOError                   # :nodoc: #
+  end
+
   class FileREOError < REOError                    # :nodoc: #
   end
 
@@ -176,7 +179,7 @@ module RobustExcelOle
       begin
         cell = name_object(name).RefersToRange
         cell.Interior.ColorIndex = opts[:color] 
-        workbook.modified_cells << cell unless cell_modified?(cell) if workbook
+        workbook.modified_cells << cell if workbook #unless cell_modified?(cell)
         cell.Value = value
       rescue WIN32OLERuntimeError
         raise RangeNotEvaluatable, "cannot assign value to range named #{name.inspect} in #{self.inspect}" 
@@ -192,6 +195,7 @@ module RobustExcelOle
     # @option opts [Symbol] :default  the default value that is provided if no contents could be returned
     # @return [Variant] the contents of a range with given name   
     def rangeval(name, opts = {:default => :__not_provided})
+      return nameval(name, opts) if self.is_a?(Book)
       begin
         range = self.Range(name)
       rescue WIN32OLERuntimeError
@@ -227,7 +231,7 @@ module RobustExcelOle
       end
       begin
         range.Interior.ColorIndex = opts[:color]
-        workbook.modified_cells << range unless cell_modified?(range) if workbook
+        workbook.modified_cells << range if workbook #unless cell_modified?(range)
         range.Value = value
       rescue  WIN32OLERuntimeError
         raise RangeNotEvaluatable, "cannot assign value to range named #{name.inspect} in #{self.inspect}"
@@ -248,10 +252,10 @@ module RobustExcelOle
       end
     end
      
-    def cell_modified?(cell)
-      workbook.modified_cells.each{|c| return true if c.Name.Value == cell.Name.Value}    
-      false
-    end
+    #def cell_modified?(cell)
+    #  workbook.modified_cells.each{|c| return true if c.Name.Value == cell.Name.Value}    
+    #  false
+    #end
 
   end
 

data/lib/robust_excel_ole/sheet.rb

@@ -23,7 +23,11 @@ module RobustExcelOle
 
     # returns name of the sheet
     def name
-      @ole_worksheet.Name
+      begin
+        @ole_worksheet.Name
+      rescue
+        raise SheetREOError, "name #{name.inspect} could not be determined"
+      end
     end
 
     # name the sheet
@@ -40,17 +44,16 @@ module RobustExcelOle
       end
     end
 
-    # returns the value of a cell, if row and column are given
-    # returns the value of a range if its name is given 
+    # returns cell, if row and column are given 
     def [] p1, p2 = :__not_provided
       if p2 != :__not_provided  
-        y, x = p1, p2
-        yx = "#{y}_#{x}"
+        x, y = p1, p2
+        xy = "#{x}_#{y}"
         @cells = { }
         begin
-          @cells[yx] = RobustExcelOle::Cell.new(@ole_worksheet.Cells.Item(y, x))
+          @cells[xy] = RobustExcelOle::Cell.new(@ole_worksheet.Cells.Item(x, y))
         rescue
-          raise RangeNotEvaluatable, "cannot read cell (#{p1.inspect},#{p2.inspect})"
+          raise RangeNotEvaluatable, "cannot read cell (#{x.inspect},#{y.inspect})"
         end
       else
         name = p1
@@ -66,14 +69,8 @@ module RobustExcelOle
     # sets the value of a range if its name is given
     def []= (p1, p2, p3 = :__not_provided)
       if p3 != :__not_provided
-        y, x, value = p1, p2, p3
-        begin
-          cell = @ole_worksheet.Cells.Item(y, x)
-          cell.Value = value
-          cell.Interior.ColorIndex = 42 # aqua-marin, 4-green
-        rescue WIN32OLERuntimeError
-          raise RangeNotEvaluatable, "cannot assign value #{p3.inspect} to cell (#{p1.inspect},#{p2.inspect})"
-        end
+        x, y, value = p1, p2, p3
+        set_cellval(x,y,value)       
       else
         name, value = p1, p2
         begin
@@ -87,6 +84,30 @@ module RobustExcelOle
         end
       end
     end
+
+    # returns the value of a cell, if row and column are given
+    def cellval(x,y)
+      xy = "#{x}_#{y}"
+      @cells = { }
+      begin
+        @cells[xy] = RobustExcelOle::Cell.new(@ole_worksheet.Cells.Item(x, y))
+        @cells[xy].Value
+      rescue
+        raise RangeNotEvaluatable, "cannot read cell (#{p1.inspect},#{p2.inspect})"
+      end
+    end
+
+    # sets the value of a cell, if row, column and color of the cell are given
+    def set_cellval(x,y,value, opts = {:color => 0})
+      begin
+        cell = @ole_worksheet.Cells.Item(x, y)        
+        cell.Interior.ColorIndex = opts[:color] # 42 - aqua-marin, 4-green
+        @workbook.modified_cells << cell if @workbook
+        cell.Value = value
+      rescue WIN32OLERuntimeError
+        raise RangeNotEvaluatable, "cannot assign value #{value.inspect} to cell (#{y.inspect},#{x.inspect})"
+      end
+    end
     
     # assigns a name to a range (a cell) given by an address
     # @param [String] name   the range name