robust_excel_ole 1.15 → 1.18.2

data/lib/robust_excel_ole/range_owners.rb

@@ -2,7 +2,7 @@
 
 module RobustExcelOle
 
-  class RangeOwners < REOCommon
+  class RangeOwners < VbaObjects
 
     # returns the contents of a range with given name
     # if the name could not be found or the value could not be determined,
@@ -22,12 +22,13 @@ module RobustExcelOle
         raise
       end
       ole_range = name_obj.RefersToRange
+      worksheet = self if self.is_a?(Worksheet)
       value = begin
         #name_obj.RefersToRange.Value
-        if !::JRUBY_BUG_RANGES       
+        if !::RANGES_JRUBY_BUG       
           ole_range.Value
         else
-          values = RobustExcelOle::Range.new(ole_range).v
+          values = RobustExcelOle::Range.new(ole_range, worksheet).v
           (values.size==1 && values.first.size==1) ? values.first.first : values
         end
       rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException 
@@ -39,10 +40,10 @@ 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 !::RANGES_JRUBY_BUG
             ole_range.Value
           else
-            values = RobustExcelOle::Range.new(ole_range).v
+            values = RobustExcelOle::Range.new(ole_range, worksheet).v
             (values.size==1 && values.first.size==1) ? values.first.first : values
           end
         rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException 
@@ -61,7 +62,8 @@ module RobustExcelOle
     # sets the contents of a range
     # @param [String]  name  the name of a range
     # @param [Variant] value the contents of the range
-    def set_namevalue_glob(name, value, opts = { })  # opts is deprecated
+    # @option opts [Symbol] :color the color of the cell when set
+    def set_namevalue_glob(name, value, opts = { }) 
       begin
         name_obj = begin
           name_object(name)
@@ -69,13 +71,12 @@ module RobustExcelOle
           raise
         end        
         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
+        ole_range.Interior.ColorIndex = opts[:color] unless opts[:color].nil?
+        if !::RANGES_JRUBY_BUG
           ole_range.Value = value
         else
           address_r1c1 = ole_range.AddressLocal(true,true,XlR1C1)
-          row, col = Address.int_range(address_r1c1)
+          row, col = address_tool.as_integer_ranges(address_r1c1)
           row.each_with_index do |r,i|
             col.each_with_index do |c,j|
               ole_range.Cells(i+1,j+1).Value = (value.respond_to?(:first) ? value[i][j] : value )
@@ -105,11 +106,12 @@ module RobustExcelOle
         raise NameNotFound, "name #{name.inspect} not in #{self.inspect}"
       end
       begin
+        worksheet = self if self.is_a?(Worksheet)
         #value = ole_range.Value
-        value = if !::JRUBY_BUG_RANGES
+        value = if !::RANGES_JRUBY_BUG
           ole_range.Value
         else
-          values = RobustExcelOle::Range.new(ole_range).v
+          values = RobustExcelOle::Range.new(ole_range, worksheet).v
           (values.size==1 && values.first.size==1) ? values.first.first : values
         end
       rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException 
@@ -127,21 +129,21 @@ module RobustExcelOle
     # assigns a value to a range given a locally defined name
     # @param [String]  name   the name of a range
     # @param [Variant] value  the assigned value   
-    def set_namevalue(name, value, opts = { })  # opts is deprecated
+    # @option opts [Symbol] :color the color of the cell when set
+    def set_namevalue(name, value, opts = { })  
       begin
-        return set_namevalue_glob(name, value, opts) if self.is_a?(Workbook)  # opts deprecated
+        return set_namevalue_glob(name, value, opts) if self.is_a?(Workbook) 
         ole_range = self.Range(name)
-      rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException
+      rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException, VBAMethodMissingError
         raise NameNotFound, "name #{name.inspect} not in #{self.inspect}"
       end
       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
+        ole_range.Interior.ColorIndex = opts[:color] unless opts[:color].nil?
+        if !::RANGES_JRUBY_BUG
           ole_range.Value = value
         else
           address_r1c1 = ole_range.AddressLocal(true,true,XlR1C1)
-          row, col = Address.int_range(address_r1c1)
+          row, col = address_tool.as_integer_ranges(address_r1c1)
           row.each_with_index do |r,i|
             col.each_with_index do |c,j|
               ole_range.Cells(i+1,j+1).Value = (value.respond_to?(:first) ? value[i][j] : value)
