robust_excel_ole 1.27 → 1.32

data/lib/robust_excel_ole/range_owners.rb

@@ -14,17 +14,15 @@ module RobustExcelOle
     # @param  [Hash]        opts      the options
     # @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 namevalue_glob(name, opts = { :default => :__not_provided })
+    def namevalue_global(name, opts = { default: :__not_provided })
       name_obj = begin
-        name_object(name)
+        get_name_object(name)
       rescue NameNotFound => msg
-        return opts[:default] unless opts[:default] == :__not_provided
         raise
       end
       ole_range = name_obj.RefersToRange
       worksheet = self if self.is_a?(Worksheet)
       value = begin
-        #name_obj.RefersToRange.Value
         if !::RANGES_JRUBY_BUG       
           ole_range.Value
         else
@@ -33,11 +31,9 @@ module RobustExcelOle
         end
       rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException 
         sheet = if self.is_a?(Worksheet) then self
-                elsif self.is_a?(Workbook) then self.sheet(1)
-                elsif self.is_a?(Excel) then self.workbook.sheet(1)
+        elsif self.is_a?(Workbook) then self.sheet(1)
         end
         begin
-          #sheet.Evaluate(name_obj.Name).Value
           # does it result in a range?
           ole_range = sheet.Evaluate(name_obj.Name)
           if !::RANGES_JRUBY_BUG
@@ -63,111 +59,42 @@ module RobustExcelOle
     # @param [String]  name  the name of a range
     # @param [Variant] value the contents of the range
     # @option opts [Symbol] :color the color of the range when set
-    def set_namevalue_glob(name, value, opts = { }) 
-      begin
-        name_obj = begin
-          name_object(name)
-        rescue NameNotFound => msg
-          raise
-        end        
-        ole_range = name_object(name).RefersToRange
-        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_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 )
-            end
+    def set_namevalue_global(name, value, opts = { }) 
+      name_obj = begin
+        get_name_object(name)
+      rescue NameNotFound => msg
+        raise
+      end        
+      ole_range = name_obj.RefersToRange
+      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_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?(:pop) ? value[i][j] : value )
           end
         end
-        value
-      rescue #WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException
-        raise RangeNotEvaluatable, "cannot assign value to range named #{name.inspect} in #{self.inspect}"
-      end
-    end
-
-    # returns the contents of a range with a locally defined name
-    # evaluates the formula if the contents is a formula
-    # if the name could not be found or the range or value could not be determined,
-    # then return default value, if provided, raise error otherwise
-    # @param  [String]      name      the name of a range
-    # @param  [Hash]        opts      the options
-    # @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 namevalue(name, opts = { :default => :__not_provided })
-      return namevalue_glob(name, opts) if self.is_a?(Workbook)
-      begin
-        ole_range = self.Range(name)
-      rescue # WIN32OLERuntimeError, VBAMethodMissingError, Java::OrgRacobCom::ComFailException 
-        return opts[:default] unless opts[:default] == :__not_provided
-        raise NameNotFound, "name #{name.inspect} not in #{self.inspect}"
-      end
-      begin
-        worksheet = self if self.is_a?(Worksheet)
-        #value = ole_range.Value
-        value = if !::RANGES_JRUBY_BUG
-          ole_range.Value
-        else
-          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 
-        return opts[:default] unless opts[:default] == :__not_provided
-        raise RangeNotEvaluatable, "cannot determine value of range named #{name.inspect} in #{self.inspect}"
-      end
-      if value == -2146828288 + RobustExcelOle::XlErrName
-        return opts[:default] unless opts[:default] == __not_provided
-        raise RangeNotEvaluatable, "cannot evaluate range named #{name.inspect} in #{File.basename(workbook.stored_filename).inspect rescue nil}"
       end
-      return opts[:default] unless (opts[:default] == :__not_provided) || value.nil?
       value
-    end
-
-    # 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   
-    # @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) 
-        ole_range = self.Range(name)
-      rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException, VBAMethodMissingError
-        raise NameNotFound, "name #{name.inspect} not in #{self.inspect}"
-      end
-      begin
-        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_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)
-            end
-          end
-        end
-        value
-      rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException
-        raise RangeNotEvaluatable, "cannot assign value to range named #{name.inspect} in #{self.inspect}"
-      end
+    rescue #WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException
+      raise RangeNotEvaluatable, "cannot assign value to range named #{name.inspect} in #{self.inspect}\n#{$!.message}"
     end
 
     # @private
-    def nameval(name, opts = { :default => :__not_provided })   # :deprecated: #
-      namevalue_glob(name, opts)
+    def nameval(name, opts = { default: :__not_provided })   # :deprecated: #
+      namevalue_global(name, opts)
     end
 
     # @private
     def set_nameval(name, value)        # :deprecated: #
