robust_excel_ole 1.11 → 1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 344c336ba61c5f1b98839047f69cbbac1ddef451291fa32260c47218421d78cc
-  data.tar.gz: 169a63ca7cb3d582443aa046228797cc946e9f47f45e97019b21504f8a897384
+  metadata.gz: b568d18d573ee255b9c3601e983c3d7b1ff062fe50b97dc10bc1e9a79efb1556
+  data.tar.gz: 3f87e8db112deb8e414f77b2d5756158a79b135413ba6a1116d7b7abf68c710f
 SHA512:
-  metadata.gz: dc9e189d01012805dd02d668c833e96b9597997b518a2b9ce6beb671969e007d8cae5d362a045fbd439a4368cf7ddfdfee66b535d60e9b4e9c68db7a99023989
-  data.tar.gz: 1e04fa12bc2e5956fb0efa68a92b185557b8180909da820517ab55affd3bf8154d297aa9a2b0eaa8e8a161fc31972560ea74f5beefa2fc51225f45b392c122fc
+  metadata.gz: e3ba0806cf0f4c0fec0ae85eee158fe5b9422d901f9172ad4eb274a1118eaf7dc61a7e47cd0f5d276bacd40e0506b4d7531bbcd4d93334bfe1dc1242a3f803db
+  data.tar.gz: eb1ee24dcb77a5d7b84715b56352b43b7df7f3e2f64130761e911313b0cca921f2c8ca7a1ae3f64ef84e6c4933b21dc81097b759ed99abed64549b7ac26c56e2

data/Changelog

@@ -1,6 +1,17 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+## [1.12]
+
+### Added
+   - Workbook.open: option :if_unsaved => :save
+   - Workbook#color_if_modified
+
+### Changed:
+   - Workbook#save, save_as: no parameter +discoloring
+   - RangeOwners#set_namevalue, set_namevalue_glob, Worksheet#set_cellval: 
+     no optional parameter for color 
+
 
 ## [1.11]
 

data/README.rdoc

@@ -1,11 +1,19 @@
 = RobustExcelOle
 
-This library automates reading, modifying, and writing Excel workbooks. It is designed to support several kinds of concurrency of both simultaneously running Excel instances and simultanously happening user interactions.
-RobustExcelOle deals with various cases of Excel and user behaviour,
-and implements workarounds for some Excel bugs.
-The gem provides convenient methods for common tasks, and facilitates referenced libraries.
+RobustExcelOle helps controlling Excel. 
+This obviously includes standard tasks like reading and writing Excel workbooks.
+The gem is designed to manage simultaneously running Excel instances, even with simultanously happening user interactions. 
+
+RobustExcelOle deals with various cases of Excel (and user) behaviour, and
+supplies workarounds for some Excel and JRuby bugs. 
+
+It supports handling workbooks across Excel instances by keeping track of workbooks and instances. Conflicts are managed before Excel notices.
+
+Library references are supported.
+
+RobustExcelOle works by sending VBA methods via Win32OLE. 
+Therefore, it runs on Windows only.
 
-RobustExcelOle works by sending VBA methods via Win32OLE. It keeps track of Excel workbooks and Excel instances.
 
 == Requirements
 
@@ -226,7 +234,9 @@ Without the option +:default+, the workbook can be forced to be opened in the cu
 
   workbook2 = Workbook.open('spec/data/workbook.xls', :excel => excel1)
 
-As a further feature, RobustExcelOle allows processing workbooks, while still supporting user's interactions: The commands enable to open, close, reopen, read, modify, write and save Excel workbooks, without the need of the user's interaction, and even without the user noticing. Thus, while running a script containing RobustExcelOle commands, the user can open and process workbooks in any Excel instances at any time. RobustExcelOle manages the complex cases of conflicts that might occur such that the user does not need to interfere and the script can continue.
+=== Managing conflicts with unsaved and blocking workbooks
+
+RobustExcelOle enables processing workbooks, while still supporting user's interactions: The commands enable to open, close, reopen, read, modify, write and save Excel workbooks, without the need of the user's interaction, and even without the user noticing. Thus, while running a script containing RobustExcelOle commands, the user can open and process workbooks in any Excel instances at any time. RobustExcelOle manages the complex cases of conflicts that might occur such that the user does not need to interfere and the script can continue.
 
 For example, suppose we want to process a list of workbooks. RobustExcelOle allows to rapidly open, manipulate, close and save these workbooks. Now assume, the workbook "workbook.xls" is being processed, while the user has already opened this workbook, has modified but not saved it yet. Excel would prompt a message and ask the user what to do. RobustExcelOle solves this conflict by using an option that states whether the changes of the user should be saved (accepted) or discarded (forgotten) before opening the workbook, e.g.
 
