robust_excel_ole 0.6 → 0.6.1

data/lib/robust_excel_ole/book.rb

@@ -141,8 +141,7 @@ module RobustExcelOle
       else
         file = file_or_workbook
         ensure_excel(options)
-        ensure_workbook(file, options)
-        @ole_workbook.CheckCompatibility = options[:check_compatibility]
+        ensure_workbook(file, options)        
         @can_be_closed = false if @can_be_closed.nil?
       end
       bookstore.store(self)
@@ -172,15 +171,32 @@ module RobustExcelOle
         begin
           object.excel
         rescue
-          raise ExcelErrorOpen, "given object is neither an Excel, a Workbook, nor a Win32ole"
+          raise TypeErrorREO, "given object is neither an Excel, a Workbook, nor a Win32ole"
         end
       end
-      #rescue
-        # trace "no Excel, Book, or WIN32OLE object representing a Workbook or an Excel instance"
     end
 
   public
 
+    def self.open_in_current_excel(file, opts = { })
+      options = DEFAULT_OPEN_OPTS.merge(opts)
+      filename = General::absolute_path(file)
+      ole_workbook = WIN32OLE.connect(filename)
+      workbook = Book.new(ole_workbook)
+      workbook.visible = options[:visible] unless options[:visible].nil?
+      update_links_opt =
+            case options[:update_links]
+            when :alert; RobustExcelOle::XlUpdateLinksUserSetting
+            when :never; RobustExcelOle::XlUpdateLinksNever
+            when :always; RobustExcelOle::XlUpdateLinksAlways
+            else RobustExcelOle::XlUpdateLinksNever
+          end
+      workbook.UpdateLinks = update_links_opt
+      workbook.CheckCompatibility = options[:check_compatibility]
+      workbook
+    end
+
+
     def ensure_excel(options)   # :nodoc: #
       return if @excel && @excel.alive?
       options[:excel] = options[:force_excel] ? options[:force_excel] : options[:default_excel]
@@ -191,23 +207,23 @@ module RobustExcelOle
 
     def ensure_workbook(file, options)     # :nodoc: #
       file = @stored_filename ? @stored_filename : file
-      raise(ExcelErrorOpen, "filename is nil") if file.nil?
+      raise(FileNameNotGiven, "filename is nil") if file.nil?
       unless File.exist?(file)
         if options[:if_absent] == :create
           @ole_workbook = excel_class.current.generate_workbook(file)
         else 
-          raise ExcelErrorOpen, "file #{file.inspect} not found"
+          raise FileNotFound, "file #{file.inspect} not found"
         end
       end
       @ole_workbook = @excel.Workbooks.Item(File.basename(file)) rescue nil
       if @ole_workbook then
         obstructed_by_other_book = (File.basename(file) == File.basename(@ole_workbook.Fullname)) && 
                                    (not (General::absolute_path(file) == @ole_workbook.Fullname))
-        # if book is obstructed by a book with same name and different path
+        # if workbook is obstructed by a workbook with same name and different path
         if obstructed_by_other_book then
           case options[:if_obstructed]
           when :raise
-            raise ExcelErrorOpen, "blocked by a book with the same name in a different path: #{@ole_workbook.Fullname.tr('\\','/')}"
+            raise WorkbookBlocked, "blocked by a workbook with the same name in a different path: #{@ole_workbook.Fullname.tr('\\','/')}"
           when :forget
             @ole_workbook.Close
             @ole_workbook = nil
@@ -219,7 +235,7 @@ module RobustExcelOle
             open_or_create_workbook(file, options)
           when :close_if_saved
             if (not @ole_workbook.Saved) then
-              raise ExcelErrorOpen, "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('\\','/')}"
             else 
               @ole_workbook.Close
               @ole_workbook = nil
@@ -231,14 +247,14 @@ module RobustExcelOle
             @excel = excel_class.new(excel_options)
             open_or_create_workbook(file, options)
           else
