robust_excel_ole 1.31 → 1.32

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

@@ -85,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
   
@@ -93,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:
 
@@ -170,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 ===
 

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]