robust_excel_ole 1.13 → 1.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f76aadd233f6dd4c2f5d568d54ef10c6c030762544906a3357c7f04464e24846
-  data.tar.gz: 68101beb84d01cd1b2da24c4568a833d5b6d641c5829b3b7e1da793c651a1aa3
+  metadata.gz: b63b8ec97e714c16c5b4e3f1bb60f7e160aba0469ad14d47b766fa1778919c1f
+  data.tar.gz: 1e0af619c00875ae92782cfa25a091335de3e1235723be9c2ecef2924b4f3cf9
 SHA512:
-  metadata.gz: 8b79a216b5460efd0b51ff81c335e53c37d8c7530185838f88e7befc0eacbd686338d7578ffee7db399795427c0983abc091a2c673230e126d01ff335e1cb80f
-  data.tar.gz: 55c8c0bb5a58d2574bf2938333e551e91402e7eb75eb40bc380fc3eee998766aa693f7e4eb5f615ad21f2c9882376259c900b813541547f47b0f3d071121cc10
+  metadata.gz: 54d8101340e7a2c82af0a761998a466a931df0dc5eaf0bd5117a513f89ebf3e38fa6e27dd04af909f0d8cf8125117b126c8df7d642843c993862f6af2966afbd
+  data.tar.gz: 9f92d1018a35b7d018b7b3c3f7f3bb71383b7cb3914429a7986fe097a3ea9e8ac7ae77c011adff4075d4b56946c08ae8d9fdb9c69a51abb65b6109ea4f66cd00

data/Changelog

@@ -1,6 +1,16 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+## [1.14]
+
+### Changed
+   - Workbook.unobtrusively: removed parameter :rw_change_excel
+   
+
+## [1.13]
+
+  - no interface change
+
 ## [1.12]
 
 ### Added
@@ -8,9 +18,10 @@ All notable changes to this project will be documented in this file.
    - Workbook#color_if_modified
 
 ### Changed:
-   - Workbook#save, save_as: no parameter +discoloring
+   - Workbook#save, save_as: removed parameter :discoloring
    - RangeOwners#set_namevalue, set_namevalue_glob, Worksheet#set_cellval: 
-     no optional parameter for color 
+     removed optional parameter for color 
+   - Workbook#open: removed option :excel => :reserved_new  
 
 
 ## [1.11]
@@ -23,7 +34,6 @@ All notable changes to this project will be documented in this file.
 ## [1.10]
 
 ### Added
-  - workarounds for running in Jruby
   - Range,Cell#v
 
 ## [1.9]
@@ -74,7 +84,7 @@ All notable changes to this project will be documented in this file.
   - 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.1] 2018-9-12
 
 ## [1.2] - 2018-11-8
 

data/README.rdoc

@@ -44,11 +44,7 @@ and go into the path of the gem 'robust_excel_ole'. There you start the console
 
   reo
 
-or
-
-  jreo
-
-depending on whether you are using ruby or jruby.
+If you don't want to use a version manager to switch between ruby and jruby, you can apply the command +reo+ when using ruby, and +jreo+ when using jruby.
 
 The call of the console will include RobustExcelOle for you.
 
@@ -62,10 +58,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. See 
+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 visible status of the workbook.
+For example, you can determine the name and whether the workbook is visible.
 
   workbook.Name 
   # => "workbook.xls"
@@ -79,7 +75,7 @@ First we want to make the workbook visible.
 
   workbook.visible = true
 
-This method makes both the Excel instance and the window of the Workbook-win32ole-object visible.
+This method makes both the Excel instance and the window of the Workbook WIN32OLE object visible.
 
 Let's read the value of a named cell.
 
@@ -94,22 +90,14 @@ Then we'll save the workbook.
 
   workbook.save
 
