robust_excel_ole 0.3.4 → 0.3.5

data/lib/robust_excel_ole/book.rb

@@ -1,4 +1,3 @@
-
 # -*- coding: utf-8 -*-
 
 require 'weakref'
@@ -11,12 +10,14 @@ module RobustExcelOle
     attr_accessor :stored_filename
     attr_accessor :options
 
+
       DEFAULT_OPEN_OPTS = { 
         :excel => :reuse,
         :default_excel => :reuse,
-        :if_locked     => :readonly,       
+        :if_lockraiseed     => :readonly,       
         :if_unsaved    => :raise,
         :if_obstructed => :raise,
+        :if_absent     => :raise,
         :read_only => false
       }
 
@@ -51,8 +52,9 @@ module RobustExcelOle
       #                  :close_if_saved      -> close the old book and open the new book, if the old book is saved,
       #                                          otherwise raise an exception.
       #                  :new_excel           -> open the new book in a new Excel    
-      # :if_absent       :create (default)    -> creates a new Excel file, if it does not exists  
-      #                  :raise               -> raises an exception     , if the file does not exists
+      # :if_absent       :raise (default)     -> raises an exception     , if the file does not exists
+      #                  :create              -> creates a new Excel file, if it does not exists  
+      #                  
       # :read_only     open in read-only mode         (default: false) 
       # :displayalerts enable DisplayAlerts in Excel  (default: false)
       # :visible       make visible in Excel          (default: false)
@@ -63,19 +65,18 @@ module RobustExcelOle
         book = nil
         if (not (current_options[:force_excel] == :new && (not current_options[:if_locked] == :take_writable)))
           # if readonly is true, then prefer a book that is given in force_excel if this option is set
-          book = book_store.fetch(file, 
+          book = bookstore.fetch(file, 
                   :prefer_writable => (not current_options[:read_only]), 
-                  :prefer_excel    => (current_options[:read_only] ? Book.excel(current_options[:force_excel]) : nil)) rescue nil
+                  :prefer_excel    => (current_options[:read_only] ? current_options[:force_excel].excel : nil)) rescue nil
           if book
-            #if (((not current_options[:force_excel]) || (current_options[:force_excel].excel == book.excel)) &&
-            if (((not current_options[:force_excel]) || (Book.excel(current_options[:force_excel]) == book.excel)) &&
+            if (((not current_options[:force_excel]) || (current_options[:force_excel].excel == book.excel)) &&
                  (not (book.alive? && (not book.saved) && (not current_options[:if_unsaved] == :accept))))
               book.options = DEFAULT_OPEN_OPTS.merge(opts)
               book.get_excel 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 current_options[:read_only]))
               # reopen the book
-              book.get_workbook unless book.alive?
+              book.get_workbook(file) unless book.alive?
               return book
             end
           end
@@ -86,11 +87,10 @@ module RobustExcelOle
     end
 
     def initialize(file, opts={ }, &block)
-      @options = DEFAULT_OPEN_OPTS.merge(opts)
-      @file = file      
+      @options = DEFAULT_OPEN_OPTS.merge(opts)      
       get_excel
-      get_workbook
-      book_store.store(self)
+      get_workbook file
+      bookstore.store(self)
       if block
         begin
           yield self
@@ -99,20 +99,33 @@ module RobustExcelOle
         end
       end
     end
+
+    def self.excel_class
+      @excel_class ||= begin
+        module_name = self.parent_name
+        "#{module_name}::Excel".constantize
+      rescue NameError => e
+        Excel
+      end
+    end
+
+    def excel_class
+      self.class.excel_class
+    end
+
     
     def get_excel
       if @options[:excel] == :reuse
-        @excel = Excel.new(:reuse => true)
+        @excel = excel_class.new(:reuse => true)
       end
       @excel_options = nil
       if (not @excel)
         if @options[:excel] == :new
           @excel_options = {:displayalerts => false, :visible => false}.merge(@options)
           @excel_options[:reuse] = false
-          @excel = Excel.new(@excel_options)
+          @excel = excel_class.new(@excel_options)
         else
