robust_excel_ole 1.0.3 → 1.1

data/Changelog

@@ -1,6 +1,10 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
+## [1.1] - 2017-09-29
+
+## [1.0.4] - 2017-08-30
+
 ## [1.0.3] - 2017-08-27
 
 ## [1.0.2] - 2017-07-26

data/README.rdoc

@@ -1,6 +1,6 @@
 = RobustExcelOle
 
-This ruby gem automates modifying, reading and writing Excel files.
+This ruby gem automates reading, modifying, and writing Excel files.
 It supports simultaneously running Excel instances and user interactions.
 RobustExcelOle deals with various cases of Excel and user behaviour,
 and implements workarounds for some Excel bugs.
@@ -9,7 +9,7 @@ It supports Excel 2010.
 
 RobustExcelOle works by sending VBA methods via Win32OLE.
 Moreover, it implements a management system and keeps track of Excel files and Excel instances.
-The tool is optimised with help of rcov.
+The tool is optimised with help of the rcov tool.
 
 == Requirements
 
@@ -28,40 +28,71 @@ The tool is optimised with help of rcov.
 
 In the following, some features of RobustExcelOle are depicted.
 
-RobustExcelOle allows a "script mode" and an "interactive mode": Commands enable to open Excel files (or workbooks) in various Excel instances, enable to close, reopen, modify and save the Excel files, without the need of the user's interaction, and even without the user noticing. While running this script mode, the user can open and modify any Excel files 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.
+RobustExcelOle enables opening and processing Excel files (or workbooks) in several Excel instances. Using more than one Excel process allows, e.g., running a script that operates in one Excel instance, while a user (or another script) modifies workbooks in another Excel instance. 
 
-For example, suppose you want to process a list of workbooks (Excel files). RobustExcelOle allows to rapidly open, manipulate, close and save these workbooks (script mode). Now assume, the workbook "workbook.xls" is being processed, while the user has opened this workbook, has manipulated but not saved it yet. Excel would prompt a message and ask the user what to do. RobustExcelOle solves this conflict by using several options that state whether the changes of the user should be saved (accepted) or discarded before opening the workbook. 
+For example, suppose you want to open a workbook and make it visible.
 
