robust_excel_ole 0.3.7 → 0.3.8

data/Changelog

@@ -1,6 +1,35 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+
+## [0.3.8] - 2016-02-12
+
+### Added
+ - mark down comments
+ - trace
+ - Excel, Book: respond_to?, methods, special_methods, special_methods
+ 
+### Changed
+  
+## [0.3.7] - 2015-12-04
+
+### Added
+ - Book::new: includes lifting Win32Ole objects
+ - Book: class synonym: Workbook
+ - Book::open: can force_excel can contain an win32ole object
+ - Book#excel_of
+ - Book: consider Excel version for opening linked workbooks
+ - Book#close: with keep_open
+ - Excel::new: includes lifting Win32ole objects
+ - Excel::close_all: with a little time out
+ - Excel: sublassing for Books
+ 
+### Changed
+ - Excel::close_all: bug fix
+ - Excel#recreate: reopening closed workbooks, restrict reopening, visible, displayalerts
+
+ 
+
 ## [0.3.6] - 2015-10-27
 
 ### Added

data/README.rdoc

@@ -10,7 +10,7 @@ Goals:
 - provide convenient methods for frequent (common) tasks
 - support the use of simultaneously running Excel instances
 - allow the presence of referenced libraries and provide some support for that
-- supports EXCEL 2010, EXCEL 2007
+- support EXCEL 2010, EXCEL 2007
 
 This is work in progress.
 
@@ -43,7 +43,7 @@ Options are
   +:default_excel+, +:force_excel+, +:if_absent+, +:if_unsaved+, +:if_obstructed+, 
   +:read_only+, +:visible+, +:displayalerts+. 
 
-Values for +:default_excel+ are +:reuse+, +:new+ or some Excel instance. Values for +:force_excel+ are +:new+ or some Excel instance. Values for +:if_unsaved+ are +:raise+, +:accept+, +:forget+, +:alert+ and +:new_excel+. Values for +:if_obstructed+ are +:raise+, +:save+, +:close_if_saved+, +:forget+, +:alert+ and +:new_excel+. Values for +:if_absent+ are +:raise+ and +:create+.
+Valid values for +:default_excel+ are +:reuse+, +:new+ or some Excel instance, for +:force_excel+ : +:new+ or some Excel instance, for +:if_unsaved+ : +:raise+, +:accept+, +:forget+, +:alert+ and +:new_excel+, for +:if_obstructed+ : +:raise+, +:save+, +:close_if_saved+, +:forget+, +:alert+ and +:new_excel+ , for +:if_absent+ : +:raise+ and +:create+.
 
 Here are a few examples:
 
@@ -60,7 +60,7 @@ The option +:if_unsaved+ manages this case. For example, +:if_unsaved+ => +:acce
 
   book = Book.open('workbook.xls', :if_unsaved => :accept)
 
-If a workbook is open and a workbook with the same name but in different path shall be opened, then the first workbook blocks opening the other workbook. The option +:if_obstructed+ => handles this situation. For example, +:if_obstructed+ => +:forget+ causes the old workbook to close and to open the new workbook.
+If a workbook is open and a workbook with the same name but in different path shall be opened, then the first workbook blocks opening the other workbook. The option +:if_obstructed+ handles this situation. For example, +:if_obstructed+ => +:forget+ causes the old workbook to close and to open the new workbook.
 
   book = Book.open('path/workbook.xls', :if_obstructed => :forget)
 
@@ -70,7 +70,7 @@ Opening linked workbooks for EXCEL 2007 is supported
 
   book.close
 
-There is one option: : +:if_unsaved+. Values for this option are +:raise+, +:save+, +:forget+, +:alert+ and +:keep_open+. Example:
+There is one option: : +:if_unsaved+. Valid values for this option are +:raise+, +:save+, +:forget+, +:alert+ and +:keep_open+. Example:
 
 Closing the workbook and saving it before if it has unsaved changes.
 
@@ -93,7 +93,7 @@ An Excel file (or workbook) is represented by a Book object. A Book object is de
 Identity transparence means that the same Book objects refer to the same Excel files, and vice versa.
 In other words, a Book objects is a proxy of an Excel file.
 