-          @excel = @options[:excel]
-          @excel = Book.excel(@options[:excel])
+          @excel = @options[:excel].excel
         end
       end
       # if :excel => :new or (:excel => :reuse but could not reuse)
@@ -123,39 +136,46 @@ module RobustExcelOle
       end
     end
 
-    def get_workbook
-      raise ExcelErrorOpen, "file #{@file} not found" if ((not File.exist?(@file)) && @options[:if_absent] == :raise) 
-      @workbook = @excel.Workbooks.Item(File.basename(@file)) rescue nil
+    def get_workbook file
+      file = @stored_filename ? @stored_filename : file
+      unless File.exist?(file)
+        if @options[:if_absent] == :create
+          @workbook = excel_class.current.generate_workbook(file)
+        else 
+          raise ExcelErrorOpen, "file #{file} not found"
+        end
+      end
+      @workbook = @excel.Workbooks.Item(File.basename(file)) rescue nil
       if @workbook then
-        obstructed_by_other_book = (File.basename(@file) == File.basename(@workbook.Fullname)) && 
-                                   (not (RobustExcelOle::absolute_path(@file) == @workbook.Fullname))
+        obstructed_by_other_book = (File.basename(file) == File.basename(@workbook.Fullname)) && 
+                                   (not (RobustExcelOle::absolute_path(file) == @workbook.Fullname))
         # if book is obstructed by a book 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: #{File.basename(@file)}"
+            raise ExcelErrorOpen, "blocked by a book with the same name in a different path: #{File.basename(file)}"
           when :forget
             @workbook.Close
             @workbook = nil
-            open_or_create_workbook
+            open_or_create_workbook file
           when :save
             save unless @workbook.Saved
             @workbook.Close
             @workbook = nil
-            open_or_create_workbook
+            open_or_create_workbook file
           when :close_if_saved
             if (not @workbook.Saved) then
-              raise ExcelErrorOpen, "book with the same name in a different path is unsaved: #{File.basename(@file)}"
+              raise ExcelErrorOpen, "book with the same name in a different path is unsaved: #{File.basename(file)}"
             else 
               @workbook.Close
               @workbook = nil
-              open_or_create_workbook
+              open_or_create_workbook file
             end
           when :new_excel 
             @excel_options = {:displayalerts => false, :visible => false}.merge(@options)   
             @excel_options[:reuse] = false
-            @excel = Excel.new(@excel_options)
-            open_or_create_workbook
+            @excel = excel_class.new(@excel_options)
+            open_or_create_workbook file
           else
             raise ExcelErrorOpen, ":if_obstructed: invalid option: #{@options[:if_obstructed]}"
           end
@@ -164,22 +184,22 @@ module RobustExcelOle
           if (not @workbook.Saved) then
             case @options[:if_unsaved]
             when :raise
-              raise ExcelErrorOpen, "book is already open but not saved (#{File.basename(@file)})"
+              raise ExcelErrorOpen, "book is already open but not saved (#{File.basename(file)})"
             when :forget
               @workbook.Close
               @workbook = nil
-              open_or_create_workbook
+              open_or_create_workbook file
             when :accept
               # do nothing
             when :alert
               @excel.with_displayalerts true do
-                open_or_create_workbook
+                open_or_create_workbook file
               end 
             when :new_excel
               @excel_options = {:displayalerts => false, :visible => false}.merge(@options)
               @excel_options[:reuse] = false
-              @excel = Excel.new(@excel_options)
-              open_or_create_workbook
+              @excel = excel_class.new(@excel_options)
+              open_or_create_workbook file
             else
               raise ExcelErrorOpen, ":if_unsaved: invalid option: #{@options[:if_unsaved]}"
             end
@@ -187,23 +207,24 @@ module RobustExcelOle
         end
       else
         # book is not open
-        open_or_create_workbook
+        open_or_create_workbook file
       end
     end
 
-    def open_or_create_workbook
-      if (not File.exist?(@file))
-        @workbook = Excel.current.generate_workbook(@file)
-        return
-      end
+    def open_or_create_workbook file
       if ((not @workbook) || (@options[:if_unsaved] == :alert) || @options[:if_obstructed]) then
         begin