-      set_namevalue_glob(name, value)
+      set_namevalue_global(name, value)
     end
 
     # @private
-    def rangeval(name, opts = { :default => :__not_provided })  # :deprecated: #
+    def rangeval(name, opts = { default: :__not_provided })  # :deprecated: #
       namevalue(name, opts)
     end
 
@@ -192,53 +119,45 @@ module RobustExcelOle
     # @params [Address] address of the range
     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_tool.as_r1c1(addr))
-      rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException
-        raise RangeNotEvaluatable, "cannot add name #{name.inspect} to range #{addr.inspect}"
-      end
+      self.Names.Add(name, nil, true, nil, nil, nil, nil, nil, nil, '=' + address_tool.as_r1c1(addr))
       name
+    rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException
+      raise RangeNotEvaluatable, "cannot add name #{name.inspect} to range #{addr.inspect}\n#{$!.message}"
     end
 
-    def set_name(name,row,column)     # :deprecated :#
-      add_name(name,row,column)
+    alias set_name add_name  # :deprecated :#
+
+    # renames an Excel object
+    # @param [String] old_name the previous name of the Excel object
+    # @param [String] new_name the new name of the Excel object
+    def rename_name(old_name, new_name)
+      item = get_name_object(old_name)
+      item.Name = new_name
+    rescue RobustExcelOle::NameNotFound
+      raise
+    rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException => msg
+      raise UnexpectedREOError, "name error with name #{old_name.inspect} in #{File.basename(self.stored_filename).inspect}\n#{$!.message}"
     end
 
-    # renames a range
-    # @param [String] name     the previous range name
-    # @param [String] new_name the new range name
-    def rename_range(name, new_name)
-      begin
-        item = self.Names.Item(name)
-      rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException => msg
-        raise NameNotFound, "name #{name.inspect} not in #{File.basename(self.stored_filename).inspect}"
-      end
-      begin
-        item.Name = new_name
-      rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException => msg
-        raise UnexpectedREOError, "name error in #{File.basename(self.stored_filename).inspect}"
-      end
-    end
+    alias rename_range rename_name  # :deprecated :#
 
-    # deletes a name of a range
-    # @param [String] name     the previous range name
-    # @param [String] new_name the new range name
+    # deletes a name of an Excel object
+    # @param [String] name    the name of the Excel object
     def delete_name(name)
-      begin
-        item = self.Names.Item(name)
-      rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException
-        raise NameNotFound, "name #{name.inspect} not in #{File.basename(self.stored_filename).inspect}"
-      end
-      begin
-        item.Delete
-      rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException
-        raise UnexpectedREOError, "name error in #{File.basename(self.stored_filename).inspect}"
-      end
-    end   
+      item = get_name_object(name)
+      item.Delete
+    rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException
+      raise UnexpectedREOError, "name error with name #{name.inspect} in #{File.basename(self.stored_filename).inspect}\n#{$!.message}"
+    end
+
+    # @return [Array] defined names
+    def names
+      self.Names.to_a.map(&:name)
+    end
 
   private
 
-    def name_object(name)
+    def get_name_object(name)
       self.Names.Item(name)
     rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException, VBAMethodMissingError
       begin

data/lib/robust_excel_ole/version.rb

@@ -1,3 +1,3 @@
 module RobustExcelOle
-  VERSION = "1.27"
+  VERSION = "1.32"
 end

data/lib/robust_excel_ole/workbook.rb

@@ -11,25 +11,27 @@ module RobustExcelOle
 
   class Workbook < RangeOwners
 
-    #include General 
-    
+    include Enumerable
+
     attr_reader :ole_workbook
     attr_reader :excel
     attr_reader :stored_filename
 
     alias ole_object ole_workbook
 
+    using ToReoRefinement
+
     CORE_DEFAULT_OPEN_OPTS = {
-      :default => {:excel => :current}, 
-      :force => {},
-      :update_links => :never 
+      default: {excel: :current}, 
+      force: {},
+      update_links: :never 
     }.freeze
 
     DEFAULT_OPEN_OPTS = {
-      :if_unsaved    => :raise,
-      :if_obstructed => :raise,
-      :if_absent     => :raise,
-      :if_exists => :raise
+      if_unsaved: :raise,
+      if_obstructed: :raise,
+      if_absent: :raise,
+      if_exists: :raise
     }.merge(CORE_DEFAULT_OPEN_OPTS).freeze  
 
     ABBREVIATIONS = [
@@ -42,7 +44,7 @@ module RobustExcelOle
 
 
     # opens a workbook.
-    # @param [String] file_or_workbook a file name or WIN32OLE workbook
+    # @param [String,Pathname] file_or_workbook a file name (string or pathname) or WIN32OLE workbook
     # @param [Hash] opts the options
     # @option opts [Hash] :default or :d
     # @option opts [Hash] :force or :f
@@ -89,7 +91,7 @@ module RobustExcelOle
       process_options(opts)
       case file_or_workbook
       when NilClass
-        raise FileNameNotGiven, 'filename is nil' 
+        raise FileNameNotGiven, "filename is nil"
       when WIN32OLE
         file = file_or_workbook.Fullname.tr('\\','/') 
       when Workbook
@@ -101,7 +103,7 @@ module RobustExcelOle
         file = file_or_workbook.to_path
         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'
+        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)
@@ -110,14 +112,14 @@ module RobustExcelOle
         # if readonly is true, then prefer a book that is given in force_excel if this option is set              
         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