@@ -309,11 +319,13 @@ For more details about reading and writing contents of cells and ranges see {REA
 
 === Running in jruby
 
-RobustExcelOle runs in jruby as well. You can call the console via the command +jreo+. However, note that, due to some restrictions of the library jruby-win32ole, there are some restrictions. So we had implemented some adaptions and workarounds. Some issues still remain when running under jruby:
+RobustExcelOle runs in jruby as well. You can call the console via the command +jreo+. We implemented workarounds to cope with some restrictions of the library jruby-win32ole. Some issues still remain when running under jruby. So you might consider the following points when running RobustExcelOle under jruby:
 
-1. Excel.current or Excel.new(:reuse => true) does not connect to an already running Excel instance, unless some workbook has been opened via RobustExcelOle. 2. Excel.kill_all does work, Excel.close_all does not work. 3. When providing an absolute path, you have to state the "/" ("C:/abc.xls" works, "C:abc" does not work).
+1. +Excel.current+ or +Excel.new(:reuse => true)+ does not connect to an already running Excel instance, unless some workbook has been opened via RobustExcelOle. 
 
+2. Use +Excel.kill_all+ instead of +Excel.close_all+. +Excel.close_all does not work yet. It relies on stepping through all heap objects in ObjectSpace. In jruby ObjectSpace is disabled. Each_object will only work with Class.
 
+3. When providing an absolute path, you have to state the "/" ("C:/abc.xls" works, "C:abc" does not work).
 
 === More things
 

data/docs/README_open.rdoc

@@ -55,6 +55,7 @@ If a workbook contains unsaved changes and a new workbook with the same file nam
 +:raise+::   Raise an exeption. Don't open the workbook.
 +:accept+::  Let the unsaved workbook open.
 +:forget+::  Discard any changes and reopen the workbook.
++:save+::    Save any changes and reopen the workbook
 +:new_excel+:: Open the new workbook in a new Excel instance
 +:alert+::   Give control to Excel.
 

data/docs/README_ranges.rdoc

@@ -306,9 +306,10 @@ or
 
   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_namevalue_glob+. 
-  
-  book.set_namevalue_glob("name", "new_value", :color => 4)
+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"
 
 Similarly, the contents of a named range can be read and modified in a worksheet
 
@@ -328,13 +329,6 @@ or an Application object.
 
   excel["name"] = "new_value"
 
-When saving, the written cells get discolored when using the option :discoloring
-
-  book.save(:discoloring => true)
-
-or
-
-  book.save_as('spec/data/workbook.xls', :discoloring => true)
 
 === Reading and writing the contents of a range with a locally defined name
 
@@ -378,7 +372,7 @@ Similarly, you can write a cell.
 
 or
 
-  sheet.set_cellval(1,1,"new_value", :color => 42)
+  sheet.set_cellval(1,1,"new_value")
 
 === Accessing rows and columns
 

data/examples/{introducing_examples/example_introducing.rb → introductory_examples/example_introductory.rb}

@@ -1,7 +1,7 @@
 # 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_relative '../../lib/robust_excel_ole'
+require_relative '../../spec/helpers/create_temporary_dir'
 require "fileutils"
 
 include RobustExcelOle
@@ -13,6 +13,8 @@ Excel.kill_all
 
 # Let's open a workbook.
 workbook = Workbook.open simple_file
+# make it visible
+workbook.visible = true
 # put name of the workbook
 puts "name: #{workbook.Name}"
 value = workbook['firstcell']
@@ -20,23 +22,29 @@ puts "value: #{value}"
 # assigning a new value
 workbook['firstcell'] = "new"
 # saving the workbook
+puts "save the workbook"
 workbook.save
 # closing the workbook
+puts "close the workbook"
 workbook.close
 # reopening the workbook
+puts "reopen the workbook"
 workbook.reopen
 # further operations
 workbook['firstcell'] = "another_value"
 # saved status of the workbook
 puts "saved: #{workbook.Saved}"
 # unobtrusively reading a workbook
+puts "unobtrusively reading the workbook"
 Workbook.for_reading(simple_file) do |workbook|
   puts "value of first cell: #{workbook['firstcell']}"
 end
 puts "saved: #{workbook.Saved}"
 # unobtrusively modifying a workbook
+puts "unobtrusively modifying the workbook"
 Workbook.for_modifying(simple_file) do |workbook|
   workbook['firstcell'] = "bar"
 end
 puts "saved: #{workbook.Saved}"
 puts "value of first cell: #{workbook['firstcell']}"
+Excel.kill_all

data/examples/{introducing_examples → introductory_examples}/example_open.rb

@@ -1,7 +1,7 @@
 # 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_relative '../../lib/robust_excel_ole'
+require_relative '../../spec/helpers/create_temporary_dir'
 require "fileutils"
 
 include RobustExcelOle
@@ -14,36 +14,37 @@ another_simple_file = dir + 'another_workbook.xls'
 Excel.kill_all
 
 # open a workbook
+puts "open a workbook"
 book = Workbook.open(simple_file) 
+puts "make it visible"
+book.visible = true
 puts "book: #{book}"
 # open a workbook in a new Excel instance
-book2 = Workbook.open(another_simple_file, :default => {:excel => :new})
+puts "open the workbook in a new Excel instance and make it visible"
+book2 = Workbook.open(another_simple_file, :default => {:excel => :new}, :visible => true)
 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}"
+puts "create a new Excel"
+excel1 = Excel.create(:visible => true)
 # open the workbook in a given Excel instance
+puts "open the workbook in a given Excel instance"
 excel1 = book.excel
-book5 = Workbook.open(another_simple_file, :force => {:excel => excel1})
-puts "book5: #{book5}"
+book3 = Workbook.open(another_simple_file, :force => {:excel => excel1})
+puts "book3: #{book3}"
 # close a workbook
+puts "close the first workbook"
 book.close
-puts "close book -> book: #{book}"
 # reopen the workbook
-book6 = book.reopen
-puts "reopened book: book6: #{book6}"
+puts "reopen the workbook"
+book4 = book.reopen
+puts "book4: #{book4}"
 # unobtrusively opening a workbook
+puts "unobtrusively opening the 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
+Excel.kill_all
   

data/examples/{introducing_examples → introductory_examples}/example_range.rb

@@ -1,7 +1,7 @@
 # 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_relative '../../lib/robust_excel_ole'
+require_relative '../../spec/helpers/create_temporary_dir'
 require "fileutils"
 
 include RobustExcelOle
@@ -13,14 +13,17 @@ simple_file2 = dir + 'workbook.xls'
 Excel.kill_all
 
 # opening a workbook
+puts "opening a workbook:"
 book = Workbook.open(simple_file, :visible => true)
 # accessing the 1st worksheet of this workbook
+puts "accessing 1st worksheet"
 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}"
+puts "cell [1,2]: #{range.Value}"
+puts "B1: #{range2.Value}"
+puts "the ranges are identical"
 # the ranges are identical
 # putting the values of the range
 puts "range.values: #{range.values}"
@@ -29,39 +32,49 @@ 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
+puts 'range([1..3,1..4]): #{range3.Value}'
+puts 'range([1..3,"A".."D"]): #{range4.Value}'
+puts 'range(["A1:D3"]): #{range5.Value}'
+puts "the ranges are identical"
+# the ranges are identical
 # putting the values if the range
-puts "range3.values: #{range3.values}"
+puts "range([1..3,1..4]).values: #{range3.values}"
 # copying a range
+puts "copying the range[1..3,1..4] to cell [6,2]"
 range3.copy([6,2])
 range6 = sheet.range([6..9,2..5])
-puts "range3.Value: #{range3.Value}"
-puts "range6.Value: #{range6.Value}"
+puts "range([1..3,1..4]).Value: #{range3.Value}"
+puts "range([6..9,2..5]).Value: #{range6.Value}"
 # copying a range into another worksheet in another workbook of another Excel instance
+puts "copying a range into another worksheet in another workbook of another Excel instance"
+puts "opening a new workbook in a new 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}"
+puts "range([1..3,1..4]).Value: #{range3.Value}"
+puts "new_book.sheet(3).range([5..8,8..11]).Value: #{range7.Value}"
 # adding a defined name referring to a range consisting of the first cell
+puts "adding a defined name 'name' referring to a range consisting of the 1st cell:"
 book.add_name("name",[1,1])
 # adding a defined name referring to a rectangular range
+puts "adding a defined name 'name' referring to a rectangular range [1..2,3..4]:"
 book.add_name("name",[1..2,3..4])
 # assigning a value to that range 
+puts "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}" 
+puts 'value of range "name": #{value}'
 # renaming a range
+puts 'renaming range from "name" to "new_name"'
 book.rename_range("name", "new_name")
 # deleting the name of a range
+puts 'deleting name "new_name"'
 book.delete_name("new_name")
 # reading the value of a cell
 cell_value = sheet[1,1].Value
-puts "cell_value: #{cell_value}"
+puts "value of 1st cell: #{cell_value}"
 # writing the value of a cell
+puts 'writing the value "bar" into 1st cell'
 sheet[1,1] = "bar"