-          filename = RobustExcelOle::absolute_path(@file)
-          workbooks = @excel.Workbooks
+          filename = RobustExcelOle::absolute_path(file)
+          begin
+            workbooks = @excel.Workbooks
+          rescue RuntimeError => msg
+            puts "RuntimeError: #{msg.message}" 
+            raise ExcelErrorOpen, "Excel instance not alive or damaged" if msg.message =~ /failed to get Dispatch Interface/
+          end
           workbooks.Open(filename,{ 'ReadOnly' => @options[:read_only] })
         rescue WIN32OLERuntimeError => msg
-          puts "msg: #{msg}" 
-          raise ExcelErrorOpen, "open: user canceled or open error" if msg.message =~ /OLE error code:800A03EC/
+          puts "WIN32OLERuntimeError: #{msg.message}" 
+          raise ExcelErrorOpen, "open: user canceled or open error" if msg.message =~ /800A03EC/
         end   
         begin
           # workaround for bug in Excel 2010: workbook.Open does not always return 
@@ -215,20 +236,6 @@ module RobustExcelOle
       end
     end
 
-  private
-  
-    # return an Excel.
-    # return the given instance if it is an Excel and alive. If the given instance is a Book then take the Excel of the Book
-    def self.excel(instance)
-      raise ExcelErrorOpen, "provided instance is neither an Excel nor a Book: #{instance}" \
-        unless instance.is_a?(Excel) || instance.is_a?(Book)
-      excel = instance.is_a?(Book) ? instance.excel : instance
-      raise ExcelErrorOpen, "provided Excel instance is not alive" unless excel.alive?
-      excel
-    end
-
-  public
-
     # closes the book, if it is alive
     #
     # options:
@@ -269,91 +276,113 @@ module RobustExcelOle
 
   public
 
+    def self.for_reading(*args, &block)
+      args = args.dup
+      opts = args.last.is_a?(Hash) ? args.pop : {}
+      opts = {:read_only => true}.merge(opts)
+      args.push opts
+      unobtrusively(*args, &block)
+    end
+
+    def self.for_modifying(*args, &block)
+      args = args.dup
+      opts = args.last.is_a?(Hash) ? args.pop : {}
+      opts = {:read_only => false}.merge(opts)
+      args.push opts
+      unobtrusively(*args, &block)
+    end
+
     # modify a book such that its state (open/close, saved/unsaved, readonly/writable) remains unchanged.
-    #  options: 
-    #  :if_closed :  :hidden (default) : open closed books in one separate Excel instance that is not visible and has no displayaslerts
-    #                :reuse            : open closed books in the Excel instance of the book, if it exists, reuse another Excel, otherwise         
-    #                <excel-instance>  : open closed books in the given Excel instance
+    #  options:
+    #  :reuse (default)  : open closed books in the Excel instance of the book, if it exists, reuse another Excel, otherwise          
+    #  :hidden           : open closed books in one separate Excel instance that is not visible and has no displayaslerts    
+    #  <excel-instance>  : open closed books in the given Excel instance
     #  :read_only: Open the book unobtrusively for reading only  (default: false)
-    #  :use_readonly_excel:  if the book is opened only as ReadOnly and shall be modified, then
-    #              true:  close it and open it as writable in the excel instance where it was open so far
-    #              false (default)   open it as writable in another running excel instance, if it exists,
-    #                                otherwise open in a new excel instance.
+    #  :readonly_excel:  if the book is opened only as ReadOnly and shall be modified, then
+    #                    true:  close it and open it as writable in the excel instance where it was open so far
+    #                    false (default)   open it as writable in another running excel instance, if it exists,
+    #                                      otherwise open in a new excel instance.
     #  :keep_open: let the book open after unobtrusively opening (default: false)
-    def self.unobtrusively(file, opts = { })
+    def self.unobtrusively(file, if_closed = nil, opts = { }, &block) 
+      if if_closed.is_a? Hash
+        opts = if_closed
+        if_closed = nil
+      end
+      if_closed = :reuse unless if_closed
       options = {
-        :if_closed => :hidden,
         :read_only => false,
-        :use_readonly_excel => false,
+        :readonly_excel => false,
         :keep_open => false,
       }.merge(opts)