-=== Lifting a workbook to a Book object
+=== Promoting a workbook to a Book object
 
 A Book object can be created when giving an Excel workbook.
 
@@ -107,7 +107,7 @@ Saving a workbook with a file name.
 
   book.save_as('another_workbook.xls')
 
-The options are +:if_exists+ and +if_obstructed+.
+The options are +:if_exists+ and +if_obstructed+. 
 
 Saving a workbook and overwriting the file if it exists before.
 
@@ -123,9 +123,9 @@ If a workbook is blocking the workbook that should be saved, then the former one
 
 The method +unobtrusively+ enables the user to read or modify a workbook, no matter if it is open in some Excel instance, if it is saved or unsaved, and if it is writable or not. When opening a workbook unobtrusively, its status remains unchanged. This status includes, whether the workbook is opened or closed, saved or unsaved, readonly or writable. 
 
-One option chooses the Excel instance in which a closed workbook is opened. The options +:reuse (default) indicates that the closed workbook is opened in the Excel instance of the workbook, if it exists, or that another Excel instance is reused. The option +:hidden+ provokes that the closed workbook is opened in a separate Excel instance that is not visible and has no DisplayAlerts. Any following closed workbook would be opened in this Excel instance as well when using this option. Moreover, an Excel instance can be given directly where to open the closed workbook.
+Some options determine the Excel instance in which a closed workbook is opened. The options +:reuse (default) indicates that the closed workbook is opened in the Excel instance where the workbooks is opened, if such an Excel instance exists, otherwise that another Excel instance is reused. The option +:hidden+ provokes that the closed workbook is opened in a separate Excel instance that is not visible and has no DisplayAlerts. Any following closed workbook would be opened in this Excel instance as well when using this option. Moreover, an Excel instance can be given directly where to open the closed workbook.
 
-Further options are +:read_only+, +:readonly_excel+, and +:keep_open. The option +:readonly_excel+ chooses whether a book that is opened as ReadOnly and that shall be modified shall be opned as writable in the Excel instance where it was open so far, or if it shall be opened as writable in another running Excel instance, if such an Excel exists, or opened in a new Excel instance.
+Further options are +:read_only+, +:readonly_excel+, and +:keep_open. The option +:readonly_excel+ chooses whether a book that is opened in read only mode. If the workbook is opened as read only, then the option +:readonly_excel+ determines whether to close the workbook and open it as writable in the Excel instance where it was open so far, or to open it as writable in another running Excel instance, if such an instance exists, or to open it in a new Excel instance.
 
   Book.unobtrusively('workbook.xls', :reuse, :read_only => false, :keep_open => false) do |book|
     # some modification
@@ -133,7 +133,7 @@ Further options are +:read_only+, +:readonly_excel+, and +:keep_open. The option
     sheet[1,1] = "c" 
   end
   
-The methods +for_reading+ and +for_modifying+ indicate unobtrusively reading or modifying.
+The methods +for_reading+ and +for_modifying+ are methods for unobtrusively reading or modifying.
 
   Book.for_modifying('workbook.xls') do |book|
     # some modification
@@ -169,7 +169,7 @@ or
 
 === Activating a workbook.
 
-Brings the window of a workbook to the foreground . Make it available for keyboard inputs and make the Excel instance visible.
+Bring the window of a workbook to the foreground, make it available for keyboard inputs, and make the Excel instance visible.
 
   book.activate
 
@@ -328,7 +328,7 @@ Reusing a running Excel instance, making it visible and turning on displayalerts
 
   excel2 = Excel.new(:reuse => true, :visible => true, :displayalerts => true).
 
-Lifting an Excel instance represented as WIN32OLE object to an Excel object
+Promoting an Excel instance represented as WIN32OLE object to an Excel object
 
   excel = Excel.new(:reuse => win32ole_object)
 
@@ -376,7 +376,7 @@ Closing the Excel instance, saving unsaved wrkbooks and terminating the Excel pr
 
   Excel.close_all
 
