robust_excel_ole 1.3 → 1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ffc7730bef4461a766a8be04f470304e77c9a518
-  data.tar.gz: 74fbedab450da21841ac9d3d7663d8199792a80c
+  metadata.gz: 2c82574a7d47691397738dc69d19c58a296e612f
+  data.tar.gz: 572d90add41cf354216f3cf9dcd2ca1260148b01
 SHA512:
-  metadata.gz: adb1b208ae94315fc104b310d36c983c7f6e17f5be2d6bc64a42148d3d5cf1bf645f0682806ca930cb4fe48225ff472f358acf6001ed35187bc07322be02b3c4
-  data.tar.gz: 022d0ecaf1fb85517989c217bed5128c9e9bbe462373923aaaa9e5dbaacc3397398eb1bbe1bf2b780a9ee0f401821216e7d69068547ef0779ac61fc93c390797
+  metadata.gz: abd37e3a312f2c723fe9759b6e9f9ed5ce284e40e864c262afba3dbcf57ed5d9d59b17141b49f34d6c299f83eea0c337c33a93f960820dacb70273977272d946
+  data.tar.gz: 81d3dfad4b6720a208f7f236fa44ad18d32483df6dfb8550dda4756d5c492b5e86eb14415635b610375429009b2356a6f9a99a19b13c2f0f30026e4694ac599e

data/Changelog

@@ -1,10 +1,16 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+## [1.4]
+
+### Changed
+  - renamed Book to Workbook, Sheet to Worksheet
+
 ## [1.3.1]
 
 ### Added
   - Book#open: option :excel => :reserved_new
+  - ReoCommon#name2range
 
 ## [1.2.2]
 

data/README.rdoc