@@ -180,10 +182,11 @@ module RobustExcelOle
     # @return [Range] a range
     def range(name_or_address, address2 = :__not_provided)
       begin
+        worksheet = self if self.is_a?(Worksheet)
         if address2 == :__not_provided
           range = if name_or_address.is_a?(String)
             begin
-              RobustExcelOle::Range.new(name_object(name_or_address).RefersToRange) 
+              RobustExcelOle::Range.new(name_object(name_or_address).RefersToRange, worksheet) 
             rescue NameNotFound
               nil
             end
@@ -192,8 +195,8 @@ module RobustExcelOle
         if self.is_a?(Worksheet) && (range.nil? || (address2 != :__not_provided))
           address = name_or_address
           address = [name_or_address,address2] unless address2 == :__not_provided         
-          self.Names.Add('__dummy001',nil,true,nil,nil,nil,nil,nil,nil,'=' + Address.r1c1(address))          
-          range = RobustExcelOle::Range.new(name_object('__dummy001').RefersToRange)
+          self.Names.Add('__dummy001',nil,true,nil,nil,nil,nil,nil,nil,'=' + address_tool.as_r1c1(address))          
+          range = RobustExcelOle::Range.new(name_object('__dummy001').RefersToRange, worksheet)
           self.Names.Item('__dummy001').Delete
           workbook = self.is_a?(Workbook) ? self : self.workbook
           workbook.save
@@ -216,7 +219,7 @@ module RobustExcelOle
     def add_name(name, addr, addr_deprecated = :__not_provided)
       addr = [addr,addr_deprecated] unless addr_deprecated == :__not_provided
       begin       
-        self.Names.Add(name, nil, true, nil, nil, nil, nil, nil, nil, '=' + Address.r1c1(addr))
+        self.Names.Add(name, nil, true, nil, nil, nil, nil, nil, nil, '=' + address_tool.as_r1c1(addr))
       rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException
         raise RangeNotEvaluatable, "cannot add name #{name.inspect} to range #{addr.inspect}"
       end
@@ -257,13 +260,13 @@ module RobustExcelOle
       rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException
         raise UnexpectedREOError, "name error in #{File.basename(self.stored_filename).inspect}"
       end
-    end
+    end   
 
   private
 
     def name_object(name)
       self.Names.Item(name)
-    rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException
+    rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException, VBAMethodMissingError
       begin
         self.Parent.Names.Item(name)
       rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException
@@ -273,4 +276,16 @@ module RobustExcelOle
 
   end
 
+  # @private
+  class NameNotFound < NamesREOError               
+  end
+
+  # @private
+  class NameAlreadyExists < NamesREOError          
+  end
+
+  # @private
+  class RangeNotCreated < MiscREOError             
+  end  
+
 end

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.15"
+  VERSION = "1.18.2"
 end

data/lib/robust_excel_ole/workbook.rb

@@ -12,32 +12,33 @@ module RobustExcelOle
   class Workbook < RangeOwners
 
     #include General 
-
-    attr_accessor :excel
-    attr_accessor :ole_workbook
-    attr_accessor :stored_filename
-    attr_accessor :color_if_modified
-    attr_accessor :was_open
+    
+    attr_reader :ole_workbook
+    attr_reader :excel
+    attr_reader :stored_filename
 
     alias ole_object ole_workbook
 
-    DEFAULT_OPEN_OPTS = {
-      :default => {:excel => :current},
+    CORE_DEFAULT_OPEN_OPTS = {
+      :default => {:excel => :current}, 
       :force => {},
-      :update_links => :never,
+      :update_links => :never 
+    }.freeze
+
+    DEFAULT_OPEN_OPTS = {
       :if_unsaved    => :raise,
       :if_obstructed => :raise,
       :if_absent     => :raise,
       :if_exists => :raise
-      #:check_compatibility => false
-    }.freeze
+    }.merge(CORE_DEFAULT_OPEN_OPTS).freeze  
 
-    CORE_DEFAULT_OPEN_OPTS = {
-      :default => {:excel => :current}, :force => {}, :update_links => :never
-    }.freeze
-
-    ABBREVIATIONS = [[:default,:d], [:force, :f], [:excel, :e], [:visible, :v],
-                     [:if_obstructed, :if_blocked]].freeze
+    ABBREVIATIONS = [
+      [:default,:d],
+      [:force, :f],
+      [:excel, :e],
+      [:visible, :v],
+      [:if_obstructed, :if_blocked]
+    ].freeze
 
 
     # opens a workbook.