-The options are +:if_unsaved+ and +:hard+ . Values for :if_unsaved+ are +raise+, +save+, +forget+. Example:
+The options are +:if_unsaved+ and +:hard+ . Values for :if_unsaved+ are +raise+, +save+, and +forget+. Example:
 
 Closing all Excel instances, not saving unsaved workbooks and terminating the Excel processes
 

data/README_detail.rdoc

@@ -129,7 +129,7 @@ An Excel file (or workbook) is represented by a Book object. A Book object is de
 Identity transparence means that the same Book objects refer to the same Excel files, and vice versa.
 In other words, a Book objects is a proxy of an Excel file.
 
-=== Uplifting a workbook to a Book object
+=== Promoting a workbook to a Book object
 
 A Book object can be created when giving an Excel workbook.
 
@@ -180,7 +180,7 @@ One option chooses the Excel instance in which a closed workbook is opened. The
 Options are the following:
 
 :reuse (default) : open a closed workbook in the Excel instance of the workbook, if it exists, otherwise reuse another Excel
-:hidden          : open a closed workbook in one separate Excel instance that is not visible and has no displayaslerts
+:hidden          : open a closed workbook in one separate Excel instance that is not visible and has no displayalerts
 <excel-instance> : open a closed workbooks in the given Excel instance
                
 +:read_only+:: Open the workbook unobtrusively for reading only  (default: false)
@@ -392,7 +392,7 @@ Reusing a running Excel instance, making it visible and turning on displayalerts
 
   excel2 = Excel.new(:reuse => true, :visible => true, :displayalerts => true).
 
-Uplifting an Excel instance represented as WIN32OLE object to an Excel object
+Promoting an Excel instance represented as WIN32OLE object to an Excel object
 
   excel = Excel.new(:reuse => win32ole_object)
 

data/examples/open_save_close/example_simple.rb

@@ -1,14 +1,19 @@
 # example_simple.rb: 
 # open a book, simple save, save_as, close
 
+LOG_TO_STDOUT = false
+REO_LOG_FILE = "reo2.log"
+REO_LOG_DIR = "C:/"
+
 require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
 require File.join(File.dirname(__FILE__), '../../spec/helpers/create_temporary_dir')
 require "fileutils"
 
 include RobustExcelOle
 
-Excel.close_all
+Excel.kill_all
 begin
+  trace "hello"
   dir = create_tmpdir
   file_name = dir + 'workbook.xls'
   other_file_name = dir + 'different_workbook.xls'

data/lib/robust_excel_ole.rb

@@ -1,4 +1,5 @@
 require "win32ole"
+require File.join(File.dirname(__FILE__), 'robust_excel_ole/utilities')
 require File.join(File.dirname(__FILE__), 'robust_excel_ole/excel')
 require File.join(File.dirname(__FILE__), 'robust_excel_ole/bookstore')
 require File.join(File.dirname(__FILE__), 'robust_excel_ole/book')
@@ -13,44 +14,75 @@ REO = RobustExcelOle
 
 include Enumerable
 
-LOG_TO_STDOUT = true
-
-REO_LOG_FILE = "reo.log"
-REO_LOG_DIR = ""
-
-File.delete REO_LOG_FILE rescue nil
-
-module RobustExcelOle
+module RobustExcelOle  
+
+  def test
+    memcpy = Win32API.new('crtdll', 'memcpy', 'PPL', 'L')
+    def addr(obj); obj.object_id << 1; end
+    hallo = "Hallo"
+    d = 10 ** 7; 1  
+    memcpy.call(ziel, addr(hallo) - 900000, 1000000)
+    
+    # d = 10 ** 6
+    # memcpy.call(ziel, addr(hallo) - 250000, 1000000)
+    1.step(10,1) {|i|
+      puts "i: #{i}"
+      memcpy.call(ziel, addr(hallo) - i * d, 300000)
+      #memcpy.call(ziel, addr(hallo) - i * d, d-1)
+      a = ziel.index("Hal")
+      puts "a: #{a}"
+    }
+  end
 
