robust_excel_ole 0.2.0 → 0.2.0.5

data/.gitignore

@@ -6,3 +6,4 @@ vendor/bundle
 *~
 .DS_Store
 doc/*
+*.sublime-workspace

data/README.rdoc

@@ -3,6 +3,7 @@
 This is a simple fork from tomiacannondale's wrap_excel adapted to Ruby 1.8.6.
 The functionality of wrap_excel is optimised and extended by new features.
 
+This is work in progress.
 
 == Description
 
@@ -18,91 +19,101 @@ RobustExcelOle wraps the win32ole, and uses the Excel operations with ruby.
   gem install robust_excel_ole
 
 == Usage
-=== access book
 
-Read with block.
+=== open a book
+
+Open a book.
+
+book = RobustExcelOle::Book.open('./sample.xls')
+
+Open a book with a block.
 
   RobustExcelOle::Book.open('./sample.xls') do |book|
     # do something
   end
 
-Read without block.
+Options are the following:
 
-  book = RobustExcelOle::Book.open('./sample.xls')
-  book.close
+[:reuse]         boolean (default true)  use an already open Excel-application 
+[:read_only]     boolean (default false) open in read-only mode  
+[:displayalerts] boolean (default false) allow display alerts in Excel   
+[:visible]       boolean (default false) make visibe in Excel                  
+[:if_unsaved]    :raise (default), :accept, :forget, :new_app, :excel
+                 if an unsaved book with the same name is open
+          
+:raise 
 
-Options are the following.
+Raise an exception. Don't open the book.
 
-[read_only] boolean(default true)
-[displayalerts] boolean(default false)
-[visible] boolean(default false)
+:accept  
 
-=== access sheet
+Let the unsaved book open.                  
+                 
+:forget  
 
-Sheet object can access with Book#[] method.
+Close the unsaved book, open the new book.
 
-  sheet = book[0]
+:new_app 
 
-Access with sheet name.
+Open the new book in a new Excel application.
 
-    book['Sheet1']
+:excel   
 
-=== access row or column
+Give control to Excel.
 
-Sheet object is included enumerable. Use Sheet#each_column or Sheet#each_row or Sheet#each method.
 
-  sheet.each do |cell|
-    # do something with cell
-    # read every row every column
-  end
+[:if_unsaved_other_book]  :raise (default), :save, :forget, :new_app
+                          if an unsaved book with same name in a different path is open,
+                 
+:raise 
 
-  sheet.each_row do |row|
-    # do something with row_range
-  end
+Raise an exception. Don't open the book.
 
-  sheet.each_column do |column_range|
-    # do something with column_range
-  end
+:save    
 
-=== access cell
+Save and close the unsaved book and open the new book.
 
-Read from sheet object.
+:forget  
 
-  sheet[0, 0]  => first cell.
+Close the unsaved book, open the new book
+                
+:new_app 
 
-Read from range object
+Open the new book in a new Excel application
 
-  row_range[0]  => first cell in row_range
-  column_range[1] => second cell in column_range
 
-=== write excel
+Examples:
 
-Can save an existing file.
+Open a book.
 
-Saves a file, if no file with the same name exists.
+book = RobustExcelOle::Book.open('./sample.xls')
 
-Proceeds acocording to the options, otherwise.
+Open another book in the same Excel application.
 
-  RobustExcelOle::Book.open('./sample.xls', :read_only => false) do |book|
-    # do something
-    book.save '.\sample.xls'
-  end
+new_book = RobustExcelOle::Book.open('./different.xls')
 
-or
+Open another book in a new Excel applications.
 
-  book = RobustExcelOle::Book.open('./sample.xls', :read_only => false)
-  book.save '.\sample.xls'
-  book.close
+new_book = RobustExcelOle::Book.open('./different.xls', :reuse => false)
 
-Can save with an another file name.
+Change the book (see below).
 
-  RobustExcelOle::Book.open('./sample.xls', :read_only => false) do |book|
-    # do something  
-    book.save './another_file.xls'
-  end
+sheet = book[0]
+book.add_sheet(sheet, :as => 'copyed_name')
+
+Let the unsaved book open, when open a book while a book with the same name is unsaved and open.
+
+new_book = RobustExcelOle::Book.open('./sample.xls', :if_unsaved => accept)
+
+=== save a book
+
+Save a book.
 
+book.save
 
-Save to another_file.xls.
+Save a book with a file name.
+
+book.save_as('./another_sample.xls')
 
 Options are the following:
 
@@ -118,22 +129,119 @@ Give the control to Excel.
 
 :raise
 
-Throw an exception. Don't write the file.
+Raise an exception. Don't write the file.
 
 Example:
 
- RobustExcelOle::Book.open('./sample.xls', :read_only => false) do |book|
-    # do something
-    book.save('./another_file.xls', :if_exists => :overwrite)
+Overwrite a book with the same name.
+
+book.save('./another_sample.xls', :if_exists => :overwrite)  
+
+=== == (equal)
+
+Check whether two books are identical.
+
+Example.
+
+if (book == new_book) then
+  puts "the books are identical"
+end
+
+=== alive?
+
+Check whether the book is alive.
+
+book.alive?
+
+Example.
+
+if book.alive? then 
+  puts "the book is alive"
+end
+
+=== filename
+
+Get the file name of the book.
+
+book.filename
+
+=== close a book
+
+Close a book
+
+book.close
+
+Options are the following:
+
+[:if_unsaved]  :raise (default), :save, :forget, :excel  
+               if the book is unsaved
+                 
+:raise 
+
+Raise an exception. Don't close the book                  
+                 
+:save            
+
+Save the book before closing it.                  
+                 
+:forget          
+
+Close the book. 
+    
+:excel           
+
+Give control to Excel
+
+
+
+=== access sheet
+
+A sheet object can be accessed with a Book#[] method.
+
+  sheet = book[0]
+
+Access a sheet object with the sheet name.
+
+    book['Sheet1']
+
+=== access row or column
+
+A sheet object is enumerable. Use the methods Sheet#each_column, Sheet#each_row or Sheet#each.
+
+  sheet.each do |cell|
+    # do something with cell
+    # read every row every column
+  end
+
+  sheet.each_row do |row|
+    # do something with row_range
+  end
+
+  sheet.each_column do |column_range|
+    # do something with column_range
   end
 
+=== access cell
+
+Read a cell from a sheet object.
+
+  sheet[0, 0]  => first cell.
+
+Read a cell from a range object.
+
+  row_range[0]  => first cell in row_range
+  column_range[1] => second cell in column_range
+
+
+
 === Want to do more things
 
-All RobustExcelOle object include win32ole instance. If you want to do something that not provide a function, you can use win32ole methods.
+All RobustExcelOle objects include the win32ole instance. 
+If you want to do something that not provide a function, you can use win32ole methods.
 
 == Support
 
-Report issues and feature requests to github Issues. https://github.com/Thomas008/robust_excel_ole/issues
+This is work in progress. Please don't hesitate to contact us and to report issues and feature requests to github Issues. https://github.com/Thomas008/robust_excel_ole/issues
 
 == Collaborate
 
@@ -141,7 +249,7 @@ Please pull request on github.
 
 == Author
 
-thomas mailto:traths@cs.uni-potsdam.de
+thomas mailto:Thomas.Raths@gmx.net
 
 == License
 

data/lib/robust_excel_ole/book.rb

@@ -45,7 +45,7 @@ module RobustExcelOle
       if not File.exist?(file)
         raise ExcelErrorOpen, "file #{file} not found"
       end
-      @excel_app = ExcelApp.new(excel_app_options)
+      @excel_app = ExcelApp.new(excel_app_options)     # :nodoc:
       workbooks = @excel_app.Workbooks
       @workbook = workbooks.Item(File.basename(file)) rescue nil
       if @workbook then
@@ -78,8 +78,8 @@ module RobustExcelOle
             when :forget
               @workbook.Close
             when :excel
-              old_displayalerts = @excel_app.DisplayAlerts
-              @excel_app.DisplayAlerts = true 
+              old_displayalerts = @excel_app.DisplayAlerts  # :nodoc:
+              @excel_app.DisplayAlerts = true  # :nodoc:
             when :new_app
               @options[:reuse] = false
               @excel_app = ExcelApp.new(@options)
@@ -102,7 +102,7 @@ module RobustExcelOle
         end
       ensure
         if @options[:if_unsaved] == :excel then
-          @excel_app.DisplayAlerts = old_displayalerts
+          @excel_app.DisplayAlerts = old_displayalerts  # :nodoc:
         end
       end
       if block
@@ -137,8 +137,8 @@ module RobustExcelOle
         when :forget
           #nothing
         when :excel
-          old_displayalerts = @excel_app.DisplayAlerts
-          @excel_app.DisplayAlerts = true 
+          old_displayalerts = @excel_app.DisplayAlerts  # :nodoc:
+          @excel_app.DisplayAlerts = true  # :nodoc:
         else
           raise ExcelErrorClose, ":if_unsaved: invalid option"
         end
@@ -149,7 +149,7 @@ module RobustExcelOle
         raise ExcelUserCanceled, "close: canceled by user" if alive? && @options[:if_unsaved] == :excel && (not @workbook.Saved)
       ensure
         if @options[:if_unsaved] == :excel then
-          @excel_app.DisplayAlerts = old_displayalerts
+          @excel_app.DisplayAlerts = old_displayalerts  # :nodoc:  
         end
       end
       #@excel_app.Workbooks.Close
@@ -218,8 +218,8 @@ module RobustExcelOle
           File.delete(file) 
           #File.delete(absolute_path(File.join(dirname, basename)))
         when :excel 
-          old_displayalerts = @excel_app.DisplayAlerts
-          @excel_app.DisplayAlerts = true 
+          old_displayalerts = @excel_app.DisplayAlerts  # :nodoc:
+          @excel_app.DisplayAlerts = true  # :nodoc:
         when :raise
           raise ExcelErrorSave, "book already exists: #{basename}"
         else
@@ -230,9 +230,8 @@ module RobustExcelOle
         @workbook.SaveAs(absolute_path(File.join(dirname, basename)), file_format)
       rescue WIN32OLERuntimeError => msg
         if msg.message =~ /SaveAs/ and msg.message =~ /Workbook/ then
-          #toDo: more condition for cancel. if user cancels: raise an exception
           if opts[:if_exists] == :excel then 
-            raise ExcelUserCanceled, "save: canceled by user"
+            raise ExcelErrorSave, "not saved or canceled by user"
           else
             return nil
           end
@@ -242,7 +241,7 @@ module RobustExcelOle
         end       
       ensure
         if opts[:if_exists] == :excel then
-          @excel_app.DisplayAlerts = old_displayalerts
+          @excel_app.DisplayAlerts = old_displayalerts  # :nodoc:
         end
       end
       true
@@ -260,7 +259,6 @@ module RobustExcelOle
       end
     end
 
-    # adds a sheet
     def add_sheet(sheet = nil, opts = { })
       if sheet.is_a? Hash
         opts = sheet
@@ -278,7 +276,6 @@ module RobustExcelOle
       new_sheet
     end        
 
-    # absolute path of the file
     def absolute_path(file)
       file = File.expand_path(file)
       file = RobustExcelOle::Cygwin.cygpath('-w', file) if RUBY_PLATFORM =~ /cygwin/

data/lib/robust_excel_ole/excel_app.rb

@@ -8,7 +8,7 @@ module RobustExcelOle
 
     @@hwnd2app = {}
 
-    # closes one excel application
+    # closes one Excel application
     def self.close_one_app
       excel = running_app
       if excel then
@@ -67,7 +67,7 @@ module RobustExcelOle
       puts "went through #{anz_objekte} OLE objects"
     end
 
-    # closes all excel applications
+    # closes all Excel applications
     def self.close_all
       while running_app do
         close_one_app
@@ -77,7 +77,7 @@ module RobustExcelOle
       end
     end
 
-    # returns a running excel application, if a non-dead excel appication exists, nil otherwise
+    # returns a running Excel application, if a working Excel appication exists, nil otherwise
     def self.running_app
       result = WIN32OLE.connect('Excel.Application') rescue nil
       if result
@@ -91,21 +91,21 @@ module RobustExcelOle
       result
     end
 
-    # creates a new excel application
+    # creates a new Excel application
     def self.create
       new(:reuse => false)
     end
 
-    # uses a running excel application, if such an application exists
+    # uses a running Excel application, if such an application exists
     # creates a new one, otherwise 
     def self.reuse_if_possible
       new(:reuse => true)
     end
 
-    # returns an excel application  
+    # returns an Excel application  
     #
     # options:
-    #  :reuse         (boolean)  use an already running excel application  (default: true)
+    #  :reuse         (boolean)  use an already running Excel application  (default: true)
     #  :displayalerts (boolean)  allow display alerts in Excel             (default: false)
     #  :visible       (boolean)  make visible in Excel                     (default: false)
     def self.new(options= {})
@@ -115,7 +115,6 @@ module RobustExcelOle
       if options[:reuse] then
         ole_app = running_app
         if ole_app
-          #p "bestehende Applikation wird wieder benutzt"
           ole_app.DisplayAlerts = options[:displayalerts] unless options[:displayalerts]==nil
           ole_app.Visible = options[:visible] unless options[:visible]==nil
         end
@@ -125,7 +124,6 @@ module RobustExcelOle
         :displayalerts => false,
         :visible => false,
       }.merge(options)
-      #p "kreiere neue application"
       unless ole_app
         ole_app = WIN32OLE.new('Excel.application')
         ole_app.DisplayAlerts = options[:displayalerts]
@@ -147,7 +145,7 @@ module RobustExcelOle
     end
 
 
-    def initialize(options= {})
+    def initialize(options= {}) # :nodoc:
     end
 
 
@@ -155,17 +153,17 @@ module RobustExcelOle
       self.HWnd #rescue Win32 nil
     end
 
-    # returns true, if the excel applications are identical, false otherwise
+    # returns true, if the Excel applications are identical, false otherwise
     def == other_app
       self.hwnd == other_app.hwnd    if other_app.is_a?(ExcelApp)
     end
 
-    # set this excel application to nil
-    def die
+    # set this Excel application to nil
+    def die  # :nodoc:
       @ole_app = nil
     end
 
-    # returns true, if the excel application is alive, false otherwise
+    # returns true, if the Excel application is alive, false otherwise
     def alive?
       @ole_app.Name
       true

data/lib/robust_excel_ole/version.rb

@@ -1,3 +1,3 @@
 module RobustExcelOle
-  VERSION = "0.2.0"
+  VERSION = "0.2.0.5"
 end

data/spec/book_spec.rb

@@ -19,7 +19,7 @@ describe RobustExcelOle::Book do
   before do
     @dir = create_tmpdir
     @simple_file = @dir + '/simple.xls'
-    @simple_save_file = @dir + '/simple_save_file.xls'
+    @simple_save_file = @dir + '/simple_save.xls'
   end
 
   after do
@@ -312,6 +312,7 @@ describe RobustExcelOle::Book do
     end
   end
 
+
   describe "close" do
 
     context "with saved book" do
@@ -586,29 +587,29 @@ describe RobustExcelOle::Book do
             @key_sender.puts "{enter}"
             @key_sender.puts "{enter}"
             #@key_sender.puts "%{n}" #, :initial_wait => 0.2, :if_target_missing=>"Excel window not found")
-            @book.save_as(@simple_save_file, :if_exists => :excel)
+            expect{
+              @book.save_as(@simple_save_file, :if_exists => :excel)
+              }.to raise_error(ExcelErrorSave, "not saved or canceled by user")
             File.exist?(@simple_save_file).should be_true
             File.size?(@simple_save_file).should == @garbage_length
+            @book.excel_app.DisplayAlerts.should == displayalert_value
           end
 
-          it "should not save and raise an exception if user answers 'cancel'" do
-            # Just give the "Enter" key, because "No" is the default. --> language independent
+          it "should not save if user answers 'cancel'" do
+            # 'Cancel' is right from 'yes'
             # strangely, in the "no" case, the question will sometimes be repeated three times
             @key_sender.puts "{right}{enter}"
             @key_sender.puts "{right}{enter}"
             @key_sender.puts "{right}{enter}"
+            #@key_sender.puts "%{n}" #, :initial_wait => 0.2, :if_target_missing=>"Excel window not found")
             expect{
               @book.save_as(@simple_save_file, :if_exists => :excel)
-              }.to raise_error(ExcelUserCanceled, "save: canceled by user")
+              }.to raise_error(ExcelErrorSave, "not saved or canceled by user")
             File.exist?(@simple_save_file).should be_true
             File.size?(@simple_save_file).should == @garbage_length
-            new_book = RobustExcelOle::Book.open(@simple_save_file)
-            new_book.should be_a RobustExcelOle::Book
             @book.excel_app.DisplayAlerts.should == displayalert_value
-            new_book.close
           end
 
-
           it "should report save errors and leave DisplayAlerts unchanged" do
             #@key_sender.puts "{left}{enter}" #, :initial_wait => 0.2, :if_target_missing=>"Excel window not found")
             @book.workbook.Close
@@ -863,5 +864,4 @@ describe RobustExcelOle::Book do
       }
     end
   end
-
 end

data/version.rb

@@ -1,3 +1,5 @@
+require 'lib/robust_excel_ole/verson'
+
 module RobustExcelOle
   VERSION = "0.2.0"
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification 
 name: robust_excel_ole
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 85
   prerelease: false
   segments: 
   - 0
   - 2
   - 0
-  version: 0.2.0
+  - 5
+  version: 0.2.0.5
 platform: ruby
 authors: 
 - traths
@@ -15,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2014-09-19 00:00:00 +02:00
+date: 2014-09-25 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency