robust_excel_ole 0.2.0.8 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/README.rdoc CHANGED
@@ -1,24 +1,24 @@
1
1
  = RobustExcelOle
2
2
 
3
- robust_excel_ole wraps the win32ole, and uses the Excel operations with ruby.
3
+ robust_excel_ole wraps the win32ole library, and allows to perform various operations in Excel with ruby.
4
4
 
5
5
  == Description
6
6
 
7
7
  robust_excel_ole started as a simple fork from tomiacannondale's wrap_excel adapted to Ruby 1.8.6.
8
8
  The functionality of wrap_excel is optimised and extended by new features.
9
+ Most noticable extension is that books are opened in a Excel application if it is already running, instead of opening Excel whenever a book is opened.
9
10
 
10
- This is work in progress.
11
-
12
- Notice some features in robust_excel_ole that are not compatible with wrap_excel:
13
- * +save_as+ instead of +save+.
11
+ Thus some features in robust_excel_ole that are not compatible with wrap_excel:
14
12
  * +open+ uses by default a running Excel application instead of creating a new one,
15
13
  and opens a book by default in writable mode instead of read_only
16
14
  * +close+ closes the workbook instead of closing all workbooks and the Excel application.
15
+ * +save_as+ instead of +save+.
16
+
17
+ This is work in progress.
17
18
 
18
19
  == Requirements
19
20
 
20
- * Ruby 1.9.2 or higher (platform is windows)
21
- * also works with Ruby 1.8.6
21
+ * Ruby 1.8.6 or higher
22
22
 
23
23
  == Install
24
24
 
@@ -42,13 +42,12 @@ The semantics is similar to, e.g., File.open.
42
42
 
43
43
  Options are the following:
44
44
 
45
- [:reuse] boolean (default: true). use an already open Excel-application
46
- [:read_only] boolean (default: false). open in read-only mode
47
- [:displayalerts] boolean (default: false). allow display alerts in Excel
48
- [:visible] boolean (default: false). make visibe in Excel
45
+ [:reuse] use an already open Excel-application (default: true)
46
+ [:read_only] open in read-only mode (default: false)
49
47
  [:if_unsaved] :raise (default), :accept, :forget, :new_app, :excel
50
- [:if_blocking_other] :raise (default), :forget, :save_and_close, :close_or_raise, :new_app
51
-
48
+ [:if_obstructed] :raise (default), :forget, :save, :close_if_unsaved, :new_app
49
+ [:displayalerts] allow display alerts in Excel (default: false)
50
+ [:visible] make visibe in Excel (default: false)
52
51
 
53
52
  The option :if_unsaved :
54
53
 
@@ -60,15 +59,17 @@ If an unsaved book with the same name is open, then
60
59
  [:new_app] Open the new book in a new Excel application
61
60
  [:excel] Give control to Excel.
62
61
 
63
- The option :if_blocking_other :
62
+ The option :if_obstructed :
63
+
64
64
  If a book with same name in a different path is open, then
65
65
 
66
66
  [:raise] Raise an exception. Don't open the book.
67
67
  [:forget] Close the old book, open the new book.
68
- [:save_and_close] Save the old book, close it, open the new book
69
- [:close_or_raise] Close the old book and open the new book, if the old book is saved, raise an exception otherwise
68
+ [:save] Save the old book, close it, open the new book
69
+ [:close_if_saved] Close the old book and open the new book, if the old book is saved, raise an exception otherwise
70
70
  [:new_app] Open the new book in a new Excel application.
71
71
 
72
+ The values :displayalerts and :visible are reached to the class ExcelApp that controls opening and closing of Excel applications.
72
73
 
73
74
  Examples:
74
75
 
@@ -93,6 +94,34 @@ Let the unsaved book open, when opening a book and a book with the same name is
93
94
 
94
95
  new_book = RobustExcelOle::Book.open('./sample.xls', :if_unsaved => accept)
95
96
 