-  book1 = Book.open('workbook.xls')  # user
-    ...
-  book2 = Book.open('workbook.xls', :if_unsaved => accept) # script
+  book1 = Book.open('workbook.xls', :visible => true)
+
+Now we want to open another workbook in a different Excel instance.
+
+  book2 = Book.open('workbook2.xls', :force => {:excel => :new}, :visible => true)
+
+We can also create a third Excel instance and open another workbook in this instance.
+
+  excel1 = Excel.create
+  book3 = Book.open('workbook3.xls', :force => {:excel => excel1}, :visible => true)
+
+Another feature that RobustExcelOle povides is reopening workbooks after closing them.
+
+  book1.close
+  book1.reopen
+
+A workbook is opened by default in the Excel instance where it was open before most recently.
+
+   book1.close
+   book1 = Book.open('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.
+
+  book1 = Book.open('workbook.xls', :default => {:excel => :new})
 
-Similarly, if the user has opened a workbook that has the same name but a different path, the conflict is solved via options.
+The workbook can also be forced to be opened in the current, new or given Excel instance, no matter if and where it was opened before, e.g.
+
+  book2 = Book.open('workbook.xls', :force => {: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 files, 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 Excel files 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 you 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 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 before opening the workbook:
+
+  book = Book.open('workbook.xls', :if_unsaved => :accept)
+
+Similarly, if the user has opened a workbook that has the same name but a different path, the conflict is solved via an option.
 
   book1 = Book.open('path1/workbook.xls')
     ...
   book2 = Book.open('workbook.xls', :if_obstructed => :forget)
 
-Another feature that RobustExcelOle povides is reopening workbooks after closing them. A workbook is opened by default in the Excel instance where it was open before most recently. If this Excel instance is damaged or closed, then RobustExcelIle controls via options whether the workbook is opened in the current (active) Excel instance, a new or a given Excel instance, e.g.
+There are twelve options that control opening workbooks. 
 
-  book1 = Book.open('workbook.xls', :default => {:excel => :new})
-
-Moreover, 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, calculation mode is manual or automatic, and checking compatibility is done or not done. 
+Finally, 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. 
 
   Book.for_modifying('workbook.xls') do |book|
-    ...
+    # do something
   end
 
   Book.for_reading('workbook.xls') do |book|
-    ...
+    # do something
   end
 
-=== The Book objects and transperence identity
+=== The Book objects and identity transparency
 
-An Excel file (or workbook) is represented by a Book object. A Book object is defined by the full name of the workbook and the Excel instance in which it is opened. RobustExcelOle aims to ensure identity transperency.
-Identity transparence means that the same Book objects refer to the same Excel files, and vice versa.
+An Excel file (or workbook) is represented by a Book object. A Book object is defined by the full name of the workbook and the Excel instance in which it is opened. RobustExcelOle aims to ensure identity transparency.
+Identity transparency means that the same Book objects refer to the same Excel files, and vice versa.
 In other words, a Book objects is a proxy of an Excel file.
 
+Here are some more details about opening, closing, reading, writing and modifying Excel files.
+
 === Opening and closing workbooks
 
 Let's have a look at an example. Suppose, we want to open a workbook.
@@ -98,7 +129,7 @@ Reopening this workbook is done by
 
   book2.reopen
 
-=== Modifying workbooks
+=== Reading and modifying workbooks
 
 We can get the value of a named range.
 
@@ -116,7 +147,7 @@ or
 
   book2.set_nameval("new", "bar")
 
-Now we access the first worksheet by
+Then we access the first worksheet by
 
   sheet1 = book2.sheet(1)
 
@@ -156,7 +187,7 @@ and set the value
 
   sheet1.set_nameval("firstcell", "foo")
 
-We get the value of a range of a locally defined name. 
+We get the value of a range of a locally defined name.
 
   sheet1.rangeval("firstcell")     # => "foo"
 
@@ -172,7 +203,7 @@ We can copy the first worksheet, name it and add it before the third worksheet.
 
   book2.add_or_copy_sheet(sheet1, :as => "copied_name, :before => book2.last_sheet)
 
-=== Saving workbooks
+=== Saving (writing) workbooks
 
 Simple save is done by
 
@@ -200,7 +231,6 @@ or
 
   excel1 = Excel.new(:reuse => true)  
 
-
 Now we want to start a new, visible Excel instance.
 
   excel2 = Excel.create(:visible => true)
@@ -213,7 +243,7 @@ We open a workbook in this Excel instance.
 
   book4 = Book.open('more_data/workbook', {:force => {:excel => excel2}})
 
-We can close Closing an Excel instance is dony by
+We close the Excel instance by
 
   excel1.close
 
@@ -245,7 +275,7 @@ and set its value by
 
   excel2.set_rangeval("firstcell, "bar")
 
-Closing all Excel instances ist done by
+Closing all Excel instances is done by
 
   Excel.close_all(:if_unsaved => :forget)
 
@@ -255,7 +285,7 @@ Hard terminating all Excel processes is done by
 
 === More details
 
-{Readme_detail.rdoc}[file:../Readme_detail.rdoc]
+{README_detail.rdoc}[https://github.com/Thomas008/robust_excel_ole/blob/master/README_detail.rdoc]
 
 === Want to do more things
 

data/README_detail.rdoc

@@ -219,6 +219,24 @@ If a workbook blocks the workbook that should be saved, then the former one can
   book2 = Book.open('another_workbook.xls')
   book2.save_as('dir/workbook.xls', :if_exists => :overwrite, :if_obstructed => :save)  
 
+=== Opening, closing and saving a workbook under a certain name
+
+You can open a workbook with given file name.
+
+  book = Book.open('workbook.xls')
+
+You can save a workbook with given file name, if it is open.
+
+  Book.save('workbook.xls')
+
+The workbook can be saved under a new file name, if it is open.
+
+  Book.save_as('workbook.xls', 'new_workbook.xls')
+
+Finally the workbook can be closed with a given filename.
+
+  Book.close('workbook.xls')
+
 === Unobtrusively modifying a workbook
 
 The method +unobtrusively+ enables the user to read or modify a workbook, no matter if it is open in some Excel instance, if it is saved or unsaved, and if it is writable or not. When opening a workbook unobtrusively, its status remains unchanged. This status includes, whether the workbook is opened or closed, saved or unsaved, readonly or writable, visible or invisible, calculation mode is automatic or manual, and checking compatibility is turned on or off. 

data/lib/robust_excel_ole/book.rb

@@ -328,12 +328,8 @@ module RobustExcelOle
           filename = General::absolute_path(file)
           begin
             workbooks = @excel.Workbooks
-          rescue RuntimeError => msg
-            if msg.message =~ /method missing: Excel not alive/
-              raise ExcelDamaged, "Excel instance not alive or damaged" 
-            else
-              raise UnexpectedError, "unknown RuntimeError: #{msg.message}"
-            end
+          rescue WIN32OLERuntimeError => msg
+            raise UnexpectedError, "WIN32OLERuntimeError: #{msg.message} #{msg.backtrace}"
           end
           begin
             with_workaround_linked_workbooks_excel2007(options) do
@@ -343,15 +339,14 @@ module RobustExcelOle
           rescue WIN32OLERuntimeError => msg
             # for Excel2007: for option :if_unsaved => :alert and user cancels: this error appears?
             # if yes: distinguish these events
-            #raise
-            # trace "WIN32OLERuntimeError: #{msg.message}" 
+            raise UnexpectedError, "WIN32OLERuntimeError: #{msg.message} #{msg.backtrace}"
           end
           begin
             # workaround for bug in Excel 2010: workbook.Open does not always return the workbook when given file name
             begin
               @ole_workbook = workbooks.Item(File.basename(filename))
             rescue WIN32OLERuntimeError => msg
-              raise UnexpectedError, "unexpected WIN32OLERuntimeError: #{msg.message}"
+              raise UnexpectedError, "WIN32OLERuntimeError: #{msg.message}"
             end
             if options[:force][:visible].nil? && (not options[:default][:visible].nil?)
               if @excel.created   
@@ -366,7 +361,7 @@ module RobustExcelOle
             @excel.calculation = options[:calculation] unless options[:calculation].nil?
             self.Saved = true # unless self.Saved # ToDo: this is too hard
           rescue WIN32OLERuntimeError => msg
-            raise UnexpectedError, "unexpected WIN32OLERuntimeError: #{msg.message} #{msg.backtrace}"
+            raise UnexpectedError, "WIN32OLERuntimeError: #{msg.message} #{msg.backtrace}"
           end       
         end
       end
@@ -556,7 +551,7 @@ module RobustExcelOle
         if msg.message =~ /SaveAs/ and msg.message =~ /Workbook/ then
           raise WorkbookNotSaved, "workbook not saved"
         else
-          raise UnexpectedError, "unknown WIN32OELERuntimeError:\n#{msg.message}"
+          raise UnexpectedError, "unknown WIN32OLERuntimeError:\n#{msg.message}"
         end       
       end
       true
@@ -656,6 +651,24 @@ module RobustExcelOle
 
   public
 
+    # closes a given file if it is open
+    def self.close(file, opts = {:if_unsaved => :raise})
+      book = bookstore.fetch(file) rescue nil
+      book.close(opts) if book && book.alive?
+    end
+
+    # saves a given file if it is open
+    def self.save(file)
+      book = bookstore.fetch(file) rescue nil
+      book.save if book && book.alive?
+    end
+
+    # saves a given file under a new name if it is open
+    def self.save_as(file, new_file, opts = { })
+      book = bookstore.fetch(file) rescue nil
+      book.save_as(new_file, opts) if book && book.alive?
+    end
+
     # returns a sheet, if a sheet name or a number is given
     # @param [String] or [Number]
     # @returns [Sheet]

data/lib/robust_excel_ole/excel.rb

@@ -350,7 +350,7 @@ module RobustExcelOle
           #trace $!.backtrace.first(9).join "\n"
         end
       end
-      trace "went through #{anz_objekte} OLE objects"
+      #trace "went through #{anz_objekte} OLE objects"
     end   
 
 
@@ -361,12 +361,13 @@ module RobustExcelOle
     # kill all Excel instances
     # @return [Fixnum] number of killed Excel processes
     def self.kill_all
-      procs = WIN32OLE.connect("winmgmts:\\\\.")
-      processes = procs.InstancesOf("win32_process")
-      number = processes.select{|p| (p.name == "EXCEL.EXE")}.size
-      procs.InstancesOf("win32_process").each do |p|
+      number = 0
+      WIN32OLE.connect("winmgmts:\\\\.").InstancesOf("win32_process").each do |p|
         begin
-          Process.kill('KILL', p.processid) if p.name == "EXCEL.EXE"        
+          if p.name == "EXCEL.EXE"  
+            Process.kill('KILL', p.processid)       
+            number += 1
+          end
         rescue 
            #trace "kill error: #{$!}"
         end
@@ -376,7 +377,8 @@ module RobustExcelOle
     end
 
     def self.excels_number
-      WIN32OLE.connect("winmgmts:\\\\.").InstancesOf("win32_process").select{|p| (p.name == "EXCEL.EXE")}.size
+      processes = WIN32OLE.connect("winmgmts:\\\\.").InstancesOf("win32_process")
+      processes.select{ |p| p.name == "EXCEL.EXE"}.size
     end
 
     # provide Excel objects 
@@ -394,8 +396,10 @@ module RobustExcelOle
           pid2excel[pid] = excel
         end
       end
-      procs = WIN32OLE.connect("winmgmts:\\\\.")
-      processes = procs.InstancesOf("win32_process")     
+      processes = WIN32OLE.connect("winmgmts:\\\\.").InstancesOf("win32_process")
+      #excel_processes = processes.select{ |p| p.name == "EXCEL.EXE" && pid2excel.include?(p.processid)}
+      #excel_processes.map{ |p| Excel.new(pid2excel[p.processid]) }
+      processes.select{ |p| Excel.new(pid2excel[p.processid]) if p.name == "EXCEL.EXE" && pid2excel.include?(p.processid)}
       result = []
       processes.each do |p|
         if p.name == "EXCEL.EXE"
@@ -486,7 +490,7 @@ module RobustExcelOle
             raise FileNotFound, "could not save workbook with filename #{file_name.inspect}"
           else
             # todo some time: find out when this occurs : 
-            raise UnexpectedError, "unknown WIN32OELERuntimeError with filename #{file_name.inspect}: \n#{msg.message}"
+            raise UnexpectedError, "unknown WIN32OLERuntimeError with filename #{file_name.inspect}: \n#{msg.message}"
           end
         end      
       end
@@ -730,5 +734,9 @@ module RobustExcelOle
       end
     end
 
-  end  
+  end
 end
+
+class WIN32OLE
+  include Enumerable
+end  

data/lib/robust_excel_ole/general.rb

@@ -1,4 +1,4 @@
-include Enumerable
+# -*- coding: utf-8 -*-
 
 module General
 
@@ -118,5 +118,4 @@ module MethodHelpers
 
 end
 
-#REO = General
-REO = RobustExcelOle
+REO = RobustExcelOle

data/lib/robust_excel_ole/reo_common.rb

@@ -1,3 +1,5 @@
+# -*- coding: utf-8 -*-
+
 LOG_TO_STDOUT = true     unless Object.const_defined?(:LOG_TO_STDOUT)
 REO_LOG_DIR   = "" unless Object.const_defined?(:REO_LOG_DIR)
 REO_LOG_FILE  = "reo.log" unless Object.const_defined?(:REO_LOG_FILE)

data/lib/robust_excel_ole/version.rb

@@ -1,3 +1,3 @@
 module RobustExcelOle
-  VERSION = "1.0.3"
+  VERSION = "1.1"
 end

data/spec/book_spec.rb

@@ -29,6 +29,7 @@ describe Book do
     @simple_file_xlsx = @dir + '/workbook.xlsx'
     @simple_file1 = @simple_file
     @simple_file_other_path1 = @simple_file_other_path
+    @simple_save_file1 = @simple_save_file
   end
 
   after do
@@ -48,6 +49,89 @@ describe Book do
     end
   end
 
+  describe "Book::save" do
+
+    it "should save a file, if it is open" do
+      @book = Book.open(@simple_file)
+      @book.add_sheet(@sheet, :as => 'a_name')
+      @new_sheet_count = @book.ole_workbook.Worksheets.Count
+      expect {
+        Book.save(@simple_file)
+      }.to_not raise_error
+      @book.ole_workbook.Worksheets.Count.should ==  @new_sheet_count
+      @book.close
+    end
+
+    it "should not save a file, if it is not open" do
+      @book = Book.open(@simple_file)
+      @book.add_sheet(@sheet, :as => 'a_name')
+      @new_sheet_count = @book.ole_workbook.Worksheets.Count
+      @book.close(:if_unsaved => :forget)
+      expect {
+        Book.save(@simple_file)
+      }.to_not raise_error
+    end
+
+  end
+
+  describe "Book::save_as" do
+    
+    it "should save to 'simple_save_file.xls'" do
+      book = Book.open(@simple_file1)
+      Book.save_as(@simple_file1, @simple_save_file1, :if_exists => :overwrite)
+      File.exist?(@simple_save_file1).should be_true
+    end
+  end
+
+  describe "Book::close" do
+
+    it "should close the book if it is open" do
+      book = Book.open(@simple_file1)
+      Book.close(@simple_file1)
+      book.should_not be_alive
+    end
+
+    it "should not close the book if it is not open" do
+      book = Book.open(@simple_file1, :visible => true)
+      book.close
+      Book.close(@simple_file1)
+      book.should_not be_alive
+    end
+
+    it "should raise error if the book is unsaved and open" do
+      book = Book.open(@simple_file1)
+      sheet = book.sheet(1)
+      book.add_sheet(sheet, :as => 'a_name')
+      expect{
+        Book.close(@simple_file1)
+      }.to raise_error(WorkbookNotSaved, /workbook is unsaved: "workbook.xls"/)
+      expect{
+        Book.close(@simple_file, :if_unsaved => :raise)
+      }.to raise_error(WorkbookNotSaved, /workbook is unsaved: "workbook.xls"/)
+    end
+
+    it "should save and close the book" do
+      book = Book.open(@simple_file1)
+      sheet_count = book.ole_workbook.Worksheets.Count
+      sheet = book.sheet(1)
+      book.add_sheet(sheet, :as => 'a_name')
+      ole_workbook = book.ole_workbook
+      excel = book.excel
+      excel.Workbooks.Count.should == 1
+      Book.close(@simple_file1, {:if_unsaved => :save})
+      excel.Workbooks.Count.should == 0
+      book.ole_workbook.should == nil
+      book.should_not be_alive
+      expect{ole_workbook.Name}.to raise_error(WIN32OLERuntimeError)
+      new_book = Book.open(@simple_file1)
+      begin
+        new_book.ole_workbook.Worksheets.Count.should == sheet_count + 1
+      ensure
+        new_book.close
+      end
+    end
+  end
+
   describe "open" do
 
     context "with various file formats" do

data/spec/excel_spec.rb

@@ -1568,6 +1568,12 @@ module RobustExcelOle
         excel.close
       end
 
+      it "should return list of two Excel processes" do
+        excel1 = Excel.create
+        excel2 = Excel.create
+        Excel.excel_processes.should == [excel1,excel2]
+      end
+
       it "should return list of two Excel processes" do
         excel1 = Excel.new
         excel2 = Excel.current
@@ -1575,6 +1581,8 @@ module RobustExcelOle
         Excel.excel_processes.should == [excel1,excel3]
       end
 
+
+
     end
 
     context "with hwnd and hwnd2excel" do

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: robust_excel_ole
 version: !ruby/object:Gem::Version 
-  hash: 17
+  hash: 13
   prerelease: false
   segments: 
   - 1
-  - 0
-  - 3
-  version: 1.0.3
+  - 1
+  version: "1.1"
 platform: ruby
 authors: 
 - traths
@@ -15,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2017-08-27 00:00:00 +02:00
+date: 2017-10-02 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency