robust_excel_ole 0.4 → 0.5

data/examples/edit_sheets/example_access_sheets_and_cells.rb

@@ -14,7 +14,7 @@ begin
   simple_save_file = dir + 'workbook_save.xls'
   File.delete simple_save_file rescue nil
   book = Book.open(simple_file)      # open a book
-  sheet = book[0]                    # access a sheet via integer 
+  sheet = book.sheet(1)                    # access a sheet via integer 
   cell = sheet[1,1]                  # access the first cell
   puts "1st cell: #{cell.Value}"     # put the value of the first cell
   sheet[1,1] = "complex"             # write a value into a cell

data/examples/edit_sheets/example_adding_sheets.rb

@@ -33,7 +33,7 @@ begin
   show_sheets
 
   puts "adding a copy of the 2nd sheet"
-  sheet = @book[1]
+  sheet = @book.sheet(2)
   @book.add_sheet sheet
   show_sheets
 
@@ -50,7 +50,7 @@ begin
   show_sheets
 
   puts "adding a copy of the 4th sheet before the 7th sheet and name it 'sheet_copy'"
-  @book.add_sheet(@book[3], :as => 'sheet_copy', :after => @book[6])
+  @book.add_sheet(@book.sheet(4), :as => 'sheet_copy', :after => @book.sheet(7))
   show_sheets
 
   puts"adding a copy of the 2nd sheet and name it again 'second_sheet_copy'"

data/examples/edit_sheets/example_copying.rb

@@ -41,7 +41,7 @@ begin
     end
     
     sheet_names.each do |sheet_name|
-      book[sheet_name].Delete()
+      book.sheet(sheet_name).Delete()
     end
   end
 end

data/examples/edit_sheets/example_expanding.rb

@@ -42,7 +42,7 @@ begin
     end
     
     sheet_names.each do |sheet_name|
-      book[sheet_name].Delete()
+      book.sheet(sheet_name).Delete()
     end
   end
 end

data/examples/edit_sheets/example_ranges.rb

@@ -14,7 +14,7 @@ begin
   simple_save_file = dir + 'workbook_save.xls'
   File.delete simple_save_file rescue nil
   book = Book.open(simple_file)      # open a book
-  sheet = book['Sheet1']             # access a sheet via the name
+  sheet = book.sheet('Sheet1')             # access a sheet via the name
   row_r = sheet.row_range(1)         # access the whole range of the first row
   col_r = sheet.col_range(1, 1..2)   # access the first two cells of the range of the first column
   cell = col_r[0]                    # access the first cell of these cells 

data/examples/edit_sheets/example_saving.rb

@@ -25,13 +25,13 @@ begin
       book = Book.open(file_sheet_name)
       book.add_sheet sheet_orig
       book.each do |sheet|
-        sheet.Delete() unless sheet.name == sheet_orig.name 
+        sheet.Delete unless sheet.name == sheet_orig.name 
       end
       book.close(:if_unsaved => :save)
       # alternative: delete all other sheets
       #book = Book.open(file_sheet_name, :force_excel => :new, :visible => true)
       #book.each do |sheet|
-      #  book[sheet.Name].Delete() unless sheet.Name == sheet_orig.Name
+      #  book.sheet(sheet.Name).Delete() unless sheet.Name == sheet_orig.Name
       #end
     end
   end

data/examples/open_save_close/example_control_to_excel.rb

@@ -14,7 +14,7 @@ begin
   book = Book.open(file_name)          # open a book
   book.excel.visible = true                   # make current Excel visible 
   sleep 1
-  sheet = book[0]                                                        # access a sheet
+  sheet = book.sheet(1)                                                        # access a sheet
   sheet[1,1] = sheet[1,1].Value == "simple" ? "complex" : "simple"       # change a cell
   sleep 1
   begin

data/examples/open_save_close/example_if_obstructed_closeifsaved.rb

@@ -14,7 +14,7 @@ begin
   other_file_name = dir + 'more_data/workbook.xls'
   book = Book.open(file_name, :visible => true)  # open a book, make Excel visible
   sleep 1
-  sheet = book[0]
+  sheet = book.sheet(1)
   first_cell = sheet[1,1].Value                                   # access a sheet
   sheet[1,1] = first_cell == "simple" ? "complex" : "simple"      # change a cell
   sleep 1