97
+ === Close a book.
98
+
99
+ Example:
100
+
101
+ book.close
102
+
103
+ Options are the following:
104
+
105
+ [:if_unsaved] :raise (default), :save, :forget, :excel
106
+ if the book is unsaved
107
+
108
+ :raise
109
+
110
+ Raise an exception. Don't close the book.
111
+
112
+ :save
113
+
114
+ Save the book before closing it.
115
+
116
+ :forget
117
+
118
+ Close the book.
119
+
120
+ :excel
121
+
122
+ Give control to Excel.
123
+
124
+
96
125
  === Save a book.
97
126
 
98
127
  Simple save:
@@ -123,60 +152,17 @@ Overwrite a book with the same name.
123
152
 
124
153
  book.save('./another_sample.xls', :if_exists => :overwrite)
125
154
 
126
- === == (equal)
155
+ === ==
127
156
 
128
157
  Check whether two referenced Excel workbooks are identical.
129
158
 
130
- Example.
131
-
132
- if (book == new_book) then
133
- puts "the workbooks are identical"
134
- end
135
-
136
159
  === alive?
137
160
 
138
161
  Check whether the referenced Excel workbook responds to methods.
139
162
 
140
- Example:
141
-
142
- if book.alive? then
143
- puts "the book is alive"
144
- end
145
-
146
163
  === filename
147
164
 
148
- Get the file name of the book.
149
-
150
- Example:
151
-
152
- book.filename
153
-
154
- === Close a book.
155
-
156
- Example:
157
-
158
- book.close
159
-
160
- Options are the following:
161
-
162
- [:if_unsaved] :raise (default), :save, :forget, :excel
163
- if the book is unsaved
164
-
165
- :raise
166
-
167
- Raise an exception. Don't close the book.
168
-
169
- :save
170
-
171
- Save the book before closing it.
172
-
173
- :forget
174
-
175
- Close the book.
176
-
177
- :excel
178
-
179
- Give control to Excel.
165
+ Return the file name of the book with the absolute path that contains slash (/) instead of back slash (\)
180
166
 
181
167
 
182
168
 
