robust_excel_ole 0.3.7 → 0.3.8

data/lib/robust_excel_ole/bookstore.rb

@@ -1,6 +1,8 @@
 
 # -*- coding: utf-8 -*-
 
+include Utilities
+
 module RobustExcelOle
 
   class Bookstore
@@ -11,6 +13,10 @@ module RobustExcelOle
     end
 
     # returns a book with the given filename, if it was open once
+    # @param [String] filename  the file name
+    # @param [Hash]   options   the options
+    # @option option [Boolean] :prefer_writable
+    # @option option [Boolean] :prefer_excel
     # prefers open books to closed books, and among them, prefers more recently opened books
     # excludes hidden Excel instance
     # options: :prefer_writable   returns the writable book, if it is open (default: true)
@@ -29,7 +35,7 @@ module RobustExcelOle
           begin 
             @filename2books[filename_key].delete(wr_book)
           rescue
-            t "Warning: deleting dead reference failed: file: #{filename.inspect}"
+            trace "Warning: deleting dead reference failed: file: #{filename.inspect}"
           end
         else
           book = wr_book.__getobj__
@@ -51,6 +57,7 @@ module RobustExcelOle
     end
 
     # stores a workbook
+    # @param [Book] book a given book
     def store(book)
       filename_key = RobustExcelOle::canonize(book.filename)      
       if book.stored_filename
@@ -63,7 +70,7 @@ module RobustExcelOle
     end
 
     # creates and returns a separate Excel instance with Visible and DisplayAlerts equal false
-    def hidden_excel
+    def hidden_excel  # :nodoc: #
       unless (@hidden_excel_instance &&  @hidden_excel_instance.weakref_alive? && @hidden_excel_instance.__getobj__.alive?)       
         @hidden_excel_instance = WeakRef.new(Excel.create) 
       end
@@ -87,25 +94,25 @@ module RobustExcelOle
 
   private
 
-    def try_hidden_excel
+    def try_hidden_excel   # :nodoc: #
       @hidden_excel_instance.__getobj__ if (@hidden_excel_instance &&  @hidden_excel_instance.weakref_alive? && @hidden_excel_instance.__getobj__.alive?)
     end
 
     # prints the book store
-    def print
-      t "@filename2books:"
+    def print             # :nodoc: #
+      trace "@filename2books:"
       if @filename2books
         @filename2books.each do |filename,books|
-          t " filename: #{filename}"
-          t " books:"
+          trace " filename: #{filename}"
+          trace " books:"
           if books.empty? 
-            t " []" 
+            trace " []" 
           else
             books.each do |book|
               if book.weakref_alive?
-                t "#{book}"
+                trace "#{book}"
               else
-                t "weakref not alive"
+                trace "weakref not alive"
               end
             end
           end

data/lib/robust_excel_ole/cygwin.rb

@@ -11,7 +11,7 @@ module RobustExcelOle
     @conv_to_win32_path =
       Win32API.new('cygwin1.dll', 'cygwin_conv_to_win32_path', 'PP', 'I')
 
-    def cygpath(options, path)
+    def cygpath(options, path)   # :nodoc: #
       absolute = shortname = false
       func = nil
       options.delete(" \t-").chars {|opt|

data/lib/robust_excel_ole/excel.rb

@@ -2,30 +2,40 @@
 
 require 'timeout'
 
-module RobustExcelOle
+include Utilities
+
+module RobustExcelOle    
 
   class Excel
 
     @@hwnd2excel = {}
 
     # creates a new Excel instance
+    # @return [Excel] a new Excel instance
     def self.create
       new(:reuse => false)
     end
 
     # uses the current Excel instance (connects), if such a running Excel instance exists
     # creates a new one, otherwise 
+    # @return [Excel] an Excel instance
     def self.current
       new(:reuse => true)
     end
 
     # returns an Excel instance  
-    # given: a WIN32OLE object representing an Excel instance, or a Hash representing options:
+    # given a WIN32OLE object representing an Excel instance, or a Hash representing options:
+    # @param [Hash] options the options
+    # @option options [Boolean] :reuse  
+    # @option options [Boolean] :displayalerts 
+    # @option options [Boolean] :visible 
+    # options: 
     #  :reuse          connects to an already running Excel instance (true) or
     #                  creates a new Excel instance (false)   (default: true)
     #  :displayalerts  allows display alerts in Excel         (default: false)
     #  :visible        makes the Excel visible                (default: false)
     #  if :reuse => true, then DisplayAlerts and Visible are set only if they are given
+    # @return [Excel] an Excel instance
     def self.new(options = {})
       if options.is_a? WIN32OLE
         excel = options
@@ -66,8 +76,13 @@ module RobustExcelOle
     end
 
     # reopens a closed Excel instance
+    # @param [Hash] opts the options
+    # @option opts [Boolean] :reopen_workbooks
+    # @option opts [Boolean] :displayalerts
+    # @option opts [Boolean] :visible
     # options: reopen_workbooks (default: false): reopen the workbooks in the Excel instances
     #          :visible (default: false), :displayalerts (default: false)
+    # @return [Excel] an Excel instance
     def recreate(opts = {})      
       unless self.alive?
         opts = {
@@ -99,7 +114,7 @@ module RobustExcelOle
         begin
           result.Visible    # send any method, just to see if it responds
         rescue 
-          t "dead excel " + ("Window-handle = #{result.HWnd}" rescue "without window handle")
+          trace "dead excel " + ("Window-handle = #{result.HWnd}" rescue "without window handle")
           return nil
         end
       end
@@ -110,14 +125,21 @@ module RobustExcelOle
   public
 
     # closes all Excel instances
+    # @param [Hash] options the options
+    # @option options [Symbol]  :if_unsaved :raise, :save, :forget, :alert, or :keep_open
+    # @option options [Boolean] :hard
+    # @option options [Boolean] :kill_if_timeout
     # options:
     #  :if_unsaved    if unsaved workbooks are open in an Excel instance
     #                      :raise (default) -> raises an exception       
     #                      :save            -> saves the workbooks before closing
     #                      :forget          -> closes the excel instance without saving the workbooks 
+    #                      :keep_open       -> let the workbooks open
     #                      :alert           -> give control to Excel
     #  :hard          closes Excel instances soft (default: false), or, additionally kills the Excel processes hard (true)
     #  :kill_if_timeout:  kills Excel instances hard if the closing process exceeds a certain time limit (default: true)
+    # @raise ExcelError if time limit has exceeded, some Excel instance cannot be closed, or
+    #                   unsaved workbooks exist and option :if_unsaved is :raise
     def self.close_all(options={})
       options = {
         :if_unsaved => :raise,
@@ -153,12 +175,12 @@ module RobustExcelOle
 
   private
 
-    def self.manage_unsaved_workbooks(excel, options)
+    def self.manage_unsaved_workbooks(excel, options)     # :nodoc: #
       unsaved_workbooks = []
       begin
         excel.Workbooks.each {|w| unsaved_workbooks << w unless (w.Saved || w.ReadOnly)}
       rescue RuntimeError => msg
-        t "RuntimeError: #{msg.message}" 
+        trace "RuntimeError: #{msg.message}" 
         raise ExcelErrorOpen, "Excel instance not alive or damaged" if msg.message =~ /failed to get Dispatch Interface/
       end
       unless unsaved_workbooks.empty? 
@@ -199,7 +221,7 @@ module RobustExcelOle
       end
     end
 
-    def self.close_excel_ole_instance(ole_excel)
+    def self.close_excel_ole_instance(ole_excel)  # :nodoc: #
       @@hwnd2excel.delete(ole_excel.Hwnd)
       excel = ole_excel
       ole_excel = nil
@@ -214,21 +236,21 @@ module RobustExcelOle
         if weak_excel_ref.weakref_alive? then
           begin
             weak_excel_ref.ole_free
-            t "successfully ole_freed #{weak_excel_ref}"
+            trace "successfully ole_freed #{weak_excel_ref}"
           rescue
-            t "could not do ole_free on #{weak_excel_ref}"
+            trace "could not do ole_free on #{weak_excel_ref}"
           end
         end
         @@hwnd2excel.delete(excel_hwnd)
       rescue => e
-        t "Error when closing Excel: #{e.message}"
+        trace "Error when closing Excel: #{e.message}"
         #t e.backtrace
       end
       free_all_ole_objects
     end
 
     # frees all OLE objects in the object space
-    def self.free_all_ole_objects   
+    def self.free_all_ole_objects     # :nodoc: #
       anz_objekte = 0
       ObjectSpace.each_object(WIN32OLE) do |o|
         anz_objekte += 1
@@ -238,18 +260,21 @@ module RobustExcelOle
         #t o.ole_type rescue nil
         begin
           o.ole_free
-          #t "olefree OK"
+          #trace "olefree OK"
         rescue
-          #t "olefree_error: #{$!}"
-          #t $!.backtrace.first(9).join "\n"
+          #trace "olefree_error: #{$!}"
+          #trace $!.backtrace.first(9).join "\n"
         end
       end
-      t "went through #{anz_objekte} OLE objects"
+      trace "went through #{anz_objekte} OLE objects"
     end   
 
   public
 
     # closes the Excel
+    # @param [Hash] options the options
+    # @option options [Symbol] :if_unsaved :raise, :save, :forget, or :keep_open
+    # @option options [Boolean] :hard      
     #  :if_unsaved    if unsaved workbooks are open in an Excel instance
     #                      :raise (default) -> raises an exception       
     #                      :save            -> saves the workbooks before closing
@@ -285,10 +310,10 @@ module RobustExcelOle
       if weak_excel_ref.weakref_alive? then
         begin
           weak_excel_ref.ole_free
-          t "successfully ole_freed #{weak_excel_ref}"
+          trace "successfully ole_freed #{weak_excel_ref}"
         rescue => msg
-          t "#{msg.message}"
-          t "could not do ole_free on #{weak_excel_ref}"
+          trace "#{msg.message}"
+          trace "could not do ole_free on #{weak_excel_ref}"
         end
       end
       @@hwnd2excel.delete(excel_hwnd)      
@@ -305,6 +330,7 @@ module RobustExcelOle
   public
 
     # kill all Excel instances
+    # @return [Fixnum] number of killed Excel processes
     def self.kill_all
       procs = WIN32OLE.connect("winmgmts:\\\\.")
       processes = procs.InstancesOf("win32_process")
@@ -345,31 +371,31 @@ module RobustExcelOle
       result
     end
 
-    def excel
+    def excel   # :nodoc: #
       self
     end
 
-    def self.hwnd2excel(hwnd)
+    def self.hwnd2excel(hwnd)   # :nodoc: #
       excel_weakref = @@hwnd2excel[hwnd]
       if excel_weakref
         if excel_weakref.weakref_alive?
           excel_weakref.__getobj__
         else
-          t "dead reference to an Excel"
+          trace "dead reference to an Excel"
           begin 
             @@hwnd2excel.delete(hwnd)
           rescue
-            t "Warning: deleting dead reference failed! (hwnd: #{hwnd.inspect})"
+            trace "Warning: deleting dead reference failed! (hwnd: #{hwnd.inspect})"
           end
         end
       end
     end
 
-    def hwnd
+    def hwnd   # :nodoc: #
       self.Hwnd rescue nil
     end
 
-    def self.print_hwnd2excel
+    def self.print_hwnd2excel    # :nodoc: #
       @@hwnd2excel.each do |hwnd,wr_excel|
         excel_string = (wr_excel.weakref_alive? ? wr_excel.__getobj__.to_s : "weakref not alive") 
         printf("hwnd: %8i => excel: %s\n", hwnd, excel_string)
@@ -393,7 +419,7 @@ module RobustExcelOle
 
     
     # returns all unsaved workbooks in Excel instances
-    def self.unsaved_workbooks_all
+    def self.unsaved_workbooks_all    # :nodoc: #
       result = []
       @@hwnd2excel.each do |hwnd,wr_excel| 
         excel = wr_excel.__getobj__
@@ -408,7 +434,7 @@ module RobustExcelOle
       begin
         self.Workbooks.each {|w| result << w unless (w.Saved || w.ReadOnly)}
       rescue RuntimeError => msg
-        t "RuntimeError: #{msg.message}" 
+        trace "RuntimeError: #{msg.message}" 
         raise ExcelErrorOpen, "Excel instance not alive or damaged" if msg.message =~ /failed to get Dispatch Interface/
       end
       result      
@@ -417,11 +443,11 @@ module RobustExcelOle
     #self.class.map {|w| (not w.Saved)}
 
     def print_workbooks
-      self.Workbooks.each {|w| t "#{w.Name} #{w}"}
+      self.Workbooks.each {|w| puts "#{w.Name} #{w}"}
     end
 
 
-    # empty workbook is generated, saved and closed 
+    # generates, saves, and closes empty workbook
     def generate_workbook file_name                  
       self.Workbooks.Add                           
       empty_workbook = self.Workbooks.Item(self.Workbooks.Count)          
@@ -457,7 +483,7 @@ module RobustExcelOle
       @displayalerts = @ole_excel.DisplayAlerts = displayalerts_value
     end
 
-    # return if in the current Excel instance DisplayAlerts is enabled
+    # return whether DisplayAlerts is enabled in the current Excel instance
     def displayalerts 
       @displayalerts = @ole_excel.DisplayAlerts
     end
@@ -472,15 +498,15 @@ module RobustExcelOle
       @visible = @ole_excel.Visible
     end    
 
-    def to_s
+    def to_s              # :nodoc: #
       "#<Excel: " + "#{hwnd}" + ("#{"not alive" unless self.alive?}") + ">"
     end
 
-    def inspect
+    def inspect           # :nodoc: #
       self.to_s
     end
 
-    def self.book_class
+    def self.book_class   # :nodoc: #
       @book_class ||= begin
         module_name = self.parent_name
         "#{module_name}::Book".constantize
@@ -489,13 +515,27 @@ module RobustExcelOle
       end
     end
 
-    def book_class
+    def book_class        # :nodoc: #
       self.class.book_class
     end
 
+    def respond_to?(name, include_private = false)  # :nodoc: #    
+      raise ExcelError, "respond_to?: Excel not alive" unless alive?
+      super
+    end
+
+    def methods   # :nodoc: # 
+      (super + @ole_excel.ole_methods.map{|m| m.to_s}).uniq
+    end
+
+    def special_methods    # :nodoc: # 
+      (methods - Object.methods).sort
+    end
+
+
   private
 
-    def method_missing(name, *args) 
+    def method_missing(name, *args)    # :nodoc: #
       if name.to_s[0,1] =~ /[A-Z]/ 
         begin          
           raise ExcelError, "method missing: Excel not alive" unless alive?

data/lib/robust_excel_ole/sheet.rb

@@ -1,5 +1,9 @@
 # -*- coding: utf-8 -*-
+
+include Utilities
+
 module RobustExcelOle
+
   class Sheet
     attr_reader :worksheet
 
@@ -16,10 +20,13 @@ module RobustExcelOle
       end
     end
 
+    # returns name of the workbook
     def name
       @worksheet.Name
     end
 
+    # name the sheet
+    # @param [String] new_name the new name of the sheet 
     def name= (new_name)
       begin
         @worksheet.Name = new_name
@@ -27,7 +34,7 @@ module RobustExcelOle
         if msg.message =~ /800A03EC/ 
           raise ExcelErrorSheet, "sheet name #{new_name.inspect} already exists"
         else
-          t "#{msg.message}"
+          trace "#{msg.message}"
           raise ExcelErrorSheetUnknown
         end
       end
@@ -104,8 +111,12 @@ module RobustExcelOle
     end
 
     # returns the contents of a range with given name
+    # @param [String] name  the range name
+    # @param [Hash]   opts  the options
+    # @option opts [Variant] :default default value (default: nil)
     # if no contents could returned, then return default value, if a default value was provided
     #                                raise an error, otherwise
+    # @raise SheetError if value of the range cannot be evaluated
     def nvalue(name, opts = {:default => nil})
       begin
         value = self.Evaluate(name)
@@ -116,12 +127,16 @@ module RobustExcelOle
       end
       if value == -2146826259
         return opts[:default] if opts[:default]
-        raise SheetError, "cannot evaluate name #{name.inspect} in sheet"
+        raise SheeetError, "cannot evaluate name #{name.inspect} in sheet"
       end
       return opts[:default] if (value.nil? && opts[:default])
       value
     end
 
+    # assigns a value to a range with given name
+    # @param [String]  name   the range name
+    # @param [Variant] value  the assigned value
+    # @raise SheetError if name is not in the sheet or the value cannot be assigned
     def set_nvalue(name,value)
       begin
         item = self.Names.Item(name)
@@ -136,6 +151,9 @@ module RobustExcelOle
     end
 
     # assigns a name to a range (a cell) given by an address
+    # @param [String] name   the range name
+    # @param [Fixnum] row    the row
+    # @param [Fixnum] column the column
     def set_name(name,row,column)
       begin
         old_name = self[row,column].Name.Name rescue nil
@@ -146,28 +164,36 @@ module RobustExcelOle
           self.Names.Add("Name" => name, "RefersToR1C1" => "=" + address)
         end
       rescue WIN32OLERuntimeError => msg
-        t "WIN32OLERuntimeError: #{msg.message}"
+        trace "WIN32OLERuntimeError: #{msg.message}"
         raise SheetError, "cannot add name #{name.inspect} to cell with row #{row.inspect} and column #{column.inspect}"
       end
     end
 
+    def respond_to?(name, include_private = false)  # :nodoc: #    
+      super
+    end
+
+    def methods   # :nodoc: # 
+      super
+    end
+
     private
 
-    def method_missing(name, *args) 
-    if name.to_s[0,1] =~ /[A-Z]/ 
-      begin
-        @worksheet.send(name, *args)
-      rescue WIN32OLERuntimeError => msg
-        if msg.message =~ /unknown property or method/
-          raise VBAMethodMissingError, "unknown VBA property or method #{name.inspect}"
-        else 
-          raise msg
+    def method_missing(name, *args)    # :nodoc: #
+      if name.to_s[0,1] =~ /[A-Z]/ 
+        begin
+          @worksheet.send(name, *args)
+        rescue WIN32OLERuntimeError => msg
+          if msg.message =~ /unknown property or method/
+            raise VBAMethodMissingError, "unknown VBA property or method #{name.inspect}"
+          else 
+            raise msg
+          end
         end
+      else  
+        super 
       end
-    else  
-      super 
     end
-  end
 
 
     def last_row