@@ -26,7 +26,7 @@ begin
   book.save                                                           # save the unsaved book
   new_book = Book.open(file_name, :if_obstructed => :close_if_saved)  # open the new book, close the saved book    
   sleep 1
-  new_sheet = new_book[0]
+  new_sheet = new_book.sheet(1)
   new_first_cell = new_sheet[1,1].Value
   puts "the old book was saved" unless new_first_cell == first_cell 
   new_book.close                                 # close the books                  

data/examples/open_save_close/example_if_obstructed_save.rb

@@ -14,7 +14,7 @@ begin
   other_file_name = dir + 'more_data/workbook.xls'
   book = Book.open(file_name, :visible => true)  # open a book, make Excel visible
   sleep 1
-  sheet = book[0]
+  sheet = book.sheet(1)
   first_cell = sheet[1,1].value                                   # access a sheet
   sheet[1,1] = first_cell == "simple" ? "complex" : "simple"      # change a cell
   sleep 1
@@ -22,7 +22,7 @@ begin
   sleep 1                                                         #save the old book, close it, before
   old_book = Book.open(file_name, :if_obstructed => :forget ,:visible => true) # open the old book    
   sleep 1
-  old_sheet = old_book[0]
+  old_sheet = old_book.sheet(1)
   old_first_cell = old_sheet[1,1].value
   puts "the old book was saved" unless old_first_cell == first_cell 
   new_book.close                                 # close the books                      

data/examples/open_save_close/example_if_unsaved_accept.rb

@@ -12,7 +12,7 @@ begin
   dir = create_tmpdir
   file_name = dir + 'workbook.xls' 
   book = Book.open(file_name)                      # open a book 
-  sheet = book[0]                                                  # access a sheet
+  sheet = book.sheet(1)                                                  # access a sheet
   sheet[1,1] = sheet[1,1].value == "simple" ? "complex" : "simple" # change a cell
   begin
     new_book = Book.open(file_name)                # open another book with the same file name

data/examples/open_save_close/example_if_unsaved_forget.rb

@@ -14,13 +14,13 @@ begin
   book = Book.open(file_name)                      # open a book
   book.excel.visible = true                        # make current Excel visible 
   sleep 1
-  sheet = book[0]                                            # access a sheet
+  sheet = book.sheet(1)                                            # access a sheet
   first_cell = sheet[1,1].value
   sheet[1,1] = first_cell == "simple" ? "complex" : "simple" # change a cell
   sleep 1
   new_book = Book.open(file_name, :if_unsaved => :forget) # open another book with the same file name 
                                                           # and close the unsaved book without saving it
-  sheet_new_book = new_book[0]
+  sheet_new_book = new_book.sheet(1)
   if (not book.alive?) && new_book.alive? && sheet_new_book[1,1].value == first_cell then # check whether the unsaved book 
     puts "open with :if_unsaved => :forget : the unsaved book is closed and not saved."     # is closed and was not saved
   end

data/examples/open_save_close/example_if_unsaved_forget_more.rb

@@ -14,12 +14,12 @@ begin
   book = Book.open(file_name)                      # open a book
   book.excel.visible = true                        # make current Excel visible 
   sleep
-  sheet = book[0]                                            # access a sheet
+  sheet = book.sheet(1)                                            # access a sheet
   first_cell = sheet[1,1].value
   sheet[1,1] = first_cell == "simple" ? "complex" : "simple" # change a cell
   sleep 1
   new_book = Book.open(file_name, :if_unsaved => :new_excel, :visible => true) # open another book with the same file name in a new Excel
-  sheet_new_book = new_book[0]
+  sheet_new_book = new_book.sheet(1)
   if (not book.alive?) && new_book.alive? && sheet_new_book[1,1].value == first_cell then # check whether the unsaved book 
     puts "open with :if_unsaved => :forget : the unsaved book is closed and not saved."     # is closed and was not saved
   end
@@ -28,7 +28,7 @@ begin
   # open another book in the running Excel application, and make Excel visible, closing the unsaved book
   another_book = Book.open(file_name, :if_unsaved => :forget, :visible => true)  
   sleep 1