@@ -0,0 +1,40 @@
1
+ # example_gibe_control_to_excel.rb: open, close, save with giving control to Excel
2
+
3
+ require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
4
+
5
+ include RobustExcelOle
6
+
7
+ ExcelApp.close_all
8
+ begin
9
+ dir = 'c:/'
10
+ file_name = dir + 'simple.xls'
11
+ book = Book.open(file_name) # open a book
12
+ ExcelApp.reuse.Visible = true # make Excel visible
13
+ sleep 1
14
+ sheet = book[0] # access a sheet
15
+ sheet[0,0] = sheet[0,0].value == "simple" ? "complex" : "simple" # change a cell
16
+ sleep 1
17
+ begin
18
+ new_book = Book.open(file_name, :if_unsaved => :excel) # open another book with the same file name
19
+ rescue ExcelUserCanceled => msg # if the user chooses not open the book,
20
+ puts "#{msg.message}" # an exeptions is raised
21
+ end
22
+ puts "new book has opened" if new_book
23
+ ExcelApp.reuse.Visible = true
24
+ begin
25
+ book.close(:if_unsaved => :excel) # close the unsaved book.
26
+ rescue ExcelUserCanceled => msg # user is asked whether the unsaved book shall be saved
27
+ puts "#{msg.message}" # if the user chooses to cancel, then an expeption is raised
28
+ end
29
+ if new_book then
30
+ begin
31
+ new_book.save_as(file_name, :if_exists => :excel) # save the new book, if it was opened
32
+ rescue ExcelErrorSave => msg # user is asked, whether the existing file shall be overwritten
33
+ puts "save_as: #{msg.message}" # if the user chooses "no" or "cancel", an exception is raised
34
+ end
35
+
36
+ new_book.close # close the new book, if the user chose to open it
37
+ end
38
+ ensure
39
+ ExcelApp.close_all # close ALL workbooks, quit Excel application
40
+ end
@@ -0,0 +1,33 @@
1
+ # example 10: open with :if_obstructed: :close_if_saved
2
+
3
+ require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
4
+
5
+ include RobustExcelOle
6
+
7
+ ExcelApp.close_all
8
+ begin
9
+ dir = 'C:/'
10
+ file_name = dir + 'simple.xls'
11
+ other_dir = 'C:/more_data/'
12
+ other_file_name = other_dir + 'simple.xls'
13
+ book = Book.open(file_name, :visible => true) # open a book, make Excel visible
14
+ sleep 1
15
+ sheet = book[0]
16
+ first_cell = sheet[0,0].value # access a sheet
17
+ sheet[0,0] = first_cell == "simple" ? "complex" : "simple" # change a cell
18
+ sleep 1
19
+ begin
20
+ new_book = Book.open(other_file_name, :if_obstructed => :close_if_saved) # raises an exception since the file is not saved
21
+ rescue ExcelErrorOpen => msg
22
+ puts "open: #{msg.message}"
23
+ end
24
+ book.save # save the unsaved book
25
+ new_book = Book.open(file_name, :if_obstructed => :close_if_saved) # open the new book, close the saved book
26
+ sleep 1
27
+ new_sheet = new_book[0]
28
+ new_first_cell = new_sheet[0,0].value
29
+ puts "the old book was saved" unless new_first_cell == first_cell
30
+ new_book.close # close the books
31
+ ensure
32
+ ExcelApp.close_all # close all workbooks, quit Excel application
33
+ end
@@ -0,0 +1,30 @@
1
+ # example_if_obstructed_forget.rb: open with :if_obstructed: :forget, :new_app
2
+
3
+ require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
4
+
5
+ include RobustExcelOle
6
+
7
+ ExcelApp.close_all
8
+ begin
9
+ dir = 'C:/'
10
+ file_name = dir + 'simple.xls'
11
+ other_dir = 'C:/more_data/'
12
+ other_file_name = other_dir + 'simple.xls'
13
+ book = Book.open(file_name, :visible => true) # open a book, make Excel application visible
14
+ sleep 3
15
+ begin
16
+ new_book = Book.open(other_file_name) # open a book with the same file name in a different path
17
+ rescue ExcelErrorOpen => msg # by default: raises an exception
18
+ puts "open: #{msg.message}"
19
+ end
20
+ # open a new book with the same file name in a different path. close the old book before.
21
+ new_book = Book.open(other_file_name, :if_obstructed => :forget)
22
+ sleep 3
23
+ # open another book with the same file name in a different path. Use a new Excel application
24
+ another_book = Book.open(file_name, :if_obstructed => :new_app, :visible => true)
25
+ sleep 3
26
+ new_book.close # close the books
27
+ another_book.close
28
+ ensure
29
+ ExcelApp.close_all # close all workbooks, quit Excel application
30
+ end
@@ -0,0 +1,31 @@
1
+ # example_if_obstructed_save.rb:
2
+ # open with :if_obstructed: :save
3
+
4
+ require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
5
+
6
+ include RobustExcelOle
7
+
8
+ ExcelApp.close_all
9
+ begin
10
+ dir = 'C:/'
11
+ file_name = dir + 'simple.xls'
12
+ other_dir = 'C:/more_data/'
13
+ other_file_name = other_dir + 'simple.xls'
14
+ book = Book.open(file_name, :visible => true) # open a book, make Excel visible
15
+ sleep 1
16
+ sheet = book[0]
17
+ first_cell = sheet[0,0].value # access a sheet
18
+ sheet[0,0] = first_cell == "simple" ? "complex" : "simple" # change a cell
19
+ sleep 1
20
+ new_book = Book.open(other_file_name, :if_obstructed => :save) # open a book with the same file name in a different path
21
+ sleep 1 #save the old book, close it, before
22
+ old_book = Book.open(file_name, :if_obstructed => :forget ,:visible => true) # open the old book
23
+ sleep 1
24
+ old_sheet = old_book[0]
25
+ old_first_cell = old_sheet[0,0].value
26
+ puts "the old book was saved" unless old_first_cell == first_cell
27
+ new_book.close # close the books
28
+ old_book.close
29
+ ensure
30
+ ExcelApp.close_all # close all workbooks, quit Excel application
31
+ end
@@ -0,0 +1,38 @@
1
+ # example_ifunsaved_accept.rb:
2
+ # open with :if_unsaved => :accept, close with :if_unsaved => :save
3
+
4
+ require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
5
+
6
+ include RobustExcelOle
7
+
8
+ ExcelApp.close_all
9
+ begin
10
+ dir = 'C:/'
11
+ file_name = dir + 'simple.xls'
12
+ book = Book.open(file_name) # open a book
13
+ sheet = book[0] # access a sheet
14
+ sheet[0,0] = sheet[0,0].value == "simple" ? "complex" : "simple" # change a cell
15
+ begin
16
+ new_book = Book.open(file_name) # open another book with the same file name
17
+ rescue ExcelErrorOpen => msg # by default: raises an exception:
18
+ puts "open error: #{msg.message}" # a book with the same name is already open and unsaved
19
+ end
20
+ new_book = Book.open(file_name, :if_unsaved => :accept) # open another book with the same file name
21
+ # and let the unsaved book open
22
+ if book.alive? && new_book.alive? then # check whether the referenced workbooks
23
+ puts "open with :if_unsaved => :accept : the two books are alive." # respond to methods
24
+ end
25
+ if book == new_book then # check whether the book are equal
26
+ puts "both books are equal"
27
+ end
28
+ begin
29
+ book.close # close the book. by default: raises an exception:
30
+ rescue ExcelErrorClose => msg # book is unsaved
31
+ puts "close error: #{msg.message}"
32
+ end
33
+ book.close(:if_unsaved => :save) # save the book before closing it
34
+ puts "closed the book successfully with option :if_unsaved => :save"
35
+ new_book.close # close the other book. It is already saved.
36
+ ensure
37
+ ExcelApp.close_all # close workbooks, quit Excel application
38
+ end
@@ -0,0 +1,34 @@
1
+ # example_ifunsaved_forget.rb:
2
+ # open with :if_unsaved => :forget, :new_app, close with :if_unsaved => :save
3
+
4
+ require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
5
+
6
+ include RobustExcelOle
7
+
8
+ ExcelApp.close_all
9
+ begin
10
+ dir = 'C:/'
11
+ file_name = dir + 'simple.xls'
12
+ book = Book.open(file_name) # open a book
13
+ ExcelApp.reuse.Visible = true # make Excel visible
14
+ sleep 1
15
+ sheet = book[0] # access a sheet
16
+ first_cell = sheet[0,0].value
17
+ sheet[0,0] = first_cell == "simple" ? "complex" : "simple" # change a cell
18
+ sleep 1
19
+ new_book = Book.open(file_name, :if_unsaved => :forget) # open another book with the same file name
20
+ # and close the unsaved book without saving it
21
+ sheet_new_book = new_book[0]
22
+ if (not book.alive?) && new_book.alive? && sheet_new_book[0,0].value == first_cell then # check whether the unsaved book
23
+ puts "open with :if_unsaved => :forget : the unsaved book is closed and not saved." # is closed and was not saved
24
+ end
25
+ sleep 1
26
+ sheet_new_book[0,0] = sheet_new_book[0,0].value == "simple" ? "complex" : "simple" # change a cell
27
+ # open another book in a new Excel application, and make Excel visible, leaving the unsaved book open
28
+ another_book = Book.open(file_name, :if_unsaved => :new_app, :visible => true)
29
+ sleep 3 # leaving the unsaved book open
30
+ new_book.close(:if_unsaved => :forget )
31
+ another_book.close
32
+ ensure
33
+ ExcelApp.close_all # close all workbooks, quit Excel application
34
+ end
@@ -0,0 +1,27 @@
1
+ # example_read_only: open with read_only mode. save, close
2
+
3
+ require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
4
+
5
+ include RobustExcelOle
6
+
7
+ ExcelApp.close_all
8
+ begin
9
+ dir = 'C:/'
10
+ file_name = dir + 'simple.xls'
11
+ other_file_name = dir + 'different_simple.xls'
12
+ # open a book with read_only and make Excel visible
13
+ book = Book.open(file_name, :read_only => true, :visible => true)
14
+ sheet = book[0] # access a sheet
15
+ sleep 1
16
+ sheet[0,0] = sheet[0,0].value == "simple" ? "complex" : "simple" # change a cell
17
+ sleep 1
18
+ begin
19
+ book.save # simple save.
20
+ rescue ExcelErrorSave => msg # raises an exception because book is opened in read_only mode
21
+ puts "save_as error: #{msg.message}"
22
+ end
23
+ book.close # close the book without saving it
24
+ ensure
25
+ ExcelApp.close_all # close workbooks, quit Excel application
26
+ end
27
+
@@ -0,0 +1,31 @@
1
+ # example_reuse.rb: open a book in a running Excel application and in a new one. make visible
2
+
3
+ require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
4
+
5
+ include RobustExcelOle
6
+
7
+ ExcelApp.close_all
8
+ begin
9
+ dir = 'C:/'
10
+ file_name1 = dir + 'simple.xls'
11
+ file_name2 = dir + 'different_simple.xls'
12
+ file_name3 = dir + 'different_simple.xls'
13
+ file_name4 = dir + 'book_with_blank.xls'
14
+ book1 = Book.open(file_name1) # open a book in a new Excel application since no Excel is open
15
+ ExcelApp.reuse.Visible = true # make Excel visible
16
+ sleep 2
17
+ book2 = Book.open(file_name2) # open a new book in the same Excel application
18
+ sleep 2 # (by default: :reuse => true)
19
+ book3 = Book.open(file_name3, :reuse => false, :visible => true) # open another book in a new Excel application,
20
+ sleep 2 # make Excel visible
21
+ book4 = Book.open(file_name4, :reuse => true, :visible => true) # open anther book, and use a running Excel application
22
+ sleep 2 # (Excel chooses the first Excel application)
23
+ book1.close # close the books
24
+ book2.close
25
+ book3.close
26
+ book4.close
27
+ ensure
28
+ ExcelApp.close_all # close all workbooks, quit Excel application
29
+ end
30
+
31
+
@@ -0,0 +1,30 @@
1
+ # example_simple.rb: open a book, simple save, save_as, close
2
+
3
+ require File.join(File.dirname(__FILE__), '../../lib/robust_excel_ole')
4
+
5
+ include RobustExcelOle
6
+
7
+ ExcelApp.close_all
8
+ begin
9
+ dir = 'C:/'
10
+ file_name = dir + 'simple.xls'
11
+ other_file_name = dir + 'different_simple.xls'
12
+ book = Book.open(file_name) # open a book. default: :read_only => false
13
+ ExcelApp.reuse.Visible = true # make Excel visible
14
+ sheet = book[0] # access a sheet
15
+ sleep 1
16
+ sheet[0,0] = sheet[0,0].value == "simple" ? "complex" : "simple" # change a cell
17
+ sleep 1
18
+ book.save # simple save
19
+ begin
20
+ book.save_as(other_file_name) # save_as : default :if_exists => :raise
21
+ rescue ExcelErrorSave => msg
22
+ puts "save_as error: #{msg.message}"
23
+ end
24
+ book.save_as(other_file_name, :if_exists => :overwrite) # save_as with :if_exists => :overwrite
25
+ puts "save_as: saved successfully with option :if_exists => :overwrite"
26
+ book.close # close the book
27
+ ensure
28
+ ExcelApp.close_all # close workbooks, quit Excel application
29
+ end
30
+