robust_excel_ole 1.27 → 1.32

data/docs/README_excel.rdoc

@@ -12,7 +12,7 @@ You can create a new Excel instance by
 
 or 
 
-  excel1 = Excel.new(:reuse => false)  
+  excel1 = Excel.new(reuse: false)  
 
 In case you want to reuse an already running Excel instance, write
 
@@ -20,7 +20,7 @@ In case you want to reuse an already running Excel instance, write
 
 or 
 
-  excel2 = Excel.new(:reuse => true)  
+  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+).
 
@@ -28,7 +28,7 @@ The option +:calculation+ specifies, whether the calculation mode is being force
 
 You can also type-lift an Excel instance represented as WIN32OLE object to an Excel object.
 
-  excel = Excel.new(win32ole_object, :visible => true)
+  excel = Excel.new(win32ole_object, visible: true)
 
 Once you have got an Excel object, you can apply all VBA methods that you would apply to a VBA Application object
 (see https://docs.microsoft.com/en-us/office/vba/api/excel.application(object)#methods).
@@ -40,17 +40,17 @@ You can set all options in a given Excel instance
 
   excel = Excel.current
 
-  excel.for_this_instance(:visible => true, :displayalerts => true, :calculation => :manual)
+  excel.set_options(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)
+  excel1 = Excel.create(visible: true)
 
 or
 
-  excel1 = Excel.new(:reuse => false, :visible => true)  
+  excel1 = Excel.new(reuse: false, visible: true)  
 
 or 
 
@@ -62,7 +62,7 @@ or
 
 You can enable DisplayAlerts with, e.g. 
 
-  excel1 = Excel.new(:reuse => true, :displayalerts => true)
+  excel1 = Excel.new(reuse: true, displayalerts: true)
 
 or 
 
@@ -99,30 +99,22 @@ You can do it in a block:
 
 You can set options for all workbooks of an Excel instance.
 
-  excel.for_all_workooks(:visible => true, :read_only => true)
+  excel.each_workook(visible: true, read_only: true)
 
 
-=== Showing and traversing through all workbooks
+=== Showing and traversing all workbooks
 
-You can yield an array of all Workbook objects of an Excel instance.
+The method +each+ provides an enumerator traversing all workbook objects. You can yield an array of all Workbook objects of an Excel instance, by applying +to_a+ or
 
   excel.workbooks
 
-You can access all Workbook objects by using the methods Excel#each_workbook and Excel#each_workbook_with_index. Here are some examples:
+You can access all Workbook objects supplying options by using the methods Excel#each_workbook and Excel#each_workbook_with_index. Here are some examples:
   
-  excel.each_workbook {|w| puts w.filename}
+  excel.each_workbook(displayalerts: true) {|w| puts w.filename}
 
 and
 
-  excel.each_workbook.with_index {|w,i| puts w,i }
-
-With help of these methods you can also supply options, e.g. without a block,
-
-  excel.each_workbook(:visible => true) 
-
-or, with a block,
-
-  excel.each_workbook(:visible => true) {|w| puts w}
+  excel.each_workbook.with_index(displayalerts: true) {|w,i| puts w,i }
 
 === Accessing the active workbook
 
@@ -143,7 +135,7 @@ The method +close has the option +:if_unsaved+ with the values +:raise+, +:save+
 
 For example, if you want to close an Excel instance and save unsaved workbooks, use
 
-  excel.close(:if_unsaved => :save)
+  excel.close(if_unsaved: :save)
 
 === Recreating an Excel instance    
 
@@ -154,7 +146,7 @@ Closed Excel instances can also be reopened. This includes reopening all workboo
 
 The options are +:reopen_workbooks+, +:visible+ and +:displayalerts+.
 
-  excel.recreate(:reopen_workbooks => true, :visible => true, :displayalerts => true)
+  excel.recreate(reopen_workbooks: true, visible: true, displayalerts: true)
 
 === Providing Excel instances
 
@@ -168,7 +160,7 @@ Providing all Excel instances (opened via RobustExcelOle) as objects of the clas
 
 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)   
+  Excel.close_all(if_unsaved: :raise)   
 
 === Terminating all Excel processes
 

data/docs/README_listobjects.rdoc

