robust_excel_ole 0.3.0 → 0.3.1

data/lib/robust_excel_ole/book.rb

@@ -14,9 +14,14 @@ module RobustExcelOle
       
       # opens a book.
       # 
+      # when reopening a book that was opened and closed before, transparency identity is ensured:
+      # same Book objects refer to the same Excel files, and vice versa
+      # 
       # options: 
-      # :default_excel   if the book was already open in an Excel instance, then open it there, otherwise:
-      #                   :reuse (default) -> connect to a running Excel instance if it exists, open in a new Excel otherwise
+      # :default_excel   if the book was already open in an Excel instance, then open it there.
+      #                  Otherwise, i.e. if the book was not open before or the Excel instance
+      #                   :reuse (default) -> connect to a (the first opened) running Excel instance 
+      #                                       if it exists, open in a new Excel otherwise
       #                   :new             -> open in a new Excel instance
       #                   <instance>       -> open in the given Excel instance
       # :force_excel     no matter whether the book was already open
@@ -28,53 +33,62 @@ module RobustExcelOle
       #                   :take_writable      -> use the Excel instance in which the book is writable,
       #                                          if such an Excel instance exists
       #                   :force_writability  -> make it writable in the desired Excel
+      #                   (does not work yet)
       # :if_locked_unsaved  if the book is open in another Excel instance and contains unsaved changes
       #                  :raise    -> raise an exception
       #                  :save     -> save the unsaved book 
       #                  (not implemented yet)
       # :if_unsaved     if an unsaved book with the same name is open, then
-      #                  :raise (default) -> raise an exception
-      #                  :forget          -> close the unsaved book, open the new book             
-      #                  :accept          -> let the unsaved book open                  
-      #                  :alert           -> give control to Excel
-      #                  :new_excel       -> open the new book in a new Excel
+      #                  :raise               -> raise an exception
+      #                  :forget              -> close the unsaved book, open the new book             
+      #                  :accept              -> let the unsaved book open                  
+      #                  :alert               -> give control to Excel
+      #                  :new_excel (default) -> open the new book in a new Excel
       # :if_obstructed  if a book with the same name in a different path is open, then
-      #                  :raise (default) -> raise an exception 
-      #                  :forget          -> close the old book, open the new book
-      #                  :save            -> save the old book, close it, open the new book
-      #                  :close_if_saved  -> close the old book and open the new book, if the old book is saved
-      #                                      raise an exception otherwise
-      #                  :new_excel       -> open the new book in a new Excel
-      #                  :reuse_excel     -> try the next free running Excel, if it exists, open a new Excel, else
-      # :read_only     open in read-only mode         (default: false)
+      #                  :raise               -> raise an exception 
+      #                  :forget              -> close the old book, open the new book
+      #                  :save                -> save the old book, close it, open the new book
+      #                  :close_if_saved      -> close the old book and open the new book, if the old book is saved
+      #                                          raise an exception otherwise
+      #                  :new_excel (default) -> open the new book in a new Excel                  
+      # :read_only     open in read-only mode         (default: false) 
       # :displayalerts enable DisplayAlerts in Excel  (default: false)
       # :visible       make visibe in Excel           (default: false)
-      # If :default_excel is set, then DisplayAlerts and Visible are set only if these parameters are given,
-      #                                   not set by default
-
-     
+      # if :default_excel is set, then DisplayAlerts and Visible are set only if these parameters are given
+    
       def open(file, opts={ }, &block)
         @options = {
           :excel => :reuse,
           :default_excel => :reuse,
           :if_locked     => :readonly,       
-          :if_unsaved    => :raise,
-          :if_obstructed => :raise,
+          :if_unsaved    => :new_excel,
+          :if_obstructed => :new_excel,
           :read_only => false
         }.merge(opts)
         #self.set_defaults(opts) ???
         book = nil
         if (not (@options[:force_excel] == :new && (not @options[:if_locked] == :take_writable)))
-          book = book_store.fetch(file, :readonly_excel => (@options[:read_only] ? @options[:force_excel] : nil)) rescue nil
+          # if readonly is true, then prefer a book that is given in force_excel if this option is set
+          book = book_store.fetch(file, :prefer_writable => (not @options[:read_only]), :prefer_excel => (@options[:read_only] ? @options[:force_excel] : nil)) rescue nil
           if book
