robust_excel_ole 1.2 → 1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 11b718a2903204d3521cdfad3ef539537841dd06
-  data.tar.gz: 07a2911b36560a7f505c17914ed441c3ee2add3c
+  metadata.gz: ffc7730bef4461a766a8be04f470304e77c9a518
+  data.tar.gz: 74fbedab450da21841ac9d3d7663d8199792a80c
 SHA512:
-  metadata.gz: 7086927359fd13e8f573ab33eb7aa81ba8d7f19ffcdf1b42d2a61fdfa02414bcfbeabc6846114a0eebddf30b8f28f5d14682f756222122b404bf237bc784a217
-  data.tar.gz: eb1e7673ba0fbb4402e8fd81669a2f9d80b75f7305044aa8093ca15260d3573178c6e30c79e671e9ed6997b6e1b79bbf30301b86ca78e60124faed430b82c4c2
+  metadata.gz: adb1b208ae94315fc104b310d36c983c7f6e17f5be2d6bc64a42148d3d5cf1bf645f0682806ca930cb4fe48225ff472f358acf6001ed35187bc07322be02b3c4
+  data.tar.gz: 022d0ecaf1fb85517989c217bed5128c9e9bbe462373923aaaa9e5dbaacc3397398eb1bbe1bf2b780a9ee0f401821216e7d69068547ef0779ac61fc93c390797

data/Changelog

@@ -1,6 +1,26 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+## [1.3.1]
+
+### Added
+  - Book#open: option :excel => :reserved_new
+
+## [1.2.2]
+
+### Added
+  - ReoCommon#add_name, rename_range, delete_name
+  - Sheet#range
+  - Range#copy
+
+### Changed:
+  - ReoCommon#namevalue, namevalue_glob, set_namevalue, set_namevalue_glob replace
+    set_namevalue replaces set_rangeval, set_namevalue_glob, respectively
+
+## [1.2.1] 2018-9-2
+
+## [1.2] - 2018-11-8
+
 ## [1.1.6] - 2018-20-7
 
 ### Added

data/README.rdoc

@@ -44,7 +44,10 @@ Let's open a workbook.
 
   workbook = Workbook.open 'spec/data/workbook.xls'
 
-Now we have a Workbook object that wraps a win32ole object. That is, you can send any win32ole (VBA) method to it. For example, you can determine the name and the saved-status of the workbook.
+Now we have a Workbook object that wraps a win32ole object. That is, you can send any win32ole (VBA) method to it. See 
+https://docs.microsoft.com/en-us/office/vba/api/excel.workbook#methods.
+
+For example, you can determine the name and the saved-status of the workbook.
 
   workbook.Name 
   # => "workbook.xls"
@@ -248,6 +251,10 @@ For more details about processing worksheets see {README_sheet}[https://github.c
 
 === Reading and writing ranges in worksheets
 
+We can define a rectangular range by providing the top left and the bottum down cell.
+
+  sheet.range(1..3,1..4)
+
 We can read the first three cells of the first row
 
   sheet.row_range(1, 1..3).values   # => ["foo","workbook","sheet1"]

data/docs/README_excel.rdoc

@@ -6,7 +6,7 @@ RobustExcelOle enables simultanously running Excel instances. An Excel applicati
 
 === Creating and reusing an Excel instance.
 
-You can start a new Excel instance by
+You can create a new Excel instance by
 
   excel1 = Excel.create
 
@@ -30,6 +30,10 @@ You can also promote an Excel instance represented as WIN32OLE object to an Exce
 
   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).
+For some common and complex tasks you can use the methods of RobustExcelOle. 
+
 === Setting options
 
 You can set all options in a given Excel instance
@@ -86,13 +90,11 @@ You can set the calculation mode of an Excel instance to manual or automatic.
 You can do it in a block:
 
   excel = Excel.create