-            raise ExcelErrorOpen, ":if_obstructed: invalid option: #{options[:if_obstructed].inspect}"
+            raise OptionInvalid, ":if_obstructed: invalid option: #{options[:if_obstructed].inspect}"
           end
         else
           # book open, not obstructed by an other book, but not saved and writable
           if (not @ole_workbook.Saved) then
             case options[:if_unsaved]
             when :raise
-              raise ExcelErrorOpen, "workbook is already open but not saved: #{File.basename(file).inspect}"
+              raise WorkbookNotSaved, "workbook is already open but not saved: #{File.basename(file).inspect}"
             when :forget
               @ole_workbook.Close
               @ole_workbook = nil
@@ -246,16 +262,14 @@ module RobustExcelOle
             when :accept
               # do nothing
             when :alert, :excel
-              @excel.with_displayalerts true do
-                open_or_create_workbook(file,options)
-              end 
+              @excel.with_displayalerts(true) { open_or_create_workbook(file,options) }
             when :new_excel
               excel_options = {:visible => false}.merge(options)
               excel_options[:reuse] = false
               @excel = excel_class.new(excel_options)
               open_or_create_workbook(file, options)
             else
-              raise ExcelErrorOpen, ":if_unsaved: invalid option: #{options[:if_unsaved].inspect}"
+              raise OptionInvalid, ":if_unsaved: invalid option: #{options[:if_unsaved].inspect}"
             end
           end
         end
@@ -276,19 +290,21 @@ module RobustExcelOle
           rescue RuntimeError => msg
             trace "RuntimeError: #{msg.message}" 
             if msg.message =~ /method missing: Excel not alive/
-              raise ExcelErrorOpen, "Excel instance not alive or damaged" 
+              raise ExcelDamaged, "Excel instance not alive or damaged" 
             else
-              raise ExcelErrorOpen, "unknown RuntimeError"
+              raise UnexpectedError, "unknown RuntimeError"
             end
           rescue WeakRef::RefError => msg
-            trace "WeakRefError: #{msg.message}"
-            raise ExcelErrorOpen, "#{msg.message}"
+            raise ExcelWeakRef, "#{msg.message}"
           end
           # 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
           count = workbooks.Count
-          workbooks.Add if @excel.Version == "12.0" && count == 0
+          if @excel.Version == "12.0" && count == 0
+            workbooks.Add 
+            #@excel.set_calculation(:automatic)
+          end
           update_links_opt =
             case options[:update_links]
             when :alert; RobustExcelOle::XlUpdateLinksUserSetting
@@ -296,27 +312,29 @@ module RobustExcelOle
             when :always; RobustExcelOle::XlUpdateLinksAlways
             else RobustExcelOle::XlUpdateLinksNever
           end
+          # probably bug in Excel: setting UpadateLinks seems to be dependent on calculation mode:
+          # update happens, if calcultion mode is automatic, does not, if calculation mode is manual
+          # parameter 'UpdateLinks' has no effect
           @excel.with_displayalerts(update_links_opt == :alert ? true : @excel.displayalerts) do
-            # ??? determining update_links_opt here does not work, it is always XlUpdateLinksNever afterwords
             workbooks.Open(filename, { 'ReadOnly' => options[:read_only] , 'UpdateLinks' => update_links_opt } )
           end
-          workbooks.Open(filename, { 'ReadOnly' => options[:read_only] } )
           workbooks.Item(1).Close if @excel.Version == "12.0" && count == 0                   
         rescue WIN32OLERuntimeError => msg
-          trace "WIN32OLERuntimeError: #{msg.message}" 
+          # trace "WIN32OLERuntimeError: #{msg.message}" 
           if msg.message =~ /800A03EC/
-            raise ExcelErrorOpen, "open: user canceled or open error"
+            raise WorkbookError, "open: user canceled or open error"
           else 
-            raise ExcelErrorOpen, "unknown WIN32OLERuntimeError"
+            raise UnexpectedError, "unknown WIN32OLERuntimeError"
           end
         end   
         begin
           # workaround for bug in Excel 2010: workbook.Open does not always return the workbook with given file name
           @ole_workbook = workbooks.Item(File.basename(filename))       
           self.visible = options[:visible] unless options[:visible].nil?