-            if (not @options[:force_excel] || (@options[:force_excel] == book.excel))
+            if ((not @options[:force_excel]) || (@options[:force_excel] == book.excel))
+              if (not book.excel.alive?)
+                book.get_excel
+              end
               if book.excel.alive?
                 # condition: :if_unsaved is not set or :accept or workbook is not unsaved
                 if_unsaved_not_set_or_accept_or_workbook_saved = (@options[:if_unsaved] == :accept || @options[:if_unsaved] == :raise || (not book.workbook) || book.workbook.Saved)
-                if ((not book.alive?) || if_unsaved_not_set_or_accept_or_workbook_saved)  
+                if ((not book.alive?) || if_unsaved_not_set_or_accept_or_workbook_saved)
                   book.set_defaults(opts)
+                  # if the book is opened with a different readonly mode in the same Excel, 
+                  # then save it, close and open the book with the new readonly mode
+                  if (book.alive? && (not book.readonly == @options[:read_only]))
+                    book.Save unless (book.readonly || book.saved)
+                    book.workbook.Close if book.alive?
+                    book.workbook = nil unless book.alive?
+                  end
                   # reopen the book
-                  book.get_workbook          
+                  book.get_workbook   
                 end
                 return book if book.alive? && if_unsaved_not_set_or_accept_or_workbook_saved
               end
@@ -107,8 +121,8 @@ module RobustExcelOle
         :excel => :reuse,
         :default_excel => :reuse,
         :if_locked     => :readonly,       
-        :if_unsaved    => :raise,
-        :if_obstructed => :raise,
+        :if_unsaved    => :new_excel,
+        :if_obstructed => :new_excel,
         :read_only => false
       }.merge(opts)
     end
@@ -203,8 +217,6 @@ module RobustExcelOle
     end
 
     def open_workbook
-      #p "open_workbook:"
-      #p "@file:#{@file}"
       if ((not @workbook) || (@options[:if_unsaved] == :alert) || @options[:if_obstructed]) then
         begin
           filename = RobustExcelOle::absolute_path(@file)
@@ -225,10 +237,10 @@ module RobustExcelOle
     #
     # options:
     #  :if_unsaved    if book is unsaved
-    #                      :raise   -> raise an exception       (default)             
-    #                      :save    -> save the book before it is closed                  
-    #                      :forget  -> close the book 
-    #                      :alert   -> give control to excel
+    #                      :raise          -> raise an exception       
+    #                      :save (default) -> save the book before it is closed                  
+    #                      :forget         -> close the book 
+    #                      :alert          -> give control to excel
     def close(opts = {:if_unsaved => :raise})
       if ((alive?) && (not @workbook.Saved) && (not @workbook.ReadOnly)) then
         case opts[:if_unsaved]
@@ -261,37 +273,42 @@ module RobustExcelOle
 
   public
 
-    # modify a book such that its state remains unchanged.
+    # modify a book such that its state (open/close, saved/unsaved, readonly/writable) remains unchanged.
     #  options: 
-    #  :visible:  Make the book visible in the Excel (default: false)
+    #  :visible:   Make the book visible in the Excel (default: false)
     #  :keep_open: let the book open after modification (default: false)
-    #  if the book is read_only and modified (unsaved), then
-    #    only the saved version of the book is unobtrusively modified, 
-    #    not the current changed version
-    # returns the block result
+    #  :read_only: Open the book unobtrusively for reading only  (default: false)
+    #  :use_this:  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
+    #                                in a new excel instance, otherwise
     def self.unobtrusively(file, opts = { })
       options = {
         :keep_open => false,
-        :visible => false
+        :visible => false,
+        :read_only => false,
+        :use_this => false
       }.merge(opts)
-      book = book_store.fetch(file)
+      book = book_store.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_readonly = was_not_alive_or_nil ? false : book.ReadOnly
+      was_saved = was_not_alive_or_nil ? true : book.saved
+      was_readonly = book.readonly unless was_not_alive_or_nil
       old_book = book if was_readonly