+            (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]),
-                                  :prefer_excel    => (opts[:read_only] ? forced_excel : nil))
+            bookstore.fetch(file, prefer_writable: !(opts[:read_only]),
+                                  prefer_excel: (opts[:read_only] ? forced_excel : nil))
           end
         rescue
           raise
@@ -153,12 +155,12 @@ module RobustExcelOle
         ole_excel = begin 
           @ole_workbook.Application
         rescue WIN32OLERuntimeError
-          raise ExcelREOError, 'could not determine the Excel instance'
+          raise ExcelREOError, "could not determine the Excel instance\n#{$!.message}"
         end
         @excel = excel_class.new(ole_excel)
         filename = @ole_workbook.Fullname.tr('\\','/') 
       else
-        filename = file_or_workbook            
+        filename = file_or_workbook
         ensure_workbook(filename, opts)        
       end      
       apply_options(filename, opts)
@@ -182,7 +184,7 @@ module RobustExcelOle
       self.class.set_was_open(hash, value)
     end
 
-    def self.process_options(opts, proc_opts = {:use_defaults => true})
+    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)
@@ -224,9 +226,9 @@ module RobustExcelOle
       return if @excel && @excel.alive?
       excel_option = options[:force][:excel] || options[:default][:excel] || :current
       @excel = if excel_option == :new
-        excel_class.new(:reuse => false) 
+        excel_class.new(reuse: false) 
       elsif excel_option == :current
-        excel_class.new(:reuse => true)
+        excel_class.new(reuse: true)
       elsif excel_option.respond_to?(:to_reo)
         excel_option.to_reo.excel
       else
@@ -235,13 +237,12 @@ module RobustExcelOle
       raise ExcelREOError, "Excel is not alive" unless @excel && @excel.alive?
     end
 
-
     # @private    
-    def ensure_workbook(filename, options)  
+    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 && 
+      if options[:if_unsaved]==:accept && alive? && 
         ((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"
       end
@@ -254,7 +255,7 @@ module RobustExcelOle
       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]
+        open_or_create_workbook(filename,options) if (!options[:read_only].nil?) && options[:read_only] != @ole_workbook.ReadOnly
       else
         if (excel_option.nil? || excel_option == :current) &&  
           !(::CONNECT_JRUBY_BUG && filename[0] == '/')
@@ -270,7 +271,6 @@ module RobustExcelOle
     # 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) 
       end
@@ -283,14 +283,14 @@ module RobustExcelOle
 
     # connects to an unknown workbook
     def connect(filename, options)   
-      workbooks_number = excel_class.excels_number==0 ? 0 : excel_class.current.Workbooks.Count
+      workbooks_number = excel_class.instance_count==0 ? 0 : excel_class.current.Workbooks.Count
       @ole_workbook = begin
         WIN32OLE.connect(General.absolute_path(filename))
       rescue
         if $!.message =~ /moniker/
           raise WorkbookConnectingBlockingError, "some workbook is blocking when connecting"
         else 
-          raise WorkbookConnectingUnknownError, "unknown error when connecting to a workbook"
+          raise WorkbookConnectingUnknownError, "unknown error when connecting to a workbook\n#{$!.message}"
         end
       end
       ole_excel = begin
@@ -299,7 +299,7 @@ module RobustExcelOle
         if $!.message =~ /dispid/
           raise WorkbookConnectingUnsavedError, "workbook is unsaved when connecting"
         else 
-          raise WorkbookConnectingUnknownError, "unknown error when connecting to a workbook"
+          raise WorkbookConnectingUnknownError, "unknown error when connecting to a workbook\n#{$!.message}"
         end
       end
       set_was_open options, (ole_excel.Workbooks.Count == workbooks_number)
@@ -327,7 +327,7 @@ module RobustExcelOle
     def manage_blocking_or_unsaved_workbook(filename, options)
       filename = General.absolute_path(filename)
       filename = General.canonize(filename)
-      previous_file = General.canonize(@ole_workbook.Fullname)
+      previous_file = General.canonize(@ole_workbook.Fullname.gsub('\\','/'))
       obstructed_by_other_book = (File.basename(filename) == File.basename(previous_file)) &&
                                  (File.dirname(filename) != File.dirname(previous_file)) 
       if obstructed_by_other_book
@@ -341,11 +341,12 @@ module RobustExcelOle
       end        
     end
 
-    def manage_blocking_workbook(filename, options)
+    def manage_blocking_workbook(filename, options)     
+      blocked_filename = -> { General.canonize(@ole_workbook.Fullname.tr('\\','/')) }
       case options[:if_obstructed]
       when :raise
         raise WorkbookBlocked, "can't open workbook #{filename},
-        because it is being blocked by #{@ole_workbook.Fullname.tr('\\','/')} with the same name in a different path." +
+        because it is being blocked by #{blocked_filename.call} with the same name in a different path." +
         "\nHint: Use the option :if_blocked with values :forget or :save,
          to allow automatic closing of the old workbook (without or with saving before, respectively),
          before the new workbook is being opened."
@@ -355,8 +356,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('\\','/')}" +
-          "\nHint: Use the option :if_blocked => :save to save the workbook"
+          raise WorkbookBlocked, "workbook with the same name in a different path is unsaved: #{blocked_filename.call}" +
+          "\nHint: Use the option if_blocked: :save to save the workbook"
         else
           manage_forgetting_workbook(filename, options)
         end