-Excel.close_all(:if_unsaved => :forget)
+Excel.kill_all

data/examples/modifying_sheets/example_access_sheets_and_cells.rb

@@ -1,8 +1,8 @@
 # example_access_sheets_and_cells.rb: 
 # access sheets, print cells, rows, and columns of a sheet
 
-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_relative '../../lib/robust_excel_ole'
+require_relative '../../spec/helpers/create_temporary_dir'
 require "fileutils"
 
 include RobustExcelOle
@@ -13,7 +13,7 @@ begin
   simple_file = dir + 'workbook.xls'
   simple_save_file = dir + 'workbook_save.xls'
   File.delete simple_save_file rescue nil
-  book = Workbook.open(simple_file)      # open a book
+  book = Workbook.open(simple_file, :visible => true)      # open a book
   sheet = book.sheet(1)                    # access a sheet via integer 
   cell = sheet[1,1]                  # access the first cell
   puts "1st cell: #{cell.Value}"     # put the value of the first cell
@@ -34,7 +34,7 @@ begin
         when :each_row    then "row"
         when :each_column then "column"
         end 
-      puts "#{item_name} #{i}: #{item.Value}" # put values of the item of the sheet
+      puts "#{item_name} #{i}: #{item.Value}" # put values of the item of the worksheet
     end
   end
 
@@ -42,11 +42,12 @@ begin
   sheet_enum[:each_row]    # put rows
   sheet_enum[:each_column] # put columns
 
-  book.save                # save the book
-  book.close               # close the book
+  book.save                # save the workbook
+  book.close               # close the workbook
   
 ensure
-  Excel.close_all(:if_unsaved => :forget)
+  #Excel.close_all(:if_unsaved => :forget)
+  Excel.kill_all
   rm_tmp(dir)
 end
 

data/examples/modifying_sheets/example_add_names.rb

@@ -3,8 +3,8 @@
 # the contents of each cell is copied
 # the new workbook's name is extended by the suffix "_named"
 
-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_relative '../../lib/robust_excel_ole'
+require_relative '../../spec/helpers/create_temporary_dir'
 require "fileutils"
 
 include RobustExcelOle
@@ -17,15 +17,13 @@ begin
   filename = dir + "/" + workbook_name
   puts "filename: #{filename}"
 
-  Excel.close_all if_unsaved: :forget
+  #Excel.close_all if_unsaved: :forget
+  Excel.kill_all
   book = Workbook.new filename, if_absent: :create, visible: true, if_unsaved: :accept
   sheet = book.sheet(1)
   puts "book: #{book}"
   puts "sheet: #{sheet}"
 
-  # book.Names.Add("µ",  RefersToR1C1Local:"=Z")
-  # book.Names.Add("µ_1", RefersToR1C1Local:"=Z(-1)")
-
   def define_columns sheet, columns_ids
     puts "define_columns:"
     first_column = sheet.range("A")
@@ -43,8 +41,6 @@ begin
       puts "sheet[1,colnr]: #{sheet[1,colnr].Value}"
       sheet.add_name(nam,[nil,colnr])
       puts "sheet.Range().Address: #{sheet.Range(nam).Address}"
-      #sheet.add_name(nam,"A")
-      # blatt.Names.Add(Name: nam, RefersTo: "="+erste_spalte.Offset(0,idx).Address)
     end
   end
 

data/examples/modifying_sheets/example_adding_sheets.rb

@@ -1,8 +1,8 @@
 # example_adding_sheets.rb: 
 # adding new and copied at various positions with various sheet names
 
-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_relative '../../lib/robust_excel_ole'
+require_relative '../../spec/helpers/create_temporary_dir'
 require "fileutils"
 
 include RobustExcelOle
@@ -13,11 +13,11 @@ begin
   simple_file = dir + 'workbook.xls'
   simple_save_file = dir + 'workbook_save.xls'
   File.delete simple_save_file rescue nil
-  @book = Workbook.open(simple_file)      # open a book
+  @book = Workbook.open(simple_file, :visible => true)      # open a workbook
 
   def show_sheets 
-    @book.each do |sheet|               # access each sheet
-      puts "sheet name: #{sheet.name}" #  put the sheet name
+    @book.each do |sheet|               # access each worksheet
+      puts "sheet name: #{sheet.name}" #  put the worksheet name
     end
   end
 
@@ -63,7 +63,8 @@ begin
   @book.close(:if_unsaved => :forget)   # close the book without saving it
   
 ensure
-  Excel.close_all(:if_unsaved => :forget)
+  Excel.kill_all
+  #Excel.close_all(:if_unsaved => :forget)
   rm_tmp(dir)
 end