robust_excel_ole 1.16 → 1.18.3

data/lib/robust_excel_ole/vba_objects.rb

@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+
+module RobustExcelOle
+
+  class VbaObjects < Base
+
+    def to_reo
+      self
+    end
+
+    # @private
+    def address_tool
+      excel.address_tool
+    end
+
+  end
+
+  # @private
+  class RangeNotEvaluatable < MiscREOError         
+  end
+
+  # @private
+  class OptionInvalid < MiscREOError               
+  end
+
+  # @private
+  class ObjectNotAlive < MiscREOError              
+  end
+
+end

data/lib/robust_excel_ole/version.rb

@@ -1,3 +1,3 @@
 module RobustExcelOle
-  VERSION = "1.16"
+  VERSION = "1.18.3"
 end

data/lib/robust_excel_ole/workbook.rb

@@ -22,7 +22,7 @@ module RobustExcelOle
     CORE_DEFAULT_OPEN_OPTS = {
       :default => {:excel => :current}, 
       :force => {},
-      :update_links => :never
+      :update_links => :never 
     }.freeze
 
     DEFAULT_OPEN_OPTS = {
@@ -85,7 +85,7 @@ module RobustExcelOle
     # :check_compatibility  true -> check compatibility when saving
     # :update_links         true -> user is being asked how to update links, false -> links are never updated
     # @return [Workbook] a representation of a workbook   
-    def self.new(file_or_workbook, opts = { }, &block)
+    def self.new(file_or_workbook, opts = { })
       process_options(opts)
       case file_or_workbook
       when NilClass
@@ -93,7 +93,7 @@ module RobustExcelOle
       when WIN32OLE
         file = file_or_workbook.Fullname.tr('\\','/') 
       when Workbook
-        return file_or_workbook
+        file = file_or_workbook.Fullname.tr('\\','/')
       when String
         file = file_or_workbook
         raise FileNotFound, "file #{General.absolute_path(file).inspect} is a directory" if File.directory?(file)
@@ -105,9 +105,12 @@ module RobustExcelOle
       book = nil
       if opts[:force][:excel] != :new
         # if readonly is true, then prefer a book that is given in force_excel if this option is set              
-        forced_excel = 
+        forced_excel = begin
           (opts[:force][:excel].nil? || opts[:force][:excel] == :current) ? 
-            (excel_class.new(:reuse => true) if !::CONNECT_JRUBY_BUG) : excel_of(opts[:force][:excel])              
+            (excel_class.new(:reuse => true) if !::CONNECT_JRUBY_BUG) : opts[:force][:excel].to_reo.excel
+        rescue NoMethodError
+          raise TypeREOError, "provided Excel option value is neither an Excel object nor a valid option"
+        end
         begin
           book = if File.exists?(file)
             bookstore.fetch(file, :prefer_writable => !(opts[:read_only]),
@@ -115,7 +118,7 @@ module RobustExcelOle
           end
         rescue
           raise
-          trace "#{$!.message}"
+          #trace "#{$!.message}"
         end
         if book 
           set_was_open opts, book.alive?
@@ -125,12 +128,12 @@ module RobustExcelOle
             !(book.alive? && !book.saved && (opts[:if_unsaved] != :accept))
             opts[:force][:excel] = book.excel if book.excel && book.excel.alive?
             book.ensure_workbook(file,opts)
-            book.set_options(file,opts)
+            book.send :apply_options, file, opts
             return book
           end
         end
       end        
-      super(file_or_workbook, opts, &block)
+      super(file_or_workbook, opts)
     end
 
     singleton_class.send :alias_method, :open, :new
@@ -141,25 +144,23 @@ module RobustExcelOle
     # @param [Hash]    opts             
     # @option opts [Symbol] see above
     # @return [Workbook] a workbook
-    def initialize(file_or_workbook, options, &block)
+    def initialize(file_or_workbook, opts)
       if file_or_workbook.is_a? WIN32OLE
         @ole_workbook = file_or_workbook
-        ole_excel = begin
-          WIN32OLE.connect(@ole_workbook.Fullname).Application
-        rescue
+        ole_excel = begin 
+          @ole_workbook.Application
+        rescue WIN32OLERuntimeError
           raise ExcelREOError, 'could not determine the Excel instance'
         end
         @excel = excel_class.new(ole_excel)
-        filename = file_or_workbook.Fullname.tr('\\','/') 
+        filename = @ole_workbook.Fullname.tr('\\','/') 
       else
         filename = file_or_workbook            
-        ensure_workbook(filename, options)        
+        ensure_workbook(filename, opts)        
       end      
-      set_options(filename, options)
+      apply_options(filename, opts)
       store_myself
-      r1c1_letters = @ole_workbook.Worksheets.Item(1).Cells.Item(1,1).Address(true,true,XlR1C1).gsub(/[0-9]/,'')
-      address_class.new(r1c1_letters)
-      if block
+      if block_given?
         begin
           yield self
         ensure
@@ -170,28 +171,21 @@ module RobustExcelOle
  
   private    
 
-    # @private
     def self.set_was_open(hash, value)
       hash[:was_open] = value if hash.has_key?(:was_open)
     end
 
-    # @private
     def set_was_open(hash, value)
       self.class.set_was_open(hash, value)
     end
 
-    # @private
-    # translates abbreviations and synonyms and merges with default options
     def self.process_options(opts, proc_opts = {:use_defaults => true})
       translate(opts)
       default_opts = (proc_opts[:use_defaults] ? DEFAULT_OPEN_OPTS : CORE_DEFAULT_OPEN_OPTS).dup
       translate(default_opts)
-      opts.merge!(default_opts) {|key, v1, v2| v1 }
-      opts[:default] = default_opts[:default].merge(opts[:default]) unless opts[:default].nil?
-      opts[:force] = default_opts[:force].merge(opts[:force]) unless opts[:force].nil?
+      opts.merge!(default_opts) { |key, v1, v2| !v2.is_a?(Hash) ? v1 : v2.merge(v1 || {}) }
     end
 
-    # @private
     def self.translate(opts)
       erg = {}
       opts.each do |key,value|
@@ -219,34 +213,26 @@ module RobustExcelOle
       opts[:force][:excel] = :current if opts[:force][:excel] == :reuse || opts[:force][:excel] == :active
     end
 
-    # returns an Excel object when given Excel, Workbook or Win32ole object representing a Workbook or an Excel
-    # @private
-    def self.excel_of(object) 
-      begin
-        object = object.to_reo if object.is_a? WIN32OLE
-        object.excel
-      rescue
-        raise TypeREOError, 'given object is neither an Excel, a Workbook, nor a Win32ole'
-      end
-    end
-
   public
 
     # @private
     # ensures an excel but not for jruby if current Excel shall be used
     def ensure_excel(options)
       return if @excel && @excel.alive?
-      excel_option = options[:force][:excel].nil? ? options[:default][:excel] : options[:force][:excel]
+      excel_option = options[:force][:excel] || options[:default][:excel] || :current
       @excel = if excel_option == :new
         excel_class.new(:reuse => false) 
-      elsif excel_option.nil? || excel_option == :current
+      elsif excel_option == :current
         excel_class.new(:reuse => true)
+      elsif excel_option.respond_to?(:to_reo)
+        excel_option.to_reo.excel
       else
-        self.class.excel_of(excel_option)
+        raise TypeREOError, "provided Excel option value is neither an Excel object nor a valid option"
       end
-      raise ExcelREOError, "excel is not alive" unless @excel && @excel.alive?
+      raise ExcelREOError, "Excel is not alive" unless @excel && @excel.alive?
     end
 
+
     # @private    
     def ensure_workbook(filename, options)  
       set_was_open options, true
@@ -263,12 +249,12 @@ module RobustExcelOle
       workbooks = @excel.Workbooks
       @ole_workbook = workbooks.Item(File.basename(filename)) rescue nil if @ole_workbook.nil?
       if @ole_workbook && alive?
-        set_was_open options, true #if @was_open.nil? # necessary?
+        set_was_open options, true
         manage_blocking_or_unsaved_workbook(filename,options)
         open_or_create_workbook(filename,options) if @ole_workbook.ReadOnly != options[:read_only]
       else
-        if excel_option.nil? || excel_option == :current &&  
-          (!::CONNECT_JRUBY_BUG || filename[0] != '/')
+        if (excel_option.nil? || excel_option == :current) &&  
+          !(::CONNECT_JRUBY_BUG && filename[0] == '/')
           connect(filename,options)
         else 
           open_or_create_workbook(filename,options)
@@ -276,11 +262,14 @@ module RobustExcelOle
       end       
     end
 
-    # @private
-    def set_options(filename, options)
-      # changing read-only mode
+  private
+
+    # applies options to workbook named with filename
+    def apply_options(filename, options)
+      # changing read-only mode      
+      #ensure_workbook(filename, options) if options[:read_only] && options[:read_only] != @ole_workbook.ReadOnly
       if (!options[:read_only].nil?) && options[:read_only] != @ole_workbook.ReadOnly
-        ensure_workbook(filename, options)
+        ensure_workbook(filename, options) 
       end
       retain_saved do
         self.visible = options[:force][:visible].nil? ? @excel.Visible : options[:force][:visible]
@@ -289,36 +278,32 @@ module RobustExcelOle
       end      
     end
 
-  private
-
-    # @private
     # connects to an unknown workbook
-    def connect(filename,options)   
+    def connect(filename, options)   
       workbooks_number = excel_class.excels_number==0 ? 0 : excel_class.current.Workbooks.Count
       @ole_workbook = begin
         WIN32OLE.connect(General.absolute_path(filename))
       rescue
         if $!.message =~ /moniker/
-          raise WorkbookConnectingBlockingError
-        else
-          raise WorkbookConnectingUnknownError
+          raise WorkbookConnectingBlockingError, "some workbook is blocking when connecting"
+        else 
+          raise WorkbookConnectingUnknownError, "unknown error when connecting to a workbook"
         end
       end
       ole_excel = begin
         @ole_workbook.Application     
       rescue 
         if $!.message =~ /dispid/
-          raise WorkbookConnectingUnsavedError
-        else
-          raise WorkbookConnectingUnknownError
+          raise WorkbookConnectingUnsavedError, "workbook is unsaved when connecting"
+        else 
+          raise WorkbookConnectingUnknownError, "unknown error when connecting to a workbook"
         end
       end
       set_was_open options, (ole_excel.Workbooks.Count == workbooks_number)
       @excel = excel_class.new(ole_excel)
     end
 
-    # @private
-    def manage_nonexisting_file(filename,options)   
+    def manage_nonexisting_file(filename, options)   
       return if File.exist?(filename)
       abs_filename = General.absolute_path(filename)
       if options[:if_absent] == :create
@@ -336,8 +321,7 @@ module RobustExcelOle
       end
     end
 
-    # @private
-    def manage_blocking_or_unsaved_workbook(filename,options)
+    def manage_blocking_or_unsaved_workbook(filename, options)
       filename = General.absolute_path(filename)
       filename = General.canonize(filename)
       previous_file = General.canonize(@ole_workbook.Fullname)
@@ -354,8 +338,7 @@ module RobustExcelOle
       end        
     end
 
-    # @private
-    def manage_blocking_workbook(filename,options)
+    def manage_blocking_workbook(filename, options)
       case options[:if_obstructed]
       when :raise
         raise WorkbookBlocked, "can't open workbook #{filename},
@@ -369,7 +352,8 @@ module RobustExcelOle
         manage_saving_workbook(filename, options)        
       when :close_if_saved
         if !@ole_workbook.Saved
-          raise WorkbookBlocked, "workbook with the same name in a different path is unsaved: #{@ole_workbook.Fullname.tr('\\','/')}"
+          raise WorkbookBlocked, "workbook with the same name in a different path is unsaved: #{@ole_workbook.Fullname.tr('\\','/')}" +
+          "\nHint: Use the option :if_blocked => :save to save the workbook"
         else
           manage_forgetting_workbook(filename, options)
         end
@@ -381,15 +365,14 @@ module RobustExcelOle
       end
     end
 
-    # @private
-    def manage_unsaved_workbook(filename,options)
+    def manage_unsaved_workbook(filename, options)
       case options[:if_unsaved]
       when :raise
         raise WorkbookNotSaved, "workbook is already open but not saved: #{File.basename(filename).inspect}" +
         "\nHint: Save the workbook or open the workbook using option :if_unsaved with values :forget and :accept to
          close the unsaved workbook and reopen it, or to let the unsaved workbook open, respectively"
       when :forget
-        manage_forgetting_workbook(filename,options)
+        manage_forgetting_workbook(filename, options)
       when :accept
         # do nothing
       when :save
@@ -404,27 +387,23 @@ module RobustExcelOle
       end
     end
 
-    # @private
     def manage_forgetting_workbook(filename, options)
       @excel.with_displayalerts(false) { @ole_workbook.Close }
       @ole_workbook = nil
       open_or_create_workbook(filename, options)
     end
 
-    # @private
     def manage_saving_workbook(filename, options)
       save unless @ole_workbook.Saved
       manage_forgetting_workbook(filename, options)
     end
 
-    # @private
     def manage_new_excel(filename, options)
       @excel = excel_class.new(:reuse => false)
       @ole_workbook = nil
       open_or_create_workbook(filename, options)
     end
     
-    # @private
     def open_or_create_workbook(filename, options)
       return if @ole_workbook && options[:if_unsaved] != :alert && options[:if_unsaved] != :excel &&
         (options[:read_only].nil? || options[:read_only]==@ole_workbook.ReadOnly )
@@ -460,7 +439,6 @@ module RobustExcelOle
       end
     end    
            
-    # @private
     # translating the option UpdateLinks from REO to VBA
     # setting UpdateLinks works only if calculation mode is automatic,
     # parameter 'UpdateLinks' has no effect
@@ -473,7 +451,6 @@ module RobustExcelOle
       end
     end
 
-    # @private
     # workaround for linked workbooks for Excel 2007:
     # opening and closing a dummy workbook if Excel has no workbooks.
     # delay: with visible: 0.2 sec, without visible almost none
@@ -537,13 +514,10 @@ module RobustExcelOle
       else
         close_workbook
       end
-      # trace "close: canceled by user" if alive? &&
-      #  (opts[:if_unsaved] == :alert || opts[:if_unsaved] == :excel) && (not @ole_workbook.Saved)
     end
 
   private
 
-    # @private
     def close_workbook
       @ole_workbook.Close if alive?
       @ole_workbook = nil unless alive?
@@ -596,7 +570,8 @@ module RobustExcelOle
       self.class.unobtrusively_opening(file, opts, alive?, &block)
     end
 
-    @private
+  private
+
     def self.unobtrusively_opening(file, opts, book_is_alive, &block)
       process_options(opts)
       opts = {:if_closed => :current, :keep_open => false}.merge(opts)    
@@ -620,15 +595,15 @@ module RobustExcelOle
         was_saved = book.saved
         was_check_compatibility = book.check_compatibility
         was_calculation = book.excel.properties[:calculation]
-        book.set_options(file,opts) 
+        book.send :apply_options, file, opts
         yield book
       ensure
         if book && book.alive?
           do_not_write = opts[:read_only] || opts[:writable]==false
           book.save unless book.saved || do_not_write || !book.writable
           if (opts[:read_only] && was_writable) || (!opts[:read_only] && !was_writable)
-            book.set_options(file, opts.merge({:read_only => !was_writable, 
-                                               :if_unsaved => (opts[:writable]==false ? :forget : :save)}))
+            book.send :apply_options, file, opts.merge({:read_only => !was_writable, 
+                                            :if_unsaved => (opts[:writable]==false ? :forget : :save)})
           end
           was_open = open_opts[:was_open]
           if was_open
@@ -642,6 +617,8 @@ module RobustExcelOle
       end
     end
 
+  public 
+
     # reopens a closed workbook
     # @options options
     def reopen(options = { })
@@ -655,10 +632,6 @@ module RobustExcelOle
     def save(opts = { })  # option opts is deprecated #
       raise ObjectNotAlive, 'workbook is not alive' unless alive?
       raise WorkbookReadOnly, 'Not opened for writing (opened with :read_only option)' if @ole_workbook.ReadOnly   
-      # if you have open the workbook with :read_only => true,
-      # then you could close the workbook and open it again with option :read_only => false
-      # otherwise the workbook may already be open writable in an another Excel instance
-      # then you could use this workbook or close the workbook there
       begin
         @ole_workbook.Save
       rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException => msg
@@ -748,12 +721,6 @@ module RobustExcelOle
 
   private
 
-    def store_myself
-      bookstore.store(self)
-      @stored_filename = filename
-    end
-
-    # @private
     def save_as_workbook(file, options)  
       dirname, basename = File.split(file)
       file_format =
@@ -773,6 +740,11 @@ module RobustExcelOle
       end
     end
 
+    def store_myself
+      bookstore.store(self)
+      @stored_filename = filename
+    end
+
   public
 
     # closes a given file if it is open
@@ -811,12 +783,22 @@ module RobustExcelOle
       raise NameNotFound, "could not return a sheet with name #{name.inspect}"
     end
 
+    def worksheets_count
+      @ole_workbook.Worksheets.Count
+    end
+
     def each
       @ole_workbook.Worksheets.each do |sheet|
         yield worksheet_class.new(sheet)
       end
     end
 
+    def worksheets
+      result = []
+      each { |worksheet| result << worksheet }   
+      result
+    end
+
     def each_with_index(offset = 0)
       i = offset
       @ole_workbook.Worksheets.each do |sheet|
@@ -841,36 +823,18 @@ module RobustExcelOle
       new_sheet_name = opts.delete(:as)
       last_sheet_local = last_sheet
       after_or_before, base_sheet = opts.to_a.first || [:after, last_sheet_local]
+      base_sheet_ole = base_sheet.ole_worksheet
       begin
-        if !::COPYSHEETS_JRUBY_BUG
-          if sheet
-            sheet.Copy({ after_or_before.to_s => base_sheet.ole_worksheet })
-          else
-            @ole_workbook.Worksheets.Add({ after_or_before.to_s => base_sheet.ole_worksheet })
-            #@ole_workbook.Worksheets.Item(ole_workbook.Worksheets.Count).Activate
-          end
+        if !::COPYSHEETS_JRUBY_BUG          
+          add_or_copy_sheet_simple(sheet, { after_or_before.to_s => base_sheet_ole })
         else
           if after_or_before == :before 
-            if sheet
-              sheet.Copy(base_sheet.ole_worksheet)
-            else
-              ole_workbook.Worksheets.Add(base_sheet.ole_worksheet)
-            end
+            add_or_copy_sheet_simple(sheet, base_sheet_ole)
           else
-            #not_given = WIN32OLE_VARIANT.new(nil, WIN32OLE::VARIANT::VT_NULL)
-            #ole_workbook.Worksheets.Add(not_given,base_sheet.ole_worksheet)          
             if base_sheet.name != last_sheet_local.name
-              if sheet
-                sheet.Copy(base_sheet.Next)
-              else
-                ole_workbook.Worksheets.Add(base_sheet.Next)
-              end
+              add_or_copy_sheet_simple(sheet, base_sheet.Next)
             else
-              if sheet
-                sheet.Copy(base_sheet.ole_worksheet)  
-              else
-                ole_workbook.Worksheets.Add(base_sheet.ole_worksheet) 
-              end
+              add_or_copy_sheet_simple(sheet, base_sheet_ole)
               base_sheet.Move(ole_workbook.Worksheets.Item(ole_workbook.Worksheets.Count-1))
               ole_workbook.Worksheets.Item(ole_workbook.Worksheets.Count).Activate
             end
@@ -879,12 +843,23 @@ module RobustExcelOle
       rescue WIN32OLERuntimeError, NameNotFound, Java::OrgRacobCom::ComFailException
         raise WorksheetREOError, "could not add given worksheet #{sheet.inspect}"
       end
-      ole_sheet = ole_workbook.Activesheet
-      new_sheet = worksheet_class.new(ole_sheet)
+      new_sheet = worksheet_class.new(ole_workbook.Activesheet)
       new_sheet.name = new_sheet_name if new_sheet_name
       new_sheet
     end
 
+  private
+  
+    def add_or_copy_sheet_simple(sheet, base_sheet_ole_or_hash)
+      if sheet
+        sheet.Copy(base_sheet_ole_or_hash)  
+      else
+        ole_workbook.Worksheets.Add(base_sheet_ole_or_hash) 
+      end
+    end 
+
+  public
+
     # for compatibility to older versions
     def add_sheet(sheet = nil, opts = { })
       add_or_copy_sheet(sheet, opts)
@@ -914,7 +889,7 @@ module RobustExcelOle
     # @param [String]  name  the name of the range
     # @param [Variant] value the contents of the range
     def []= (name, value)
-      set_namevalue_glob(name,value,:color => 42)   
+      set_namevalue_glob(name, value, :color => 42)   
     end
 
     # sets options
@@ -922,19 +897,7 @@ module RobustExcelOle
     def for_this_workbook(opts)
       return unless alive?
       self.class.process_options(opts, :use_defaults => false)
-      visible_before = visible
-      check_compatibility_before = check_compatibility
-      unless opts[:read_only].nil?
-        # if the ReadOnly status shall be changed, then close and reopen it
-        if (!writable && !(opts[:read_only])) || (writable && opts[:read_only])
-          opts[:check_compatibility] = check_compatibility if opts[:check_compatibility].nil?
-          close(:if_unsaved => true)
-          open_or_create_workbook(@stored_filename, opts)
-        end
-      end
-      self.visible = opts[:force][:visible].nil? ? visible_before : opts[:force][:visible]
-      self.CheckCompatibility = opts[:check_compatibility].nil? ? check_compatibility_before : opts[:check_compatibility]
-      @excel.calculation = opts[:calculation] unless opts[:calculation].nil?
+      self.send :apply_options, @stored_filename, opts
     end
 
     # brings workbook to foreground, makes it available for heyboard inputs, makes the Excel instance visible
@@ -950,7 +913,6 @@ module RobustExcelOle
       true
     rescue
       @ole_workbook = nil  # dead object won't be alive again
-      # t $!.message
       false
     end
 
@@ -1012,6 +974,7 @@ module RobustExcelOle
         self.filename == other_book.filename
     end
 
+    # @private
     def self.books
       bookstore.books
     end
@@ -1062,16 +1025,6 @@ module RobustExcelOle
       end
     end
 
-    # @private
-    def self.address_class    
-      @address_class ||= begin
-        module_name = self.parent_name
-        "#{module_name}::Address".constantize
-      rescue NameError => e
-        Address
-      end
-    end
-
     # @private
     def excel_class        
       self.class.excel_class
@@ -1082,11 +1035,6 @@ module RobustExcelOle
       self.class.worksheet_class
     end
 
-    # @private
-    def address_class        
-      self.class.address_class
-    end
-
     include MethodHelpers
 
   private
@@ -1116,6 +1064,47 @@ module RobustExcelOle
 
 public
 
+  # @private
+  class WorkbookBlocked < WorkbookREOError         
+  end
+
+  # @private
+  class WorkbookNotSaved < WorkbookREOError        
+  end
+
+  # @private
+  class WorkbookReadOnly < WorkbookREOError        
+  end
+
+  # @private
+  class WorkbookBeingUsed < WorkbookREOError       
+  end
+
+  # @private
+  class WorkbookConnectingUnsavedError < WorkbookREOError        
+  end
+
+  # @private
+  class WorkbookConnectingBlockingError < WorkbookREOError       
+  end
+
+  # @private
+  class WorkbookConnectingUnknownError < WorkbookREOError       
+  end
+
+  # @private
+  class FileAlreadyExists < FileREOError           
+  end
+
+  # @private
+  class FileNameNotGiven < FileREOError            
+  end
+
+  # @private
+  class FileNotFound < FileREOError                
+  end
+  
+  
   Book = Workbook
 
 end