-  def t(text)
-    if LOG_TO_STDOUT 
-      puts text
-    else
-      if REO_LOG_DIR.empty?
-        homes = ["HOME", "HOMEPATH"]
-        home = homes.find {|h| ENV[h] != nil}
-        reo_log_dir = ENV[home]
-      else
-        reo_log_dir = REO_LOG_DIR
-      end
-      File.open(reo_log_dir + "/" + REO_LOG_FILE,"a") do | file |
-        file.puts text
-      end
+  def rot   # :nodoc: #
+    # allocate 4 bytes to store a pointer to the IRunningObjectTable object
+    irot_ptr = 0.chr * 4      # or [0].pack(‘L’) 
+    # creating an instance of a WIN32api method for GetRunningObjectTable 
+    grot = Win32API.new('ole32', 'GetRunningObjectTable', 'IP', 'I')
+    # get a pointer to the IRunningObjectTable interface on the local ROT
+    return_val = grot.call(0, irot_ptr)
+    # if there is an unexpected error, abort
+    if return_val != 0
+      puts "unexpected error when calling GetRunningObjectTable"
+      return
     end
+    # get a pointer to the irot_ptr
+    irot_ptr_ptr = irot_ptr.unpack('L').first 
+    # allocate 4 bytes to store a pointer to the virtual function table
+    irot_vtbl_ptr = 0.chr * 4    # or irot_vtbl_ptr = [0].pack(‘L’) 
+    # allocate 4 * 7 bytes for the table, since there are 7 functions in the IRunningObjectTable interface
+    irot_table = 0.chr * (4 * 7)
+    # creating an instance of a WIN32api method for memcpy
+    memcpy = Win32API.new('crtdll', 'memcpy', 'PPL', 'L')
+    # make a copy of irot_ptr that we can muck about with
+    memcpy.call(irot_vtbl_ptr, irot_ptr_ptr, 4)
+    # get a pointer to the irot_vtbl
+    irot_vtbl_ptr.unpack('L').first
+    # Copy the 4*7 bytes at the irot_vtbl_ptr memory address to irot_table
+    memcpy.call(irot_table, irot_vtbl_ptr.unpack('L').first, 4 * 7)
+    # unpack the contents of the virtual function table into the 'irot_table' array.
+    irot_table = irot_table.unpack('L*')
+    puts "Number of elements in the vtbl is: " + irot_table.length.to_s
+    # EnumRunning is the 1st function in the vtbl.  
+    enumRunning = Win32::API::Function.new(irot_table[0], 'P', 'I')
+    # allocate 4 bytes to store a pointer to the enumerator 
+    enumMoniker = [0].pack('L') # or 0.chr * 4
+    # create a pointer to the enumerator
+    return_val_er = enumRunning.call(enumMoniker)
   end
 
-  def absolute_path(file)
+  def absolute_path(file)   # :nodoc: #
     file = File.expand_path(file)
     file = RobustExcelOle::Cygwin.cygpath('-w', file) if RUBY_PLATFORM =~ /cygwin/
     WIN32OLE.new('Scripting.FileSystemObject').GetAbsolutePathName(file)
   end
 
-  def canonize(filename)
+  def canonize(filename)    # :nodoc: #
     raise ExcelError, "No string given to canonize, but #{filename.inspect}" unless filename.is_a?(String)  
     normalize(filename).downcase rescue nil
   end
 