@@ -253,7 +253,7 @@ For more details about processing worksheets see {README_sheet}[https://github.c
 
 We can define a rectangular range by providing the top left and the bottum down cell.
 
-  sheet.range(1..3,1..4)
+  sheet.range([1..3,1..4])
 
 We can read the first three cells of the first row
 

data/docs/README_open.rdoc

@@ -6,7 +6,7 @@ If you want to open a workbook, use
   
   book = Workbook.open('spec/data/workbook.xls')
 
-Once you have got an Book object, you can apply all VBA methods that you would apply to a VBA Workbook object
+Once you have got an Workbook object, you can apply all VBA methods that you would apply to a VBA Workbook object
 (see https://docs.microsoft.com/en-us/office/vba/api/excel.workbook#methods).
 For some common and complex tasks you can use the methods of RobustExcelOle.
 

data/docs/README_ranges.rdoc

@@ -2,7 +2,7 @@
 
 == Reading and writing the contents of ranges and cells
 
-RobustExcelOle enables to read and write the contents of ranges and cells in workbooks. This can be done from a Sheet, a Book or an Excel object representing a Worksheet, Workbook, or Application object, respectively. You can use VBA methods or methods provided by RobustExcelOle.
+RobustExcelOle enables to read and write the contents of ranges and cells in workbooks. This can be done from a Worksheet, a Workbook or an Excel object representing a Worksheet, Workbook, or Application object, respectively. You can use VBA methods or methods provided by RobustExcelOle.
 
 === Introducing Example
 
@@ -10,13 +10,21 @@ Suppose you have opened a workbook.
 
   book = Workbook.open('spec/data/workbook.xls', :visible => true)
 
-We can access a range consisting of one cell by providing the row and and the column of a cell. With help of VBA methods you can put
+We access the first worksheet:
+  
+  sheet = book.sheet(1)
+
+Now we can access a range consisting of one cell by providing the row and and the column of a cell. With help of VBA methods you can put
 
-  sheet.Range(sheet.Cells(1,1))
+  sheet.Range(sheet.Cells(1,2))
 
 or using RobustExcelOle
 
-  range = sheet.range(1,1)
+  range = sheet.range([1,2])
+
+or, using the A1-format,
+
+  range = sheet.range("B1")
 
 Similarly you can access a rectangular range. Using VBA methods we provide the row and column of the top left cell and the row and column of the bottum right cell. 
 
@@ -24,24 +32,36 @@ Similarly you can access a rectangular range. Using VBA methods we provide the r
 
 In RobustExcelOle we would supply the rows and columns as integer ranges.
 
-  range = sheet.range(1..3,1..4)
+  range = sheet.range([1..3,1..4])
+
+or, using the A1-format
+
+  range = sheet.range([1..3,"A".."D"])
+
+or
+
+  range = sheet.range(["A1:D3"])
 
 You can read the values by 
 
+  range.Value
+
+or as flat array
+  
   range.values
 
 Now we copy and paste a range. With help of VBA methods you would do
 
-  range.Copy(:destination => sheet.range(6,2).ole_range)
+  range.Copy(:destination => sheet.range([6,2]).ole_range)
 
 or with help of RobustExcelOle
 
-  range.copy(6,2)
+  range.copy([6,2])
 
 You can also copy a range into another worksheet in another workbook.
 
   book2 = Workbook.open('spec/data/another_workbook.xls', :excel => :new, :visible => true)
-  range.copy(5,8,book2.sheet(3))
+  range.copy([5,8],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
 
@@ -49,7 +69,7 @@ Now we define a name that refers to a range consisting of only the first cell, i
 
 RobustExcelOle provides the method +add_name+.
 
-  book.add_name("name",1,1)
+  book.add_name("name",[1,1])
 
 We define a name of a rectangular range. With help of VBA methods this is done by supplying the row and column of the top left cell and the row and columns of the bottum right cell of the range.
 
@@ -57,25 +77,21 @@ We define a name of a rectangular range. With help of VBA methods this is done b
 
 Using RobustExcelOle Defining a name referring to a rectangular range is done by providing the rows and columns as integer range.
 
-  book.add_name("name",1..2,3..4)
+  book.add_name("name",[1..2,3..4])
 
 Now we can assign a value to that named range. With help of VBA methods this can be done by
 
-  book.Names.Item("name").RefersToRange.Value = "bar"
-
-Using RobustExcelOle the assignment can be done by
+  book.Names.Item("name").RefersToRange.Value = [["foo", "bar"],[1.0, nil]]
 
-  book["name"] = "bar"
-
-Similarly, we can read the value of the range, using VBA methods
+Now we can read value of that range.
 
-  book.Names.Item("name").RefersToRange.Value
-  => "bar"
+  book.Names.Item("rec_name").RefersToRange.Value
+  => [["foo", "bar"],[1.0, nil]]
 
-or RobustExcelOle
+or
 
   book["name"]
-  => "bar" 
+  => [["foo", "bar"],[1.0, nil]]
 
 Finally we can rename a range, and delete the name of a range. With help of VBA methods this can be achieved by
 
@@ -87,17 +103,13 @@ Using RobustExcelOle, we write
   book.rename_range("name", "new_name")
   book.delete_name("name")
 
-Suppose you have a worksheet
-
-  sheet1 = book.sheet(1)
-
 Now we can read the value of cell simply by providing the row and the column
 
   sheet.Cells.Item(1,1).Value
 
 or with RobustExcelOle
 
-  sheet[1,1].value  
+  sheet[1,1].Value  
   => "foo
 
 Similarly, you can write a cell.
@@ -108,67 +120,58 @@ or using RobustExcelOle
 
   sheet[1,1] = "new_value"
 
-Suppose you want to define a named range consisting of several cells forming a rectangular. Using VBA methods this can be done by
-
-  book.Names.Add("Name" => "rec_name", "RefersToR1C1" => "=Z1S2:Z3S4")
-
-and using RobustExcelOle
+ In the following some details are being summarized. 
 
-  book.add_name("rec_name",1,2,3,4)
-
-We assign values to the cells of that range
+=== Accessing a range
 
-  book.Names.Item("rec_name").RefersToRange.Value = 
-      [["foo", nil, "bar"], [nil, "foobar", nil], ["is", "nice", nil]]
+You can access a range via its address or defined name. RobustExcelOle allows the R1C1- and the A1-format.
 
-or
+For example, you can access a range consisting of one cell by providing the row and and the column of a cell. 
 
-  book["rec_name"] = [["foo", nil, "bar"], [nil, "foobar", nil], ["is", "nice", nil]]
+  range = sheet.range([1,1])
 
-Now we can read value of that range.
+Using the A1-format you write
 
-  book.Names.Item("rec_name").RefersToRange.Value
-  => [["workbook", "sheet1", nil], [nil, "foobaaa", nil], ["is", "nice", nil]]
+  range = sheet.range("A1") 
 
-or
+You can access a rectangular range by providing the row and column of the top left cell and the row and column of the bottum right cell. 
 
-  book["rec_name"]
-  => [["workbook", "sheet1", nil], [nil, "foobaaa", nil], ["is", "nice", nil]] 
+  range = sheet.range([1..3,1..4])
 
-In the following some details are being summarized. 
+or using the a1-format
 
-=== Accessing a range
+  range = sheet.range([1..3,"A".."D"])
 
-You can access a range consisting of one cell by providing the row and and the column of a cell. 
+or
 
-  range = sheet.range(1,1)
+  range = sheet.range("A1:D3")
 
-You can access a rectangular range by providing the row and column of the top left cell and the row and column of the bottum right cell. 
+You get the values of the range as flat array with help of
 
-  range = sheet.range(1..3,1..4)
+  range.values
 
-You get the values of the range with
+You can access a range via its defined name with
 
-  range.values
+  range = sheet.name2range("name")
 
 === Copying a range
 
 You can copy and paste a range. 
 
-  range.copy(6,2)
+  range.copy([6,2])
 
 You can also copy a range into another worksheet in another workbook, and even another Excel instance. When copying into another Excel instance the destination shall be a cell (a rectangular range destination is not being considered)
 
   book2 = Workbook.open('spec/data/another_workbook.xls', :excel => :new, :visible => true)
-  range.copy(5,8,book2.sheet(3))
+  range.copy([5,8],book2.sheet(3))
 
 === Naming a cell
 
 You can (re-) define a name referring to a cell with help of VBA methods by stating its name, and the row and the column of the cell.
 
-  book.add_name("name",1,1)
+  book.add_name("name",[1,1])
 
-Most methods can be done for Workbook, Sheet, and Excel objects.
+Most methods can be done for Workbook, Worksheet, and Excel objects.
 
 === Reading and writing the contents of a named range in a workbook.
 
@@ -256,7 +259,7 @@ Similarly to namevalue, you can provide a default value that is returned when oc
 
 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):
 
-  sheet[1,1].value  
+  sheet[1,1].Value  
   => "foo
 
 or
@@ -274,7 +277,7 @@ or
 
 === Accessing rows and columns
 
-The methods Sheet#each, Sheet#each_row and Sheet#each_column enable to access each cell, row and column, respectively.
+The methods Worksheet#each, Worksheet#each_row and Worksheet#each_column enable to access each cell, row and column, respectively.
 
   sheet.each do |cell|
     # do something with cell

data/docs/README_sheet.rdoc

@@ -2,7 +2,7 @@
 
 == Accessing and processing worksheets
 
-Worksheets are represented by Sheet objects.
+Worksheets are represented by Worksheet objects.
 
 Assume you have opened a workbook
 

data/examples/introducing_examples/example_introducing.rb

@@ -0,0 +1,42 @@
+# introducing example
+
+require File.expand_path('../../lib/robust_excel_ole', File.dirname(__FILE__))
+require File.join(File.dirname(File.expand_path(__FILE__)), '../../spec/helpers/create_temporary_dir')
+require "fileutils"
+
+include RobustExcelOle
+
+dir = create_tmpdir
+simple_file = dir + 'another_workbook.xls'
+
+Excel.kill_all
+
+# Let's open a workbook.
+workbook = Workbook.open simple_file
+# put name of the workbook
+puts "name: #{workbook.Name}"
+value = workbook['firstcell']
+puts "value: #{value}"
+# assigning a new value
+workbook['firstcell'] = "new"
+# saving the workbook
+workbook.save
+# closing the workbook
+workbook.close
+# reopening the workbook
+workbook.reopen
+# further operations
+workbook['firstcell'] = "another_value"
+# saved status of the workbook
+puts "saved: #{workbook.Saved}"
+# unobtrusively reading a workbook
+Workbook.for_reading(simple_file) do |workbook|
+  puts "value of first cell: #{workbook['firstcell']}"
+end
+puts "saved: #{workbook.Saved}"
+# unobtrusively modifying a workbook
+Workbook.for_modifying(simple_file) do |workbook|
+  workbook['firstcell'] = "bar"
+end
+puts "saved: #{workbook.Saved}"
+puts "value of first cell: #{workbook['firstcell']}"

data/examples/introducing_examples/example_open.rb

@@ -0,0 +1,49 @@
+# introducing example example_open.rb
+
+require File.expand_path('../../lib/robust_excel_ole', File.dirname(__FILE__))
+require File.join(File.dirname(File.expand_path(__FILE__)), '../../spec/helpers/create_temporary_dir')
+require "fileutils"
+
+include RobustExcelOle
+
+dir = create_tmpdir
+simple_file = dir + 'workbook.xls'
+different_simple_file = dir + 'different_workbook.xls'
+another_simple_file = dir + 'another_workbook.xls'
+
+Excel.kill_all
+
+# open a workbook
+book = Workbook.open(simple_file) 
+puts "book: #{book}"
+# open a workbook in a new Excel instance
+book2 = Workbook.open(another_simple_file, :default => {:excel => :new})
+puts "book2: #{book2}"
+# open the workbook in a separate, reserved Excel instance.
+book3 = Workbook.open(different_simple_file, :default => {:excel => :reserved_new})
+puts "book3: #{book3}"
+# open the workbook in a new Excel instance and make it visible
+book4 = Workbook.open(simple_file, :force => {:excel => :new}, :visible => true)
+puts "book4: #{book4}"
+# open the workbook in a given Excel instance
+excel1 = book.excel
+book5 = Workbook.open(another_simple_file, :force => {:excel => excel1})
+puts "book5: #{book5}"
+# close a workbook
+book.close
+puts "close book -> book: #{book}"
+# reopen the workbook
+book6 = book.reopen
+puts "reopened book: book6: #{book6}"
+# unobtrusively opening a workbook
+Workbook.unobtrusively(simple_file) do |book|
+  sheet = book.sheet(1)
+  sheet[1,1] = "c" 
+end
+book6.close
+book5.close
+book4.close
+book3.close
+book2.close
+Excel.close_all
+  

data/examples/introducing_examples/example_range.rb

@@ -0,0 +1,67 @@
+# introducing example example_range.rb
+
+require File.expand_path('../../lib/robust_excel_ole', File.dirname(__FILE__))
+require File.join(File.dirname(File.expand_path(__FILE__)), '../../spec/helpers/create_temporary_dir')
+require "fileutils"
+
+include RobustExcelOle
+
+dir = create_tmpdir
+simple_file = dir + 'another_workbook.xls'
+simple_file2 = dir + 'workbook.xls'
+
+Excel.kill_all
+
+# opening a workbook
+book = Workbook.open(simple_file, :visible => true)
+# accessing the 1st worksheet of this workbook
+sheet = book.sheet(1) 
+# accessing a range consisting of one cell
+range = sheet.range([1,2])
+range2 = sheet.range("B1")
+puts "range: #{range.Value}"
+puts "range2: #{range2.Value}"
+# the ranges are identical
+# putting the values of the range
+puts "range.values: #{range.values}"
+# accessing a rectangular range given rows and columns
+range3 = sheet.range([1..3,1..4])
+range4 = sheet.range([1..3,"A".."D"])
+# accessing the same range given the left top and the right bottum corner
+range5 = sheet.range(["A1:D3"])
+puts "range3: #{range3.Value}"
+puts "range4: #{range4.Value}"
+puts "range5: #{range5.Value}"
+# the ranges are identival
+# putting the values if the range
+puts "range3.values: #{range3.values}"
+# copying a range
+range3.copy([6,2])
+range6 = sheet.range([6..9,2..5])
+puts "range3.Value: #{range3.Value}"
+puts "range6.Value: #{range6.Value}"
+# copying a range into another worksheet in another workbook of another Excel instance
+book2 = Workbook.open(simple_file2, :excel => :new, :visible => true)
+range3.copy([5,8], book2.sheet(3))
+range7 = book2.sheet(3).range([5..8,8..11])
+puts "range3.Value: #{range3.Value}"
+puts "range7.Value: #{range7.Value}"
+# adding a defined name referring to a range consisting of the first cell
+book.add_name("name",[1,1])
+# adding a defined name referring to a rectangular range
+book.add_name("name",[1..2,3..4])
+# assigning a value to that range 
+book["name"] = [["foo", "bar"],[1.0, nil]]
+# reading the value of that range
+value = book["name"]
+puts "value: #{value}" 
+# renaming a range
+book.rename_range("name", "new_name")
+# deleting the name of a range
+book.delete_name("new_name")
+# reading the value of a cell
+cell_value = sheet[1,1].Value
+puts "cell_value: #{cell_value}"
+# writing the value of a cell
+sheet[1,1] = "bar"
+Excel.close_all(:if_unsaved => :forget)