robust_excel_ole 1.1.3 → 1.1.4

data/README_detail.rdoc

@@ -280,6 +280,12 @@ This method ensures keeping the save status of the workbook
     # some reading or modifying
   end
 
+=== Setting options
+
+You can set options, e.g. with
+
+  book.for_this_workbook(:visible => true, :read_only => true)
+
 === Checking whether the workbook is alive.
 
 This method finds out whether the Excel workbook that is referenced by the Workbook object responds to methods.
@@ -536,17 +542,17 @@ You can turn off and off DisplayAlerts in a block.
 
 === Making all workbooks visible or invisible
 
-  excel1.workbooks_visible true  
+  excel.workbooks_visible true  
 
-  excel1.workbooks_visible false   
+  excel.workbooks_visible false   
 
 === Setting options
 
 You can set all options in a given Excel instance
 
-  e1 = Excel.current
+  excel = Excel.current
 
-  e1.set_options(:visible => true, :displayalerts => true)
+  excel.for_this_instance(:visible => true, :displayalerts => true)
 
 === Bringing an Excel instance to the foreground
 

data/README_development.rdoc

@@ -0,0 +1,5 @@
+= RobustExcelOle
+
+=== Development
+
+The tests of RobustExcelOle are optimised with help of the rcov tool.  

data/README_excel.rdoc

@@ -0,0 +1,145 @@
+= RobustExcelOle
+
+== Creating, using and closing Excel instances
+
+RobustExcelOle enables simultanously running Excel instances. An Excel application is represented by an Excel object.
+
+=== Creating and reusing an Excel instance.
+
+You can start a new Excel instance by
+
+  excel1 = Excel.create
+
+or 
+
+  excel1 = Excel.new(:reuse => false)  
+
+In case you want to reuse an already running Excel instance, write
+
+  excel2 = Excel.current
+
+or 
+
+  excel2 = Excel.new(:reuse => true)  
+
+Options of the methods +create+ and +new+ are +:reuse+ (+true+, +false+), +:visible+ (+true+, +false+), +:displayalerts+ (+true+, +false+, +:if_visible+), +:calculation+ (+:manual+, +:automatic+, +nil+) and +:screenupdating+ (+true+, +false+).
+
+The option +:calculation+ specifies, whether the calculation mode is being forced to be manual (:manual), automatic (+:automatic+) or is not being forced (+nil+).
+
+You can also promote an Excel instance represented as WIN32OLE object to an Excel object.
+
+  excel = Excel.new(win32ole_object, :visible => true)
+
+=== Setting options
+
+You can set all options in a given Excel instance
+
+  excel = Excel.current
+
+  excel.for_this_instance(:visible => true, :displayalerts => true, :calculation => :manual)
+
+=== Making an Excel visible or invisible
+
+You can create a new Excel instance and make it visible.
+
+  excel1 = Excel.create(:visible => true)
+
+or
+
+  excel1 = Excel.new(:reuse => false, :visible => true)  
+
+or 
+
+  excel1 = Excel.create
+  excel1.visible = true  
+
+
+=== Enabling or disabling DisplayAlerts
+
+You can enable DisplayAlerts with, e.g. 
+
+  excel1 = Excel.new(:reuse => true, :displayalerts => true)
+
+or 
+
+  excel1 = Excel.current
+  excel1.displayalerts = true
+
+and turn DisplayAlerts off with
+
+  excel1.displayalerts = false
+
+You can turn off and off DisplayAlerts in a block.
+
+  excel = Excel.create
+  excel.with_displayalerts false do
+    # do something
+  end
+
+=== Setting Calculation mode.
+
+You can set the calculation mode of an Excel instance to manual or automatic.
+
+  excel.calculation = :manual
+
+You can do it in a block:
+
+  excel = Excel.create
+  book = Workbook.open('workbook.xls')
+  excel.with_calculation(:manual) do 
+    # do something
+  end
+
+
+
+=== Setting options for all workbooks
+
+You can set options for all workbooks of an Excel instance.
+
+  excel.for_all_workooks(:visible => true, :read_only => true)
+
+=== Bringing an Excel instance to the foreground
+
+  excel1.focus
+
+=== Closing an Excel
+
+  excel = Excel.current
+  excel.close
+
+The method +close has the option +:if_unsaved+ with the values +:raise+, +:save+, +:forget+ and +:alert+.
+
+For example, if you want to close an Excel instance and save unsaved workbooks, use
+
+  excel.close(:if_unsaved => :save)
+
+=== Recreating an Excel instance    
+
+Closed Excel instances can also be reopened. This includes reopening all workbooks that were open in that Excel instance.
+
+  excel.close
+  excel.recreate
+
+The options are :reopen_workbooks, :visible and :displayalerts.
+
+  excel.recreate(:reopen_workbooks => true, :visible => true, :displayalerts => true)
+
+=== Providing Excel instances
+
+Providing all Excel instances (opened via RobustExcelOle) as objects of the class Excel
+
+  Excel.excel_processes 
+
+=== Closing all Excel instances
+
+  Excel.close_all
+
+This method has the option +:if_unsaved+ as described above. For example, if you want to close all Excel instances containing saved workbooks and raise an error for Excel instances with unsaved workbooks, use
+
+  Excel.close_all(:if_unsaved => :raise)   
+
+=== Terminating all Excel processes
+
+  Excel.kill_all
+
+This method kills all Excel instances no matter whether they contain unsaved workbooks.  