-      book = book_store.fetch(file, :prefer_writable => (not options[:read_only]))
+      book = bookstore.fetch(file, :prefer_writable => (not options[:read_only]))
       was_not_alive_or_nil = book.nil? || (not book.alive?)
       was_saved = was_not_alive_or_nil ? true : book.saved
       was_writable = book.writable unless was_not_alive_or_nil
       begin 
         book = 
           if was_not_alive_or_nil 
-            case options[:if_closed] 
-            when :hidden 
-              open(file, :force_excel => book_store.hidden_excel)
+            case if_closed
             when :reuse
-              open(file)
+              open(file, :read_only => options[:read_only])
+            when :hidden 
+              open(file, :force_excel => bookstore.hidden_excel, :read_only => options[:read_only])
             else 
-              open(file, :force_excel => options[:if_closed])
+              open(file, :force_excel => if_closed, :read_only => options[:read_only])
             end
           else
             if was_writable || options[:read_only]
               book
             else
-              options[:use_readonly_excel] ? open(file, :force_excel => book.excel) : open(file, :force_excel => :new)
+              options[:readonly_excel] ? open(file, :force_excel => book.excel, :read_only => options[:read_only]) : 
+                                         open(file, :force_excel => :new, :read_only => options[:read_only])
             end
           end
         yield book
       ensure
-        book.save if (was_not_alive_or_nil || was_saved || ((not was_writable) && (not options[:read_only]))) && (book && (not book.saved))
+        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)
         # book was open, readonly and shoud be modified
-        if (not was_not_alive_or_nil) && (not options[:read_only]) && (not was_writable) && options[:use_readonly_excel]
+        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
         book.close if (was_not_alive_or_nil && (not opts[:keep_open]) && book)
       end
     end
 
+    def reopen
+      self.class.open(self.stored_filename)
+    end
+
     # rename a range
     def rename_range(name,new_name)
       begin
-        p "name: #{name}"
-        p "new_name: #{new_name}"
         item = self.Names.Item(name)
-        p "nil" if item.nil?
       rescue WIN32OLERuntimeError
-        raise ExcelErrorRename, "name #{name} not in #{File.basename(self.stored_filename)}"  
+        raise ExcelError, "name #{name} not in #{File.basename(self.stored_filename)}"  
       end
       begin
         item.Name = new_name
       rescue WIN32OLERuntimeError
-        raise ExcelErrorRename, "name error in #{File.basename(self.stored_filename)}"      
+        raise ExcelError, "name error in #{File.basename(self.stored_filename)}"      
       end
     end
 
     # returns the contents of a range with given name
-    def nvalue(name)
+    # if no contents could 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
-        raise ExcelErrorNValue, "name #{name} not in #{File.basename(self.stored_filename)}"  
+        return opts[:default] if opts[:default]
+        raise ExcelErrorNValue, "name #{name} not in #{File.basename(self.stored_filename)}"
       end
       begin
-        referstorange = item.RefersToRange
-      rescue WIN32OLERuntimeError
-        raise ExcelErrorNValue, "range error in #{File.basename(self.stored_filename)}"      
-      end
-      begin
-        referstorange.Value
-      rescue WIN32OLERuntimeError
-        raise ExcelErrorNValue, "value error in #{File.basename(self.stored_filename)}" 
+        value = item.RefersToRange.Value
+      rescue  WIN32OLERuntimeError
+        return opts[:default] if opts[:default]
+        raise ExcelErrorNValue, "RefersToRange error of name #{name} in #{File.basename(self.stored_filename)}"
       end
+      value
     end
 
     # set the contents of a range with given name
@@ -364,14 +393,19 @@ module RobustExcelOle
         raise ExcelErrorNValue, "name #{name} not in #{File.basename(self.stored_filename)}"  
       end
       begin
-        referstorange = item.RefersToRange
+        item.RefersToRange.Value = value
       rescue WIN32OLERuntimeError