-      old_visible = book ? book.visible : false
-      begin
-        book = was_not_alive_or_nil ? open(file, :if_obstructed => :new_excel) : 
-               (was_readonly ? open(file, :force_excel => :new) : book)
-        book.visible = options[:visible]       
+      old_visible = (book && book.excel.alive?) ? book.excel.visible : false
+      begin 
+        book = was_not_alive_or_nil ? open(file) :
+               (((not was_readonly) || options[:read_only]) ? book : 
+                (options[:use_this] ? open(file, :force_excel => book.excel) : open(file, :force_excel => :new)))
+        book.excel.visible = options[:visible]       
         yield book
       ensure
-        book.save if (was_not_alive_or_nil || was_saved || was_readonly) && (not book.Saved)
-        if was_readonly
+        book.save if (was_not_alive_or_nil || was_saved || (was_readonly && (not options[:read_only]))) && (not book.saved)
+        # book was open, readonly and shoud be modified
+        if (not was_not_alive_or_nil) && (not options[:read_only]) && was_readonly && options[:use_this]
           book.close
-          book = old_book
+          open(file, :if_obstructed => :new_excel, :read_only => true)
         end
-        book.visible = old_visible
+        book.excel.visible = old_visible
         book.close if (was_not_alive_or_nil && (not opts[:keep_open]))
       end
     end
@@ -332,35 +349,20 @@ module RobustExcelOle
       @workbook.Fullname.tr('\\','/') rescue nil
     end
 
+    def readonly
+      @workbook.ReadOnly
+    end
+
+    def saved
+      @workbook.Saved
+    end
+
     # returns true, if the full book names and excel appications are identical, false, otherwise  
     def == other_book
       other_book.is_a?(Book) &&
       @excel == other_book.excel &&
       self.filename == other_book.filename  
     end
-
-    # returns if the Excel instance is visible
-    def visible 
-      @excel.visible
-    end
-
-   # make the Excel instance visible or invisible
-    # option: visible_value     true -> make Excel visible, false -> make Excel invisible
-    def visible= visible_value
-      @excel.visible = visible_value
-    end
-
-   # returns if DisplayAlerts is enabed in the Excel instance
-    def displayalerts 
-      @excel.displayalerts
-    end
-
-    # enable in the Excel instance Dispayalerts
-    #  option: displayalerts_value     true -> enable DisplayAlerts, false -> disable DispayAlerts
-    def displayalerts= displayalerts_value
-      @excel.displayalerts = displayalerts_value
-    end
-
  
     # saves a book.
     # returns true, if successfully saved, nil otherwise

data/lib/robust_excel_ole/book_store.rb

@@ -10,33 +10,34 @@ module RobustExcelOle
     end
 
     # returns a book with the given filename, if it was open once
-    # preference order: writable book, readonly unsaved book, readonly book (the last one), closed book
-    # options:  
-    #  :readonly_excel => <instance> -> return the book that was open in the given excel instance, 
-    #                                 even if it is not writable, if such a book exists
-    #                          prefer the writable book as described above, otherwise 
-    def fetch(filename, options = { })
+    # prefers open books to closed books, and among them, prefers more recently opened books
+    # options: :prefer_writable   return the writable book, if it is open (default: true)
+    #                             return the book according to the preference order mentioned above, otherwise
+    #          :prefer_excel      return the book in the given excel instance, if it exists
+    #                             proceed according to prefer_writable otherwise
+    def fetch(filename, options = {:prefer_writable => true })
       filename_key = RobustExcelOle::canonize(filename)
-      readonly_book = readonly_unsaved_book = closed_book = result = nil
-      books = @filename2books[filename_key]
-      return nil unless books
-      books.each do |book|
-        return book if options[:readonly_excel] && book.excel == options[:readonly_excel]
-        if book.alive?
-          if (not book.ReadOnly)
-            if options[:readonly_excel]
-              result = book
-            else
-              return book
-            end
+      weakref_books = @filename2books[filename_key]
+      return nil unless weakref_books
+      result = open_book = closed_book = nil      
+      weakref_books.each do |wr_book|
+        if (not wr_book.weakref_alive?)
+          @filename2books[filename_key].delete(wr_book)
+        else
+          if options[:prefer_excel] && wr_book.excel == options[:prefer_excel]
+            result = wr_book
+            break 
+          end
+          if wr_book.alive?
+            open_book = wr_book
+            break if ((not wr_book.readonly) && options[:prefer_writable])
           else
