robust_excel_ole 1.1.3 → 1.1.4

data/README_save_close.rdoc

@@ -0,0 +1,77 @@
+= RobustExcelOle
+
+== Saving and closing workbooks
+
+=== Saving a workbook.
+
+Imagine, you have opened a workbook with
+
+  book = Workbook.open('workbook.xls', :visible => true)
+
+and have modified it.
+
+You can save the workbook by
+
+  book.save
+
+If you want to save a workbook with a file name, then use
+
+  book.save_as('new_workbook.xls')
+
+The options and respective valid values are the following:
+
++:if_exists+:: +:raise+ (default), +:overwrite+, +:alert+
++:if_obstruced+:: +:raise (default), +:forget+, +:save+, +close_if_saved
+
+The option +:if_exists+ :
+
+If a workbook with the file name already exists, then
+
++:raise+::     Raise an exeption. Don't write the file.
++:overwrite+:: Delete the existing file and write the file. If the workbook is open in an Excel instance, then raise an exception.
++:alert+::     Give the control to Excel.
+  
+For example, you want to save a workbook and overwrite the file if it exists before, then use
+
+  book.save_as('another_workbook.xls', :if_exists => :overwrite) 
+
+If a workbook blocks the workbook that should be saved, then the former one can be saved and closed before.
+
+  book = Workbook.open('workbook.xls')
+  book2 = Workbook.open('another_workbook.xls')
+  book2.save_as('dir/workbook.xls', :if_exists => :overwrite, :if_obstructed => :save)  
+
+=== Closing a workbook.
+
+You can close the workbook with the command
+
+  book.close
+
+There is one option: +:if_unsaved+ . It can have one of the following values:
+
++:raise+ (default), +:save+, +:forget+, +:alert+
+
+The option specifies: If the workbook is unsaved, then
+
++:save+::   Save the workbook before closing it.
++:raise+::  Raise an exception. Don't close the workbook.
++:forget+:: Close the workbook. 
++:alert+::  Give control to Excel.
+
+=== Opening, saving and closing a workbook under a certain name
+
+You can open a workbook with given file name.
+
+  book = Workbook.open('workbook.xls')
+
+You can save a workbook with given file name, if it is open.
+
+  Workbook.save_as('workbook.xls')
+
+The workbook can be saved under a new file name, if it is open.
+
+  Workbook.save_as('workbook.xls', 'new_workbook.xls')
+
+Finally the workbook can be closed with a given filename.
+
+  Workbook.close('workbook.xls')

data/README_sheet.rdoc

@@ -0,0 +1,71 @@
+= RobustExcelOle
+
+== Accessing and processing worksheets
+
+Worksheets are represented by Sheet objects.
+
+Assume you have opened a workbook
+
+  book = Workbook.open('workbook.xls', :visible => true)
+
+=== Accessing a worksheet.
+
+You can access a worksheet by giving the number
+
+  sheet = book.sheet(1)
+
+or its name
+
+  sheet = book.sheet('Sheet1')
+
+You can get the first and last worksheet with
+
+  sheet = book.first_sheet  
+
+and
+
+  sheet = book.last_sheet  
+
+You can access all sheet objects by using the methods Workbook#each.
+
+  book.each do |sheet|               
+    # do something with sheet
+  end
+
+=== Reading and changing the worksheet name
+
+You can read and change the worksheet name.
+
+  sheet1.name
+  # => "Sheet1"
+
+  sheet1.name = "new_sheet"
+
+=== Adding and copying a worksheet.
+
+You can add (append) an empty worksheet using
+
+  book.add_empty_sheet
+
+Additionally you can name it.
+
+  book.add_empty_sheet(:as => 'sheet_name')
+
+You can specify the position of the added empty worksheet.
+
+  book.add_empty_sheet(:as => 'new_name', :before => another_sheet)
+
+You can copy a worksheet and add it.
+
+  book.copy_sheet sheet
+
+Additionally you can specify a name and a position.
+
+  book.copy_sheet(sheet, :as => 'new_name', :after => another_sheet)
+
+If you want to copy a worksheet, if a sheet is given, and add an empty worksheet, if no worksheet is given, then use
+
+  book.add_or_copy_sheet
+
+  book.add_or_copy_sheet(sheet, :as => 'new_name', :after => another_sheet)  
+

data/examples/open_save_close/example_control_to_excel.rb

@@ -26,13 +26,13 @@ begin
   Excel.current.visible = true
   begin
   	book.close(:if_unsaved => :alert)                      # close the unsaved book. 