-Finally we want to close the workbook.
-
-  workbook.close
-
-One special feature of RobustExcelOle is that it enables reopening workbooks.
-
-  workbook.reopen
-
-The workbook is now open again and ready for applying further operations, e.g.
-
-  workbook['firstcell'] = "another_value"
-  workbook.save
-  workbook.close
+=== More features when opening, modifying, creating, saving and closing workbooks
 
 RobustExcelOle allows unobtrusively reading and modifying workbooks, i.e. accessing workbooks without changing their "status". The status comprises whether the workbook is open or closed, saved or unsaved, read-only or writable, visible or invisible, whether the calculation mode is manual or automatic, and checking compatibility is done or not done (the Workbook object remembers its properties).
 
+  Workbook.unobtrusively('spec/data/workbook.xls') do |workbook|
+    # do something
+  end
+
   Workbook.for_modifying('spec/data/workbook.xls') do |workbook|
     # do something
   end
@@ -122,9 +110,7 @@ You can also create a new, empty workbook.
 
   Workbook.create('spec/data/new_workbook.xls', :visible => true)
 
-=== More features when opening, modifying, creating saving and closing workbooks
-
-We can open the workbook using a block, similar to, e.g., +File.open+. 
+Moreover, you can open the workbook using a block, similar to, e.g., +File.open+. 
 
   Workbook.open('spec/data/workbook.xls') do |workbook|
     # do something
@@ -142,7 +128,7 @@ or, using abbreviations,
 
   workbook = Workbook.open('spec/data/workbook.xls', :v => true)
 
-Note that Workbook.open can also connect to workbooks which were not opened via RobustExcelOle (but had been opened before by some user).
+Note that +Workbook.open+ can also connect to workbooks which were not opened via RobustExcelOle (but had been opened before by some user).
 
 For more details about opening workbooks see {README_open}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_open.rdoc]
  
@@ -154,7 +140,11 @@ or save the workbook under a different name.
 
   workbook.save_as('spec/data/new_workbook.xls')
 
-Finally we can save and close the workbook in one step.
+Finally we can close the workbook
+
+  workbook.save
+
+or save and close the workbook in one step.
 
   workbook.close(:if_unsaved => :save)
 
@@ -196,7 +186,8 @@ For hard terminating all Excel processes we can use
 
   Excel.kill_all
 
-For more details about creating Excel instances see README_excel[https://github.com/Thomas008/robust_excel_ole/blob/master/README/README_excel_rdoc]
+For more details about opening Excel instances see {README_excel}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_excel.rdoc]
+
 
 === Opening workbooks in several Excel instances
 
@@ -213,12 +204,12 @@ Now we want to open another workbook in a different Excel instance.
 We can also create a third Excel instance and open another workbook in this instance.
 
   excel1 = Excel.create
-  book3 = Workbook.open('spec/data/another_workbook.xls', :excel => excel1)
+  workbook3 = Workbook.open('spec/data/another_workbook.xls', :excel => excel1)
 
 A workbook is opened by default in the Excel instance where it was open before most recently.
 
-   book1.close
-   book1 = Workbook.open('spec/data/workbook.xls') 
+   workbook1.close
+   workbook1 = Workbook.open('spec/data/workbook.xls') 
 
 If this Excel instance is damaged or closed, then options control whether the workbook shall be opened in the current (active), a new or a given Excel instance.
 
@@ -252,22 +243,22 @@ Assume we have opened a workbook
 
 We access the first worksheet by
 
-  sheet = workbook.sheet(1)
+  worksheet = workbook.sheet(1)
 
 or 
 
-  sheet = workbook.sheet('Sheet1')
+  worksheet = workbook.sheet('Sheet1')
 
 or
   
-  sheet = workbook.first_sheet
+  worksheet = workbook.first_sheet
 
 We can read and change the worksheet name.
 
-  sheet.name
+  worksheet.name
   # => "Sheet1"
 
-  sheet.name = "new_sheet"
+  worksheet.name = "new_sheet"
 
 We can copy the first worksheet, name it and add it before the third worksheet.
 