@@ -371,9 +372,14 @@ module RobustExcelOle
     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"
+        msg = if !options[:read_only].nil? && @ole_workbook.ReadOnly != options[:read_only]
+          "cannot change read-only mode of the workbook #{File.basename(filename).inspect}, because it contains unsaved changes"
+        else
+          "workbook is already open but not saved: #{File.basename(filename).inspect}"
+        end
+        raise WorkbookNotSaved, msg +
+        "\nHint: Use the option :if_unsaved with values :forget to close the unsaved workbook, 
+         :accept to let it open, or :save to save it, respectivly"
       when :forget
         manage_forgetting_workbook(filename, options)
       when :accept
@@ -402,46 +408,53 @@ module RobustExcelOle
     end
 
     def manage_new_excel(filename, options)
-      @excel = excel_class.new(:reuse => false)
+      @excel = excel_class.new(reuse: false)
       @ole_workbook = nil
       open_or_create_workbook(filename, options)
     end
-    
+
+    def explore_workbook_error(msg, want_change_readonly = nil)
+      if msg.message =~ /800A03EC/ && msg.message =~ /0x80020009/
+        # error message: 
+        # 'This workbook is currently referenced by another workbook and cannot be closed'
+        # 'Diese Arbeitsmappe wird momentan von einer anderen Arbeitsmappe verwendet und kann nicht geschlossen werden.'
+        if want_change_readonly==true
+          raise WorkbookLinked, "read-only mode of this workbook cannot be changed, because it is being used by another workbook"
+        elsif want_change_readonly.nil?
+          raise WorkbookLinked, "workbook is being used by another workbook"
+        end
+      end
+      if msg.message !~ /800A03EC/ || msg.message !~ /0x80020009/ || want_change_readonly==false
+        raise UnexpectedREOError, "unknown WIN32OLERuntimeError:\n#{msg.message}"
+      end
+    end
+
     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 )
+                (options[:read_only].nil? || options[:read_only]==@ole_workbook.ReadOnly )
+      abs_filename = General.absolute_path(filename)
+      workbooks = begin 
+        @excel.Workbooks
+      rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException => msg
+        raise UnexpectedREOError, "cannot access workbooks: #{msg.message} #{msg.backtrace}"
+      end
       begin
-        abs_filename = General.absolute_path(filename)
-        begin
-          workbooks = @excel.Workbooks
-        rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException => msg
-          raise UnexpectedREOError, "cannot access workbooks: #{msg.message} #{msg.backtrace}"
-        end
-        begin
-          with_workaround_linked_workbooks_excel2007(options) do
-            # temporary workaround until jruby-win32ole implements named parameters (Java::JavaLang::RuntimeException (createVariant() not implemented for class org.jruby.RubyHash)
-            workbooks.Open(abs_filename, 
-                                      updatelinks_vba(options[:update_links]), 
-                                      options[:read_only] )
-          end
-        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}"
-        end
-        begin
-          # 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, Java::OrgRacobCom::ComFailException => msg
-            raise UnexpectedREOError, "WIN32OLERuntimeError: #{msg.message}"
-          end
-        rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException => msg
-          raise UnexpectedREOError, "WIN32OLERuntimeError: #{msg.message} #{msg.backtrace}"
+        with_workaround_linked_workbooks_excel2007(options) do
+          # temporary workaround until jruby-win32ole implements named parameters (Java::JavaLang::RuntimeException (createVariant() not implemented for class org.jruby.RubyHash)
+          workbooks.Open(abs_filename, updatelinks_vba(options[:update_links]), options[:read_only] )
         end