-  book = Workbook.open('workbook.xls')
+  book = Workbook.open('spec/data/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.

data/docs/README_open.rdoc

@@ -4,12 +4,16 @@
 
 If you want to open a workbook, use
   
-  book = Workbook.open('workbook.xls')
+  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
+(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.
 
 You can also open a workbook with a block. 
 The semantics is similar to, e.g.,  +File.open+.
 
-  Workbook.open('workbook.xls') do |book|
+  Workbook.open('spec/data/workbook.xls') do |book|
     # do something
   end
 
@@ -41,7 +45,7 @@ You can use the following abbreviations: +:f+ for  +:force+, +:d+ for +:default+
 
 The option +:excel+ :
 
-Valid values are : +:current+ (or +:active+ or +:reuse+), +:new+, or a given Excel instance (default: +:current).
+Valid values are : +:current+ (or +:active+ or +:reuse+), +:new+, +:reserved_new+, or a given Excel instance (default: +:current).
 
 The option +:if_unsaved+  : 
 
@@ -74,45 +78,49 @@ 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})
+  book = Workbook.open('spec/data/workbook.xls', :default => {:excel => :current})
 
 or
   
-  Workbook.open('workbook.xls')
+  book = Workbook.open('spec/data/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})
+  book = Workbook.open('spec/data/workbook.xls', :default => {:excel => :new})
+
+You can also open the workbook in a separate, reserved Excel instance.
+
+  book = Workbook.open('spec/data/workbook.xls', :default => {:excel => :reserved_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})
+  book = 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.open('workbook.xls', :excel => :new)
+  book = Workbook.open('spec/data/workbook.xls', :excel => :new)
 
 You can also specify an Excel instance
 
   excel1 = Excel.create
-  Workbook.open('workbook.xls', :excel => excel1)
+  book = 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('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.open('workbook.xls', :excel => :new, :visible => true, :default => {:excel => excel1})
+  book = Workbook.open('spec/data/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})  
+  book = Workbook.open('spec/data/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)
+  book = 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_obstructed+ handles this situation, e.g.
 
@@ -128,7 +136,7 @@ Doing updating links seems to be dependent on calculation mode: updates happen,
 
 A special feature of RobustExcelOle is that it allows to reopen workbooks after closing them.
 
-  book = Workbook.open('workbook.xls')
+  book = Workbook.open('spec/data/workbook.xls')
   book.close
   book.reopen
 
@@ -160,7 +168,7 @@ Options are the following:
 +:keep_open+::       Whether the workbook shall be open after unobtrusively opening (default: false)
 
 
-  Workbook.unobtrusively('workbook.xls') do |book|
+  Workbook.unobtrusively('spec/data/workbook.xls') do |book|
     # some modification
     sheet = book[0]
     sheet[1,1] = "c" 
@@ -168,7 +176,7 @@ Options are the following:
   
 The methods +for_reading+ and +for_modifying+ indicate unobtrusively reading or modifying.
 
-  Workbook.for_modifying('workbook.xls') do |book|
+  Workbook.for_modifying('spec/data/workbook.xls') do |book|
     # some modification
     sheet = book[0]
     sheet[1,1] = "c" 
@@ -180,7 +188,7 @@ Remark: The methods +unobtrusively+, +for_reading+ and +for_modifying+ work only
 
 This method ensures keeping the save status of the workbook
 
-  book = Workbook.open('workbook.xls')
+  book = Workbook.open('spec/data/workbook.xls')
   book.retain_saved do
     # some reading or modifying
   end

data/docs/README_ranges.rdoc

@@ -2,27 +2,193 @@
 
 == 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, in VBA.
+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.
+
+=== Introducing Example
+
+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
+
+  sheet.Range(sheet.Cells(1,1))
+
+or using RobustExcelOle
+
+  range = sheet.range(1,1)
+
+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. 
+
+  range = sheet.Range(sheet.Cells(1,1), sheet.Cells(3,4))
+
+In RobustExcelOle we would supply the rows and columns as integer ranges.
+
+  range = sheet.range(1..3,1..4)
+
+You can read the values by 
+
+  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)
+
+or with help of RobustExcelOle
+
+  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))
+
+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
+
+  book.Names.Add("Name" => "name", "RefersToR1C1" => "=Z1S1")
+
+RobustExcelOle provides the method +add_name+.
+
+  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.
+
+  book.Names.Add("Name" => "name", "RefersToR1C1" => "=Z1S3:Z2S4")
+
+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)
+
+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["name"] = "bar"
+
+Similarly, we can read the value of the range, using VBA methods
+
+  book.Names.Item("name").RefersToRange.Value
+  => "bar"
+
+or RobustExcelOle
+
+  book["name"]
+  => "bar" 
+
+Finally we can rename a range, and delete the name of a range. With help of VBA methods this can be achieved by
+
+  book.Names.Item("name").Name = "new_name"
+  book.Names.Item("new_name").Delete
+
+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  
+  => "foo
+
+Similarly, you can write a cell.
+
+  sheet.Cells.Item(1,1).Value = "new_value"
+
+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
+
+  book.add_name("rec_name",1,2,3,4)
+
+We assign values to the cells of that range
+
+  book.Names.Item("rec_name").RefersToRange.Value = 
+      [["foo", nil, "bar"], [nil, "foobar", nil], ["is", "nice", nil]]
+
+or
+
+  book["rec_name"] = [["foo", nil, "bar"], [nil, "foobar", nil], ["is", "nice", nil]]
+
+Now we can read value of that range.
+
+  book.Names.Item("rec_name").RefersToRange.Value
+  => [["workbook", "sheet1", nil], [nil, "foobaaa", nil], ["is", "nice", nil]]
+
+or
+
+  book["rec_name"]
+  => [["workbook", "sheet1", nil], [nil, "foobaaa", nil], ["is", "nice", nil]] 
+
+In the following some details are being summarized. 
+
+=== Accessing a range
+
+You can access a range consisting of one cell by providing the row and and the column of a cell. 
+
+  range = sheet.range(1,1)
+
+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. 
+
+  range = sheet.range(1..3,1..4)
+
+You get the values of the range with
+
+  range.values
+
+=== Copying a range
+
+You can copy and paste a range. 
+
+  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))
+
+=== 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)
+
+Most methods can be done for Workbook, Sheet, and Excel objects.
 
 === 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)
+  book = 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 +nameval+.
+You can get the contents of a range with a defined name with help of the method [] or +namevalue_glob+.
 
   book["name"] 
   => "value"
 
 or
 
-  book.nameval("name")
+  book.namevalue_glob("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.
+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.
 
-  book.namval("name", :default => "default_value")
+  book.namvalue_glob("name", :default => "default_value")
 
 You can set the contents of a range with
 
@@ -30,11 +196,11 @@ You can set the contents of a range with
 
 or
 
-  book.set_nameval("name", "new_value")
+  book.set_namevalue_glob("name", "new_value")
 
-The method []= colors the written cell. You can specify the color of a changed range via the method +set_nameval+. 
+The method []= colors the written cell. You can specify the color of a changed range via the method +set_namevalue_glob+. 
   
-  book.set_nameval("name", "new_value", :color => 4)
+  book.set_namevalue_glob("name", "new_value", :color => 4)
 
 Similarly, the contents of a named range can be read and modified in a worksheet
 
@@ -60,31 +226,31 @@ When saving, the written cells get discolored when using the option :discoloring
 
 or
 
-  book.save_as('workbook.xls', :discoloring => true)
+  book.save_as('spec/data/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 by
 
-  sheet.rangeval("name")
+  sheet.namevalue("name")
   => "value"
 
 or
 
-  excel.rangeval("name")
+  excel.namevalue("name")
   => "value" 
 
 and be modified by
 
-  sheet.set_rangeval("name", "value")
+  sheet.set_namevalue("name", "value")
 
 or
 
-  excel.set_rangeval("name", "value")
+  excel.set_namevalue("name", "value")
 
-Similarly to nameval, you can provide a default value that is returned when ocurring an error.
+Similarly to namevalue, you can provide a default value that is returned when ocurring an error.
 
-  sheet.rangeval("name", :default => "default_value")
+  sheet.namevalue("name", :default => "default_value")
 
 === Accessing a cell
 
@@ -106,7 +272,6 @@ or
 
   sheet.set_cellval(1,1,"new_value", :color => 42)
 
-
 === Accessing rows and columns
 
 The methods Sheet#each, Sheet#each_row and Sheet#each_column enable to access each cell, row and column, respectively.
@@ -139,8 +304,3 @@ 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")