-  sheet_another_book = another_book[0]
+  sheet_another_book = another_book.sheet(1)
   sheet_another_book[1,1] = sheet_another_book[1,1].value == "simple" ? "complex" : "simple" # change a cell                                                                   
   another_book.close(:if_unsaved => :forget )           # close the last book without saving it.                      
   book.close(:if_unsaved => :save)                      # close the first book and save it before

data/examples/open_save_close/example_read_only.rb

@@ -12,7 +12,7 @@ begin
   file_name = dir + 'workbook.xls'
   other_file_name = dir + 'different_workbook.xls'
   book = Book.open(file_name, :read_only => true, :visible => true) # open a book with read_only and make Excel visible
-  sheet = book[0]                                     			        # access a sheet
+  sheet = book.sheet(1)                                     			        # access a sheet
   sleep 1     
   sheet[1,1] = sheet[1,1].value == "simple" ? "complex" : "simple" # change a cell
   sleep 1

data/examples/open_save_close/example_rename_cells.rb

@@ -13,7 +13,7 @@ begin
   file_name = dir + 'workbook.xls'
   book = Book.open(file_name)                                # open a book.  default:  :read_only => false
   book.excel.visible = true                                          # make current Excel visible
-  sheet = book[0]
+  sheet = book.sheet(1)
   workbook = book.ole_workbook
   fullname = workbook.Fullname
   puts "fullname: #{fullname}"  

data/examples/open_save_close/example_simple.rb

@@ -19,7 +19,7 @@ begin
   other_file_name = dir + 'different_workbook.xls'
   book = Book.open(file_name)                                # open a book.  default:  :read_only => false
   book.excel.visible = true                                  # make current Excel visible
-  sheet = book[0]                                            # access a sheet
+  sheet = book.sheet(1)                                            # access a sheet
   sleep 1     
   sheet[1,1] = sheet[1,1].value == "simple" ? "complex" : "simple"  # change a cell
   sleep 1

data/examples/open_save_close/example_unobtrusively.rb

@@ -11,14 +11,14 @@ begin
   dir = create_tmpdir
   simple_file = dir + 'workbook.xls'
   book = Book.open(simple_file, :visible => true)  # open a book, make Excel visible
-  old_sheet = book[0]
+  old_sheet = book.sheet(1)
   p "1st cell: #{old_sheet[1,1].value}"
   sleep 2
   Book.unobtrusively(simple_file) do |book|   # modify the book and keep its status unchanged
-    sheet = book[0]
+    sheet = book.sheet(1)
     sheet[1,1] = sheet[1,1].value == "simple" ? "complex" : "simple"
   end
-  new_sheet = book[0]
+  new_sheet = book.sheet(1)
   p "1st cell: #{new_sheet[1,1].value}"
   p "book saved" if book.Saved
   book.close                                 # close the book                      

data/lib/robust_excel_ole.rb

@@ -1,4 +1,5 @@
 require "win32ole"
+require File.join(File.dirname(__FILE__), 'robust_excel_ole/reo_common')
 require File.join(File.dirname(__FILE__), 'robust_excel_ole/general')
 require File.join(File.dirname(__FILE__), 'robust_excel_ole/excel')
 require File.join(File.dirname(__FILE__), 'robust_excel_ole/bookstore')

data/lib/robust_excel_ole/book.rb

@@ -4,7 +4,7 @@ require 'weakref'
 
 module RobustExcelOle
 
-  class Book
+  class Book < REOCommon
 
     attr_accessor :excel
     attr_accessor :ole_workbook
@@ -21,7 +21,8 @@ module RobustExcelOle
         :if_unsaved    => :raise,
         :if_obstructed => :raise,
         :if_absent     => :raise,
-        :read_only => false
+        :read_only => false,
+        :check_compatibility => true
       }
 
     class << self
@@ -31,7 +32,7 @@ module RobustExcelOle
       # @param [Hash] opts the options
       # @option opts [Variant] :default_excel  :reuse (default), :new, or <excel-instance>     
       # @option opts [Variant] :force_excel    :new (default), or <excel-instance>
-      # @option opts [Symbol]  :if_unsaved     :raise (default), :forget, :accept, :alert, or :new_excel
+      # @option opts [Symbol]  :if_unsaved     :raise (default), :forget, :accept, :alert, :excel, or :new_excel
       # @option opts [Symbol]  :if_obstructed  :raise (default), :forget, :save, :close_if_saved, or _new_excel
       # @option opts [Symbol]  :if_absent      :raise (default), or :create
       # @option opts [Boolean] :read_only      true (default), or false