+      rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException => msg
+        # for Excel2007: for option :if_unsaved => :alert and user cancels: this error appears?; distinguish these events
+        want_change_readonly = !options[:read_only].nil? && (options[:read_only] != @ole_workbook.ReadOnly)
+      end
+      # workaround for bug in Excel 2010: workbook.Open does not always return the workbook when given file name
+      @ole_workbook = begin
+        workbooks.Item(File.basename(filename))
+      rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException => msg
+        raise UnexpectedREOError, "WIN32OLERuntimeError: #{msg.message}"
       end
-    end    
-           
+    end  
+
     # translating the option UpdateLinks from REO to VBA
     # setting UpdateLinks works only if calculation mode is automatic,
     # parameter 'UpdateLinks' has no effect
@@ -480,7 +493,7 @@ module RobustExcelOle
     # @param [String] filename the filename under which the new workbook should be saved
     # @param [Hash] opts the options as in Workbook::open
     def self.create(filename, opts = { })
-      open(filename, :if_absent => :create)
+      open(filename, if_absent: :create)
     end
 
     # closes the workbook, if it is alive
@@ -495,34 +508,37 @@ module RobustExcelOle
     #                      :alert or :excel -> gives control to excel
     # @raise WorkbookNotSaved if the option :if_unsaved is :raise and the workbook is unsaved
     # @raise OptionInvalid if the options is invalid
-    def close(opts = {:if_unsaved => :raise})
-      if alive? && !@ole_workbook.Saved && writable
-        case opts[:if_unsaved]
-        when :raise
-          raise WorkbookNotSaved, "workbook is unsaved: #{File.basename(self.stored_filename).inspect}" +
-          "\nHint: Use option :save or :forget to close the workbook with or without saving"
-        when :save
-          save
-          close_workbook
-        when :forget
-          @excel.with_displayalerts(false) { close_workbook }
-        when :keep_open
-          # nothing
-        when :alert, :excel
-          @excel.with_displayalerts(true) { close_workbook }
-        else
-          raise OptionInvalid, ":if_unsaved: invalid option: #{opts[:if_unsaved].inspect}" +
-          "\nHint: Valid values are :raise, :save, :keep_open, :alert, :excel"
-        end
-      else
+    def close(opts = {if_unsaved: :raise})
+      return close_workbook unless (alive? && !@ole_workbook.Saved && writable)
+      case opts[:if_unsaved]
+      when :raise
+        raise WorkbookNotSaved, "workbook is unsaved: #{File.basename(self.stored_filename).inspect}" +
+        "\nHint: Use option :save or :forget to close the workbook with or without saving"
+      when :save
+        save
         close_workbook
+      when :forget
+        @excel.with_displayalerts(false) { close_workbook }
+      when :keep_open
+        # nothing
+      when :alert, :excel
+        @excel.with_displayalerts(true) { close_workbook }
+      else
+        raise OptionInvalid, ":if_unsaved: invalid option: #{opts[:if_unsaved].inspect}" +
+        "\nHint: Valid values are :raise, :save, :keep_open, :alert, :excel"
       end
     end
 
   private
 
     def close_workbook
-      @ole_workbook.Close if alive?
+      if alive?
+        begin
+          @ole_workbook.Close 
+        rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException => msg
+          explore_workbook_error(msg)          
+        end
+      end      
       @ole_workbook = nil unless alive?
     end
 
@@ -539,29 +555,31 @@ module RobustExcelOle
     end
 
     def for_reading(opts = { }, &block)
-      unobtrusively({:writable => false}.merge(opts), &block)
+      unobtrusively({writable: false}.merge(opts), &block)
     end
 
     def for_modifying(opts = { }, &block)
-      unobtrusively({:writable => true}.merge(opts), &block)
+      unobtrusively({writable: true}.merge(opts), &block)
     end
 
     def self.for_reading(arg, opts = { }, &block)
-      unobtrusively(arg, {:writable => false}.merge(opts), &block)
+      unobtrusively(arg, {writable: false}.merge(opts), &block)
     end
 
     def self.for_modifying(arg, opts = { }, &block)
-      unobtrusively(arg, {:writable => true}.merge(opts), &block)
+      unobtrusively(arg, {writable: true}.merge(opts), &block)
     end
 
     # allows to read or modify a workbook such that its state remains unchanged
     # state comprises: open, saved, writable, visible, calculation mode, check compatibility
     # @param [String] file_or_workbook     a file name or WIN32OLE workbook