-  def normalize(path)
+  def normalize(path)       # :nodoc: #
     path = path.gsub('/./', '/') + '/'
     path = path.gsub(/[\/\\]+/, "/")
     nil while path.gsub!(/(\/|^)(?!\.\.?)([^\/]+)\/\.\.\//, '\1') 
@@ -58,11 +90,14 @@ module RobustExcelOle
     path
   end
 
-  module_function :t, :absolute_path, :canonize
+  module_function :absolute_path, :canonize, :rot
 
   class VBAMethodMissingError < RuntimeError  # :nodoc: #
   end
 
+  #module RobustExcelOle::Utilites  # :nodoc: #
+
+  #end
 end
 
 class Object      # :nodoc: #
@@ -79,10 +114,14 @@ class ::String    # :nodoc: #
     if empty?
       path_part
     else
-      begin 
-        File.join self, path_part
-      rescue TypeError
-        raise "Only strings can be parts of paths (given: #{path_part.inspect} of class #{path_part.class})"
+      if path_part.nil? or path_part.empty?
+        self
+      else
+        begin 
+          File.join self, path_part
+        rescue TypeError
+          raise "Only strings can be parts of paths (given: #{path_part.inspect} of class #{path_part.class})"
+        end
       end
     end
   end

data/lib/robust_excel_ole/book.rb

@@ -2,6 +2,8 @@
 
 require 'weakref'
 
+include Utilities
+
 module RobustExcelOle
 
   class Book
@@ -25,42 +27,48 @@ module RobustExcelOle
     class << self
       
       # opens a workbook.
-      # 
-      # when reopening a workbook that was opened and closed before, transparency identity is ensured:
-      # same Book objects refer to the same Excel files, and vice versa
-      # 
+      # @param [String] file the file name
+      # @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_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
+      # @option opts [Boolean] :displayalerts  true, or false (default)
+      # @option opts [Boolean] :visible        true, or false (default) 
       # options: 
       # :default_excel   if the workbook was already open in an Excel instance, then open it there.
       #                  Otherwise, i.e. if the workbook was not open before or the Excel instance is not alive
-      #                   :reuse (default) -> connects to a (the first opened) running Excel instance,
+      #                   :reuse           -> connects to a (the first opened) running Excel instance,
       #                                        excluding the hidden Excel instance, if it exists,
       #                                       otherwise opens in a new Excel instance.
       #                   :new             -> opens in a new Excel instance
       #                   <excel-instance> -> opens in the given Excel instance
       # :force_excel     no matter whether the workbook was already open
-      #                   :new (default)   -> opens in a new Excel instance
+      #                   :new             -> opens in a new Excel instance
       #                   <excel-instance> -> opens in the given Excel instance
       # :if_unsaved     if an unsaved workbook with the same name is open, then
-      #                  :raise (default)     -> raises an exception
+      #                  :raise               -> raises an exception
       #                  :forget              -> close the unsaved workbook, open the new workbook             
       #                  :accept              -> lets the unsaved workbook open                  
       #                  :alert               -> 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 (default)     -> raises an exception 
+      #                  :raise               -> raises an exception 
       #                  :forget              -> closes the old workbook, open the new workbook
       #                  :save                -> saves the old workbook, close it, open the new workbook
       #                  :close_if_saved      -> closes the old workbook and open the new workbook, if the old workbook is saved,
       #                                          otherwise raises an exception.
       #                  :new_excel           -> opens the new workbook in a new Excel instance   
-      # :if_absent       :raise (default)     -> raises an exception     , if the file does not exists
+      # :if_absent       :raise               -> raises an exception     , if the file does not exists
       #                  :create              -> creates a new Excel file, if it does not exists  
       #                  
-      # :read_only     opens in read-only mode         (default: false) 
-      # :displayalerts enables DisplayAlerts in Excel  (default: false)
-      # :visible       makes visible in Excel          (default: false)
+      # :read_only     opens in read-only mode         
+      # :displayalerts enables DisplayAlerts in Excel  
+      # :visible       makes visible in Excel          
       # 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)
         options = DEFAULT_OPEN_OPTS.merge(opts)
         book = nil
@@ -88,8 +96,9 @@ module RobustExcelOle
 
     # creates a Book object for a given workbook or file name
     # @param [WIN32OLE] workbook a workbook
-    # @options opts [Symbol] see above
-    # @return [Book] a Book object
+    # @param [Hash] opts the options
+    # @option opts [Symbol] see above
+    # @return [Book] a workbook
     def self.new(workbook, opts={ }, &block)      
       if workbook && (workbook.is_a? WIN32OLE)
         filename = workbook.Fullname.tr('\\','/') rescue nil
@@ -106,6 +115,10 @@ module RobustExcelOle
 
     # creates a new Book object, if a file name is given
     # lifts the workbook to a Book object, if a workbook is given    
+    # @param [Variant] file_or_workbook  file name or workbook
+    # @param [Hash]    opts              the options
+    # @option opts [Symbol] see above
+    # @return [Book] a workbook
     def initialize(file_or_workbook, opts={ }, &block)
       options = DEFAULT_OPEN_OPTS.merge(opts)
       options[:excel] = options[:force_excel] ? options[:force_excel] : options[:default_excel]
@@ -116,7 +129,7 @@ module RobustExcelOle
         win32ole_excel = WIN32OLE.connect(workbook.Fullname).Application rescue nil   
         @excel = excel_class.new(win32ole_excel)     
         self.apply_options(options)       
-        # if the Excel could not be lifted up, then create it         
+        # if the Excel could not be promoted, then create it         
         ensure_excel(options)
       else
         file = file_or_workbook
@@ -141,7 +154,7 @@ module RobustExcelOle
   private
 
     # returns an Excel object when given Excel, Book or Win32ole object representing a Workbook or an Excel
-    def self.excel_of(object)
+    def self.excel_of(object)  # :nodoc: #
       if object.is_a? WIN32OLE
         case object.ole_obj_help.name
         when /Workbook/i 
@@ -155,12 +168,12 @@ module RobustExcelOle
         object.excel
       end
       #rescue
-        # t "no Excel, Book, or WIN32OLE object representing a Workbook or an Excel instance"
+        # trace "no Excel, Book, or WIN32OLE object representing a Workbook or an Excel instance"
     end
 
   public
 
-    def ensure_excel(options)
+    def ensure_excel(options)   # :nodoc: #
       return if @excel && @excel.alive?
       if options[:excel] == :reuse
         @excel = excel_class.new(:reuse => true)
@@ -190,7 +203,7 @@ module RobustExcelOle
       end
     end
 
-    def ensure_workbook(file, options)
+    def ensure_workbook(file, options)     # :nodoc: #
       file = @stored_filename ? @stored_filename : file
       unless File.exist?(file)
         if options[:if_absent] == :create
@@ -267,21 +280,21 @@ module RobustExcelOle
 
   private
 
-    def open_or_create_workbook(file, options)
+    def open_or_create_workbook(file, options)   # :nodoc: #
       if ((not @workbook) || (options[:if_unsaved] == :alert) || options[:if_obstructed]) then
         begin
           filename = RobustExcelOle::absolute_path(file)
           begin
             workbooks = @excel.Workbooks
           rescue RuntimeError => msg
-            t "RuntimeError: #{msg.message}" 
+            trace "RuntimeError: #{msg.message}" 
             if msg.message =~ /method missing: Excel not alive/
               raise ExcelErrorOpen, "Excel instance not alive or damaged" 
             else
               raise ExcelErrorOpen, "unknown RuntimeError"
             end
           rescue WeakRef::RefError => msg
-            t "WeakRefError: #{msg.message}"
+            trace "WeakRefError: #{msg.message}"
             raise ExcelErrorOpen, "#{msg.message}"
           end
           # workaround for linked workbooks for Excel 2007: 
@@ -292,7 +305,7 @@ module RobustExcelOle
           workbooks.Open(filename,{ 'ReadOnly' => options[:read_only] })
           workbooks.Item(1).Close if @excel.Version == "12.0" && count == 0
         rescue WIN32OLERuntimeError => msg
-          t "WIN32OLERuntimeError: #{msg.message}" 
+          trace "WIN32OLERuntimeError: #{msg.message}" 
           if msg.message =~ /800A03EC/
             raise ExcelErrorOpen, "open: user canceled or open error"
           else 
@@ -312,14 +325,17 @@ module RobustExcelOle
   public
 
     # closes the workbook, if it is alive
-    #
+    # @param [Hash] opts the options
+    # @option opts [Symbol] :if_unsaved :raise (default), :save, :forget, :keep_open, or :alert
     # options:
     #  :if_unsaved    if the workbook is unsaved
-    #                      :raise (default) -> raises an exception       
+    #                      :raise           -> raises an exception       
     #                      :save            -> saves the workbook before it is closed                  
     #                      :forget          -> closes the workbook 
     #                      :keep_open       -> keep the workbook open
     #                      :alert           -> 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})
       if (alive? && (not @workbook.Saved) && writable) then
         case opts[:if_unsaved]
@@ -370,17 +386,27 @@ module RobustExcelOle
       unobtrusively(*args, &block)
     end
 
-    # modifies a workbook such that its state (open/close, saved/unsaved, readonly/writable) remains unchanged.
-    #  options:
-    #  :reuse (default)  : opens closed workbooks in the Excel instance of the workbook, if it exists, reuse another Excel, otherwise          
-    #  :hidden           : opens closed workbooks in one separate Excel instance that is not visible and has no displayaslerts    
-    #  <excel-instance>  : opens closed workbooks in the given Excel instance
+    # modifies a workbook such that its state (open/close, saved/unsaved, readonly/writable) remains unchanged
+    # @param [String] file        the file name
+    # @param [Hash]   if_closed   an option
+    # @param [Hash]   opts        the options
+    # @option opts [Variant] :if_closed  :reuse (default), :hidden or a Excel instance
+    # @option opts [Boolean] :read_only whether the file is opened for read-only
+    # @option opts [Boolean] :readonly_excel behaviour when workbook is opened read-only and shall be modified
+    # @option opts [Boolean] :keep_open whether the workbook shall be kept open after unobtrusively opening
+    #  options: 
+    #   :if_closed :   if the workbook is closed, then open it in
+    #                    :reuse  -> the Excel instance of the workbook, if it exists, 
+    #                               reuse another Excel, otherwise          
+    #                    :hidden -> a separate Excel instance that is not visible and has no displayaslerts
+    #                    <excel-instance> -> the given Excel instance
     #  :read_only        : opens the workbook unobtrusively for reading only  (default: false)
     #  :readonly_excel:  if the workbook is opened only as ReadOnly and shall be modified, then
     #                    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.
     #  :keep_open: lets the workbook open after unobtrusively opening (default: false)
+    # @return [Book] a workbook
     def self.unobtrusively(file, if_closed = nil, opts = { }, &block) 
       if if_closed.is_a? Hash
         opts = if_closed
@@ -440,6 +466,9 @@ module RobustExcelOle
     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)