-          @ole_workbook.UpdateLinks = update_links_opt
+          #@ole_workbook.UpdateLinks = update_links_opt
+          @ole_workbook.CheckCompatibility = options[:check_compatibility]
         rescue WIN32OLERuntimeError
-          raise ExcelErrorOpen, "cannot find the file #{File.basename(filename).inspect}"
+          raise FileNotFound, "cannot find the file #{File.basename(filename).inspect}"
         end       
       end
     end
@@ -333,32 +351,30 @@ module RobustExcelOle
     #                      :forget          -> closes the workbook 
     #                      :keep_open       -> keep the workbook open
     #                      :alert or :excel -> gives control to excel
-    # @raise ExcelErrorClose if the option :if_unsaved is :raise and the workbook is unsaved, or option is invalid
-    # @raise ExcelErrorCanceled if the user has canceled 
+    # @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? && (not @ole_workbook.Saved) && writable) then
         case opts[:if_unsaved]
         when :raise
-          raise ExcelErrorClose, "workbook is unsaved: #{File.basename(self.stored_filename).inspect}"
+          raise WorkbookNotSaved, "workbook is unsaved: #{File.basename(self.stored_filename).inspect}"
         when :save
           save
           close_workbook
         when :forget
-          close_workbook
+          @excel.with_displayalerts(false) { close_workbook }
         when :keep_open
           # nothing
         when :alert, :excel
-          @excel.with_displayalerts true do
-            close_workbook
-          end
+          @excel.with_displayalerts(true) { close_workbook }
         else
-          raise ExcelErrorClose, ":if_unsaved: invalid option: #{opts[:if_unsaved].inspect}"
+          raise OptionInvalid, ":if_unsaved: invalid option: #{opts[:if_unsaved].inspect}"
         end
       else
         close_workbook
       end
-      raise ExcelUserCanceled, "close: canceled by user" if alive? && 
-      (opts[:if_unsaved] == :alert || opts[:if_unsaved] == :excel) && (not @ole_workbook.Saved)
+      trace "close: canceled by user" if alive? &&  
+        (opts[:if_unsaved] == :alert || opts[:if_unsaved] == :excel) && (not @ole_workbook.Saved)
     end
 
   private
@@ -474,18 +490,17 @@ module RobustExcelOle
     end
 
     # simple save of a workbook.
-    # @raise ExcelErrorSave if workbook is not alive or opened for read-only, or another error occurs
     # @return [Boolean] true, if successfully saved, nil otherwise
     def save      
-      raise ExcelErrorSave, "workbook is not alive" if (not alive?)
-      raise ExcelErrorSave, "Not opened for writing (opened with :read_only option)" if @ole_workbook.ReadOnly
+      raise ObjectNotAlive, "workbook is not alive" if (not alive?)
+      raise WorkbookReadOnly, "Not opened for writing (opened with :read_only option)" if @ole_workbook.ReadOnly
       begin
         @ole_workbook.Save 
       rescue WIN32OLERuntimeError => msg
         if msg.message =~ /SaveAs/ and msg.message =~ /Workbook/ then
-          raise ExcelErrorSave, "workbook not saved"
+          raise WorkbookNotSaved, "workbook not saved"
         else
-          raise ExcelErrorSaveUnknown, "unknown WIN32OELERuntimeError:\n#{msg.message}"
+          raise UnexpectedError, "unknown WIN32OELERuntimeError:\n#{msg.message}"
         end       
       end
       true
@@ -507,14 +522,11 @@ module RobustExcelOle
     #                  :save                -> saves the blocking workbook and closes it
     #                  :close_if_saved      -> closes the blocking workbook, if it is saved, 
     #                                          otherwise raises an exception
-    # @raise ExcelErrorSave if workbook is not alive, opened in read-only mode, invalid options,
-    #                          the file already exists (with option :if_exists :raise),
-    #                          the workbook is blocked by another one (with option :if_obstructed :raise)
     # @return [Book], the book itself, if successfully saved, raises an exception otherwise
     def save_as(file, opts = { } )