@@ -279,35 +270,35 @@ 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])
+  worksheet.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"]
+  worksheet.row_range(1, 1..3).values   # => ["foo","workbook","sheet1"]
 
 and the third column
 
-  sheet.col_range(3).values   # => ["sheet1", 2.0, 4.0]
+  worksheet.col_range(3).values   # => ["sheet1", 2.0, 4.0]
 
 We can read the first cell, using
 
-  sheet[1,1].value    # => "foo"
+  worksheet[1,1].value    # => "foo"
 
 or
 
-  sheet.row_range(1)[0].value    # => "foo"
+  worksheet.row_range(1)[0].value    # => "foo"
 
 Then we modify it.
 
-  sheet[1,1] = "hello"
+  worksheet[1,1] = "hello"
 
 We get the value of a named range 
 
-  sheet["firstcell"]    # => "hello"
+  worksheet["firstcell"]    # => "hello"
 
 and set another value to that range.
 
-  sheet["firstcell"] = "new_value"
+  worksheet["firstcell"] = "new_value"
 
 For more details about reading and writing contents of cells and ranges see {README_ranges}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_ranges.rdoc]
 

data/docs/README_excel.rdoc

@@ -110,7 +110,7 @@ You can yield an array of all Workbook objects of an Excel instance.
 
 You can access all Workbook objects by using the methods Excel#each_workbook and Excel#each_workbook_with_index. Here are some examples:
   
-  excel.each_workook {|w| puts w.filename}
+  excel.each_workbook {|w| puts w.filename}
 
 and
 
@@ -146,7 +146,7 @@ Closed Excel instances can also be reopened. This includes reopening all workboo
   excel.close
   excel.recreate
 
-The options are :reopen_workbooks, :visible and :displayalerts.
+The options are +:reopen_workbooks+, +:visible+ and +:displayalerts+.
 
   excel.recreate(:reopen_workbooks => true, :visible => true, :displayalerts => true)
 

data/docs/README_open.rdoc

@@ -2,9 +2,9 @@
 
 === Opening a workbook.
 
-If you want to open a workbook, use
+If you want to open a workbook, you can use the methods +open+ or +new+.
   
-  book = Workbook.open('spec/data/workbook.xls')
+  workbook = Workbook.open('spec/data/workbook.xls')
 
 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).
@@ -46,7 +46,7 @@ You can use the following abbreviations or synonyms: +:f+ for  +:force+, +:d+ fo
 
 The option +:excel+ :
 
-Valid values are : +:current+ (or +:active+ or +:reuse+), +:new+, +:reserved_new+, or a given Excel instance (default: +:current).
+Valid values are : +:current+ (or +:active+ or +:reuse+), +:new+, or a given Excel instance (default: +:current).
 
 The option +:if_unsaved+  : 
 
@@ -80,32 +80,28 @@ 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
 
-  book = Workbook.open('spec/data/workbook.xls', :default => {:excel => :current})
+  workbook = Workbook.open('spec/data/workbook.xls', :default => {:excel => :current})
 
 or
   
-  book = Workbook.open('spec/data/workbook.xls')
+  workbook = Workbook.open('spec/data/workbook.xls')
 
 In case you want to open such a workbook in a new Excel instance, then use
 
-  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})
+  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
 
-  book = 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).
 
-  book = 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
-  book = 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
 
@@ -114,22 +110,24 @@ If you want to open the workbook and make its window visible, then use
 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. 
 