@@ -83,51 +84,59 @@ module RobustExcelOle
     # :visible              true -> makes the workbook visible
     # :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)
-      options = process_options(opts)
-      if file_or_workbook.is_a? WIN32OLE
+    # @return [Workbook] a representation of a workbook   
+    def self.new(file_or_workbook, opts = { })
+      process_options(opts)
+      case file_or_workbook
+      when NilClass
+        raise FileNameNotGiven, 'filename is nil' 
+      when WIN32OLE
         file = file_or_workbook.Fullname.tr('\\','/') 
-      else
+      when Workbook
+        file = file_or_workbook.Fullname.tr('\\','/')
+      when String
         file = file_or_workbook
-        raise(FileNameNotGiven, 'filename is nil') if file.nil?
-        raise(FileNotFound, "file #{General.absolute_path(file).inspect} is a directory") if File.directory?(file)
+        raise FileNotFound, "file #{General.absolute_path(file).inspect} is a directory" if File.directory?(file)
+      else
+        raise TypeREOError, 'given object is neither a filename, a Win32ole, nor a Workbook object'
       end
       # try to fetch the workbook from the bookstore
+      set_was_open opts, file_or_workbook.is_a?(WIN32OLE)
       book = nil
-      if options[:force][:excel] != :new
+      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 = 
-          (options[:force][:excel].nil? || options[:force][:excel] == :current) ? 
-            (excel_class.new(:reuse => true) if !::JRUBY_BUG_CONNECT) : excel_of(options[:force][:excel])              
+        forced_excel = begin
+          (opts[:force][:excel].nil? || opts[:force][:excel] == :current) ? 
+            (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 => !(options[:read_only]),
-                                  :prefer_excel    => (options[:read_only] ? forced_excel : nil))
+            bookstore.fetch(file, :prefer_writable => !(opts[:read_only]),
+                                  :prefer_excel    => (opts[:read_only] ? forced_excel : nil))
           end
         rescue
-          trace "#{$!.message}"
+          raise
+          #trace "#{$!.message}"
         end
         if book 
-          # hack (unless condition): calling Worksheet[]= causes calling Worksheet#workbook which calls Workbook#new(ole_workbook)
-          book.was_open = book.alive? unless file_or_workbook.is_a? WIN32OLE 
+          set_was_open opts, book.alive?
           # drop the fetched workbook if it shall be opened in another Excel instance
           # or the workbook is an unsaved workbook that should not be accepted
-          if (options[:force][:excel].nil? || options[:force][:excel] == :current || forced_excel == book.excel) &&
-            !(book.alive? && !book.saved && (options[:if_unsaved] != :accept))
-            options[:force][:excel] = book.excel if book.excel && book.excel.alive?
-            book.ensure_workbook(file,options)
-            book.set_options(file,options)
+          if (opts[:force][:excel].nil? || opts[:force][:excel] == :current || forced_excel == book.excel) &&
+            !(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.send :apply_options, file, opts
             return book
           end
         end
       end        
-      super(file_or_workbook, options, &block)
+      super(file_or_workbook, opts)
     end
 
-    def self.open(file_or_workbook, opts = { }, &block)
-      new(file_or_workbook, opts, &block)
-    end
+    singleton_class.send :alias_method, :open, :new
 
     # creates a new Workbook object, if a file name is given
     # Promotes the win32ole workbook to a Workbook object, if a win32ole-workbook is given
@@ -135,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)
-      bookstore.store(self)
-      r1c1_letters = @ole_workbook.Worksheets.Item(1).Cells.Item(1,1).Address(true,true,XlR1C1).gsub(/[0-9]/,'') #('ReferenceStyle' => XlR1C1).gsub(/[0-9]/,'')
-      address_class.new(r1c1_letters)
-      if block
+      apply_options(filename, opts)
+      store_myself
+      if block_given?
         begin
           yield self
         ensure
@@ -164,52 +171,46 @@ module RobustExcelOle
  
   private    
 
-    # translates abbreviations and synonyms and merges with default options
-    def self.process_options(options, proc_opts = {:use_defaults => true})
-      translator = proc do |opts|
-        erg = {}
-        opts.each do |key,value|
-          new_key = key
-          ABBREVIATIONS.each { |long,short| new_key = long if key == short }
-          if value.is_a?(Hash)
-            erg[new_key] = {}
-            value.each do |k,v|
-              new_k = k
-              ABBREVIATIONS.each { |l,s| new_k = l if k == s }
-              erg[new_key][new_k] = v
-            end
-          else
-            erg[new_key] = value
-          end
-        end
-        erg[:default] ||= {}
-        erg[:force] ||= {}
-        force_list = [:visible, :excel]
-        erg.each { |key,value| erg[:force][key] = value if force_list.include?(key) }
-        erg[:default][:excel] = erg[:default_excel] unless erg[:default_excel].nil?
-        erg[:force][:excel] = erg[:force_excel] unless erg[:force_excel].nil?
-        erg[:default][:excel] = :current if erg[:default][:excel] == :reuse || erg[:default][:excel] == :active
-        erg[:force][:excel] = :current if erg[:force][:excel] == :reuse || erg[:force][:excel] == :active
-        erg
-      end
-      opts = translator.call(options)
-      default_open_opts = proc_opts[:use_defaults] ? DEFAULT_OPEN_OPTS : CORE_DEFAULT_OPEN_OPTS        
-      default_opts = translator.call(default_open_opts)
-      opts = default_opts.merge(opts)
-      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
+    def self.set_was_open(hash, value)
+      hash[:was_open] = value if hash.has_key?(:was_open)
     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'
+    def set_was_open(hash, value)
+      self.class.set_was_open(hash, value)
+    end
+
+    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| !v2.is_a?(Hash) ? v1 : v2.merge(v1 || {}) }
+    end
+
+    def self.translate(opts)
+      erg = {}
+      opts.each do |key,value|
+        new_key = key
+        ABBREVIATIONS.each { |long,short| new_key = long if key == short }
+        if value.is_a?(Hash)
+          erg[new_key] = {}
+          value.each do |k,v|
+            new_k = k
+            ABBREVIATIONS.each { |l,s| new_k = l if k == s }
+            erg[new_key][new_k] = v
+          end
+        else
+          erg[new_key] = value
+        end
       end
+      opts.merge!(erg)
+      opts[:default] ||= {}
+      opts[:force] ||= {}
+      force_list = [:visible, :excel]
+      opts.each { |key,value| opts[:force][key] = value if force_list.include?(key) }
+      opts[:default][:excel] = opts[:default_excel] unless opts[:default_excel].nil?
+      opts[:force][:excel] = opts[:force_excel] unless opts[:force_excel].nil?
+      opts[:default][:excel] = :current if opts[:default][:excel] == :reuse || opts[:default][:excel] == :active
+      opts[:force][:excel] = :current if opts[:force][:excel] == :reuse || opts[:force][:excel] == :active
     end
 
   public
@@ -218,20 +219,25 @@ module RobustExcelOle
     # 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
       return if (@ole_workbook && alive? && (options[:read_only].nil? || @ole_workbook.ReadOnly == options[:read_only]))
+      set_was_open options, false
       if options[:if_unsaved]==:accept && 
         ((options[:read_only]==true && self.ReadOnly==false) || (options[:read_only]==false && self.ReadOnly==true))
         raise OptionInvalid, ":if_unsaved:accept and change of read-only mode is not possible"
@@ -242,27 +248,28 @@ module RobustExcelOle
       ensure_excel(options)
       workbooks = @excel.Workbooks
       @ole_workbook = workbooks.Item(File.basename(filename)) rescue nil if @ole_workbook.nil?
-      if @ole_workbook
-        @was_open = true if @was_open.nil? # necessary?
+      if @ole_workbook && alive?
+        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 &&  
-          (!::JRUBY_BUG_CONNECT || filename[0] != '/')
-          workbooks_number_before_connect = @excel.Workbooks.Count
+        if (excel_option.nil? || excel_option == :current) &&  
+          !(::CONNECT_JRUBY_BUG && filename[0] == '/')
           connect(filename,options)
-          @was_open = @excel.Workbooks.Count == workbooks_number_before_connect
         else 
           open_or_create_workbook(filename,options)
         end
       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]
@@ -271,40 +278,32 @@ module RobustExcelOle
       end      
     end
 
-  private
-
-    # @private
     # connects to an unknown workbook
-    def connect(filename,options)
-      excels_number = excel_class.excels_number
-      workbooks_number = if excels_number>0 
-        excel_class.current.Workbooks.Count 
-      else 0
-      end
-      abs_filename = General.absolute_path(filename)
+    def connect(filename, options)   
+      workbooks_number = excel_class.excels_number==0 ? 0 : excel_class.current.Workbooks.Count
       @ole_workbook = begin
-        WIN32OLE.connect(abs_filename)
+        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
@@ -322,11 +321,12 @@ module RobustExcelOle
       end
     end
 
-    # @private
-    def manage_blocking_or_unsaved_workbook(filename,options)
-      obstructed_by_other_book = if (File.basename(filename) == File.basename(@ole_workbook.Fullname)) 
-        General.absolute_path(filename) != @ole_workbook.Fullname
-      end      
+    def manage_blocking_or_unsaved_workbook(filename, options)
+      filename = General.absolute_path(filename)
+      filename = General.canonize(filename)
+      previous_file = General.canonize(@ole_workbook.Fullname)
+      obstructed_by_other_book = (File.basename(filename) == File.basename(previous_file)) &&
+                                 (File.dirname(filename) != File.dirname(previous_file)) 
       if obstructed_by_other_book
         # workbook is being obstructed by a workbook with same name and different path
         manage_blocking_workbook(filename,options)        
@@ -338,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},
@@ -353,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
@@ -365,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
@@ -388,34 +387,29 @@ 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 )
       begin
         abs_filename = General.absolute_path(filename)
         begin
-          @was_open = false if @was_open.nil?
           workbooks = @excel.Workbooks
         rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException => msg
           raise UnexpectedREOError, "cannot access workbooks: #{msg.message} #{msg.backtrace}"
@@ -427,7 +421,7 @@ module RobustExcelOle
                                       updatelinks_vba(options[:update_links]), 
                                       options[:read_only] )
           end
-        rescue WIN32OLERuntimeError => msg
+        rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException => msg
           # for Excel2007: for option :if_unsaved => :alert and user cancels: this error appears?
           # if yes: distinguish these events
           raise UnexpectedREOError, "cannot open workbook: #{msg.message} #{msg.backtrace}"
@@ -436,29 +430,27 @@ module RobustExcelOle
           # workaround for bug in Excel 2010: workbook.Open does not always return the workbook when given file name
           begin
             @ole_workbook = workbooks.Item(File.basename(filename))
-          rescue WIN32OLERuntimeError => msg
+          rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException => msg
             raise UnexpectedREOError, "WIN32OLERuntimeError: #{msg.message}"
           end
-        rescue WIN32OLERuntimeError => msg
+        rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException => msg
           raise UnexpectedREOError, "WIN32OLERuntimeError: #{msg.message} #{msg.backtrace}"
         end
       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
     def updatelinks_vba(updatelinks_reo)
       case updatelinks_reo
-      when :alert then RobustExcelOle::XlUpdateLinksUserSetting
-      when :never then RobustExcelOle::XlUpdateLinksNever
+      when :alert  then RobustExcelOle::XlUpdateLinksUserSetting
+      when :never  then RobustExcelOle::XlUpdateLinksNever
       when :always then RobustExcelOle::XlUpdateLinksAlways
-      else RobustExcelOle::XlUpdateLinksNever
+      else              RobustExcelOle::XlUpdateLinksNever
       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
@@ -522,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?
@@ -581,9 +570,10 @@ module RobustExcelOle
       self.class.unobtrusively_opening(file, opts, alive?, &block)
     end
 
-    @private
+  private
+
     def self.unobtrusively_opening(file, opts, book_is_alive, &block)
-      opts = process_options(opts)
+      process_options(opts)
       opts = {:if_closed => :current, :keep_open => false}.merge(opts)    
       raise OptionInvalid, 'contradicting options' if opts[:writable] && opts[:read_only] 
       if book_is_alive.nil?
@@ -598,33 +588,37 @@ module RobustExcelOle
       end
       open_opts = excel_opts.merge({:if_unsaved => :accept})
       begin
+        open_opts[:was_open] = nil
         book = open(file, open_opts)
         was_visible = book.visible
         was_writable = book.writable
         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
-          if book.was_open
+          was_open = open_opts[:was_open]
+          if was_open
             book.visible = was_visible    
             book.CheckCompatibility = was_check_compatibility
             book.excel.calculation = was_calculation
           end
-          book.Saved = (was_saved || !book.was_open)
-          book.close unless book.was_open || opts[:keep_open]
+          book.Saved = (was_saved || !was_open)
+          book.close unless was_open || opts[:keep_open]
         end
       end
     end
 
+  public 
+
     # reopens a closed workbook
     # @options options
     def reopen(options = { })
@@ -638,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
@@ -671,12 +661,12 @@ module RobustExcelOle
     #                  :close_if_saved      -> closes the blocking workbook, if it is saved,
     #                                          otherwise raises an exception   
     # @return [Workbook], the book itself, if successfully saved, raises an exception otherwise
-    def save_as(file, opts = { })
+    def save_as(file, options = { })
       raise FileNameNotGiven, 'filename is nil' if file.nil?
       raise ObjectNotAlive, 'workbook is not alive' unless alive?
       raise WorkbookReadOnly, 'Not opened for writing (opened with :read_only option)' if @ole_workbook.ReadOnly
       raise(FileNotFound, "file #{General.absolute_path(file).inspect} is a directory") if File.directory?(file)
-      options = self.class.process_options(opts)      
+      self.class.process_options(options)      
       if File.exist?(file)
         case options[:if_exists]
         when :overwrite
@@ -731,7 +721,6 @@ module RobustExcelOle
 
   private
 
-    # @private
     def save_as_workbook(file, options)  
       dirname, basename = File.split(file)
       file_format =
@@ -741,7 +730,7 @@ module RobustExcelOle
         when '.xlsm' then RobustExcelOle::XlOpenXMLWorkbookMacroEnabled
         end
       @ole_workbook.SaveAs(General.absolute_path(file), file_format)
-      bookstore.store(self)
+      store_myself
     rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException => msg
       if msg.message =~ /SaveAs/ && msg.message =~ /Workbook/
         # trace "save: canceled by user" if options[:if_exists] == :alert || options[:if_exists] == :excel
@@ -751,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
@@ -789,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|
@@ -819,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 !::JRUBY_BUG_COPYSHEETS
-          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
@@ -857,14 +843,23 @@ module RobustExcelOle
       rescue WIN32OLERuntimeError, NameNotFound, Java::OrgRacobCom::ComFailException
         raise WorksheetREOError, "could not add given worksheet #{sheet.inspect}"
       end
-      #ole_sheet = @excel.Activesheet
-      ole_sheet = ole_workbook.Activesheet
-      #ole_sheet = ole_sheet.nil? ? ole_workbook.Worksheets.Item(ole_workbook.Worksheets.Count) : ole_sheet
-      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)
@@ -894,30 +889,15 @@ module RobustExcelOle
     # @param [String]  name  the name of the range
     # @param [Variant] value the contents of the range
     def []= (name, value)
-      old_color_if_modified = @color_if_modified
-      workbook.color_if_modified = 42  # 42 - aqua-marin, 4-green
-      set_namevalue_glob(name,value)   
-      workbook.color_if_modified = old_color_if_modified
+      set_namevalue_glob(name, value, :color => 42)   
     end
 
     # sets options
     # @param [Hash] opts
     def for_this_workbook(opts)
       return unless alive?
-      opts = 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.class.process_options(opts, :use_defaults => false)
+      self.send :apply_options, @stored_filename, opts
     end
 
     # brings workbook to foreground, makes it available for heyboard inputs, makes the Excel instance visible
@@ -933,7 +913,6 @@ module RobustExcelOle
       true
     rescue
       @ole_workbook = nil  # dead object won't be alive again
-      # t $!.message
       false
     end
 
@@ -995,6 +974,7 @@ module RobustExcelOle
         self.filename == other_book.filename
     end
 
+    # @private
     def self.books
       bookstore.books
     end
@@ -1045,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
@@ -1065,11 +1035,6 @@ module RobustExcelOle
       self.class.worksheet_class
     end
 
-    # @private
-    def address_class        
-      self.class.address_class
-    end
-
     include MethodHelpers
 
   private
@@ -1077,7 +1042,7 @@ module RobustExcelOle
     def method_missing(name, *args) 
       if name.to_s[0,1] =~ /[A-Z]/
         raise ObjectNotAlive, 'method missing: workbook not alive' unless alive?
-        if ::JRUBY_BUG_ERRORMESSAGE 
+        if ::ERRORMESSAGE_JRUBY_BUG 
           begin
             @ole_workbook.send(name, *args)
           rescue Java::OrgRacobCom::ComFailException 
@@ -1099,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