robust_excel_ole 0.4 → 0.5

data/.gitignore

@@ -7,3 +7,4 @@ vendor/bundle
 .DS_Store
 doc/*
 *.sublime-workspace
+.yardoc

data/Changelog

@@ -1,6 +1,21 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+## [0.5.0] - 2016-31-05
+
+### Added
+- Book: sheet, add_empty_sheet, copy_sheet
+		rangeval, set_rangeval, nameval, set_nameval
+		open: option check_compatibility
+- Sheet: last_sheet, first_sheet, rangeval, nameval
+- Excel: with_calculaiton, rangeval, set_rangeval, nameval, set_nameval, [], []=
+
+### Changed
+- Book: book.sheet(<sheet_name>) replaces book[<sheet-name>]
+        add_or_copy_sheet replaces add_sheet
+        name_val, set_name_val replaces n_value, set_n_value
+
+       
 ## [0.4] - 2016-03-16
 
 ### Added

data/README.rdoc

@@ -41,7 +41,7 @@ The semantics is similar to, e.g.,  +File.open+.
 Options are 
   
   +:default_excel+, +:force_excel+, +:if_absent+, +:if_unsaved+, +:if_obstructed+, 
-  +:read_only+, +:visible+, +:displayalerts+. 
+  +:read_only+, +:check_compatibility, +:visible+, +:displayalerts+. 
 
 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+.
 
@@ -125,7 +125,7 @@ The method +unobtrusively+ enables the user to read or modify a workbook, no mat
 
 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 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. Moreover, there are the options +:visible+ and +:displayalerts+.
+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. Moreover, there are the options +:visible+, +:displayalerts+ and +:check_compatiblity.
 
   Book.unobtrusively('workbook.xls', :reuse, :read_only => false, :keep_open => false) do |book|
     # some modification
@@ -147,25 +147,25 @@ This method finds out whether the Excel workbook that is referenced by the Book
 
   if book.alive? then sheet = book[0] end
 
-=== Setting and getting the contents of a range.
+=== Getting and setting the contents of a range in a workbook.
 
-Setting:
+Getting the contents of a range.
 
-  book["name"] = "value"
+  book["name"] 
+  => "value"
 
 or
 
-  book.set_nvalue("name") = "value"
+  book.nameval("name")
+  => "value"
 
-Getting:
+Setting the contents of a range.
 
-  book["name"] 
-  => "value"
+  book["name"] = "value"
 
 or
 
-  book.nvalue("name")
-  => "value"
+  book.set_nameval("name") = "value"
 
 === Activating a workbook.
 
@@ -201,13 +201,21 @@ Enable DisplayAlerts.
 
 === Accessing a sheet.
 
-A sheet object can be accessed with a Book#[] method via an integer number.
+Accessing the first sheet.
 
-  sheet = book[0]
+  sheet = book.sheet(1)
+
+or
 
-Accessing a sheet object with the sheet name.
+  sheet = book.first_sheet  
 
-  sheet = book['Sheet1']
+Accessing the last sheet.
+
+  sheet = book.last_sheet  
+
+Accessing a sheet with the sheet name.
+
+  sheet = book.sheet('Sheet1')
 
 Accessing sheet objects using the methods Book#each.
 
@@ -240,8 +248,8 @@ Reading a cell from a sheet object.
 
 Reading a cell from a range object.
 
-  row_range[0]  => first cell in row_range
-  column_range[1] => second cell in column_range
+  row_range[1]  => first cell in row_range
+  column_range[2] => second cell in column_range
 
 Methods to a cell are just delegated. Example:
 
@@ -270,49 +278,63 @@ Accessing a range of a column.
 
 Naming or renaming a cell range given its address.
 
-  book.add_name(1,1,"name")
+  book.set_name(1,1,"name")
+
+=== Getting and setting the contents of a named range in a worksheet
+
+Getting the value of a range.
+
+  sheet[name]
+  
+or
+
+  sheet.nameval(name)
+
+Setting the value of a range.
 
-=== Reading and modifying a Value of a named range
+  book[name] = value
 
-Returning the value of a range, e.g. a cell, that has a with a defined name.
+or
 
-  book.nvalue(name)
+  book.set_nameval(name,value)
 
-or 
+=== Getting and setting the contents of a named range in a Worksheet directly
 
-  book[name]
+Getting the value of a range.
 
-Setting the value of a range, e.g. a cell, that has a with a defined name.
+  sheet.rangeval(name)
 
-  book.set_nvalue(name,value)
+Setting the value of a range.
 
-or 
+  book.set_rangeval(name,value)
 
-  book[name] = value
+=== Copying or Adding an sheet.
 
-=== Adding a sheet.
+Adding (appending) an empty sheet.
 
-Adding a new sheet.
+  book.add_empty_sheet
 
-  book.add_sheet
+Adding an empty sheet and naming it.
 
-Adding a new sheet with a name.
+  book.add_empty_sheet(:as => 'sheet_name')
 
-  book.add_sheet(:as => 'new_sheet')
+Adding an empty sheet with a name before another sheet.
 
-Adding a new sheet with a name before another sheet.
+  book.add_empty_sheet(:as => 'new_name', :before => another_sheet)
 
-  book.add_sheet(:as => 'new_sheet2', :before => another_sheet)
+Copying a sheet and adding (appending) it.
 
-Adding a copy of a sheet with a name after another sheet.
+  book.copy_sheet sheet
 
-  book.add_sheet(sheet, :as => 'sheet_copy', :after => another_sheet)
+Copying a sheet after a another sheet and naming it.
 
-=== Value of a named cell or range
+  book.copy_sheet(sheet, :as => 'new_name', :after => another_sheet)
 
-Returning the value of a cell or range that has a with a defined name.
+Copying a sheet, if a sheet is given, adding an empty sheet, if no sheet is given.
 
-  sheet.nvalue(name)
+  book.add_or_copy_sheet
+
+  book.add_or_copy_sheet(sheet, :as => 'new_name', :after => another_sheet)  
 
 === Creating and reusing an Excel instance.
 
@@ -332,6 +354,48 @@ Promoting an Excel instance represented as WIN32OLE object to an Excel object
 
   excel = Excel.new(:reuse => win32ole_object)
 
+=== Closing an Excel
+
+  excel = Excel.current
+  excel.close
+
+The options are +:if_unsaved+ and +:hard+ . Example:
+
+Closing the Excel instance, saving unsaved wrkbooks and terminating the Excel process
+
+  excel.close(:if_unsaved => :save, :hard => true)
+
+=== Closing all Excel instances.
+
+  Excel.close_all
+
+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
+
+  Excel.close_all(:if_unsaved => :forget, :hard => :true) 
+
+=== Terminating all Excel processes
+
+  Excel.kill_all
+
+=== Recreating an Excel instance    
+
+Reopening the closed Excel instance. 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_objects  
+
 === Making Excel visible or invisible
 
 Making Excel visible.
@@ -361,47 +425,48 @@ Turning on and off in a block.
     book = Book.open('workbook.xls')
   end
 
-=== Closing an Excel
-
-  excel = Excel.current
-  excel.close
-
-The options are +:if_unsaved+ and +:hard+ . Example:
+=== Setting Calculation mode.
 
-Closing the Excel instance, saving unsaved wrkbooks and terminating the Excel process
+Setting calculation mode to manual. Options are +:manual+ and +:automatic+
+The calculation mode is not reset after the block.
 
-  excel.close(:if_unsaved => :save, :hard => true)
+  excel = Excel.create
+  book = Book.open('workbook.xls')
+  excel.with_calculation(:manual) do 
+    # do something
+  end
 
-=== Closing all Excel instances.
+=== Getting and setting the contents of a named range in an Excel application
 
-  Excel.close_all
+  excel = Excel.create
+  book = Book.open('another_workbook.xls')
 
-The options are +:if_unsaved+ and +:hard+ . Values for :if_unsaved+ are +raise+, +save+, and +forget+. Example:
+Getting the value of a range.
 
-Closing all Excel instances, not saving unsaved workbooks and terminating the Excel processes
+  excel[name]
+  
+or
 
-  Excel.close_all(:if_unsaved => :forget, :hard => :true) 
+  excel.nameval(name)
 
-=== Terminating all Excel processes
+Setting the value of a range.
 
-  Excel.kill_all
+  excel[name] = value
 
-=== Recreating an Excel instance    
+or
 
-Reopening the closed Excel instance. This includes reopening all workbooks that were open in that Excel instance.
+  excel.set_nameval(name,value)
 
-  excel.close
-  excel.recreate
+=== Getting and setting the contents of a named range in an Excel application directly
 
-The options are :reopen_workbooks, :visible and :displayalerts.
+Getting the value of a range.
 
-  excel.recreate(:reopen_workbooks => true, :visible => true, :displayalerts => true)
+  excel.rangeval(name)
 
-=== Providing Excel instances
+Setting the value of a range.
 
-Providing all Excel instances (opened via RobustExcelOle) as objects of the class Excel
+  excel.set_rangeval(name,value)
 
-  Excel.excel_objects
 
 === Examples
 

data/README_detail.rdoc

@@ -47,6 +47,7 @@ Options are the following:
 +:if_unsaved+::      specify behaviour if the workbook was unsaved (default: +new_excel+)
 +:if_obstructed+::   specidy 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
 +:displayalerts+::   allow display alerts in Excel (default: +false+)
 +:visible+::         make visibe in Excel (default: +false+)
 
@@ -188,9 +189,10 @@ Options are the following:
                      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)
-+:visible+::   change the Excel into visible or invisible
-+:displayalerts+:: change the Excel into enable or disable displayalerts
++:keep_open+::          let the workbook open after unobtrusively opening (default: false)
++:visible+::            change the Excel into visible or invisible
++:displayalerts+::      change the Excel into enable or disable displayalerts
++:check_compatibility+:: checks compatibility when saving
 
   Book.unobtrusively('workbook.xls') do |book|
     # some modification
@@ -211,25 +213,26 @@ The methods +for_reading+ and +for_modifying+ indicate unobtrusively reading or
 
   book.alive?
 
-=== Setting and getting the contents of a range.
+=== Getting and setting the contents of a range.
 
-Setting:
 
-  book["name"] = "value"
+Getting the contents of a range.
+
+  book["name"] 
+  => "value"
 
 or
 
-  book.set_nvalue("name") = "value"
+  book.nameval("name")
+  => "value"
 
-Getting:
+Setting the contents of a range.
 
-  book["name"] 
-  => "value"
+  book["name"] = "value"
 
 or
 
-  book.nvalue("name")
-  => "value"
+  book.set_nameval("name") = "value"
 
 === Activating a workbook.
 
@@ -266,13 +269,21 @@ Options: +true+ -> enable DisplayAlerts , +false+ -> Disable DisplayAlerts
 
 === Accessing a sheet.
 
-A sheet object can be accessed with a Book#[] method via an integer number.
+Accessing the first sheet.
 
-  sheet = book[0]
+  sheet = book.sheet(1)
 
-Accessing a sheet object with the sheet name.
+or
 
-  sheet = book['Sheet1']
+  sheet = book.first_sheet  
+
+Accessing the last sheet.
+
+  sheet = book.last_sheet  
+
+Accessing a sheet with the sheet name.
+
+  sheet = book.sheet('Sheet1')
 
 Accessing sheet objects using the methods Book#each.
 
@@ -280,6 +291,7 @@ Accessing sheet objects using the methods Book#each.
     # do something with sheet
   end
 
+
 === Accessing a row or a column.
 
 A sheet object is enumerable. Use the methods Sheet#each_column, Sheet#each_row or Sheet#each.
@@ -305,7 +317,7 @@ Reading a cell from a sheet object.
 
 Reading a cell from a range object.
 
-  row_range[0]  => first cell in row_range
+  row_range[1]  => first cell in row_range
   column_range[1] => second cell in column_range
 
 Methods to cell are just delegated as VBA methods. Example:
@@ -336,49 +348,63 @@ Accessing a range of a column.
 
 Naming or renaming a cell range given its address.
 
-  book.add_name(1,1,"name")
+  book.set_name(1,1,"name")
+
+=== Getting and setting the contents of a named range
 
-=== Reading and modifying a Value of a named range
+Getting the value of a range.
 
-Returning the value of a range, e.g. a cell, that has a with a defined name.
+  sheet[name]
+  
+or
+
+  sheet.nameval(name)
 
-  book.nvalue(name)
+Setting the value of a range.
 
-or 
+  book[name] = value
 
-  book[name]
+or
 
-Setting the value of a range, e.g. a cell, that has a with a defined name.
+  book.set_nameval(name,value)
 
-  book.set_nvalue(name,value)
+=== Getting and setting the contents of a named range directly
 
-or 
+Getting the value of a range.
 
-  book[name] = value
+  sheet.rangeval(name)
 
-=== Adding a sheet.
+Setting the value of a range.
 
-Adding a new sheet.
+  book.set_rangeval(name,value)
 
-  book.add_sheet
+=== Copying or Adding an sheet.
 
-Adding a new sheet with a name.
+Adding (appending) an empty sheet.
 
-  book.add_sheet(:as => 'new_sheet')
+  book.add_empty_sheet
 
-Adding a new sheet with a name before another sheet.
+Adding an empty sheet and naming it.
 
-  book.add_sheet(:as => 'new_sheet2', :before => another_sheet)
+  book.add_empty_sheet(:as => 'sheet_name')
 
-Adding a copy of a sheet with a name after another sheet.
+Adding an empty sheet with a name before another sheet.
 
-  book.add_sheet(sheet, :as => 'sheet_copy', :after => another_sheet)
+  book.add_empty_sheet(:as => 'new_name', :before => another_sheet)
 
-=== Value of a named cell or range
+Copying a sheet and adding (appending) it.
 
-Returning the value of a cell or range that has a with a defined name.
+  book.copy_sheet sheet
 
-  sheet.nvalue(name)
+Copying a sheet after a another sheet and naming it.
+
+  book.copy_sheet(sheet, :as => 'new_name', :after => another_sheet)
+
+Copying a sheet, if a sheet is given, adding an empty sheet, if no sheet is given.
+
+  book.add_or_copy_sheet
+
+  book.add_or_copy_sheet(sheet, :as => 'new_name', :after => another_sheet)
 
 === Creating and reusing an Excel instance.
 
@@ -398,6 +424,46 @@ Promoting an Excel instance represented as WIN32OLE object to an Excel object
 
   excel = Excel.new(:reuse => win32ole_object)
 
+
+=== Closing an Excel
+
+  excel = Excel.current
+  excel.close
+
+Closing the Excel instance and terminating the Excel process
+
+  excel.close(:hard => true)
+
+=== Closing all Excel instances.
+
+  Excel.close_all
+
+ Closing the Excel instances and terminating the Excel processes
+
+  Excel.close_all(:hard => true) 
+
+=== Terminating all Excel processes
+
+  Excel.kill_all
+
+=== Recreating an Excel instance    
+
+Reopening the closed Excel instance. This includes reopening all workbooks that were open in that Excel instance.
+
+  excel.close
+  excel.recreate
+
+Options are :visible and :displayalerts
+
+  excel.recreate(:visible => true, :displayalerts => true)
+
+=== Providing Excel instances
+
+Providing all Excel instances (opened via RobustExcelOle) as objects of the class Excel
+
+  Excel.excel_objects
+
+
 === Making Excel visible or invisible
 
 Making Excel visible.
@@ -427,43 +493,47 @@ Turning on and off in a block.
     book = Book.open('workbook.xls')
   end
 
-=== Closing an Excel
-
-  excel = Excel.current
-  excel.close
+=== Setting Calculation mode.
 
-Closing the Excel instance and terminating the Excel process
+Setting calculation mode to manual. Options are +:manual+ and +:automatic+
+The calculation mode is not reset after the block.
 
-  excel.close(:hard => true)
+  excel = Excel.create
+  book = Book.open('workbook.xls')
+  excel.with_calculation(:manual) do 
+    # do something
+  end  
 
-=== Closing all Excel instances.
+=== Getting and setting the contents of a named range in an Excel application
 
-  Excel.close_all
+  excel = Excel.create
+  book = Book.open('another_workbook.xls')
 
- Closing the Excel instances and terminating the Excel processes
+Getting the value of a range.
 
-  Excel.close_all(:hard => true) 
+  excel[name]
+  
+or
 
-=== Terminating all Excel processes
+  excel.nameval(name)
 
-  Excel.kill_all
+Setting the value of a range.
 
-=== Recreating an Excel instance    
+  excel[name] = value
 
-Reopening the closed Excel instance. This includes reopening all workbooks that were open in that Excel instance.
+or
 
-  excel.close
-  excel.recreate
+  excel.set_nameval(name,value)
 
-Options are :visible and :displayalerts
+=== Getting and setting the contents of a named range in an Excel application directly
 
-  excel.recreate(:visible => true, :displayalerts => true)
+Getting the value of a range.
 
-=== Providing Excel instances
+  excel.rangeval(name)
 
-Providing all Excel instances (opened via RobustExcelOle) as objects of the class Excel
+Setting the value of a range.
 
-  Excel.excel_objects
+  excel.set_rangeval(name,value)  
 
 
 === Examples