-  book = Workbook.open('spec/data/workbook.xls', :excel => :new, :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
 
-  book = Workbook.open('spec/data/workbook.xls', :e => :new, :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
 
-  book = 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.
 
-  book = Workbook.open('path/workbook.xls', :if_blocked => :forget)
+  workbook = Workbook.open('path/workbook.xls', :if_blocked => :forget)
 
 Remarks:
 
+The methods +open+ and +new+ connect to workbooks opened outside of RobustExcelOle as well.
+
 Opening linked workbooks for EXCEL 2007 is supported
 
 Doing updating links seems to be dependent on calculation mode: updates happen, if the calcultion mode is automatic, and does not happen, if calculation mode is manual.
@@ -138,23 +136,42 @@ 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('spec/data/workbook.xls')
-  book.close
-  book.reopen
+  workbook = Workbook.open('spec/data/workbook.xls')
+  workbook.close
+  workbook.reopen
 
 The closed workbook is now alive again, i.e. is open and responds to Excel methods.
 
-Technically, this feature is implemented in such way, that a Workbook object is a proxy of an Excel workbook. A Workbook object is defined by the full workbook name and the Excel instance in which it is opened. RobustExcelOle ensures identity transparency which means that the same Workbook objects refer to the same workbooks, and vice versa.
+=== Promoting WIN32OLE objects to RobustExcelOle objects
+
+Promoting means here: enriching a given object of a certain class by properties and methods of another class. 
+The method +General.to_reo+ enables promoting WIN32OLE objects to RobustExcelOle objects such that the attributes and methods of RobustExcelOle can be applied to these objects. For example, assume we have a WIN32OLE workbook +win32ole_workbook+:
+
+  win32ole_workbook.to_class
+  => WIN32OLE
+
+This object can be promoted to a RobustExcelOle workbook.
+
+  workbook = win32ole_workbook.to_reo
+  workbook.to_class
+  => RobustExcelOle::Workbook
+
+Similarly, Excel, Worksheet, and Range WIN32OLE objects can be promoted to corresponding RobustExcelOle objects. 
+
+The method +to_reo+ uses the method +new+. You can apply the method +new+ directly.
+
+  workbook = Workbook.new(win32ole_workbook)
+
+You can supply options, e.g. +:visible+.
 
-=== Promoting a workbook to a Workbook object
+   workbook = Workbook.new(win32ole_workbook, :visible => true) 
 
-A Workbook object can be created when giving an Excel workbook.
 
-   book = Workbook.new(win32ole_workbook)
+=== Identity transperence ===
 
-Note that only a restricted number of options can be considered, e.g. +:visible+
+A RobustExcelOle Workbook object is a proxy of an Excel WIN32OLE workbook. A Workbook object is defined by the full workbook name and the Excel instance in which it is opened. RobustExcelOle ensures identity transparency which means that identical Workbook objects refer to identical Excel workbooks, and vice versa. Identity transperence ensures that, no matter how a Workbook object was created - by filename or by promoting an Excel workbook - two Workbook objects are identical, if and only if the Excel workbooks, they are referring to, are identical. 
 
-   book = Workbook.new(win32ole_workbook, :visible => true)
+Similarly, each Excel, Worksheet and a Range object in RobustExcelOle is a proxy of a corresponding Excel, Worksheet and a Range object in WIN32OLE. For these objects identity transperence holds as well.
 
 === Unobtrusively modifying a workbook
 
@@ -176,26 +193,26 @@ Options are the following:
 
   Workbook.unobtrusively('spec/data/workbook.xls') do |book|
     # some modification
-    sheet = book[0]
-    sheet[1,1] = "c" 
+    worksheet = book[0]
+    worksheet[1,1] = "c" 
   end
   
 The methods +for_reading+ and +for_modifying+ indicate unobtrusively reading or modifying.
 
   Workbook.for_modifying('spec/data/workbook.xls') do |book|
     # some modification
-    sheet = book[0]
-    sheet[1,1] = "c" 
+    worksheet = book[0]
+    worksheet[1,1] = "c" 
   end
 
-Note, that the methods +unobtrusively+, +for_reading+ and +for_modifying+ work not only for workbooks opened via RobustExcelOle, but do also connect to workbooks opened outside RobustExcelOle.
+Note, that the methods +unobtrusively+, +for_reading+ and +for_modifying+ work not only for workbooks opened via RobustExcelOle, but connect to workbooks opened outside RobustExcelOle as well.
 
 === Retaining the saved-status
 
 This method ensures keeping the save status of the workbook
 
-  book = Workbook.open('spec/data/workbook.xls')
-  book.retain_saved do
+  workbook = Workbook.open('spec/data/workbook.xls')
+  workbook.retain_saved do
     # some reading or modifying
   end
 
@@ -203,7 +220,7 @@ This method ensures keeping the save status of the workbook
 
 This method finds out whether the Excel workbook that is referenced by the Workbook object responds to methods.
 
-  book.alive?
+  workbook.alive?
   # => true
 
 == Code

data/docs/README_ranges.rdoc

@@ -8,39 +8,39 @@ RobustExcelOle enables to read and write the contents of ranges and cells in wor
 
 Suppose you have opened a workbook.
 
-  book = Workbook.open('spec/data/workbook.xls', :visible => true)
+  workbook = Workbook.open('spec/data/workbook.xls', :visible => true)
 
 We access the first worksheet:
   
-  sheet = book.sheet(1)
+  worksheet = workbook.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,2))
+  worksheet.Range(sheet.Cells(1,2))
 
 or using RobustExcelOle
 
