robust_excel_ole 0.2.1 → 0.2.2.1

data/README.rdoc

@@ -30,7 +30,7 @@ This is work in progress.
 
 Example:
 
-  book = RobustExcelOle::Book.open('./sample.xls')
+  book = RobustExcelOle::Book.open('simple.xls')
 
 Open a book with a block. 
 The semantics is similar to, e.g.,  File.open.
@@ -38,93 +38,60 @@ The semantics is similar to, e.g.,  File.open.
   RobustExcelOle::Book.open('./sample.xls') do |book|
     # do something
   end
-                  
 
 Options are the following:
 
-[:reuse]         use an already open Excel-application (default: true) 
-[:read_only]     open in read-only mode (default: false)  
-[:if_unsaved]    :raise (default), :accept, :forget, :new_app, :excel
-[:if_obstructed]  :raise (default), :forget, :save, :close_if_unsaved, :new_app
-[:displayalerts] allow display alerts in Excel (default: false)
-[:visible]       make visibe in Excel (default: false)                           
++:read_only+::       open in read-only mode (default: +false+)  
++:if_unsaved+::      +:raise+ (default), +:accept+, +:forget+, +:new_app+, +:alert+
++:if_obstructed+::   :raise (default), +:forget+, +:save+, +:close_if_unsaved+, +:new_app+
++:reuse+::           use an already open Excel-application (default: +true+) 
++:excel+::           an Excel appication (default: +nil+)
++:displayalerts+::   allow display alerts in Excel (default: +false+)
++:visible+::         make visibe in Excel (default: +false+)
 
-The option :if_unsaved  : 
+The option +:if_unsaved+  : 
 
 If an unsaved book with the same name is open, then
-          
-[:raise ]  Raise an exeption. Don't open the book.
-[:accept]  Let the unsaved book open.                  
-[:forget]  Close the unsaved book, open the new book.
-[:new_app] Open the new book in a new Excel application
-[:excel]   Give control to Excel.
 
-The option :if_obstructed :
++:raise+::   Raise an exeption. Don't open the book.
++:accept+::  Let the unsaved book open.
++:forget+::  Close the unsaved book, open the new book.
++:new_app+:: Open the new book in a new Excel application
++:alert+::   Give control to Excel.
 
-If a book with same name in a different path is open, then
-                 
-[:raise]   Raise an exception. Don't open the book.
-[:forget]  Close the old book, open the new book.
-[:save]  Save the old book, close it, open the new book
-[:close_if_saved] Close the old book and open the new book, if the old book is saved, raise an exception otherwise
-[:new_app] Open the new book in a new Excel application.
-
-The values :displayalerts and :visible are reached to the class ExcelApp that controls opening and closing of Excel applications.
-
-Examples:
-
-Open a book.
-
-  book = RobustExcelOle::Book.open('./sample.xls')
-
-Open another book in the same Excel application.
-
-  new_book = RobustExcelOle::Book.open('./different.xls')
-
-Open another book in a new Excel applications.
+The option +:if_obstructed+ :
 
-  new_book = RobustExcelOle::Book.open('./different.xls', :reuse => false)
-
-Change the book (see below).
-
-  sheet = book[0]
-  book.add_sheet(sheet, :as => 'copyed_name')
+If a book with same name in a different path is open, then
 
-Let the unsaved book open, when opening a book and a book with the same name is unsaved and open.
++:raise+::          Raise an exception. Don't open the book.
++:forget+::         Close the old book, open the new book.
++:save+::           Save the old book, close it, open the new book
++:close_if_saved+:: Close the old book and open the new book, if the old book is saved, raise an exception otherwise
++:new_app+::        Open the new book in a new Excel application.
 
-  new_book = RobustExcelOle::Book.open('./sample.xls', :if_unsaved => accept)
+The values :displayalerts and :visible are reached to the class Excel that controls opening and closing of Excel applications.
 
 === Close a book.
 
-Example:
+Simple close.
 
   book.close
 
 Options are the following:
 