-        raise ExcelErrorNValue, "range error in #{File.basename(self.stored_filename)}"      
+        raise ExcelErrorNValue, "RefersToRange error of name #{name} in #{File.basename(self.stored_filename)}"    
       end
+    end
+
+    def activate
+      @excel.visible = true
       begin
-        referstorange.Value = value
+        self.Activate
+        self.ActiveSheet.Activate
       rescue WIN32OLERuntimeError
-        raise ExcelErrorNValue, "value error in #{File.basename(self.stored_filename)}" 
+        raise ExcelError, "cannot activate"
       end
     end
 
@@ -474,7 +508,7 @@ module RobustExcelOle
             when '.xlsm': RobustExcelOle::XlOpenXMLWorkbookMacroEnabled
           end
         @workbook.SaveAs(RobustExcelOle::absolute_path(file), file_format)
-        book_store.store(self)
+        bookstore.store(self)
       rescue WIN32OLERuntimeError => msg
         if msg.message =~ /SaveAs/ and msg.message =~ /Workbook/ then
           if @opts[:if_exists] == :alert then 
@@ -491,9 +525,24 @@ module RobustExcelOle
 
   public
 
-    def [] sheet
-      sheet += 1 if sheet.is_a? Numeric
-      RobustExcelOle::Sheet.new(@workbook.Worksheets.Item(sheet))
+    # returns a sheet, if a name of a sheet 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
+      begin
+        RobustExcelOle::Sheet.new(@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}"
+        end
+      end
+    end
+
+    # set the value of a range given its name
+    def []= (name, value)
+      set_nvalue(name,value)
     end
 
     def each
@@ -507,35 +556,40 @@ module RobustExcelOle
         opts = sheet
         sheet = nil
       end
-
       new_sheet_name = opts.delete(:as)
-
       ws = @workbook.Worksheets
-      after_or_before, base_sheet = opts.to_a.first || 
-                                    [:after, Sheet.new(ws.Item(ws.Count))]
-      base_sheet = base_sheet.sheet
+      after_or_before, base_sheet = opts.to_a.first || [:after, Sheet.new(ws.Item(ws.Count))]
+      base_sheet = base_sheet.worksheet
       sheet ? sheet.Copy({ after_or_before.to_s => base_sheet }) : @workbook.WorkSheets.Add({ after_or_before.to_s => base_sheet })
       new_sheet = RobustExcelOle::Sheet.new(@excel.Activesheet)
       begin
         new_sheet.name = new_sheet_name if new_sheet_name
       rescue WIN32OLERuntimeError => msg
-        if msg.message =~ /OLE error code:800A03EC/ 
+        if msg.message =~ /800A03EC/ 
           raise ExcelErrorSheet, "sheet name already exists"
+        else
+          puts "#{msg.message}"
+          raise ExcelErrorSheetUnknown
         end
       end
       new_sheet
-    end        
+    end      
 
-    def add_name name
+    def self.bookstore
+      @@bookstore ||= Bookstore.new
     end
 
-    def self.book_store
-      @@bookstore ||= BookStore.new
+    def bookstore
+      self.class.bookstore
+    end   
+
+    def to_s
+      "<#BOOK:" + "#{"not alive " unless alive?}" + "#{File.basename(@stored_filename)}" + " #{@workbook} #{@excel}"  + ">"
     end
 
-    def book_store
-      self.class.book_store
-    end   
+    def inspect
+      self.to_s
+    end
 
   private
 
@@ -577,10 +631,7 @@ public
   class ExcelErrorSaveUnknown < ExcelErrorSave  # :nodoc: #
   end
 
-  class ExcelErrorRename < WIN32OLERuntimeError # :nodoc: #
-  end
-
-  class ExcelErrorNValue < WIN32OLERuntimeError # :nodoc: #
+  class ExcelErrorNValue < ExcelError  # :nodoc: #
   end
 
   class ExcelUserCanceled < RuntimeError # :nodoc: #
@@ -589,4 +640,6 @@ public
   class ExcelErrorSheet < ExcelError    # :nodoc: #
   end
 
+  class ExcelErrorSheetUnknown < ExcelErrorSheet    # :nodoc: #
+  end
 end