data/README_open.rdoc

@@ -0,0 +1,202 @@
+= RobustExcelOle
+
+=== Opening and unobtrusively modifying a workbook.
+
+If you want to open a workbook, use
+  
+  book = Workbook.open('workbook.xls')
+
+You can also open a workbook with a block. 
+The semantics is similar to, e.g.,  +File.open+.
+
+  Workbook.open('workbook.xls') do |book|
+    # do something
+  end
+
+The options are the following:
+
++:default+:: if the workbook was already open, then use the properties of this workbook.otherwise use the properties stated in +:default+
+
++:force+:: no matter whether the workbook was open before, use the properties stated in +:force+
+
++:excel+ and +:visible+ are options stated in +:default+ or +:force+
+
++:excel+::          specifies the Excel instance. 
+
++:visible+::        makes the workbook visible or invisible
+
++:if_unsaved+::      specify behaviour if the workbook was unsaved (default: +new_excel+)
+
++:if_obstructed+::   specify behaviour if the workbook is blocked by another book (default: +new_excel+)
+
++:read_only+::       open in read-only mode (default: +false+)
+
++:check_compatibility:: check compatibility when saving
+
++:calculation+::     forces the calculation mode to be manual (:manual) or automatic (:automatic)
+
++:if_absent+::       specify behaviour if the workbook with the given file name does not exist if the workbook does not exist (default: +create+)
+
+You can use the following abbreviations:
+
++:f+:: +:force+
++:d+:: +:default+
++:e+:: +:excel+
++:v+:: +:visible+
+
+The option +:excel+ :
+
+Valid values are : +:current+ (or +:active+ or +:reuse+), +:new+, or a given Excel instance (default: +:current).
+
+The option +:if_unsaved+  : 
+
+If a workbook contains unsaved changes and a new workbook with the same file name shall be opened, then
+
++:raise+::   Raise an exeption. Don't open the workbook.
++:accept+::  Let the unsaved workbook open.
++:forget+::  Discard any changes and reopen the workbook.
++:new_excel+:: Open the new workbook in a new Excel instance
++:alert+::   Give control to Excel.
+
+The option +:if_obstructed+ :
+
+If a workbook is open and a new workbook with same name and a different path is open, then
+
++:raise+::          Raise an exception. Don't open the workbook.
++:forget+::         Close the old workbook, open the new workbook.
++:save+::           Save the old workbook, close it, open the new workbook
++:close_if_saved+:: Close the old workbook and open the new workbook, if the old workbook is saved, otherwise raise an exception.
++:new_excel+::      Open the new workbook in a new Excel instance.
+
+The option +:if_absent  :
+
+If the Excel file does not exists, then
+
++:create+::   Create a new Excel file
++:raise+::    Raise an exception.
+  
+Here are a few examples:
+
+If you want to open a workbook that was not opened before, or reopen a workbook that was open in an Excel instance that is now closed, in the current (active) Excel instance, then use
+
+  Workbook.open('workbook.xls', :default => {:excel => :current})
+
+or
+  
+  Workbook.open('workbook.xls')
+
+In case you want to open such a workbook in a new Excel instance, then use
+
+  Workbook.open('workbook.xls', :default => {:excel => :new})
+
+If you want to open a workbook in a new Excel instance, no matter if it was opened before, you can write
+
+  Workbook.open('workbook.xls', :force => {:excel => :new})
+
+For simplicity, you can also leave out the +:force+ option (but not the +:default+ option).
+
+  Workbook.open('workbook.xls', :excel => :new)
+
+You can also specify an Excel instance
+
+  excel1 = Excel.create
+  # do something
+  Workbook.open('workbook.xls', :excel => excel1)
+
+If you want to open the workbook and make its window visible, then use
+
+  book = Workbook.open('workbook.xls', :visible => true)
+
+You can combine options, e.g. 
+
+  Workbook.open('workbook.xls', :excel => :new, :visible => true, :default => {:excel => excel1})
+
+You can use the abbreviations, e.g. in this case
+
+  Workbook.open('workbook.xls', :e => :new, :v => true, :d => {:e => excel1})  
+
+If a workbook contains unsaved changes and a workbook with the same filename shall be opened, then the option +:if_unsaved+ manages this conflict. For example, if the workbook with the unsaved changes shall remain open, you can use
+
+  book = Workbook.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, i.e. the first workbook blocks opening the other workbook, then the option +:if_obstructed+ handles this situation, e.g.
+
+  book = Workbook.open('path/workbook.xls', :if_obstructed => :forget)
+
+Remarks:
+
+Opening linked workbooks for EXCEL 2007 is supported
+
+Doing updating links seems to be dependent on calculation mode: updates happen, if the calcultion mode is automatic, and does not happen, if calculation mode is manual.
+
+=== Reopening a workbook.
+
+A special feature of RobustExcelOle is that it allows to reopen workbooks after closing them.
+
+  book = Workbook.open('workbook.xls')
+  book.close
+  book.reopen
+
+The closed workbook is now alive again, i.e. is open and responds to Excel methods.
+
+This feature is a result of providing identity transparence and storing the file name.
+
+=== The Workbook objects and transperence identity
+
+An Excel file (or workbook) is represented by a Workbook object. A Workbook object is defined by the full name of the workbook and the Excel instance in which it is opened. RobustExcelOle aims to ensure identity transperency.
+Identity transparence means that the same Workbook objects refer to the same Excel files, and vice versa.
+In other words, a Workbook objects is a proxy of an Excel file.
+
+=== Promoting a workbook to a Workbook object
+
+A Workbook object can be created when giving an Excel workbook.
+
+   book = Workbook.new(win32ole_workbook)
+
+
+=== Unobtrusively modifying a workbook
+
+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, visible or invisible, calculation mode is automatic or manual, and checking compatibility is turned on or off. 
+
+One option chooses the Excel instance in which a closed workbook is opened. The option +:current+ (or +:active+, or +: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.  Moreover, an Excel instance can be given directly where to open the closed workbook.
+
+Options are the following:
+
++:current+ (or +:active, or +:reuse+:): (default) : open a closed workbook in the Excel instance where it was opened most recently, if such an Excel instance exists, otherwise open it in the current (first opened) Excel instance
+               
++:read_only+:: Open the workbook unobtrusively for reading only  (default: false)
++:readonly_excel+::  if the workbook 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 workbook open after unobtrusively opening (default: false)
+
+  Workbook.unobtrusively('workbook.xls') do |book|
+    # some modification
+    sheet = book[0]
+    sheet[1,1] = "c" 
+  end
+  
+The methods +for_reading+ and +for_modifying+ indicate unobtrusively reading or modifying.
+
+  Workbook.for_modifying('workbook.xls') do |book|
+    # some modification
+    sheet = book[0]
+    sheet[1,1] = "c" 
+  end
+
+=== Retaining the saved-status
+
+This method ensures keeping the save status of the workbook
+
+  book = Workbook.open('workbook.xls')
+  book.retain_saved do
+    # some reading or modifying
+  end
+
+=== Checking whether the workbook is alive.
+
+This method finds out whether the Excel workbook that is referenced by the Workbook object responds to methods.
+
+  book.alive?
+  # => true
+

data/README_ranges.rdoc

@@ -0,0 +1,134 @@
+= RobustExcelOle
+
+== Reading and writing the contents of ranges and cells
+
+RobustExcelOle enables to read and write the contents of ranges and cells in Excel files. This can be done from a Sheet, a Book or an Excel object representing a Worksheet, Workbook, or Application object in VBA.
+
+=== Reading and writing the contents of a named range in a workbook.
+
+Assume you have opened a workbook:
+ 
+  book = Workbook.open('workbook.xls', :visible => true)
+
+You can get the contents of a range with a defined name with help of the method [] or nameval:
+
+  book["name"] 
+  => "value"
+
+or
+
+  book.nameval("name")
+  => "value"
+
+Using nameval, via the option :default you can provide a value that is returned when the name cannot be found or some other error would occur.
+
+  book.namval("name", :default => "default_value")
+
+You can set the contents of a range with
+
+  book["name"] = "new_value"
+
+or
+
+  book.set_nameval("name", "new_value")
+
+The method []= colors the written cell. You can specify the color of a changed range via the method set_nameval: 
+  
+  book.set_nameval("name", "new_value", :color => 4)
+
+Similarly, the contents of a named range can be read and modified in a worksheet 
+
+  sheet = book.sheet(1)
+
+  sheet["name"]
+  => value
+
+  sheet["name"] = "new_value" 
+
+or an application object:
+
+  excel = book.excel
+
+  excel["name"]
+  => "value"
+
+  excel["name"] = "new_value"
+
+When saving, the written cells get discolored when using the option :discoloring
+
+  book.save(:discoloring => true)
+
+or
+
+  book.save_as('workbook.xls', :discoloring => true)
+
+=== Reading and writing the contents of a range with a locally defined name
+
+The contents of locally defined ranges can be read
+
+  sheet.rangeval("name")
+  => "value"
+
+or
+
+  excel.rangeval("name")
+  => "value" 
+
+and be modified:
+
+  sheet.set_rangeval("name", "value")
+
+or
+
+  excel.set_rangeval("name", "value")
+
+Similarly to nameval, you can provide a default value that is returned when ocurring an error.
+
+  sheet.rangeval("name", :default => "default_value")
+
+=== Accessing a cell
+
+You can read and write a cell from a sheet object by providing the row and the column. For example, the following lines provide and set the value of the first cell (first row, first column):
+
+  sheet[1,1].value  
+  => "foo
+
+  sheet[1,1] = "new_value"
+
+=== Accessing rows and columns
+
+The methods Sheet#each, Sheet#each_row and Sheet#each_column enable to access each cell, row and column, respectively.
+
+  sheet.each do |cell|
+    # do something with cell
+    # read every row, every column
+  end
+
+  sheet.each_row do |row|
+    # do something with row
+  end
+
+  sheet.each_column do |column|
+    # do something with column
+  end
+
+You access a range of a row by giving the number of the row, and optionally, the range of the cell numbers.
+
+  sheet.row_range(1)  # => first row
+  sheet.row_range(1, 1..3 )  # => first three cells of the first row  
+
+Simarly you can access a range of a column.
+
+  sheet.col_range(3)  # => third column
+  sheet.col_range(3, 1..2)  # => first two cells of the third column
+
+Within a row or column range you can access a certain cell.
+
+  row_range[1]  # => first cell in row_range
+  column_range[2] # => second cell in column_range
+
+=== Naming a cell
+
+You can (re-) name a cell range.
+
+  sheet.set_name(1,1,"name")