-      raise(ExcelErrorSave, "filename is nil") if file.nil?
-      raise ExcelErrorSave, "workbook is not alive" if (not alive?)
-      raise ExcelErrorSave, "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" if (not alive?)
+      raise WorkbookReadOnly, "Not opened for writing (opened with :read_only option)" if @ole_workbook.ReadOnly
       options = {
         :if_exists => :raise,
         :if_obstructed => :raise,
@@ -529,7 +541,7 @@ module RobustExcelOle
             begin
               File.delete(file)
             rescue Errno::EACCES
-              raise ExcelErrorSave, "workbook is open and used in Excel"
+              raise WorkbookBeingUsed, "workbook is open and used in Excel"
             end
           end
         when :alert, :excel 
@@ -538,9 +550,9 @@ module RobustExcelOle
           end
           return self
         when :raise
-          raise ExcelErrorSave, "file already exists: #{File.basename(file).inspect}"
+          raise FileAlreadyExists, "file already exists: #{File.basename(file).inspect}"
         else
-          raise ExcelErrorSave, ":if_exists: invalid option: #{options[:if_exists].inspect}"
+          raise OptionInvalid, ":if_exists: invalid option: #{options[:if_exists].inspect}"
         end
       end
       blocking_workbook = 
@@ -552,15 +564,15 @@ module RobustExcelOle
       if blocking_workbook then
         case options[:if_obstructed]
         when :raise
-          raise ExcelErrorSave, "blocked by another workbook: #{blocking_workbook.Fullname.tr('\\','/')}"
+          raise WorkbookBlocked, "blocked by another workbook: #{blocking_workbook.Fullname.tr('\\','/')}"
         when :forget
           # nothing
         when :save
           blocking_workbook.Save
         when :close_if_saved
-          raise ExcelErrorSave, "blocking workbook is unsaved: #{File.basename(file).inspect}" unless blocking_workbook.Saved
+          raise WorkbookBlocked, "blocking workbook is unsaved: #{File.basename(file).inspect}" unless blocking_workbook.Saved
         else
-          raise ExcelErrorSave, ":if_obstructed: invalid option: #{options[:if_obstructed].inspect}"
+          raise OptionInvalid, ":if_obstructed: invalid option: #{options[:if_obstructed].inspect}"
         end
         blocking_workbook.Close
       end
@@ -583,14 +595,10 @@ module RobustExcelOle
         bookstore.store(self)
       rescue WIN32OLERuntimeError => msg
         if msg.message =~ /SaveAs/ and msg.message =~ /Workbook/ then
-          if options[:if_exists] == :alert || options[:if_exists] == :excel then 
-            raise ExcelErrorSave, "not saved or canceled by user"
-          else
-            return nil
-          end
-          # another possible semantics. raise ExcelErrorSaveFailed, "could not save Workbook"
+          trace "save: canceled by user" if options[:if_exists] == :alert || options[:if_exists] == :excel
+          # another possible semantics. raise WorkbookError, "could not save Workbook"
         else
-          raise ExcelErrorSaveUnknown, "unknown WIN32OELERuntimeError:\n#{msg.message}"
+          raise UnexpectedError, "unknown WIN32OELERuntimeError:\n#{msg.message}"
         end       
       end
     end
@@ -604,8 +612,8 @@ module RobustExcelOle
       begin
         sheet_class.new(@ole_workbook.Worksheets.Item(name))
       rescue WIN32OLERuntimeError => msg
-        raise ExcelError, "could not return a sheet with name #{name.inspect}"
-        trace "#{msg.message}"
+        raise NameNotFound, "could not return a sheet with name #{name.inspect}"
+        # trace "#{msg.message}"
       end
     end    
 
@@ -622,7 +630,7 @@ module RobustExcelOle
     # @option opts [Symbol] :as     new name of the copied sheet
     # @option opts [Symbol] :before a sheet before which the sheet shall be inserted
     # @option opts [Symbol] :after  a sheet after which the sheet shall be inserted
-    # @raise  ExcelErrorSheet if the sheet name already exists
+    # @raise  NameAlreadyExists if the sheet name already exists
     # @return [Sheet] the copied sheet
     def copy_sheet(sheet, opts = { })
       new_sheet_name = opts.delete(:as)
@@ -632,7 +640,7 @@ module RobustExcelOle
       begin
         new_sheet.name = new_sheet_name if new_sheet_name
       rescue WIN32OLERuntimeError => msg
-        msg.message =~ /800A03EC/ ? raise(ExcelErrorSheet, "sheet name already exists") : raise(ExcelErrorSheetUnknown)
+        msg.message =~ /800A03EC/ ? raise(NameAlreadyExists, "sheet name already exists") : raise(UnexpectedError)
       end
       new_sheet
     end      
@@ -643,7 +651,7 @@ module RobustExcelOle
     # @option opts [Symbol] :as     new name of the copied added sheet
     # @option opts [Symbol] :before a sheet before which the sheet shall be inserted
     # @option opts [Symbol] :after  a sheet after which the sheet shall be inserted
-    # @raise  ExcelErrorSheet if the sheet name already exists
+    # @raise  NameAlreadyExists if the sheet name already exists
     # @return [Sheet] the added sheet
     def add_empty_sheet(opts = { })
       new_sheet_name = opts.delete(:as)
@@ -653,7 +661,7 @@ module RobustExcelOle
       begin
         new_sheet.name = new_sheet_name if new_sheet_name
       rescue WIN32OLERuntimeError => msg
-        msg.message =~ /800A03EC/ ? raise(ExcelErrorSheet, "sheet name already exists") : raise(ExcelErrorSheetUnknown)
+        msg.message =~ /800A03EC/ ? raise(NameAlreadyExists, "sheet name already exists") : raise(UnexpectedError)
       end
       new_sheet
     end    
@@ -665,7 +673,6 @@ module RobustExcelOle
     # @option opts [Symbol] :as     new name of the copied or added sheet
     # @option opts [Symbol] :before a sheet before which the sheet shall be inserted
     # @option opts [Symbol] :after  a sheet after which the sheet shall be inserted
-    # @raise  ExcelErrorSheet if the sheet name already exists
     # @return [Sheet] the copied or added sheet
     def add_or_copy_sheet(sheet = nil, opts = { })
       if sheet.is_a? Hash
@@ -710,16 +717,14 @@ module RobustExcelOle
     # @param  [String]      name      the name of the range
     # @param  [Hash]        opts      the options
     # @option opts [Symbol] :default  the default value that is provided if no contents could be returned
-    # @raise  ExcelError if range name is not in the workbook or if range value could not be evaluated
     # @return [Variant] the contents of a range with given name
-  
     def nameval(name, opts = {:default => nil})
       default_val = opts[:default]
       begin
         name_obj = self.Names.Item(name)
       rescue WIN32OLERuntimeError
         return default_val if default_val
-        raise ExcelError, "name #{name.inspect} not in #{File.basename(self.stored_filename).inspect}"
+        raise NameNotFound, "name #{name.inspect} not in #{File.basename(self.stored_filename).inspect}"
       end
       begin
         value = name_obj.RefersToRange.Value
@@ -728,12 +733,12 @@ module RobustExcelOle
           value = self.sheet(1).Evaluate(name_obj.Name)
         rescue WIN32OLERuntimeError
           return default_val if default_val
-          raise ExcelError, "cannot evaluate name #{name.inspect} in #{File.basename(self.stored_filename).inspect}"
+          raise RangeNotEvaluatable, "cannot evaluate range named #{name.inspect} in #{File.basename(self.stored_filename).inspect}"
         end
       end
       if value == RobustExcelOle::XlErrName  # -2146826259
         return default_val if default_val
-        raise ExcelError, "cannot evaluate name #{name.inspect} in #{File.basename(self.stored_filename).inspect}"
+        raise RangeNotEvaluatable, "cannot evaluate range named #{name.inspect} in #{File.basename(self.stored_filename).inspect}"
       end 
       return default_val if default_val && value.nil?
       value      
@@ -742,46 +747,44 @@ module RobustExcelOle
     # sets the contents of a range
     # @param [String]  name  the name of a range
     # @param [Variant] value the contents of the range
-    # @raise ExcelError if range name is not in the workbook or if value could not be assigned to range
     def set_nameval(name, value) 
       begin
         name_obj = self.Names.Item(name)
       rescue WIN32OLERuntimeError
-        raise ExcelError, "name #{name.inspect} not in #{File.basename(self.stored_filename).inspect}"  
+        raise NameNotFound, "name #{name.inspect} not in #{File.basename(self.stored_filename).inspect}"  
       end
       begin
         name_obj.RefersToRange.Value = value
       rescue WIN32OLERuntimeError
-        raise ExcelError, "cannot assign value to range named #{name.inspect} in #{File.basename(self.stored_filename).inspect}"    
+        raise RangeNotEvaluatable, "cannot assign value to range named #{name.inspect} in #{File.basename(self.stored_filename).inspect}"    
       end
     end    
 
     # renames a range
     # @param [String] name     the previous range name
     # @param [String] new_name the new range name
-    # @raise ExcelError if name is not in the file, or if new_name cannot be set
     def rename_range(name, new_name)
       begin
         item = self.Names.Item(name)
       rescue WIN32OLERuntimeError
-        raise ExcelError, "name #{name.inspect} not in #{File.basename(self.stored_filename).inspect}"  
+        raise NameNotFound, "name #{name.inspect} not in #{File.basename(self.stored_filename).inspect}"  
       end
       begin
         item.Name = new_name
       rescue WIN32OLERuntimeError
-        raise ExcelError, "name error in #{File.basename(self.stored_filename).inspect}"      
+        raise UnexpectedError, "name error in #{File.basename(self.stored_filename).inspect}"      
       end
     end
 
     # brings workbook to foreground, makes it available for heyboard inputs, makes the Excel instance visible
-    # @raise ExcelError if workbook cannot be activated    
     def activate      
       @excel.visible = true
       begin
-        Win32API.new("user32","SetForegroundWindow","I","I").call(@excel.hwnd)     # Excel  2010
+        Win32API.new("user32","SetForegroundWindow","I","I").call    # Excel  2010
+        SetForegroundWindow.call(@excel.Hwnd)
         @ole_workbook.Activate   # Excel 2007
-      rescue WIN32OLERuntimeError
-        raise ExcelError, "cannot activate"
+      rescue WIN32OLERuntimeError => msg
+        raise UnexpectedError, "cannot activate: #{message.msg}"
       end
     end
 
@@ -796,7 +799,7 @@ module RobustExcelOle
       saved = @ole_workbook.Saved
       @excel.visible = true if visible_value
       @ole_workbook.Windows(@ole_workbook.Name).Visible = visible_value if @excel.Visible
-      save if saved && (not self.ReadOnly)
+      @ole_workbook.Saved = saved
     end
 
     # returns true, if the workbook reacts to methods, false otherwise
@@ -893,7 +896,7 @@ module RobustExcelOle
     def method_missing(name, *args)   # :nodoc: #
       if name.to_s[0,1] =~ /[A-Z]/ 
         begin
-          raise ExcelError, "method missing: workbook not alive" unless alive?
+          raise ObjectNotAlive, "method missing: workbook not alive" unless alive?
           @ole_workbook.send(name, *args)
         rescue WIN32OLERuntimeError => msg
           if msg.message =~ /unknown property or method/
@@ -912,31 +915,6 @@ public
 
   Workbook = Book
 
-  class ExcelError < RuntimeError    # :nodoc: #
-  end
 
-  class ExcelErrorOpen < ExcelError   # :nodoc: #
-  end
-
-  class ExcelErrorClose < ExcelError    # :nodoc: #
-  end
-
-  class ExcelErrorSave < ExcelError   # :nodoc: #
-  end
-
-  class ExcelErrorSaveFailed < ExcelErrorSave  # :nodoc: #
-  end
-
-  class ExcelErrorSaveUnknown < ExcelErrorSave  # :nodoc: #
-  end
-
-  class ExcelUserCanceled < RuntimeError # :nodoc: #
-  end
-  
-  class ExcelErrorSheet < ExcelError    # :nodoc: #
-  end
-
-  class ExcelErrorSheetUnknown < ExcelErrorSheet    # :nodoc: #
-  end
 
 end