@@ -52,7 +53,7 @@ module RobustExcelOle
       #                  :raise               -> raises an exception
       #                  :forget              -> close the unsaved workbook, open the new workbook             
       #                  :accept              -> lets the unsaved workbook open                  
-      #                  :alert               -> gives control to Excel
+      #                  :alert or :excel     -> gives control to Excel
       #                  :new_excel           -> opens the new workbook in a new Excel instance
       # :if_obstructed  if a workbook with the same name in a different path is open, then
       #                  :raise               -> raises an exception 
@@ -66,7 +67,8 @@ module RobustExcelOle
       #                  
       # :read_only     opens in read-only mode         
       # :displayalerts enables DisplayAlerts in Excel  
-      # :visible       makes visible in Excel          
+      # :visible       makes visible in Excel        
+      # :check_compatibility  check compatibility when saving
       # if :default_excel is set, then DisplayAlerts and Visible are set only if these parameters are given
       # @return [Book] a workbook
       def open(file, opts={ }, &block)
@@ -114,7 +116,7 @@ module RobustExcelOle
     end
 
     # creates a new Book object, if a file name is given
-    # lifts the workbook to a Book object, if a workbook is given    
+    # Promotes the workbook to a Book object, if a win32ole-workbook is given    
     # @param [Variant] file_or_workbook  file name or workbook
     # @param [Hash]    opts              the options
     # @option opts [Symbol] see above
@@ -165,7 +167,11 @@ module RobustExcelOle
           object.excel
         end
       else
-        object.excel
+        begin
+          object.excel
+        rescue
+          raise ExcelErrorOpen, "given object is neither an Excel, a Book, nor a Win32ole"
+        end
       end
       #rescue
         # trace "no Excel, Book, or WIN32OLE object representing a Workbook or an Excel instance"
@@ -215,7 +221,7 @@ module RobustExcelOle
         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: #{File.basename(file).inspect}"
+            raise ExcelErrorOpen, "blocked by a book with the same name in a different path: #{@ole_workbook.Fullname.tr('\\','/')}"
           when :forget
             @ole_workbook.Close
             @ole_workbook = nil
@@ -227,7 +233,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: #{File.basename(file).inspect}"
+              raise ExcelErrorOpen, "workbook with the same name in a different path is unsaved: #{@ole_workbook.Fullname.tr('\\','/')}"
             else 
               @ole_workbook.Close
               @ole_workbook = nil
@@ -253,7 +259,7 @@ module RobustExcelOle
               open_or_create_workbook(file, options)
             when :accept
               # do nothing
-            when :alert
+            when :alert, :excel
               @excel.with_displayalerts true do
                 open_or_create_workbook(file,options)
               end 
@@ -299,7 +305,8 @@ module RobustExcelOle
           workbooks.Add if @excel.Version == "12.0" && count == 0
           workbooks.Open(filename,{ 'ReadOnly' => options[:read_only] })
           workbooks.Item(1).Close if @excel.Version == "12.0" && count == 0
-          @can_be_closed = false
+          workbooks.Item(1).CheckCompatibility = options[:check_compatibility]
+          @can_be_closed = false if @can_be_closed.nil?
         rescue WIN32OLERuntimeError => msg
           trace "WIN32OLERuntimeError: #{msg.message}" 
           if msg.message =~ /800A03EC/
@@ -329,7 +336,7 @@ module RobustExcelOle
     #                      :save            -> saves the workbook before it is closed                  
     #                      :forget          -> closes the workbook 
     #                      :keep_open       -> keep the workbook open
-    #                      :alert           -> gives control to excel
+    #                      :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 
     def close(opts = {:if_unsaved => :raise})
@@ -344,7 +351,7 @@ module RobustExcelOle
           close_workbook
         when :keep_open
           # nothing
-        when :alert
+        when :alert, :excel
           @excel.with_displayalerts true do
             close_workbook
           end
@@ -354,7 +361,8 @@ module RobustExcelOle
       else
         close_workbook
       end
-      raise ExcelUserCanceled, "close: canceled by user" if alive? && opts[:if_unsaved] == :alert && (not @ole_workbook.Saved)
+      raise ExcelUserCanceled, "close: canceled by user" if alive? && 
+      (opts[:if_unsaved] == :alert || opts[:if_unsaved] == :excel) && (not @ole_workbook.Saved)
     end
 
   private
@@ -403,8 +411,9 @@ module RobustExcelOle
     #                    true:  closes it and open it as writable in the Excel instance where it was open so far
     #                    false (default)   opens it as writable in another running excel instance, if it exists,
     #                                      otherwise open in a new Excel instance.
-    # :displayalerts enables DisplayAlerts in Excel  
-    # :visible       makes visible in Excel 
+    # :displayalerts      enables DisplayAlerts in Excel  
+    # :visible            makes visible in Excel 
+    # :check_compatibility checks compatibility when saving
     # @return [Book] a workbook
     def self.unobtrusively(file, if_closed = nil, opts = { }, &block) 
       if if_closed.is_a? Hash
@@ -415,7 +424,8 @@ module RobustExcelOle
       options = {
         :read_only => false,
         :readonly_excel => false,
-        :keep_open => false
+        :keep_open => false,
+        :check_compatibility => true
       }.merge(opts)
       book = bookstore.fetch(file, :prefer_writable => (not options[:read_only]))
       was_not_alive_or_nil = book.nil? || (not book.alive?)
@@ -428,7 +438,7 @@ module RobustExcelOle
           false
         end
       was_saved = was_not_alive_or_nil ? true : book.saved
-      was_writable = book.writable unless was_not_alive_or_nil
+      was_writable = book.writable unless was_not_alive_or_nil      
       begin 
         book = 
           if was_not_alive_or_nil 
@@ -450,15 +460,19 @@ module RobustExcelOle
           end
         book.excel.displayalerts = options[:displayalerts] unless options[:displayalerts].nil?
         book.excel.visible = options[:visible] unless options[:visible].nil?
+        old_check_compatibility = book.CheckCompatibility
+        book.CheckCompatibility = options[:check_compatibility]
         yield book
       ensure
-        book.save if (was_not_alive_or_nil || was_saved || ((not options[:read_only]) && (not was_writable))) && (not options[:read_only]) && book && (not book.saved)
+        was_saved_or_appeared = was_saved || was_not_alive_or_nil || (not was_writable)
+        book.save if book && (not book.saved) && (not options[:read_only]) && was_saved_or_appeared
         # book was open, readonly and shoud be modified
         if (not was_not_alive_or_nil) && (not options[:read_only]) && (not was_writable) && options[:readonly_excel]
           open(file, :force_excel => book.excel, :if_obstructed => :new_excel, :read_only => true)
         end
         @can_be_closed = true if options[:keep_open] && book
         book.close if (was_not_alive_or_nil && (not now_alive) && (not options[:keep_open]) && book)
+        book.CheckCompatibility = old_check_compatibility if book && book.alive?
       end
     end
 
@@ -467,136 +481,6 @@ module RobustExcelOle
       self.class.open(self.stored_filename)
     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}"  
-      end
-      begin
-        item.Name = new_name
-      rescue WIN32OLERuntimeError
-        raise ExcelError, "name error in #{File.basename(self.stored_filename).inspect}"      
-      end
-    end
-
-    # returns the contents of a range with given name
-    # @param  [String]      name      the range name
-    # @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
-    # @raise  SheetError if range value could not be evaluated
-    # @return [Variant] the contents of a range with given name
-    # if no contents could be returned, then return default value, if a default value was provided
-    #                                   raise an error, otherwise
-    def nvalue(name, opts = {:default => nil})
-      begin
-        item = self.Names.Item(name)
-      rescue WIN32OLERuntimeError
-        return opts[:default] if opts[:default]
-        raise ExcelError, "name #{name.inspect} not in #{File.basename(self.stored_filename).inspect}"
-      end
-      begin
-        value = item.RefersToRange.Value
-      rescue  WIN32OLERuntimeError
-        begin
-          sheet = self[0]
-          value = sheet.Evaluate(name)
-        rescue WIN32OLERuntimeError
-          return opts[:default] if opts[:default]
-          raise SheetError, "cannot evaluate name #{name.inspect} in sheet"
-        end
-      end
-      if value == -2146826259
-        return opts[:default] if opts[:default]
-        raise SheetError, "cannot evaluate name #{name.inspect} in sheet"
-      end 
-      return opts[:default] if (value.nil? && opts[:default])
-      value      
-    end
-
-    # sets the contents of a range with given name
-    # @param [String]  name  the range name
-    # @param [Variant] value the contents of the range
-    # @raise ExcelError if range name is not in the workbook or if a RefersToRange error occurs
-    def set_nvalue(name, value) 
-      begin
-        item = self.Names.Item(name)
-      rescue WIN32OLERuntimeError
-        raise ExcelError, "name #{name.inspect} not in #{File.basename(self.stored_filename).inspect}"  
-      end
-      begin
-        item.RefersToRange.Value = value
-      rescue WIN32OLERuntimeError
-        raise ExcelError, "RefersToRange error of name #{name.inspect} 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
-        @ole_workbook.Activate   # Excel 2007
-      rescue WIN32OLERuntimeError
-        raise ExcelError, "cannot activate"
-      end
-    end
-
-    # returns true, if the workbook is visible, false otherwise 
-    def visible
-      @excel.Windows(@ole_workbook.Name).Visible
-    end
-
-    # makes a workbook visible or invisible
-    # @param [Boolean] visible_value value that determines whether the workbook shall be visible
-    def visible= visible_value
-      saved = @ole_workbook.Saved
-      @excel.Windows(@ole_workbook.Name).Visible = visible_value
-      save if saved 
-    end
-
-    # returns true, if the workbook reacts to methods, false otherwise
-    def alive?
-      begin 
-        @ole_workbook.Name
-        true
-      rescue 
-        @ole_workbook = nil  # dead object won't be alive again
-        #t $!.message
-        false
-      end
-    end
-
-    # returns the full file name of the workbook
-    def filename
-      @ole_workbook.Fullname.tr('\\','/') rescue nil
-    end
-
-    def writable   # :nodoc: #
-      (not @ole_workbook.ReadOnly) if @ole_workbook
-    end
-
-    def saved   # :nodoc: #
-      @ole_workbook.Saved if @ole_workbook
-    end
-
-    # @return [Boolean] true, if the full book names and excel Instances are identical, false otherwise  
-    def == other_book
-      other_book.is_a?(Book) &&
-      @excel == other_book.excel &&
-      self.filename == other_book.filename  
-    end
-
-    def self.books
-      bookstore.books
-    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
@@ -618,13 +502,13 @@ module RobustExcelOle
     # saves a workbook with a given file name.
     # @param [String] file   file name
     # @param [Hash]   opts   the options
-    # @option opts [Symbol] :if_exists      :raise (default), :overwrite, or :alert
+    # @option opts [Symbol] :if_exists      :raise (default), :overwrite, or :alert, :excel
     # @option opts [Symbol] :if_obstructed  :raise (default), :forget, :save, or :close_if_saved
     # options: 
     # :if_exists  if a file with the same name exists, then  
     #               :raise     -> raises an exception, dont't write the file  (default)
     #               :overwrite -> writes the file, delete the old file
-    #               :alert     -> gives control to Excel
+    #               :alert or :excel -> gives control to Excel
     #  :if_obstructed   if a workbook with the same name and different path is already open and blocks the saving, then
     #                  :raise               -> raises an exception 
     #                  :forget              -> closes the blocking workbook
@@ -634,7 +518,7 @@ module RobustExcelOle
     # @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 [Boolean] true, if successfully saved, nil otherwise
+    # @return [Book], the book itself, if successfully saved, raises an exception otherwise
     def save_as(file = nil, opts = { } )
       raise ExcelErrorSave, "Workbook is not alive" if (not alive?)
       raise ExcelErrorSave, "Not opened for writing (opened with :read_only option)" if @ole_workbook.ReadOnly
@@ -647,7 +531,7 @@ module RobustExcelOle
         when :overwrite
           if file == self.filename
             save
-            return
+            return self
           else
             begin
               File.delete(file)
@@ -655,12 +539,11 @@ module RobustExcelOle
               raise ExcelErrorSave, "workbook is open and used in Excel"
             end
           end
-        when :alert 
+        when :alert, :excel 
           @excel.with_displayalerts true do
             save_as_workbook(file, options)
           end
-          true
-          return
+          return self
         when :raise
           raise ExcelErrorSave, "file already exists: #{File.basename(file).inspect}"
         else