-  rescue WorkbookError => msg                          # user is asked whether the unsaved book shall be saved
+  rescue WorkbookREOError => msg                          # user is asked whether the unsaved book shall be saved
   	puts "#{msg.message}"                                  # if the user chooses to cancel, then an expeption is raised
   end
   if new_book then
   	begin
   	  new_book.save_as(file_name, :if_exists => :alert)    # save the new book, if it was opened
-  	rescue WorkbookError => msg                           # user is asked, whether the existing file shall be overwritten
+  	rescue WorkbookREOError => msg                           # user is asked, whether the existing file shall be overwritten
   	  puts "save_as: #{msg.message}"                       # if the user chooses "no" or "cancel", an exception is raised
   	end 
 

data/lib/robust_excel_ole/book.rb

@@ -25,13 +25,8 @@ module RobustExcelOle
       :check_compatibility => false,       
       :update_links => :never
     }
-
-    SYNONYMS_OPTS = [[[:default],[:d]], [[:force], [:f]], 
-                     [[:default,:excel],[:default_excel]],[[:force,:excel],[:force_excel]],                    
-                     [[:default,:excel],[:default,:e]], [[:force,:excel],[:force,:e]],
-                     [[:default,:visible],[:default,:v]], [[:force,:visible],[:force,:v]],
-                     [[:force,:visible],[:visible]], [[:force,:visible],[:v]]
-    ]
+     
+    ABBREVIATIONS = [[:default,:d], [:force, :f], [:excel, :e], [:visible, :v]]
 
     class << self
       
@@ -95,11 +90,14 @@ module RobustExcelOle
                  (not (book.alive? && (not book.saved) && (not options[:if_unsaved] == :accept))))
               book.options = options
               book.ensure_excel(options) # unless book.excel.alive?
-              # if the book is opened as readonly and should be opened as writable, then close it and open the book with the new readonly mode
-              book.close if (book.alive? && (not book.writable) && (not options[:read_only]))
+              # if the ReadOnly status shall be changed, then save, close and reopen it
+              book.close(:if_unsaved => :save) if (book.alive? && 
+                (((not book.writable) and (not options[:read_only])) or
+                  (book.writable and options[:read_only]))) 
               # reopens the book
               book.ensure_workbook(file,options) unless book.alive?
               book.visible = options[:force][:visible] unless options[:force][:visible].nil?
+              book.CheckCompatibility = options[:check_compatibility] unless options[:check_compatibility].nil?
               book.excel.calculation = options[:calculation] unless options[:calculation].nil?
               return book
             end
@@ -139,8 +137,9 @@ module RobustExcelOle
     # @param [Hash]    opts              the options
     # @option opts [Symbol] see above
     # @return [Book] a workbook
-    def initialize(file_or_workbook, opts={ }, &block)
-      options = self.class.process_options(opts)
+    #def initialize(file_or_workbook, opts={ }, &block)
+    def initialize(file_or_workbook, options={ }, &block)
+      #options = self.class.process_options(opts)
       if file_or_workbook.is_a? WIN32OLE        
         workbook = file_or_workbook
         @ole_workbook = workbook        
@@ -169,29 +168,41 @@ module RobustExcelOle
 
   private
 
-    # merges options with defaults and translates abbreviations and synonyms
-    def self.process_options(options) # :nodoc: #
+    # translates abbreviations and synonyms and merges with default options
+    def self.process_options(options, proc_opts = {:use_defaults => true})
       translator = proc do |opts|
-        SYNONYMS_OPTS.each do |a|
-          synonym = a[1][1].nil? ? opts[a[1][0]] : opts[a[1][0]][a[1][1]] unless opts[a[1][0]].nil?
-          unless synonym.nil?
-            if a[0][1].nil?
-              opts[a[0][0]] = synonym if opts[a[0][0]].nil?
-            else
-              opts[a[0][0]] = {} if opts[a[0][0]].nil?
-              opts[a[0][0]][a[0][1]] = synonym if opts[a[0][0]][a[0][1]].nil?
+        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{|long,short| new_k = long if k == short}
+              erg[new_key][new_k] = v
             end
-          end          
+          else
+            erg[new_key] = value
+          end
         end