-[:if_unsaved]  :raise (default), :save, :forget, :excel  
-               if the book is unsaved
++:if_unsaved+,  +:raise+ (default), +:save+, +:forget+, +:alert+
 
-:raise 
+If the book is unsaved, then
 
-Raise an exception. Don't close the book.                  
-                 
-:save            
-
-Save the book before closing it.                  
-                 
-:forget          
-
-Close the book. 
-    
-:excel           
-
-Give control to Excel.
++:raise+::  Raise an exception. Don't close the book.
++:save+::   Save the book before closing it.
++:forget+:: Close the book. 
++:alert+::  Give control to Excel.
 
 
 === Save a book.
 
-Simple save:
+Simple save.
 
   book.save
 
@@ -134,23 +101,16 @@ Save a book with a file name.
 
 Options are the following:
 
-[:if_exists] :raise (default), :overwrite, :excel
++:if_exists+:: +:raise+ (default), +:overwrite+, +:alert+
 
-The option :if_exists :
+The option +:if_exists+ :
 
 If a book with the file name already exists, then
 
-[:raise]     Raise an exeption. Don't write the file.
-[:overwrite] Delete the existing file and write the file. 
-             If the book is open in an Excel application, then raise an exeption.
-[:excel]     Give the control to Excel.
-
-
-Example:
-
-Overwrite a book with the same name.
-
-  book.save('./another_sample.xls', :if_exists => :overwrite)  
++:raise+::     Raise an exeption. Don't write the file.
++:overwrite+:: Delete the existing file and write the file. If the book is open in an Excel application, then raise an exception.
++:alert+::     Give the control to Excel.
+  
 
 === == 
 
@@ -174,7 +134,7 @@ A sheet object can be accessed with a Book#[] method.
 
 Access a sheet object with the sheet name.
 
-    book['Sheet1']
+  book['Sheet1']
 
 === Access a row or a column.
 
@@ -204,6 +164,99 @@ Read a cell from a range object.
   row_range[0]  => first cell in row_range
   column_range[1] => second cell in column_range
 
+= Examples
+
+Include robust_excel_ole.
+
+  include RobustExcelOle
+
+=== Example 1 
+
+Open a book.
+
+  book = Book.open('simple.xls')
+
+Access a sheet.
+
+  sheet = book[0]
+  
+Change a cell.
+
+  sheet[0,0] = "new"
+  
+Save the book.
+
+  book.save
+
+Save it with a different name, and overwrite if a file with this name exists.
+
+  book.save_as('different_simple.xls', :if_exists => :overwrite)
+
+Close the book.
+
+  book.close  
+
+=== Example 2
+
+Open the book again in a new Excel application and make it visible.
+
+  book1.open('simple.xls', :reuse => false, :visible => true)
+
+Add a sheet.
+
+  book1.add_sheet
+
+Open a new book with the same name in a new Excel. Leave the unsaved book in the old Excel.
+
+  book2.open('simple.xls', :if_unsaved => :new_app)
+
+Access a sheet and Change a cell.
+
+  sheet = book2[0]
+  sheet[0,0] = "another"
+
+Open another book with the same name in the running Excel. Close the unsaved book. 
+
+  book3.open('simple.xls', :if_unsaved => :forget)
+
+Add a sheet.
+
+  book3.add_sheet
+
+Close the book without saving it.
+
+  book3.close(:if_unsaved => :forget)
+
+Close the first book and save it before.
+
+  book1.close(:if_unsaved => :save)
+
+=== Example 3
+
+Open a book.
+
+  book1 = Book.open('simple.xls')
+
+Open a book with the same name in a different path. Close the old book.
+
+  book2 = Book.open('more/simple.xls', :if_obstructed => :forget)
+
+Change its cell.
+
+  sheet = book2[0]
+  sheet[0,0] = "new"
+
+Open a book with the same name in a different path. Save and close the unsaved book before.
+
+  book3 = Book.open('simple.xls', :if_obstructed => :save)
+
+Open a book with the same name in a different path. The other book is closed, since it is saved. 
+
+  book4 = Book.open('more/simple.xls', :if_obstructed => :close_if_unsaved)
+
+Close the book.
+
+  book4.close
 
 
 === Want to do more things

data/examples/edit_sheets/example_print_cells.rb

@@ -0,0 +1,43 @@
+# example 1: open a book, print the cells, rows, and columns of a sheet
+
+require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
+require File.join(File.dirname(__FILE__), '../../spec/helpers/create_temporary_dir')
+require "fileutils"
+
+include RobustExcelOle
+
+Excel.close_all
+begin
+  dir = create_tmpdir
+  simple_file = dir + 'simple.xls'
+  simple_save_file = dir + 'simple_save.xls'
+  File.delete simple_save_file rescue nil
+  book = Book.open(simple_file)
+  sheet = book[0]
+  cell = sheet[0,0]
+
+  sheet_enum = proc do |enum_method|
+    i = 0
+    sheet.send(enum_method) do |cell|
+      i = i + 1
+      puts "sheet.#{enum_method} #{i}: #{cell.value}"
+    end
+  end
+
+  sheet_enum[:each]
+  sheet_enum[:each_row]
+  sheet_enum[:each_column]
+
+  col_r = sheet.col_range(0,1..2).values
+  row_r = sheet.row_range(0,1..2).values
+  puts "row range of 1st row, 1..2: #{row_r}"
+  puts "column range of 1st column, 1..2: #{col_r}"
+  sheet[0,0] = "complex"
+  book.save
+  book.close
+ensure
+  Excel.close_all
+  rm_tmp(dir)
+end
+
+  

data/examples/open_save_close/example_control_to_excel.rb

@@ -1,15 +1,18 @@
-# example_gibe_control_to_excel.rb: open, close, save  with giving control to Excel 
+# example_give_control_to_excel.rb: 
+# open, close, save  with giving control to Excel 
 
 require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
+require File.join(File.dirname(__FILE__), '../../spec/helpers/create_temporary_dir')
+require "fileutils"
 
 include RobustExcelOle
 
-ExcelApp.close_all
+Excel.close_all
 begin
-  dir = 'c:/'
+  dir = create_tmpdir
   file_name = dir + 'simple.xls' 
   book = Book.open(file_name)          # open a book
-  ExcelApp.reuse.Visible = true                              # make Excel visible 
+  Excel.current.Visible = true                              # make Excel visible 
   sleep 1
   sheet = book[0]                                                        # access a sheet
   sheet[0,0] = sheet[0,0].value == "simple" ? "complex" : "simple"       # change a cell
@@ -20,7 +23,7 @@ begin
   	puts "#{msg.message}"                                  #   an exeptions is raised
   end
   puts "new book has opened" if new_book
-  ExcelApp.reuse.Visible = true
+  Excel.current.Visible = true
   begin
   	book.close(:if_unsaved => :excel)                      # close the unsaved book. 
   rescue ExcelUserCanceled => msg                          # user is asked whether the unsaved book shall be saved
@@ -36,5 +39,6 @@ begin
   	new_book.close                                         # close the new book, if the user chose to open it
   end
 ensure                                                              
-  ExcelApp.close_all                                       # close ALL workbooks, quit Excel application
+  Excel.close_all                                       # close ALL workbooks, quit Excel application
+  rm_tmp(dir)
 end

data/examples/open_save_close/example_if_obstructed_closeifsaved.rb

@@ -1,15 +1,17 @@
-# example 10: open with :if_obstructed: :close_if_saved
+# example_if_obstructed_close_if_saved.rb:
+# open with :if_obstructed: :close_if_saved
 
 require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
+require File.join(File.dirname(__FILE__), '../../spec/helpers/create_temporary_dir')
+require "fileutils"
 
 include RobustExcelOle
 
-ExcelApp.close_all
+Excel.close_all
 begin