-    # @param [Hash]   opts        the options
-    # @option opts [Variant] :if_closed  :current (default), :new or an Excel instance
-    # @option opts [Boolean] :read_only true/false (default), open the workbook in read-only/read-write modus (save changes)
-    # @option opts [Boolean] :writable  true (default)/false changes of the workbook shall be saved/not saved
+    # @param [Hash]   opts        the options   
+    # @option opts [Boolean] :read_only true/false (default), force to open the workbook in read-only/read-write mode
+    # @option opts [Boolean] :writable  true (default)/false changes of the workbook shall be saved/not saved, 
+    #                                   and the workbook is being opened in read-only/read-write mode by default 
+    #                                   (when the workbook was not open before)
     # @option opts [Boolean] :keep_open whether the workbook shall be kept open after unobtrusively opening (default: false)
+    # @option opts [Variant] :if_closed  :current (default), :new or an Excel instance
     # @return [Workbook] a workbook
     def self.unobtrusively(file_or_workbook, opts = { }, &block)
       file = (file_or_workbook.is_a? WIN32OLE) ? file_or_workbook.Fullname.tr('\\','/') : file_or_workbook
@@ -577,36 +595,37 @@ module RobustExcelOle
 
     def self.unobtrusively_opening(file, opts, book_is_alive, &block)
       process_options(opts)
-      opts = {:if_closed => :current, :keep_open => false}.merge(opts)    
-      raise OptionInvalid, 'contradicting options' if opts[:writable] && opts[:read_only] 
+      opts = {if_closed: :current, keep_open: false}.merge(opts)    
+      raise OptionInvalid, "contradicting options" if opts[:writable] && opts[:read_only] 
       if book_is_alive.nil?
         prefer_writable = ((!(opts[:read_only]) || opts[:writable] == true) &&
                            !(opts[:read_only].nil? && opts[:writable] == false))
-        known_book = bookstore.fetch(file, :prefer_writable => prefer_writable) 
+        known_book = bookstore.fetch(file, prefer_writable: prefer_writable) 
       end
       excel_opts = if (book_is_alive==false || (book_is_alive.nil? && (known_book.nil? || !known_book.alive?)))
-        {:force => {:excel => opts[:if_closed]}}
+        {force: {excel: opts[:if_closed]}}
       else
-        {:force => {:excel => opts[:force][:excel]}, :default => {:excel => opts[:default][:excel]}}
+        {force: {excel: opts[:force][:excel]}, default: {excel: opts[:default][:excel]}}
       end
-      open_opts = excel_opts.merge({:if_unsaved => :accept})
+      open_opts = excel_opts.merge({if_unsaved: :accept})
       begin
-        open_opts[:was_open] = nil
+        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]
+        opts[:read_only] = !opts[:writable] unless (!opts[:read_only].nil? || opts[:writable].nil? || open_opts[:was_open])
         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.send :apply_options, file, opts.merge({:read_only => !was_writable, 
-                                            :if_unsaved => (opts[:writable]==false ? :forget : :save)})
+          if  ((opts[:read_only] && was_writable) || (!opts[:read_only] && !was_writable))
+            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
@@ -626,20 +645,20 @@ module RobustExcelOle
     # @options options
     def reopen(options = { })
       book = self.class.open(@stored_filename, options)
-      raise WorkbookREOError('cannot reopen book') unless book && book.alive?
+      raise WorkbookREOError("cannot reopen workbook\n#{$!.message}") unless book && book.alive?
       book
     end
 
     # simple save of a workbook.
     # @return [Boolean] true, if successfully saved, nil otherwise
     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   
+      raise ObjectNotAlive, "workbook is not alive" unless alive?
+      raise WorkbookReadOnly, "Not opened for writing (opened with :read_only option)" if @ole_workbook.ReadOnly   
       begin
         @ole_workbook.Save
       rescue WIN32OLERuntimeError, Java::OrgRacobCom::ComFailException => msg
         if msg.message =~ /SaveAs/ && msg.message =~ /Workbook/
-          raise WorkbookNotSaved, 'workbook not saved'
+          raise WorkbookNotSaved, "workbook not saved"
         else
           raise UnexpectedREOError, "unknown WIN32OLERuntimeError:\n#{msg.message}"
         end
@@ -665,64 +684,72 @@ module RobustExcelOle
     #                                          otherwise raises an exception   
     # @return [Workbook], the book itself, if successfully saved, raises an exception otherwise
     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 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)