-        opts[:default][:excel] = :current if (not opts[:default].nil?) && (opts[:default][:excel] == :reuse || opts[:default][:excel] == :active)
-        opts[:force][:excel] = :current if (not opts[:force].nil?) && (opts[:force][:excel] == :reuse || opts[:force][:excel] == :active)        
-        opts
+        erg[:default] = {} if erg[:default].nil?
+        erg[:force] = {} if erg[:force].nil?
+        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
-      default_opts = translator.call(DEFAULT_OPEN_OPTS)
-      given_opts = translator.call(options)
-      opts = default_opts.merge(given_opts)
+      opts = translator.call(options)
+      default_open_opts = proc_opts[:use_defaults] ? DEFAULT_OPEN_OPTS : 
+        {:default => {:excel => :current}, :force => {}, :update_links => :never }
+      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[:force] = default_opts[:force].merge(opts[:force]) unless opts[:force].nil?  
       opts
     end
 
@@ -210,7 +221,7 @@ module RobustExcelOle
         begin
           object.excel
         rescue
-          raise TypeErrorREO, "given object is neither an Excel, a Workbook, nor a Win32ole"
+          raise TypeREOError, "given object is neither an Excel, a Workbook, nor a Win32ole"
         end
       end
     end
@@ -333,7 +344,7 @@ module RobustExcelOle
           begin
             workbooks = @excel.Workbooks
           rescue WIN32OLERuntimeError => msg
-            raise UnexpectedError, "WIN32OLERuntimeError: #{msg.message} #{msg.backtrace}"
+            raise UnexpectedREOError, "WIN32OLERuntimeError: #{msg.message} #{msg.backtrace}"
           end
           begin
             with_workaround_linked_workbooks_excel2007(options) do
@@ -343,14 +354,14 @@ module RobustExcelOle
           rescue WIN32OLERuntimeError => msg
             # for Excel2007: for option :if_unsaved => :alert and user cancels: this error appears?
             # if yes: distinguish these events
-            raise UnexpectedError, "WIN32OLERuntimeError: #{msg.message} #{msg.backtrace}"
+            raise UnexpectedREOError, "WIN32OLERuntimeError: #{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 => msg
-              raise UnexpectedError, "WIN32OLERuntimeError: #{msg.message}"
+              raise UnexpectedREOError, "WIN32OLERuntimeError: #{msg.message}"
             end
             if options[:force][:visible].nil? && (not options[:default][:visible].nil?)
               if @excel.created   
@@ -365,7 +376,7 @@ module RobustExcelOle
             @excel.calculation = options[:calculation] unless options[:calculation].nil?
             self.Saved = true # unless self.Saved # ToDo: this is too hard
           rescue WIN32OLERuntimeError => msg
-            raise UnexpectedError, "WIN32OLERuntimeError: #{msg.message} #{msg.backtrace}"
+            raise UnexpectedREOError, "WIN32OLERuntimeError: #{msg.message} #{msg.backtrace}"
           end       
         end
       end
@@ -490,7 +501,6 @@ module RobustExcelOle
     # @return [Book] a workbook
 
     # state = [:open, :saved, :writable, :visible, :calculation, :check_compatibility]
-
     def self.unobtrusively(file, opts = { }, &block) 
       options = {:if_closed => :current, 
                  :read_only => false,
@@ -540,14 +550,15 @@ module RobustExcelOle
     end
 
     # reopens a closed workbook
-    def reopen
-      self.class.open(self.stored_filename)
+    # @options options 
+    def reopen(options = { })
+      self.class.open(@stored_filename, options)
     end
 
     # simple save of a workbook.
-    # @option opts [Boolean]  states, whether colored ranges shall be discolored
+    # @option opts [Boolean] :discoloring  states, whether colored ranges shall be discolored
     # @return [Boolean] true, if successfully saved, nil otherwise
-    def save(opts = {:discoloring => false})      
+    def save(opts = {:discoloring => false})  
       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
@@ -558,7 +569,7 @@ module RobustExcelOle
         if msg.message =~ /SaveAs/ and msg.message =~ /Workbook/ then
           raise WorkbookNotSaved, "workbook not saved"
         else
-          raise UnexpectedError, "unknown WIN32OLERuntimeError:\n#{msg.message}"
+          raise UnexpectedREOError, "unknown WIN32OLERuntimeError:\n#{msg.message}"
         end       
       end      
       true
@@ -580,7 +591,7 @@ 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
-    # :discoloring     states, wheter colored ranges shall be discolored
+    # :discoloring     states, whether colored ranges shall be discolored
     # @return [Book], the book itself, if successfully saved, raises an exception otherwise
     def save_as(file, opts = { } )
       raise FileNameNotGiven, "filename is nil" if file.nil?
@@ -657,9 +668,9 @@ module RobustExcelOle
       rescue WIN32OLERuntimeError => msg
         if msg.message =~ /SaveAs/ and msg.message =~ /Workbook/ then
           # trace "save: canceled by user" if options[:if_exists] == :alert || options[:if_exists] == :excel
-          # another possible semantics. raise WorkbookError, "could not save Workbook"
+          # another possible semantics. raise WorkbookREOError, "could not save Workbook"
         else
-          raise UnexpectedError, "unknown WIN32OELERuntimeError:\n#{msg.message}"
+          raise UnexpectedREOError, "unknown WIN32OELERuntimeError:\n#{msg.message}"
         end       
       end
     end
@@ -667,6 +678,7 @@ module RobustExcelOle
   public
 
     # closes a given file if it is open
+    # @options opts [Symbol] :if_unsaved
     def self.close(file, opts = {:if_unsaved => :raise})
       book = bookstore.fetch(file) rescue nil
       book.close(opts) if book && book.alive?
@@ -799,10 +811,34 @@ module RobustExcelOle
       begin
         item.Name = new_name
       rescue WIN32OLERuntimeError
-        raise UnexpectedError, "name error in #{File.basename(self.stored_filename).inspect}"      
+        raise UnexpectedREOError, "name error in #{File.basename(self.stored_filename).inspect}"      
       end
     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 ((not writable) and (not opts[:read_only])) or (writable and opts[:read_only])          
+          #opts[:check_compatibility] = opts[:check_compatibility].nil? ? check_compatibility :
+          #                             DEFAULT_OPEN_OPTS[:check_compatibility] 
+          #opts[:check_compatibility] = opts[:check_compatibility].nil? ? check_compatibility :
+          #                             opts[:check_compatibility]
+          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?
+    end
+
     # brings workbook to foreground, makes it available for heyboard inputs, makes the Excel instance visible
     def focus
       self.visible = true

data/lib/robust_excel_ole/excel.rb

@@ -133,10 +133,6 @@ module RobustExcelOle
       self 
     end
 
-    def set_options(options)
-      self.class.new(@ole_excel, options)
-    end
-
   private
     
     # returns a Win32OLE object that represents a Excel instance to which Excel connects
@@ -217,9 +213,9 @@ module RobustExcelOle
         @ole_excel.Workbooks.Close
       rescue WIN32OLERuntimeError => msg
         if msg.message =~ /800A03EC/
-          raise ExcelError, "user canceled or runtime error"
+          raise ExcelREOError, "user canceled or runtime error"
         else 
-          raise UnexpectedError, "unknown WIN32OLERuntimeError: #{msg.message}"
+          raise UnexpectedREOError, "unknown WIN32OLERuntimeError: #{msg.message}"
         end
       end   
       weak_wkbks = nil
@@ -490,7 +486,7 @@ module RobustExcelOle
             raise FileNotFound, "could not save workbook with filename #{file_name.inspect}"
           else
             # todo some time: find out when this occurs : 
-            raise UnexpectedError, "unknown WIN32OLERuntimeError with filename #{file_name.inspect}: \n#{msg.message}"
+            raise UnexpectedREOError, "unknown WIN32OLERuntimeError with filename #{file_name.inspect}: \n#{msg.message}"
           end
         end      
       end
@@ -568,6 +564,32 @@ module RobustExcelOle
       end
     end
 
+    # set options in this Excel instance
+    def for_this_instance(options)
+      self.class.new(@ole_excel, options)
+    end
+
+    def set_options(options)
+      for_this_instance(options)
+    end
+
+    # set options in all workbooks
+    def for_all_workbooks(options)
+      ole_workbooks = begin
+        @ole_excel.Workbooks
+      rescue WIN32OLERuntimeError => msg
+        if msg.message =~ /failed to get Dispatch Interface/
+          raise ExcelDamaged, "Excel instance not alive or damaged"
+        else
+          raise ExcelREOError, "workbooks could not be determined"
+        end 
+      end
+      ole_workbooks.each do |ole_workbook|
+        book_class.open(ole_workbook).for_this_workbook(options)
+      end
+    end
+
+=begin
     # make all workbooks visible or invisible
     def workbooks_visible= visible_value
       begin
@@ -580,6 +602,7 @@ module RobustExcelOle
         raise ExcelDamaged, "Excel instance not alive or damaged" if msg.message =~ /failed to get Dispatch Interface/
       end
     end
+=end
 
     def focus
       self.visible = true