@@ -676,7 +559,7 @@ module RobustExcelOle
       if blocking_workbook then
         case options[:if_obstructed]
         when :raise
-          raise ExcelErrorSave, "blocked by another workbook: #{File.basename(file).inspect}"
+          raise ExcelErrorSave, "blocked by another workbook: #{blocking_workbook.Fullname.tr('\\','/')}"
         when :forget
           # nothing
         when :save
@@ -689,7 +572,7 @@ module RobustExcelOle
         blocking_workbook.Close
       end
       save_as_workbook(file, options)
-      true
+      self
     end
 
   private
@@ -707,7 +590,7 @@ module RobustExcelOle
         bookstore.store(self)
       rescue WIN32OLERuntimeError => msg
         if msg.message =~ /SaveAs/ and msg.message =~ /Workbook/ then
-          if options[:if_exists] == :alert then 
+          if options[:if_exists] == :alert || options[:if_exists] == :excel then 
             raise ExcelErrorSave, "not saved or canceled by user"
           else
             return nil
@@ -722,65 +605,238 @@ module RobustExcelOle
   public
 
     # returns a sheet, if a sheet name or a number is given
-    # returns the value of the range, if a global name of a range in the book is given 
-    def [] name
-      name += 1 if name.is_a? Numeric
+    # @param [String] or [Number]
+    # @returns [Sheet]
+    def sheet(name)
       begin
         sheet_class.new(@ole_workbook.Worksheets.Item(name))
       rescue WIN32OLERuntimeError => msg
-        if msg.message =~ /8002000B/
-          nvalue(name)
-        else
-          raise ExcelError, "could neither return a sheet nor a value of a range when giving the name #{name.inspect}"
-        end
+        raise ExcelError, "could not return a sheet with name #{name.inspect}"
+        trace "#{msg.message}"
       end
-    end
-
-    # sets the value of a range given its name
-    # @param [String]  name  the name of the range
-    # @param [Variant] value the contents of the range
-    def []= (name, value)
-      set_nvalue(name,value)
-    end
+    end    
 
     def each
       @ole_workbook.Worksheets.each do |sheet|
         yield sheet_class.new(sheet)
       end
     end
+  
+    # copies a sheet to another position
+    # default: copied sheet is appended
+    # @param [Sheet] sheet a sheet that shall be copied
+    # @param [Hash]  opts  the options
+    # @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
+    # @return [Sheet] the copied sheet
+    def copy_sheet(sheet, opts = { })
+      new_sheet_name = opts.delete(:as)
+      after_or_before, base_sheet = opts.to_a.first || [:after, last_sheet]
+      sheet.Copy({ after_or_before.to_s => base_sheet.worksheet })
+      new_sheet = sheet_class.new(@excel.Activesheet)
+      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)
+      end
+      new_sheet
+    end      
 
-    # adds a sheet to the workbook
-    # @param [Sheet] sheet a sheet
+    # adds an empty sheet
+    # default: empty sheet is appended
     # @param [Hash]  opts  the options
-    # @option opts [Symbol] :as     new name of the copyed sheet
+    # @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
     # @return [Sheet] the added sheet
-    def add_sheet(sheet = nil, opts = { })
-      if sheet.is_a? Hash
-        opts = sheet
-        sheet = nil
-      end
+    def add_empty_sheet(opts = { })
       new_sheet_name = opts.delete(:as)
-      ws = @ole_workbook.Worksheets
-      after_or_before, base_sheet = opts.to_a.first || [:after, sheet_class.new(ws.Item(ws.Count))]
-      base_sheet = base_sheet.worksheet
-      sheet ? sheet.Copy({ after_or_before.to_s => base_sheet }) : @ole_workbook.WorkSheets.Add({ after_or_before.to_s => base_sheet })
+      after_or_before, base_sheet = opts.to_a.first || [:after, last_sheet]
+      @ole_workbook.Worksheets.Add({ after_or_before.to_s => base_sheet.worksheet })
       new_sheet = sheet_class.new(@excel.Activesheet)
       begin
         new_sheet.name = new_sheet_name if new_sheet_name
       rescue WIN32OLERuntimeError => msg