-            book.Saved ? readonly_book = book : readonly_unsaved_book = book
+            closed_book = wr_book
           end
-        else
-          closed_book = book
         end
       end
-      result ? result : (readonly_unsaved_book ? readonly_unsaved_book : (readonly_book ? readonly_book : closed_book))
+      result = result ? result : (open_book ? open_book : closed_book)
+      result.__getobj__ if result
     end
 
     # stores a book
@@ -44,12 +45,29 @@ module RobustExcelOle
       filename_key = RobustExcelOle::canonize(book.filename)      
       if book.stored_filename
         old_filename_key = RobustExcelOle::canonize(book.stored_filename)
+        # deletes the weak reference to the book
         @filename2books[old_filename_key].delete(book)
       end
-      @filename2books[filename_key] |= [book] 
+      @filename2books[filename_key] |= [WeakRef.new(book)]
       book.stored_filename = book.filename
     end
 
+    # returns all excel instances and the workbooks that are open in them
+    # first: only the stored excel instances are considered
+    def excel_list
+      excel2books = Hash.new {|hash, key| hash[key] = [] }
+      if @filename2books
+        @filename2books.each do |filename,books|
+          if books
+            books.each do |book|
+              excel2books[book.excel] |= [book.workbook]
+            end
+          end
+        end
+      end
+      excel2books
+    end
+
     # prints the book store
     def print
       p "@filename2books:"
@@ -58,10 +76,16 @@ module RobustExcelOle
           p " filename: #{filename}"
           p " books:"
           p " []" if books == []
-          books.each do |book|
-            p "#{book}"
-            p "excel: #{book.excel}"
-            p "alive: #{book.alive?}"
+          if books
+            books.each do |book|
+              if book.weakref_alive?
+                p "#{book}"
+                p "excel: #{book.excel}"
+                p "alive: #{book.alive?}"
+              else
+                p "weakref not alive"
+              end
+            end
           end
         end
       end

data/lib/robust_excel_ole/excel.rb

@@ -139,7 +139,6 @@ module RobustExcelOle
         excel.Workbooks.Close
         excel_hwnd = excel.HWnd
         excel.Quit
-        #excel.ole_free
         weak_excel_ref = WeakRef.new(excel)
         excel = nil
         GC.start

data/lib/robust_excel_ole/version.rb

@@ -1,3 +1,3 @@
 module RobustExcelOle
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

data/robust_excel_ole.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |s|
   s.authors     = ["traths"]
   s.email       = ["Thomas.Raths@gmx.net"]
   s.homepage    = "https://github.com/Thomas008/robust_excel_ole"
-  s.summary     = "RobustExcelOle wraps the win32ole library and implements various operations in Excel"
-  s.description = "RobustExcelOle wraps the win32ole library, and allows to perform various operation in Excel with ruby in a reliable way. Detailed description please see the README."
+  s.summary     = "RobustExcelOle processes Excel files and wraps the win32ole library."
+  s.description = "RobustExcelOle processes Excel files, provides all win32ole operations, convenient methods for opening, saving and closing, and implements an Excel file management system."
 
   s.rubyforge_project = "robust_excel_ole"
 
@@ -23,11 +23,6 @@ Gem::Specification.new do |s|
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
-  s.add_development_dependency "rake", '>= 0.9.2'
   s.add_development_dependency "rspec", '>= 2.6.0'
-  s.add_development_dependency "rb-fchange", '>= 0.0.5'
-  s.add_development_dependency "wdm", '>= 0.0.3'
-  s.add_development_dependency "win32console", '>= 1.3.2'
-  s.add_development_dependency "guard-rspec", '>= 2.1.1'
   s.required_ruby_version = '>= 1.8.6'
 end