-      self.class.process_options(options)      
-      if File.exist?(file)
-        case options[:if_exists]
-        when :overwrite
-          if file == self.filename
-            save
-            return self
-          else
-            begin
-              File.delete(file)
-            rescue Errno::EACCES
-              raise WorkbookBeingUsed, 'workbook is open and being used in an Excel instance'
-            end
-          end
-        when :alert, :excel
-          @excel.with_displayalerts true do
-            save_as_workbook(file, options)
-          end
-          return self
-        when :raise
-          raise FileAlreadyExists, "file already exists: #{File.basename(file).inspect}" +
-          "\nHint: Use option :if_exists => :overwrite, if you want to overwrite the file" 
+      self.class.process_options(options)
+      begin  
+        saveas_manage_if_exists(file, options)
+        saveas_manage_if_blocked(file, options)
+        save_as_workbook(file, options)
+      rescue AlreadyManaged
+        nil
+      end
+      self
+    end
+
+  private
+
+    def saveas_manage_if_exists(file, options)
+      return unless File.exist?(file)
+      case options[:if_exists]
+      when :overwrite
+        if file == self.filename
+          save
+          raise AlreadyManaged
         else
-          raise OptionInvalid, ":if_exists: invalid option: #{options[:if_exists].inspect}" +
-          "\nHint: Valid values are :raise, :overwrite, :alert, :excel"
+          begin
+            File.delete(file)
+          rescue Errno::EACCES
+            raise WorkbookBeingUsed, "workbook is open and being used in an Excel instance"
+          end
         end
+      when :alert, :excel
+        @excel.with_displayalerts(true){ save_as_workbook(file, options) }
+        raise AlreadyManaged
+      when :raise
+        raise FileAlreadyExists, "file already exists: #{File.basename(file).inspect}" +
+        "\nHint: Use option if_exists: :overwrite, if you want to overwrite the file" 
+      else
+        raise OptionInvalid, ":if_exists: invalid option: #{options[:if_exists].inspect}" +
+        "\nHint: Valid values are :raise, :overwrite, :alert, :excel"
       end
+    end
+
+    def saveas_manage_if_blocked(file, options)
       other_workbook = @excel.Workbooks.Item(File.basename(file)) rescue nil
-      if other_workbook && self.filename != other_workbook.Fullname.tr('\\','/')
-        case options[:if_obstructed]
-        when :raise
-          raise WorkbookBlocked, "blocked by another workbook: #{other_workbook.Fullname.tr('\\','/')}" +
-          "\nHint: Use the option :if_blocked with values :forget or :save to
-           close or save and close the blocking workbook"
-        when :forget
-          # nothing
-        when :save
-          other_workbook.Save
-        when :close_if_saved
-          unless other_workbook.Saved
-            raise WorkbookBlocked, "blocking workbook is unsaved: #{File.basename(file).inspect}" +
-            "\nHint: Use option :if_blocked => :save to save the blocking workbooks"
-          end
-        else
-          raise OptionInvalid, ":if_blocked: invalid option: #{options[:if_obstructed].inspect}" +
-          "\nHint: Valid values are :raise, :forget, :save, :close_if_saved"
+      return unless other_workbook && self.filename != other_workbook.Fullname.tr('\\','/')
+      case options[:if_obstructed]
+      when :raise
+        raise WorkbookBlocked, "blocked by another workbook: #{other_workbook.Fullname.tr('\\','/')}" +
+        "\nHint: Use the option :if_blocked with values :forget or :save to
+         close or save and close the blocking workbook"
+      when :forget
+        # nothing
+      when :save
+        other_workbook.Save
+      when :close_if_saved
+        unless other_workbook.Saved
+          raise WorkbookBlocked, "blocking workbook is unsaved: #{File.basename(file).inspect}" +
+          "\nHint: Use option if_blocked: :save to save the blocking workbooks"
         end
-        other_workbook.Close
+      else
+        raise OptionInvalid, "if_blocked: invalid option: #{options[:if_obstructed].inspect}" +
+        "\nHint: Valid values are :raise, :forget, :save, :close_if_saved"
       end
-      save_as_workbook(file, options)
-      self
-    end    
-
-  private
+      other_workbook.Close
+    end
 
     def save_as_workbook(file, options)  
       dirname, basename = File.split(file)
@@ -743,6 +770,9 @@ module RobustExcelOle
       end
     end
 
+    class AlreadyManaged < Exception
+    end
+
     def store_myself
       bookstore.store(self)
       @stored_filename = filename
@@ -752,7 +782,7 @@ module RobustExcelOle
 
     # closes a given file if it is open
     # @options opts [Symbol] :if_unsaved
-    def self.close(file, opts = {:if_unsaved => :raise})
+    def self.close(file, opts = {if_unsaved: :raise})
       book = begin
         bookstore.fetch(file)
         rescue
@@ -790,21 +820,20 @@ module RobustExcelOle
       @ole_workbook.Worksheets.Count
     end
 
+    # @return [Enumerator] traversing all worksheet objects
     def each
-      @ole_workbook.Worksheets.each do |sheet|
-        yield worksheet_class.new(sheet)
+      if block_given?
+        @ole_workbook.Worksheets.lazy.each do |ole_worksheet|
+          yield worksheet_class.new(ole_worksheet)
+        end
+      else
+        to_enum(:each).lazy
       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|