-        if msg.message =~ /800A03EC/ 
-          raise ExcelErrorSheet, "sheet name already exists"
-        else
-          trace "#{msg.message}"
-          raise ExcelErrorSheetUnknown
-        end
+        msg.message =~ /800A03EC/ ? raise(ExcelErrorSheet, "sheet name already exists") : raise(ExcelErrorSheetUnknown)
       end
       new_sheet
+    end    
+
+    # copies a sheet to another position if a sheet is given, or adds an empty sheet
+    # default: copied or empty sheet is appended, i.e. added behind the last sheet
+    # @param [Sheet] sheet a sheet that shall be copied (optional)
+    # @param [Hash]  opts  the options
+    # @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
+        opts = sheet
+        sheet = nil
+      end
+      sheet ? copy_sheet(sheet, opts) : add_empty_sheet(opts)
     end      
 
+    # for compatibility to older versions
+    def add_sheet(sheet = nil, opts = { })
+      add_or_copy_sheet(sheet, opts)
+    end 
+
+    def last_sheet
+      sheet_class.new(@ole_workbook.Worksheets.Item(@ole_workbook.Worksheets.Count))
+    end
+
+    def first_sheet
+      sheet_class.new(@ole_workbook.Worksheets.Item(1))
+    end
+
+    # returns the value of a range
+    # @param [String] name the name of a range
+    # @returns [Variant] the value of the range
+    def [] name
+      nameval(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_nameval(name,value)
+    end
+
+    # returns the contents of a range with given name
+    # evaluates formula contents of the range is a formula
+    # if no contents could be returned, then return default value, if provided, raise error otherwise
+    # @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})
+      begin
+        name_obj = self.Names.Item(name)
+      rescue WIN32OLERuntimeError
+        return opts[:default] if opts[:default]
+        raise ExcelError, "name #{name.inspect} not in #{File.basename(self.stored_filename).inspect}"
+      end
+      begin
+        value = name_obj.RefersToRange.Value
+      rescue  WIN32OLERuntimeError
+        begin
+          value = self.sheet(1).Evaluate(name_obj.Name)
+        rescue WIN32OLERuntimeError
+          return opts[:default] if opts[:default]
+          raise SheetError, "cannot evaluate name #{name.inspect} in #{File.basename(self.stored_filename).inspect}"
+        end
+      end
+      if value == -2146826259
+        return opts[:default] if opts[:default]
+        raise SheetError, "cannot evaluate name #{name.inspect} in #{File.basename(self.stored_filename).inspect}"
+      end 
+      return opts[:default] if (value.nil? && opts[:default])
+      value      
+    end
+
+    # 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}"  
+      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}"    
+      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}"  
+      end
+      begin
+        item.Name = new_name
+      rescue WIN32OLERuntimeError
+        raise ExcelError, "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
+        @ole_workbook.Activate   # Excel 2007
+      rescue WIN32OLERuntimeError
+        raise ExcelError, "cannot activate"
+      end
+    end
+
+    # returns true, if the workbook is visible, false otherwise 
+    def visible
+      @excel.Windows(@ole_workbook.Name).Visible
+    end
+
+    # makes a workbook visible or invisible
+    # @param [Boolean] visible_value value that determines whether the workbook shall be visible
+    def visible= visible_value
+      saved = @ole_workbook.Saved
+      @excel.Windows(@ole_workbook.Name).Visible = visible_value
+      save if saved 
+    end
+
+    # returns true, if the workbook reacts to methods, false otherwise
+    def alive?
+      begin 
+        @ole_workbook.Name
+        true
+      rescue 
+        @ole_workbook = nil  # dead object won't be alive again
+        #t $!.message
+        false
+      end
+    end
+
+    # returns the full file name of the workbook
+    def filename
+      @ole_workbook.Fullname.tr('\\','/') rescue nil
+    end
+
+    def writable   # :nodoc: #
+      (not @ole_workbook.ReadOnly) if @ole_workbook
+    end
+
+    def saved   # :nodoc: #
+      @ole_workbook.Saved if @ole_workbook
+    end
+
+    # @return [Boolean] true, if the full book names and excel Instances are identical, false otherwise  
+    def == other_book
+      other_book.is_a?(Book) &&
+      @excel == other_book.excel &&
+      self.filename == other_book.filename  
+    end
+
+    def self.books
+      bookstore.books
+    end
+
     def self.bookstore   # :nodoc: #
       @@bookstore ||= Bookstore.new
     end