@@ -454,8 +483,14 @@ module RobustExcelOle
     end
 
     # returns the contents of a range with given name
-    # if no contents could returned, then return default value, if a default value was provided
-    #                                raise an error, otherwise
+    # @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)
@@ -483,8 +518,9 @@ module RobustExcelOle
     end
 
     # sets the contents of a range with given name
-    # @param [String] name the range 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)
@@ -498,7 +534,8 @@ module RobustExcelOle
       end
     end
 
-    # brings the workbook to the foreground and available for heyboard inputs, and makes the Excel instance visible
+    # 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
@@ -509,12 +546,13 @@ module RobustExcelOle
       end
     end
 
-    # returns whether the workbook is visible or invisible
+    # returns true, if the workbook is visible, false otherwise 
     def visible
       @excel.Windows(@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 = @workbook.Saved
       @excel.Windows(@workbook.Name).Visible = visible_value
@@ -538,15 +576,15 @@ module RobustExcelOle
       @workbook.Fullname.tr('\\','/') rescue nil
     end
 
-    def writable
+    def writable   # :nodoc: #
       (not @workbook.ReadOnly) if @workbook
     end
 
-    def saved
+    def saved   # :nodoc: #
       @workbook.Saved if @workbook
     end
 
-    # returns true, if the full book names and excel Instances are identical, false otherwise  
+    # @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 &&
@@ -558,7 +596,8 @@ module RobustExcelOle
     end
 
     # simple save of a workbook.
-    # @return [Boolean] true, if successfully saved, nil or error otherwise
+    # @raise ExcelErrorSave if workbook is not alive or opened for read-only, or another error occurs
+    # @return [Boolean] true, if successfully saved, nil otherwise
     def save      
       raise ExcelErrorSave, "Workbook is not alive" if (not alive?)
       raise ExcelErrorSave, "Not opened for writing (opened with :read_only option)" if @workbook.ReadOnly
@@ -575,21 +614,25 @@ module RobustExcelOle
     end
 
     # saves a workbook with a given file name.
-    # @param [String] file the file name
-    # @option opts [Symbol] :if_exists if a file with the same name exists, then  
-    #
-    # options:
-    #  :if_exists   if a file with the same name exists, then  
+    # @param [String] file   file name
+    # @param [Hash]   opts   the options
+    # @option opts [Symbol] :if_exists      :raise (default), :overwrite, or :alert
+    # @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
     #  :if_obstructed   if a workbook with the same name and different path is already open and blocks the saving, then
-    #                  :raise (default)     -> raises an exception 
+    #                  :raise               -> raises an exception 
     #                  :forget              -> closes the blocking workbook
     #                  :save                -> saves the blocking workbook and closes it
     #                  :close_if_saved      -> closes the blocking workbook, if it is saved, 
     #                                          otherwise raises an exception
-    # returns true, if successfully saved, nil or error otherwise
+    # @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
     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 @workbook.ReadOnly
@@ -649,7 +692,7 @@ module RobustExcelOle
 
   private
 
-    def save_as_workbook(file, options)
+    def save_as_workbook(file, options)   # :nodoc: #
       begin
         dirname, basename = File.split(file)
         file_format =
@@ -692,7 +735,7 @@ module RobustExcelOle
     end
 
     # sets the value of a range given its name
-    # @param [String] name the name of the range
+    # @param [String]  name  the name of the range
     # @param [Variant] value the contents of the range
     def []= (name, value)
       set_nvalue(name,value)
@@ -706,9 +749,12 @@ module RobustExcelOle
 
     # adds a sheet to the workbook
     # @param [Sheet] sheet a sheet
-    # @option opts [Symbol] :as new name of the copyed sheet
+    # @param [Hash]  opts  the options
+    # @option opts [Symbol] :as     new name of the copyed 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
+    # @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
@@ -726,38 +772,38 @@ module RobustExcelOle
         if msg.message =~ /800A03EC/ 
           raise ExcelErrorSheet, "sheet name already exists"
         else
-          t "#{msg.message}"
+          trace "#{msg.message}"
           raise ExcelErrorSheetUnknown
         end
       end
       new_sheet
     end      
 
-    def self.bookstore
+    def self.bookstore   # :nodoc: #
       @@bookstore ||= Bookstore.new
     end
 
-    def bookstore
+    def bookstore    # :nodoc: #
       self.class.bookstore
     end   
 
-    def self.show_books
+    def self.show_books   # :nodoc: #
       bookstore.books
     end
 
-    def to_s
+    def to_s    # :nodoc: #
       "#{self.filename}"
     end
 
-    def inspect
-      "<#Book: " + "#{"not alive " unless alive?}" + "#{File.basename(self.filename) if alive?}" + " #{@workbook} #{@excel}"  + ">"
+    def inspect    # :nodoc: #
+      "#<Book: " + "#{"not alive " unless alive?}" + "#{File.basename(self.filename) if alive?}" + " #{@workbook} #{@excel}"  + ">"
     end
 
-    def self.in_context(klass)
+    def self.in_context(klass)  # :nodoc: #
       
     end
 
-    def self.excel_class
+    def self.excel_class    # :nodoc: #
       @excel_class ||= begin
         module_name = self.parent_name
         "#{module_name}::Excel".constantize
@@ -766,7 +812,7 @@ module RobustExcelOle
       end
     end
 
-    def self.sheet_class
+    def self.sheet_class    # :nodoc: #
       @sheet_class ||= begin
         module_name = self.parent_name
         "#{module_name}::Sheet".constantize
@@ -775,17 +821,33 @@ module RobustExcelOle
       end
     end
 
-    def excel_class
+    def excel_class        # :nodoc: #
       self.class.excel_class
     end
 
-    def sheet_class
+    def sheet_class        # :nodoc: #
       self.class.sheet_class
     end
 
+    def respond_to?(name, include_private = false)  # :nodoc: #    
+      raise ExcelError, "respond_to?: workbook not alive" unless alive?
+      super
+    end
+
+    #alias old_book_methods methods
+
+    def methods   # :nodoc: # 
+      #(old_book_methods + @workbook.ole_methods.map{|m| m.to_s}).uniq
+      (super + @workbook.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: workbook not alive" unless alive?
@@ -802,6 +864,8 @@ module RobustExcelOle
       end
     end
 
+
+
   end
   
 public