-  dir = 'C:/'
+  dir = create_tmpdir
   file_name = dir + 'simple.xls'
-  other_dir = 'C:/more_data/'
-  other_file_name = other_dir + 'simple.xls'
+  other_file_name = dir + 'more_data/simple.xls'
   book = Book.open(file_name, :visible => true)  # open a book, make Excel visible
   sleep 1
   sheet = book[0]
@@ -29,5 +31,6 @@ begin
   puts "the old book was saved" unless new_first_cell == first_cell 
   new_book.close                                 # close the books                  
 ensure
-  ExcelApp.close_all                         # close all workbooks, quit Excel application
+  Excel.close_all                         # close all workbooks, quit Excel application
+  rm_tmp(dir)
 end

data/examples/open_save_close/example_if_obstructed_forget.rb

@@ -1,15 +1,17 @@
-# example_if_obstructed_forget.rb: open with :if_obstructed: :forget, :new_app
+# example_if_obstructed_forget.rb: 
+# open with :if_obstructed: :forget, :new_app
 
 require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
+require File.join(File.dirname(__FILE__), '../../spec/helpers/create_temporary_dir')
+require "fileutils"
 
 include RobustExcelOle
 
-ExcelApp.close_all
+Excel.close_all
 begin
-  dir = 'C:/'
+  dir = create_tmpdir
   file_name = dir + 'simple.xls'
-  other_dir = 'C:/more_data/'
-  other_file_name = other_dir + 'simple.xls'
+  other_file_name = dir + 'more_data/simple.xls'
   book = Book.open(file_name, :visible => true)  # open a book, make Excel application visible
   sleep 3 
   begin
@@ -26,5 +28,6 @@ begin
   new_book.close                                 # close the books                      
   another_book.close
 ensure
-  ExcelApp.close_all                         # close all workbooks, quit Excel application
+  Excel.close_all                         # close all workbooks, quit Excel application
+  rm_tmp(dir)
 end

data/examples/open_save_close/example_if_obstructed_save.rb

@@ -2,15 +2,16 @@
 # open with :if_obstructed: :save
 
 require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
+require File.join(File.dirname(__FILE__), '../../spec/helpers/create_temporary_dir')
+require "fileutils"
 
 include RobustExcelOle
 
-ExcelApp.close_all
+Excel.close_all
 begin
-  dir = 'C:/'
+  dir = create_tmpdir
   file_name = dir + 'simple.xls'
-  other_dir = 'C:/more_data/'
-  other_file_name = other_dir + 'simple.xls'
+  other_file_name = dir + 'more_data/simple.xls'
   book = Book.open(file_name, :visible => true)  # open a book, make Excel visible
   sleep 1
   sheet = book[0]
@@ -27,5 +28,6 @@ begin
   new_book.close                                 # close the books                      
   old_book.close
 ensure
-  ExcelApp.close_all                         # close all workbooks, quit Excel application
+  Excel.close_all                         # close all workbooks, quit Excel application
+  rm_tmp(dir)
 end

data/examples/open_save_close/example_if_unsaved_accept.rb

@@ -2,12 +2,14 @@
 # open with :if_unsaved => :accept, close with :if_unsaved => :save 
 
 require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
+require File.join(File.dirname(__FILE__), '../../spec/helpers/create_temporary_dir')
+require "fileutils"
 
 include RobustExcelOle
 
-ExcelApp.close_all
+Excel.close_all
 begin
-  dir = 'C:/'
+  dir = create_tmpdir
   file_name = dir + 'simple.xls' 
   book = Book.open(file_name)                      # open a book 
   sheet = book[0]                                                  # access a sheet
@@ -34,5 +36,6 @@ begin
   puts "closed the book successfully with option :if_unsaved => :save"
   new_book.close                                        # close the other book. It is already saved.
 ensure
-	  ExcelApp.close_all                                    # close workbooks, quit Excel application
+	  Excel.close_all                                    # close workbooks, quit Excel application
+    rm_tmp(dir)
 end