-  range = sheet.range([1,2])
+  range = worksheet.range([1,2])
 
 or, using the A1-format,
 
-  range = sheet.range("B1")
+  range = worksheet.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. 
 
-  range = sheet.Range(sheet.Cells(1,1), sheet.Cells(3,4))
+  range = worksheet.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])
+  range = worksheet.range([1..3,1..4])
 
 or, using the A1-format
 
-  range = sheet.range([1..3,"A".."D"])
+  range = worksheet.range([1..3,"A".."D"])
 
 or
 
-  range = sheet.range(["A1:D3"])
+  range = worksheet.range(["A1:D3"])
 
 You can read the values by 
 
@@ -75,72 +75,72 @@ or with help of RobustExcelOle
 
 You can also copy a range into another worksheet in another workbook.
 
-  book2 = 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
 
-  book.Names.Add("Name" => "name", "RefersToR1C1" => "=Z1S1")
+  workbook.Names.Add("Name" => "name", "RefersToR1C1" => "=Z1S1")
 
 RobustExcelOle provides the method +add_name+.
 
-  book.add_name("name",[1,1])
+  workbook.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")
+  workbook.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.
+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])
+  workbook.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 = [["foo", "bar"],[1.0, nil]]
+  workbook.Names.Item("name").RefersToRange.Value = [["foo", "bar"],[1.0, nil]]
 
 Now we can read value of that range.
 
-  book.Names.Item("rec_name").RefersToRange.Value
+  workbook.Names.Item("rec_name").RefersToRange.Value
   => [["foo", "bar"],[1.0, nil]]
 
 or
 
-  book["name"]
+  workbook["name"]
   => [["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
 
-  book.Names.Item("name").Name = "new_name"
-  book.Names.Item("new_name").Delete
+  workbook.Names.Item("name").Name = "new_name"
+  workbook.Names.Item("new_name").Delete
 
 Using RobustExcelOle, we write
 
-  book.rename_range("name", "new_name")
-  book.delete_name("name")
+  workbook.rename_range("name", "new_name")
+  workbook.delete_name("name")
 
 Now we can read the value of cell simply by providing the row and the column
 
-  sheet.Cells.Item(1,1).Value
+  worksheet.Cells.Item(1,1).Value
 
 or with RobustExcelOle
 
-  sheet[1,1].Value  
+  worksheet[1,1].Value  
   => "foo
 
 or
 
-  sheet[1,1].v
+  worksheet[1,1].v
   => "foo"
 
 Similarly, you can write a cell.
 
-  sheet.Cells.Item(1,1).Value = "new_value"
+  worksheet.Cells.Item(1,1).Value = "new_value"
 
 or using RobustExcelOle
 
-  sheet[1,1] = "new_value"
+  worksheet[1,1] = "new_value"
 
- In the following some details are being summarized. 
+In the following some details are being summarized. 
 
 === Accessing a range
 
@@ -148,51 +148,51 @@ You can access a range via its address or defined name. RobustExcelOle allows th
 
 For example, 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])
+  range = worksheet.range([1,1])
 
 Using the A1-format and R1C1-format you write
 
-  range = sheet.range("A1") 
+  range = worksheet.range("A1") 
 
 and
 
-  range = sheet.range("Z1S1")
+  range = worksheet.range("Z1S1")
 
 respectively.
 
 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])
+  range = worksheet.range([1..3,1..4])
 
 or using the A1-format.
 
-  range = sheet.range([1..3,"A".."D"])
+  range = worksheet.range([1..3,"A".."D"])
 
 or
 
-  range = sheet.range("A1:D3")
+  range = worksheet.range("A1:D3")
 
 or using the R1C1-format
 
-  range = sheet.range("Z1S1:Z3S4")
+  range = worksheet.range("Z1S1:Z3S4")
 
 Infinite ranges are defined, e.g., by setting the rows or columns to +nil+
 
-  range = sheet.range([1..3,nil])
-  range = sheet.range([nil,"A".."B"])
+  range = worksheet.range([1..3,nil])
+  range = worksheet.range([nil,"A".."B"])
 
 Using the A1-format you write
 
-  range = sheet.range("1:3")
-  range = sheet.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 = sheet.range("Z[1]S1:Z3S[4]")
+  range = worksheet.range("Z[1]S1:Z3S[4]")
 
 or
 
-  range = sheet.range([[1]..3,2..[4]])
+  range = worksheet.range([[1]..3,2..[4]])
 
 You get the values of the range as flat array with help of
 
@@ -200,17 +200,17 @@ You get the values of the range as flat array with help of
 
 You can access a range via its defined name with
 
-  range = sheet.range("name")
+  range = worksheet.range("name")
 
 === Copying a range
 
 Let's assume, you have a source range
 
-  range = sheet.range(1..2,3..5)
+  range = worksheet.range(1..2,3..5)
 
 or, in A1-format,
 
-  range = sheet.range("C1:E2")
+  range = worksheet.range("C1:E2")
 
 To copy it to the destination range (3..4,6..8), you can use 
 
@@ -234,47 +234,47 @@ Note that when you don't copy the values only but all formating as well, and you
 
 You can (re-) define a name referring to a range by stating its name, and the address. The address is given by integer-range-format, r1c1-format or a1-format. For example, you can define a name for a rectangular range by
 
-  book.add_name("name",[1..2,3..5])
+  workbook.add_name("name",[1..2,3..5])
 
 or
 
-  book.add_name("name","Z1S3:Z2S5")
+  workbook.add_name("name","Z1S3:Z2S5")
 
 or
 
-  book.add_name("name", "C1:E2")
+  workbook.add_name("name", "C1:E2")
 
 Similarly you can define a name referring to a cell
 
-  book.add_name("name",[1,1])
+  workbook.add_name("name",[1,1])
 
 or
 
-  book.add_name("name","Z1S1")
+  workbook.add_name("name","Z1S1")
 
 or
 
-  book.add_name("name","A1")
+  workbook.add_name("name","A1")
 
 and infinite ranges
 
-  book.add_name("name",[1..2,nil])
+  workbook.add_name("name",[1..2,nil])
 
 or
 
-  book.add_name("name", "Z1:Z2")
+  workbook.add_name("name", "Z1:Z2")
 
 or
 
-  book.add_name("name","1:2")
+  workbook.add_name("name","1:2")
 
 Furthermore, you can define a name using relative references with the r1c1-format.
 
-  book.add_name("name", "Z1S[1]:Z[2]S4")
+  workbook.add_name("name", "Z1S[1]:Z[2]S4")
 
 or
 
-  book.add_name("name", [1..[2],[1]..4])
+  workbook.add_name("name", [1..[2],[1]..4])
 
 You can do the same for an worksheet or Excel object.
 
@@ -282,43 +282,43 @@ You can do the same for an worksheet or Excel object.
 
 Assume you have opened a workbook:
  
-  book = 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+.
 
-  book["name"] 
+  workbook["name"] 
   => "value"
 
 or
 
-  book.namevalue_glob("name")
+  workbook.namevalue_glob("name")
   => "value"
 
 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.namvalue_glob("name", :default => "default_value")
+  workbook.namvalue_glob("name", :default => "default_value")
 
 You can set the contents of a range with
 
-  book["name"] = "new_value"
+  workbook["name"] = "new_value"
 
 or
 
-  book.set_namevalue_glob("name", "new_value")
+  workbook.set_namevalue_glob("name", "new_value")
 
 The method []= colors the written cell, if you have specified the color of the changed range via the method Workbook#color before, e.g.
 
-  book.color_if_modified = 4
-  book["name"] = "new_value"
+  workbook.color_if_modified = 4
+  workbook["name"] = "new_value"
 
 Similarly, the contents of a named range can be read and modified in a worksheet
 
-  sheet = book.sheet(1)
+  worksheet = workbook.sheet(1)
 
-  sheet["name"]
+  worksheet["name"]
   => value
 
-  sheet["name"] = "new_value" 
+  worksheet["name"] = "new_value" 
 
 or an Application object.
 
@@ -334,7 +334,7 @@ or an Application object.
 
 The contents of locally defined ranges can be read by
 
-  sheet.namevalue("name")
+  worksheet.namevalue("name")
   => "value"
 
 or
@@ -344,7 +344,7 @@ or
 
 and be modified by
 
-  sheet.set_namevalue("name", "value")
+  worksheet.set_namevalue("name", "value")
 
 or
 
@@ -352,54 +352,54 @@ or
 
 Similarly to namevalue, you can provide a default value that is returned when ocurring an error.
 
-  sheet.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):
 
-  sheet[1,1].Value  
+  worksheet[1,1].Value  
   => "foo
 
 or
 
-  sheet.cellval(1,1)
+  worksheet.cellval(1,1)
   => "foo"
 
 Similarly, you can write a cell.
 
-  sheet[1,1] = "new_value"
+  worksheet[1,1] = "new_value"
 
 or
 
-  sheet.set_cellval(1,1,"new_value")
+  worksheet.set_cellval(1,1,"new_value")
 
 === Accessing rows and columns
 
 The methods Worksheet#each, Worksheet#each_row and Worksheet#each_column enable to access each cell, row and column, respectively.
 
-  sheet.each do |cell|
+  worksheet.each do |cell|
     # do something with cell
     # read every row, every column
   end
 
-  sheet.each_row do |row|
+  worksheet.each_row do |row|
     # do something with row
   end
 
-  sheet.each_column do |column|
+  worksheet.each_column do |column|
     # do something with column
   end
 
 You access a range of a row by giving the number of the row, and optionally, the range of the cell numbers.
 
-  sheet.row_range(1)  # => first row
-  sheet.row_range(1, 1..3 )  # => first three cells of the first row  
+  worksheet.row_range(1)  # => first row
+  worksheet.row_range(1, 1..3 )  # => first three cells of the first row  
 
 Simarly you can access a range of a column.
 
-  sheet.col_range(3)  # => third column
-  sheet.col_range(3, 1..2)  # => first two cells of the third column
+  worksheet.col_range(3)  # => third column
+  worksheet.col_range(3, 1..2)  # => first two cells of the third column
 
 Within a row or column range you can access a certain cell.