@@ -0,0 +1,176 @@
+= RobustExcelOle
+
+== List Objects
+
+=== Creating List Objects
+
+We can define a list object (or table) from scratch.
+
+  table = ListObject.new(worksheet, "table 1", [1,1], 3, ["Person","AmountSales"])
+
+This command creates a list object in worksheet named "table 1", with upper left corner at position [1,1] (first cell), with 3 rows and the columns "Person" and "AmountSales". Please note, that creating a table this way does work for more than one rows only.
+
+Likewise we can get a given list object in a worksheet by providing its table number or name.
+
+  table = worksheet.table(1)
+
+or
+
+  table = worksheet.table("table1")
+  
+Now we have a RobustExcelOle ListObject that wraps a WIN32OLE ListObject. So we can send any WIN32OLE (VBA) method to it. See 
+https://docs.microsoft.com/en-us/office/vba/api/excel.listobject#methods.
+
+=== Accessing List Rows
+
+A row in this table (list row object) can be accessed with help of #[], given either the row number or a key. The key is a hash of the key column names and the values.
+
+  row1 = table[1]
+
+  row1 = table[{"Number" => 1, "Person" => "John"}]
+
+If you want to get more than one table row objects that match the key, then you can supply the maximal number of matches. If you want to get all matches, then you state +nil+.
+
+  rows = table[{"Number" => 1}, limit: 2]
+  rows = table[{"Number" => 1}, limit: nil]
+
+Additionally the enumerator method +each+ is being provided. So you can also traverse through the listrows.
+
+ table.each{ |listrow| puts listrow }
+
+So we get a RobustExcelOle ListRow objects that wraps a WIN32OLE ListRow. Now we can send any WIN32OLE (VBA) method to it. See 
+https://docs.microsoft.com/en-us/office/vba/api/excel.listrow#methods.
+
+=== Reading and setting values
+
+Now we can set value of a cell of the table with help of methods that are equal to or are underscored variants of the column names, e.g.
+
+  row1.AmountSales = 40
+
+or
+
+  row1.amount_sales = 40
+
+or
+
+  row1["AmountSales"] = 40
+  
+Similarly you can get the values.
+
+  row1.AmountSales
+  # => 40
+
+or
+
+  row1.amount_sales
+  # => 40
+
+or
+
+  row1["AmountSales"]
+  # => 40
+
+We can also read the values in a whole row.
+
+  table[1].to_a
+  # => ["John", 40]
+
+or
+
+  table[1].values
+  # => ["John", 40]
+
+or
+
+  table.row_values(1)
+  # => ["John", 40]
+  
+You can get the column name-value pairs by
+
+  table[1].to_h
+  # => {"Person" => "John", "AmountSales" => 40}
+
+We can set the values in a whole row.
+
+  table[1].values = ["Herber", 80]
+
+or
+
+  table[1].set_values(["Herbert", 80])
+
+or
+
+  table.set_row_values(1, ["Herbert", 80])
+  
+If the number of given values is less than the number of cells in the row, only the first values are written. The remaining values keep their value.  
+
+Similarly, we can read and set the values in a whole column, e.g.
+
+  table.column_values("Person")
+  # => ["John", "Peter"]
+
+and 
+
+  table.set_column_values(1, ["Herbert","Paul"])
+
+The column names we can get with help of
+
+  table.column_names
+
+A column can be renamed.
+
+  table.rename_column("Person", "Enterprise")
+
+or 
+
+  table.rename_column(1, "Enterprise")
+
+=== Table values   
+
+We can get the values of the table with help of the method +value+: 
+  
+  table.value
+  
+=== Adding and Deleting rows and columns
+
+We can add rows and columns, supplying optionally their name, the position and contents. 
+
+  table.add_column("column_name")
+  table.add_column("column_name", 3)
+  table.add_column("column_name", 3, ["John", "Paul"])
+  
+  table.add_row(3)
+  table.add_row(3, ["John", 40, 2, 2004])
+
+We can delete only the contents of a column
+
+  table.delete_column_values("column_name")
+
+Similarly can delete only the contents of a row.
+
+  table.delete_row_values(2)
+
+or 
+
+  table[2].delete_values
+
+Finally we can delete empty rows and columns.
+
+  table.delete_empty_rows
+  table.delete_empty_columns
+
+=== Finding values and sorting 
+
+You can find all cells containing a given value, e.g.
+
+  table.find_value(value)
+  #=> [#<Cell: (5,8)>#, #<Cell: (9,6)>#]
+
+You can sort a table according to a given column and sort order, e.g.
+
+  table.sort("Person", :ascending)
+
+== Code
+
+listobjects.rb[https://github.com/Thomas008/robust_excel_ole/blob/master/lib/robust_excel_ole/listobjects.rb]
+

data/docs/README_open.rdoc

@@ -17,6 +17,11 @@ The semantics is similar to, e.g.,  +File.open+.
     # do something
   end
 
+You can provide the filename as a string (as above) or as Pathname object.
+
+  pathname = Pathname('spec/data/workbook.xls')
+  workbook = Workbook.open(pathname)
+
 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+
@@ -80,7 +85,7 @@ 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 = Workbook.open('spec/data/workbook.xls', :default => {:excel => :current})
+  workbook = Workbook.open('spec/data/workbook.xls', default: {excel: :current})
 
 or
   
@@ -88,41 +93,41 @@ or
 
 In case you want to open such a workbook in a new Excel instance, then use
 
-  workbook = Workbook.open('spec/data/workbook.xls', :default => {:excel => :new})
+  workbook = Workbook.open('spec/data/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 = Workbook.open('spec/data/workbook.xls', :force => {:excel => :new})
+  workbook = Workbook.open('spec/data/workbook.xls', force: {excel: :new})
 
 For simplicity, you can also leave out the +:force+ option (but not the +:default+ option).
 
-  workbook = Workbook.open('spec/data/workbook.xls', :excel => :new)
+  workbook = Workbook.open('spec/data/workbook.xls', excel: :new)
 
 You can also specify an Excel instance
 
   excel1 = Excel.create
-  workbook = Workbook.open('spec/data/workbook.xls', :excel => excel1)
+  workbook = Workbook.open('spec/data/workbook.xls', excel: excel1)
 
 If you want to open the workbook and make its window visible, then use
 
-  book = Workbook.open('spec/data/workbook.xls', :visible => true)
+  book = Workbook.open('spec/data/workbook.xls', visible: true)
 
 Notice, that when the workbook is visible, the DisplayAlerts of the respective Excel instance is true, if not explicitely DisplayAlerts is set to false in this Excel instance.
 You can combine options, e.g. 
 
-  workbook = Workbook.open('spec/data/workbook.xls', :visible => true, :default => {:excel => excel1})
+  workbook = Workbook.open('spec/data/workbook.xls', visible: true, default: {excel: excel1})
 
 You can use the abbreviations, e.g. in this case
 
-  workbook = Workbook.open('spec/data/workbook.xls', :v => true, :d => {:e => excel1})  
+  workbook = Workbook.open('spec/data/workbook.xls', 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
 
-  workbook = Workbook.open('spec/data/workbook.xls', :if_unsaved => :accept)
+  workbook = Workbook.open('spec/data/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_blocked+ handles this situation, e.g.
 
-  workbook = Workbook.open('path/workbook.xls', :if_blocked => :forget)
+  workbook = Workbook.open('path/workbook.xls', if_blocked: :forget)
 
 Remarks:
 
@@ -165,11 +170,11 @@ The method +to_reo+ uses the method +new+. You can apply the method +new+ direct
 
 You can supply options, e.g. +:visible+.
 
-   workbook = Workbook.new(win32ole_workbook, :visible => true) 
+   workbook = Workbook.new(win32ole_workbook, visible: true) 
 
 You can also supply a workbook and options, e.g.
 
-   new_workbook = Workbook.new(workbook, :visible => true)
+   new_workbook = Workbook.new(workbook, visible: true)
 
 === Identity transperence ===
 
@@ -195,12 +200,11 @@ The method +unobtrusively+ enables the user to read or modify a workbook, no mat
 
 Options are the following:
 
-+:if_closed+:: the Excel instance in which to open the workbook, if it was closed (default: +:current+). (Note: this option works workbooks opened via RobustExcelOle only.)
-
 +:read_only+:: Whether the workbook shall be forced to be open in ReadOnly mode
-+:writable+::  Whether changes in the workbook shall be saved
-
++:writable+::  Whether changes in the workbook shall be saved and the workbook shall be opened in ReadOnly mode by default (i.e., when the workbook was not open before) (default: true)
 +:keep_open+:: Whether the workbook shall be open after unobtrusively opening (default: false)
++:if_closed+:: the Excel instance in which to open the workbook, if it was closed (default: +:current+). 
+(Note: this option works workbooks opened via RobustExcelOle only.)
 
 There are the class method and the instance method of +unobtrusively+. Here is an example of the class method:
 

data/docs/README_ranges.rdoc

@@ -8,7 +8,7 @@ RobustExcelOle enables to read and write the contents of ranges and cells in wor
 
 Suppose you have opened a workbook.
 
-  workbook = Workbook.open('spec/data/workbook.xls', :visible => true)
+  workbook = Workbook.open('spec/data/workbook.xls', visible: true)
 
 We access the first worksheet:
   
@@ -42,10 +42,6 @@ or
 
   range = worksheet.range(["A1:D3"])
 
-You can also access a range from a workbook by providing the worksheet
-
-  range = workbook(workbook.sheet(1), [1..3,1..4])
-
 Now you can read the values by 
 
   range.Value
@@ -61,7 +57,17 @@ or as flat array
   range.values
   =>  ["foo", "workbook", "sheet1", nil, "foo", nil, "foobaaa", nil, "matz", "is", "nice", nil]
 
-You can set values with help of range#Value or range#v, e.g.
+You can get the values of a range directly with help of the method #[], e.g.
+
+  worksheet[1..3,1..4]
+  => [["foo", "workbook", "sheet1", nil], ["foo", nil, "foobaaa", nil], ["matz", "is", "nice", nil]]
+
+You can set values with help of the method #[]= ,e.g.
+
+  worksheet[1..3,1..4] = [[1,2,3,4],[5,6,7,8],[9,10,11,12]]
+
+
+Alternatively you can use #Value=, #value= or #v=, or #set_value, e.g.
 
   range.Value = [[1,2,3,4],[5,6,7,8],[9,10,11,12]]
 
@@ -79,11 +85,11 @@ or
 
 You can color the range when setting the contents of a range.
 
-  range.set_value([[1,2,3,4],[5,6,7,8],[9,10,11,12]], :color => 42)
+  range.set_value([[1,2,3,4],[5,6,7,8],[9,10,11,12]], color: 42)
 
 Now we copy the range. With help of VBA methods you would do
 
-  range.Copy(:destination => sheet.range([4,5]).ole_range)
+  range.Copy(destination: sheet.range([4,5]).ole_range)
 
 or with help of RobustExcelOle
 
@@ -91,7 +97,7 @@ or with help of RobustExcelOle
 
 You can also copy a range into another worksheet in another workbook.
 
-  workbook2 = Workbook.open('spec/data/another_workbook.xls', :excel => :new, :visible => true)
+  workbook2 = Workbook.open('spec/data/another_workbook.xls', excel: :new, visible: true)
   range.copy([4,5],book2.sheet(3))
 
 Now we define a name that refers to a range consisting of only the first cell, i.e. the 1st row and 1st column. Using VBA methods, you can use
@@ -131,7 +137,7 @@ Finally we can rename a range, and delete the name of a range. With help of VBA
 
 Using RobustExcelOle, we write
 
-  workbook.rename_range("name", "new_name")
+  workbook.rename_name("name", "new_name")
   workbook.delete_name("name")
 
 Now we can read the value of cell simply by providing the row and the column
@@ -140,14 +146,9 @@ Now we can read the value of cell simply by providing the row and the column
 
 or with RobustExcelOle
 
-  worksheet[1,1].Value  
+  worksheet[1,1] 
   => "foo
 
-or
-
-  worksheet[1,1].v
-  => "foo"
-
 Similarly, you can write a cell.
 
   worksheet.Cells.Item(1,1).Value = "new_value"
@@ -168,11 +169,11 @@ For example, you can access a range consisting of one cell by providing the row
 
 Using the A1-format and R1C1-format you write
 
-  range = worksheet.range("A1") 
+  range = worksheet.range(["A1"]) 
 
 and
 
-  range = worksheet.range("Z1S1")
+  range = worksheet.range(["Z1S1"])
 
 respectively.
 
@@ -186,55 +187,74 @@ or using the A1-format.
 
 or
 
-  range = worksheet.range("A1:D3")
+  range = worksheet.range(["A1:D3"])
 
 or using the R1C1-format
 
-  range = worksheet.range("Z1S1:Z3S4")
+  range = worksheet.range(["Z1S1:Z3S4"])
 
-Infinite ranges are defined, e.g., by setting the rows or columns to +nil+
+Ranges containing infinite rows or columns can be defined, e.g., by setting the other parameter (columns or row) to +nil+: For example, the rows 1 to 3 you get by
 
   range = worksheet.range([1..3,nil])
+
+The columns "A" to "C" you get with help of 
+  
   range = worksheet.range([nil,"A".."B"])
 
-Using the A1-format you write
+You can yield a row also simply by providing the row number, e.g.
+  
+  range = worksheet.range(1)
+
+You can also use the A1-format, e.g.
 
-  range = worksheet.range("1:3")
-  range = worksheet.range("A:B")
+  range = worksheet.range(["1:3"])
+  range = worksheet.range(["A:B"])
 
 You can also apply relative references by using brackets, e.g.
 
-  range = worksheet.range("Z[1]S1:Z3S[4]")
+  range = worksheet.range(["Z[1]S1:Z3S[4]"])
 
 or
 
   range = worksheet.range([[1]..3,2..[4]])
 
-You can access a range also from a workbook by providing the respective worksheet
+You can access a range via its defined name with
 
-  range = workbook(worksheet, [[1..3],2..[4]])
+  range = worksheet.range("name")
 
-You get the values of the range as flat array with help of
+=== Getting and setting the value of a range
 
-  range.values
+You get the value of a range with help of #[] by providing the address of the range, or apply #value on a range, e.g.
 
-You can access a range via its defined name with
+  worksheet["name"]
 
-  range = worksheet.range("name")
+or
+
+  worksheet[1..2,3..4]
 
 or
 
-  range = workbook(worksheet, "name")
+  worksheet.range("name").value
+
+or
+
+  worksheet.range([1..2,3..4]).value
+
+The value is being restricted to the used range.
+
+If you want the values of the range as flat array, then use #values, e.g.
+
+  range.values
 
 === Copying a range
 
 Let's assume, you have a source range
 
-  range = worksheet.range(1..2,3..5)
+  range = worksheet.range([1..2,3..5])
 
 or, in A1-format,
 
-  range = worksheet.range("C1:E2")
+  range = worksheet.range(["C1:E2"])
 
 To copy it to the destination range (3..4,6..8), you can use 
 
@@ -250,7 +270,7 @@ You can copy the range into another worksheet of the same or another workbook, e
 
 Moreover, you can state, whether you want to copy the values only, and whether you want to transpose the destination range.
 
-  range.copy([3,6], destination_range, :values_only => true, :transpose => true)
+  range.copy([3,6], destination_range, values_only: true, transpose: true)
   
 Note that when you don't copy the values only but all formating as well, and you either copy into another Excel instance or transpose the range, the clipboard is being used. 
 
@@ -300,13 +320,21 @@ or
 
   workbook.add_name("name", [1..[2],[1]..4])
 
-You can do the same for an worksheet or Excel object.
+You can do the same for an worksheet.
+You get all names defined in the workbook or worksheet using the method +names+.
 
-=== Reading and writing the contents of a named range in a workbook.
+  worksheet.names
+  # => ["Sheet1!name"]
+
+  workbook.names
+  # => ["Sheet1!name", "four"]
+
+
+=== Reading and writing the contents of a range
 
 Assume you have opened a workbook:
  
-  workbook = Workbook.open('spec/data/workbook.xls', :visible => true)
+  workbook = Workbook.open('spec/data/workbook.xls', visible: true)
 
 You can get the contents of a range with a defined name with help of the method [] or +namevalue_glob+.
 
@@ -320,7 +348,7 @@ or
 
 Using +namevalue_glob+, via the option +:default+ you can provide a value that is returned when the name cannot be found or some other error would occur.
 
-  workbook.namvalue_glob("name", :default => "default_value")
+  workbook.namvalue_glob("name", default: "default_value")
 
 You can set the contents of a range with
 
@@ -332,26 +360,16 @@ or
 
 You can color the range when setting the contents of a range.
 
-  workbook.set_namevalue_glob("name", "new_value", :color => 4)
+  workbook.set_namevalue_glob("name", "new_value", color: 4)
 
 Similarly, the contents of a named range can be read and modified in a worksheet
 
   worksheet = workbook.sheet(1)
 
   worksheet["name"]
-  => value
-
-  worksheet["name"] = "new_value" 
-
-or an Application object.
-
-  excel = book.excel
-
-  excel["name"]
-  => "value"
-
-  excel["name"] = "new_value"
+  # => "old_value"
 
+  worksheet["name"] = "new_value"
 
 === Reading and writing the contents of a range with a locally defined name
 
@@ -375,13 +393,13 @@ or
 
 Similarly to namevalue, you can provide a default value that is returned when ocurring an error.
 
-  worksheet.namevalue("name", :default => "default_value")
+  worksheet.namevalue("name", default: "default_value")
 
 === Accessing a cell
 
 You can read a cell from a sheet object by providing the row and the column. For example, the following lines provide the value of the first cell (first row, first column):
 
-  worksheet[1,1].Value  
+  worksheet[1,1]
   => "foo
 
 or
@@ -398,7 +416,6 @@ or
   worksheet.set_cellval(1,1,"new_value")
 
 
-
 == Code
 
 range.rb[https://github.com/Thomas008/robust_excel_ole/blob/master/lib/robust_excel_ole/range.rb]