+      @ole_workbook.Worksheets.lazy.each do |sheet|
         yield worksheet_class.new(sheet), i
         i += 1
       end
@@ -845,7 +874,7 @@ module RobustExcelOle
           end
         end
       rescue # WIN32OLERuntimeError, NameNotFound, Java::OrgRacobCom::ComFailException
-        raise WorksheetREOError, "could not add given worksheet #{sheet.inspect}"
+        raise WorksheetREOError, "could not add given worksheet #{sheet.inspect}\n#{$!.message}"
       end
       new_sheet = worksheet_class.new(ole_workbook.Activesheet)
       new_sheet.name = new_sheet_name if new_sheet_name
@@ -889,7 +918,7 @@ module RobustExcelOle
     def range(name_or_worksheet, name_or_address = :__not_provided, address2 = :__not_provided)
       if name_or_worksheet.respond_to?(:gsub)
         name = name_or_worksheet
-        RobustExcelOle::Range.new(name_object(name).RefersToRange)
+        RobustExcelOle::Range.new(get_name_object(name).RefersToRange)
       else 
         begin 
           worksheet = name_or_worksheet.to_reo
@@ -904,21 +933,21 @@ module RobustExcelOle
     # @param [String] name the name of a range
     # @returns [Variant] the value of the range
     def [] name
-      namevalue_glob(name)
+      namevalue_global(name)
     end
 
     # sets the value of a range
     # @param [String]  name  the name of the range
     # @param [Variant] value the contents of the range
     def []= (name, value)
-      set_namevalue_glob(name, value)   
+      set_namevalue_global(name, value)   
     end
 
     # sets options
     # @param [Hash] opts
     def for_this_workbook(opts)
       return unless alive?
-      self.class.process_options(opts, :use_defaults => false)
+      self.class.process_options(opts, use_defaults: false)
       self.send :apply_options, @stored_filename, opts
     end
 
@@ -1023,14 +1052,18 @@ module RobustExcelOle
 
     # @private
     def inspect    
-      '#<Workbook: ' + ('not alive ' unless alive?).to_s + (File.basename(self.filename) if alive?).to_s + " #{@excel}" + '>'
+      #{}"#<Workbook: #{("not alive " unless alive?)} #{(File.basename(self.filename) if alive?)} #{@excel}>"
+      "#<Workbook: #{(alive? ? File.basename(self.filename) : "not alive")} #{@excel} >"
     end
 
+    using ParentRefinement
+    using StringRefinement
+
     # @private
     def self.excel_class    
       @excel_class ||= begin
         module_name = self.parent_name
-        "#{module_name}::Excel".constantize
+        "#{module_name}::Excel".constantize        
       rescue NameError => e
         # trace "excel_class: NameError: #{e}"
         Excel
@@ -1041,7 +1074,7 @@ module RobustExcelOle
     def self.worksheet_class    
       @worksheet_class ||= begin
         module_name = self.parent_name
-        "#{module_name}::Worksheet".constantize
+        "#{module_name}::Worksheet".constantize        
       rescue NameError => e
         Worksheet
       end
@@ -1062,23 +1095,20 @@ module RobustExcelOle
   private
 
     def method_missing(name, *args) 
-      if name.to_s[0,1] =~ /[A-Z]/
-        raise ObjectNotAlive, 'method missing: workbook not alive' unless alive?
-        if ::ERRORMESSAGE_JRUBY_BUG 
-          begin
-            @ole_workbook.send(name, *args)
-          rescue Java::OrgRacobCom::ComFailException 
-            raise VBAMethodMissingError, "unknown VBA property or method #{name.inspect}"
-          end
-        else
-          begin
-            @ole_workbook.send(name, *args)
-          rescue NoMethodError 
-            raise VBAMethodMissingError, "unknown VBA property or method #{name.inspect}"
-          end
+      super unless name.to_s[0,1] =~ /[A-Z]/
+      raise ObjectNotAlive, 'method missing: workbook not alive' unless alive?
+      if ::ERRORMESSAGE_JRUBY_BUG 
+        begin
+          @ole_workbook.send(name, *args)
+        rescue Java::OrgRacobCom::ComFailException 
+          raise VBAMethodMissingError, "unknown VBA property or method #{name.inspect}"
         end
       else
-        super
+        begin
+          @ole_workbook.send(name, *args)
+        rescue NoMethodError 
+          raise VBAMethodMissingError, "unknown VBA property or method #{name.inspect}"
+        end
       end
     end
 
@@ -1094,6 +1124,10 @@ public
   class WorkbookNotSaved < WorkbookREOError        
   end
 
+  # @private
+  class WorkbookLinked < WorkbookREOError        
+  end
+
   # @private
   class WorkbookReadOnly < WorkbookREOError        
   end