robust_excel_ole 0.2.3 → 0.3.0
Sign up to get free protection for your applications and to get access to all the features.
- data/README.rdoc +266 -71
- data/TodoList.md +33 -0
- data/examples/edit_sheets/example_adding_sheets.rb +7 -0
- data/examples/open_save_close/example_control_to_excel.rb +4 -4
- data/examples/open_save_close/example_default_excel.rb +49 -0
- data/examples/open_save_close/example_force_excel.rb +34 -0
- data/examples/open_save_close/example_if_obstructed_closeifsaved.rb +1 -1
- data/examples/open_save_close/example_if_obstructed_forget.rb +3 -3
- data/examples/open_save_close/example_if_unsaved_accept.rb +1 -1
- data/examples/open_save_close/example_if_unsaved_forget.rb +3 -3
- data/examples/open_save_close/example_if_unsaved_forget_more.rb +3 -3
- data/examples/open_save_close/example_read_only.rb +1 -1
- data/examples/open_save_close/example_rename_cells.rb +69 -0
- data/examples/open_save_close/example_reuse.rb +8 -8
- data/examples/open_save_close/example_simple.rb +3 -3
- data/examples/open_save_close/example_unobtrusively.rb +28 -0
- data/examples/save_sheets/example_save_sheets.rb +2 -6
- data/lib/robust_excel_ole.rb +18 -0
- data/lib/robust_excel_ole/book.rb +356 -123
- data/lib/robust_excel_ole/book_store.rb +75 -0
- data/lib/robust_excel_ole/excel.rb +105 -53
- data/lib/robust_excel_ole/robustexcelole.sublime-project +8 -8
- data/lib/robust_excel_ole/sheet.rb +29 -1
- data/lib/robust_excel_ole/version.rb +1 -1
- data/robust_excel_ole.gemspec +3 -3
- data/spec/book_spec.rb +1031 -247
- data/spec/book_store_spec.rb +306 -0
- data/spec/data/book_with_blank.xls +0 -0
- data/spec/data/merge_cells.xls +0 -0
- data/spec/data/more_simple.xls +0 -0
- data/spec/data/simple.xls +0 -0
- data/spec/excel_spec.rb +145 -90
- data/spec/sheet_spec.rb +31 -7
- metadata +15 -7
data/README.rdoc
CHANGED
@@ -6,12 +6,14 @@ robust_excel_ole wraps the win32ole library, and allows to perform various opera
|
|
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
|
9
|
+
Most notable extensions include:
|
10
|
+
* books can be opened in already running Excel instances (instead of opening a new Excel whenever a book is opened)
|
11
|
+
* a book management system stores all books that have been open. This book store is being used, e.g., for reopening a book that has been closed before. It provides transperency identity, i.e., equal Excel books correspond to equal Book objects of RobustExcelOle.
|
10
12
|
|
11
|
-
|
12
|
-
* +open+ uses by default a running Excel
|
13
|
+
Some features in robust_excel_ole that are not compatible with wrap_excel:
|
14
|
+
* +open+ uses by default a running Excel instance instead of creating a new one,
|
13
15
|
and opens a book by default in writable mode instead of read_only
|
14
|
-
* +close+ closes the workbook instead of closing all workbooks and the Excel
|
16
|
+
* +close+ closes the workbook instead of closing all workbooks and the Excel instance.
|
15
17
|
* +save_as+ instead of +save+.
|
16
18
|
|
17
19
|
This is work in progress.
|
@@ -26,37 +28,56 @@ This is work in progress.
|
|
26
28
|
|
27
29
|
== Usage
|
28
30
|
|
29
|
-
===
|
31
|
+
=== Including robust_excel_ole.
|
32
|
+
|
33
|
+
include RobustExcelOle
|
34
|
+
|
35
|
+
=== Opening a book.
|
30
36
|
|
31
37
|
Example:
|
32
38
|
|
33
|
-
book =
|
39
|
+
book = Book.open('simple.xls')
|
34
40
|
|
35
41
|
Open a book with a block.
|
36
42
|
The semantics is similar to, e.g., File.open.
|
37
43
|
|
38
|
-
|
44
|
+
Book.open('simple.xls') do |book|
|
39
45
|
# do something
|
40
46
|
end
|
41
47
|
|
42
48
|
Options are the following:
|
43
49
|
|
44
|
-
+:
|
45
|
-
+:
|
46
|
-
+:
|
47
|
-
+:
|
48
|
-
+:
|
50
|
+
+:default_excel+:: open in the Excel instance used before if the book was once open (default: +reuse+)
|
51
|
+
+:force_excel+:: open in a new or given Excel instance (defaut: +:new+)
|
52
|
+
+:if_unsaved+:: specify behaviour if the book was unsaved (default: +raise+)
|
53
|
+
+:if_obstructed+:: specidy behaviour if the book is blocked by another book (default: +raise+)
|
54
|
+
+:read_only+:: open in read-only mode (default: +false+)
|
49
55
|
+:displayalerts+:: allow display alerts in Excel (default: +false+)
|
50
56
|
+:visible+:: make visibe in Excel (default: +false+)
|
51
57
|
|
58
|
+
The option +:defaut_excel+ :
|
59
|
+
|
60
|
+
If the book was open before, then open it in the Excel instance used before. If the book cannot be reopened, then
|
61
|
+
|
62
|
+
+:reuse+:: Connect to a running Excel, if it exists, open a new Excel otherwise.
|
63
|
+
+:new+:: Open in a new Excel.
|
64
|
+
[instance]:: Open in a given Excel instance.
|
65
|
+
|
66
|
+
The option +:force_excel :
|
67
|
+
|
68
|
+
No matter if the book was open before,
|
69
|
+
|
70
|
+
+:new+:: Open in a new Excel.
|
71
|
+
[instance]:: Open in a given Excel instance.
|
72
|
+
|
52
73
|
The option +:if_unsaved+ :
|
53
74
|
|
54
75
|
If an unsaved book with the same name is open, then
|
55
76
|
|
56
77
|
+:raise+:: Raise an exeption. Don't open the book.
|
57
78
|
+:accept+:: Let the unsaved book open.
|
58
|
-
+:forget+::
|
59
|
-
+:
|
79
|
+
+:forget+:: Discard any changes and reopen the book.
|
80
|
+
+:new_excel+:: Open the new book in a new Excel instance
|
60
81
|
+:alert+:: Give control to Excel.
|
61
82
|
|
62
83
|
The option +:if_obstructed+ :
|
@@ -67,21 +88,21 @@ If a book with same name in a different path is open, then
|
|
67
88
|
+:forget+:: Close the old book, open the new book.
|
68
89
|
+:save+:: Save the old book, close it, open the new book
|
69
90
|
+:close_if_saved+:: Close the old book and open the new book, if the old book is saved, raise an exception otherwise
|
70
|
-
+:
|
91
|
+
+:new_excel+:: Open the new book in a new Excel instance.
|
71
92
|
|
72
|
-
The values :displayalerts and :visible are reached to the class Excel that controls opening and closing
|
93
|
+
The values :displayalerts and :visible are reached to the class Excel that controls opening and closing Excel instances.
|
73
94
|
|
74
|
-
===
|
95
|
+
=== Closing a book.
|
75
96
|
|
76
97
|
Simple close.
|
77
98
|
|
78
99
|
book.close
|
79
100
|
|
80
|
-
|
101
|
+
The option is : +:if_unsaved+ . It can have one of the following values:
|
81
102
|
|
82
103
|
+:if_unsaved+, +:raise+ (default), +:save+, +:forget+, +:alert+
|
83
104
|
|
84
|
-
If the book is unsaved, then
|
105
|
+
The option specifies: If the book is unsaved, then
|
85
106
|
|
86
107
|
+:raise+:: Raise an exception. Don't close the book.
|
87
108
|
+:save+:: Save the book before closing it.
|
@@ -89,15 +110,15 @@ If the book is unsaved, then
|
|
89
110
|
+:alert+:: Give control to Excel.
|
90
111
|
|
91
112
|
|
92
|
-
===
|
113
|
+
=== Saving a book.
|
93
114
|
|
94
115
|
Simple save.
|
95
116
|
|
96
117
|
book.save
|
97
118
|
|
98
|
-
|
119
|
+
Saving a book with a file name.
|
99
120
|
|
100
|
-
book.save_as('
|
121
|
+
book.save_as('another_simple.xls')
|
101
122
|
|
102
123
|
Options are the following:
|
103
124
|
|
@@ -108,41 +129,89 @@ The option +:if_exists+ :
|
|
108
129
|
If a book with the file name already exists, then
|
109
130
|
|
110
131
|
+:raise+:: Raise an exeption. Don't write the file.
|
111
|
-
+:overwrite+:: Delete the existing file and write the file. If the book is open in an Excel
|
132
|
+
+:overwrite+:: Delete the existing file and write the file. If the book is open in an Excel instance, then raise an exception.
|
112
133
|
+:alert+:: Give the control to Excel.
|
113
134
|
|
114
135
|
|
115
|
-
===
|
136
|
+
=== Unobtrusively modifying a book
|
137
|
+
|
138
|
+
When modifying the book unobtrusively, the status of the book remains unchanged. The status includes, wheter the book is opened or closed, saved or unsaved, readonly or writable.
|
139
|
+
|
140
|
+
|
141
|
+
Book.unobtrusively('simple.xls') do |book|
|
142
|
+
# some modification
|
143
|
+
sheet = book[0]
|
144
|
+
sheet[0,0] = "c"
|
145
|
+
end
|
146
|
+
|
147
|
+
=== Value of a named cell or range
|
148
|
+
|
149
|
+
Returning the value of a cell or range that has a with a defined name.
|
150
|
+
|
151
|
+
book.nvalue(name)
|
152
|
+
|
153
|
+
=== Identity.
|
154
|
+
|
155
|
+
Checking whether two referenced Excel workbooks are identical.
|
116
156
|
|
117
|
-
|
157
|
+
if book1 == book2 then puts "Both referenced Excel workbooks are identical."
|
118
158
|
|
119
|
-
===
|
159
|
+
=== Alive.
|
120
160
|
|
121
|
-
|
161
|
+
Checking whether the referenced Excel workbook responds to methods.
|
122
162
|
|
123
|
-
|
163
|
+
if book.alive? then puts "book is responding."
|
124
164
|
|
125
|
-
|
165
|
+
=== File name.
|
126
166
|
|
167
|
+
Getting the file name of the book with the absolute path that contains slash (/) instead of back slash (\).
|
127
168
|
|
169
|
+
book.filename
|
170
|
+
|
171
|
+
=== Make a book visible or invisible in Excel.
|
172
|
+
|
173
|
+
Make the book visible.
|
174
|
+
|
175
|
+
book.visible = true
|
176
|
+
|
177
|
+
Options: +true+ -> make visible , +false+ -> make invisible
|
178
|
+
|
179
|
+
Check whether the book is visible.
|
180
|
+
|
181
|
+
if book.visible then p "visible"
|
128
182
|
|
129
|
-
===
|
183
|
+
=== Enable and disable DisplayAlerts in Excel.
|
184
|
+
|
185
|
+
Enable DisplayAlerts.
|
186
|
+
|
187
|
+
book.displayalerts = true
|
188
|
+
|
189
|
+
Options: +true+ -> enable DisplayAlerts , +false+ -> Disable DisplayAlerts
|
190
|
+
|
191
|
+
|
192
|
+
Check whether DisplayAlerts is enabled.
|
193
|
+
|
194
|
+
if book.displayalerts then p "DisplayAlerts enabled"
|
195
|
+
|
196
|
+
|
197
|
+
|
198
|
+
=== Accessing a sheet.
|
130
199
|
|
131
200
|
A sheet object can be accessed with a Book#[] method via an integer number.
|
132
201
|
|
133
202
|
sheet = book[0]
|
134
203
|
|
135
|
-
|
204
|
+
Accessing a sheet object with the sheet name.
|
136
205
|
|
137
206
|
sheet = book['Sheet1']
|
138
207
|
|
139
|
-
|
208
|
+
Accessing sheet objects using the methods Book#each.
|
140
209
|
|
141
210
|
book.each do |sheet|
|
142
211
|
# do something with sheet
|
143
212
|
end
|
144
213
|
|
145
|
-
===
|
214
|
+
=== Accessing a row or a column.
|
146
215
|
|
147
216
|
A sheet object is enumerable. Use the methods Sheet#each_column, Sheet#each_row or Sheet#each.
|
148
217
|
|
@@ -159,154 +228,280 @@ A sheet object is enumerable. Use the methods Sheet#each_column, Sheet#each_row
|
|
159
228
|
# do something with column
|
160
229
|
end
|
161
230
|
|
162
|
-
===
|
231
|
+
=== Accessing a cell.
|
163
232
|
|
164
|
-
|
233
|
+
Reading a cell from a sheet object.
|
165
234
|
|
166
235
|
sheet[0, 0] => first cell.
|
167
236
|
|
168
|
-
|
237
|
+
Reading a cell from a range object.
|
169
238
|
|
170
239
|
row_range[0] => first cell in row_range
|
171
240
|
column_range[1] => second cell in column_range
|
172
241
|
|
173
|
-
|
242
|
+
Reading the value of a cell.
|
174
243
|
|
175
244
|
cell = sheet[0,0]
|
176
245
|
cell.value => value of the cell.
|
177
246
|
|
178
|
-
|
247
|
+
Writing a cell
|
179
248
|
|
180
249
|
sheet[0,0] = "new_value"
|
181
250
|
|
182
251
|
|
183
|
-
===
|
252
|
+
=== Accessing a range of a row or column.
|
184
253
|
|
185
|
-
|
254
|
+
Accessing a range of a row.
|
186
255
|
|
187
256
|
sheet.row_range(0) => first row
|
188
257
|
sheet.row_range(0, 0..2 ) => first three cells of the first row
|
189
258
|
|
190
|
-
|
259
|
+
Accessing a range of a column.
|
191
260
|
|
192
261
|
sheet.col_range(2) => third column
|
193
262
|
sheet.col_range(2, 0..1) => first two cells of the third column
|
194
263
|
|
195
264
|
|
196
|
-
===
|
265
|
+
=== Adding a sheet.
|
197
266
|
|
198
|
-
|
267
|
+
Adding a new sheet.
|
199
268
|
|
200
269
|
book.add_sheet
|
201
270
|
|
202
|
-
|
271
|
+
Adding a new sheet with a name.
|
203
272
|
|
204
273
|
book.add_sheet(:as => 'new_sheet')
|
205
274
|
|
206
|
-
|
275
|
+
Adding a new sheet with a name before another sheet.
|
207
276
|
|
208
277
|
book.add_sheet(:as => 'new_sheet2', :before => another_sheet)
|
209
278
|
|
210
|
-
|
279
|
+
Adding a copy of a sheet with a name after another sheet.
|
211
280
|
|
212
281
|
book.add_sheet(sheet, :as => 'sheet_copy', :after => another_sheet)
|
213
282
|
|
283
|
+
=== Value of a named cell or range
|
284
|
+
|
285
|
+
Returning the value of a cell or range that has a with a defined name.
|
286
|
+
|
287
|
+
sheet.nvalue(name)
|
288
|
+
|
289
|
+
=== Creating and reusing an Excel instance.
|
290
|
+
|
291
|
+
Creating a new Excel.
|
292
|
+
|
293
|
+
excel1 = Excel.create
|
294
|
+
|
295
|
+
Getting a running Excel instance and reusing it.
|
296
|
+
|
297
|
+
excel2 = Excel.current
|
298
|
+
|
299
|
+
Reusing a running Excel instance, making it visible and turning on displayalerts.
|
300
|
+
|
301
|
+
excel2 = Excel.new(:reuse => true, :visible => true, displayalerts => true).
|
302
|
+
|
303
|
+
Reusing a certain running Excel instance.
|
304
|
+
|
305
|
+
excel3 = Excel.new(:excel => excel1)
|
306
|
+
|
307
|
+
=== Making Excel visible or invisible
|
308
|
+
|
309
|
+
Making Excel visible.
|
310
|
+
|
311
|
+
excel = Excel.create
|
312
|
+
excel.visible = true
|
313
|
+
puts "visible" if excel.visible
|
314
|
+
|
315
|
+
Making Excel invisible
|
316
|
+
|
317
|
+
excel.visible = false
|
318
|
+
|
319
|
+
=== Turning on or off Displayalerts.
|
320
|
+
|
321
|
+
Turning DisplayAlerts on.
|
322
|
+
|
323
|
+
excel = Excel.create
|
324
|
+
excel.displayalerts = true
|
325
|
+
puts "allows displayalerts" if excel.displayalerts
|
326
|
+
|
327
|
+
Turning DisplayAlerts off.
|
328
|
+
|
329
|
+
excel.displayalerts = false
|
330
|
+
|
331
|
+
Turning on and off in a block.
|
332
|
+
|
333
|
+
with_displayalerts
|
334
|
+
|
335
|
+
excel = Excel.create
|
336
|
+
excel.with_displayalerts true do
|
337
|
+
book = Book.open('simple.xls')
|
338
|
+
end
|
339
|
+
|
340
|
+
=== Closing all Excel instances.
|
341
|
+
|
342
|
+
Excel.close_all
|
214
343
|
|
215
344
|
=== Examples
|
216
345
|
|
217
|
-
|
346
|
+
Including robust_excel_ole.
|
218
347
|
|
219
348
|
include RobustExcelOle
|
220
349
|
|
221
350
|
=== Example 1
|
222
351
|
|
223
|
-
|
352
|
+
Opening a book.
|
224
353
|
|
225
354
|
book = Book.open('simple.xls')
|
226
355
|
|
227
|
-
|
356
|
+
Accessing a sheet via its name.
|
228
357
|
|
229
358
|
sheet = book['Sheet1']
|
230
359
|
|
231
|
-
|
360
|
+
Changing the first cell.
|
232
361
|
|
233
362
|
sheet[0,0] = "new"
|
234
363
|
|
235
|
-
|
364
|
+
Saving the book.
|
236
365
|
|
237
366
|
book.save
|
238
367
|
|
239
|
-
|
368
|
+
Saving the book with a different name, and overwrite if a file with this name exists.
|
240
369
|
|
241
370
|
book.save_as('different_simple.xls', :if_exists => :overwrite)
|
242
371
|
|
243
|
-
|
372
|
+
Closing the book.
|
244
373
|
|
245
374
|
book.close
|
246
375
|
|
247
376
|
=== Example 2
|
248
377
|
|
249
|
-
|
378
|
+
Opening a book.
|
379
|
+
|
380
|
+
book = Book.open('simple.xls')
|
381
|
+
|
382
|
+
Opening the book in a new Excel instance and make it visible.
|
383
|
+
|
384
|
+
new_book = Book.open('simple.xls', :force_excel => :new, :visible => true)
|
385
|
+
|
386
|
+
Opening the book in a given Excel instance.
|
387
|
+
|
388
|
+
another_book = Book.open('simple.xls', :force_excel => book.excel)
|
389
|
+
|
390
|
+
Closing the books.
|
391
|
+
|
392
|
+
book.close
|
393
|
+
new_book.close
|
394
|
+
another_book.close
|
395
|
+
|
396
|
+
Reopening the book.
|
397
|
+
|
398
|
+
reopened_book = Book.open('simple.xls')
|
399
|
+
|
400
|
+
The writable book is being prefered.
|
401
|
+
|
402
|
+
reopened_book == book
|
403
|
+
=> true
|
250
404
|
|
251
|
-
|
405
|
+
Opening another book.
|
406
|
+
Since the book was not open before, reopening the book fails and the :default_excel option applies.
|
407
|
+
According to :default_excel => :new a new Excel is created, and the book is opened there.
|
252
408
|
|
253
|
-
|
409
|
+
different_book = Book.open('different.xls', :default_excel => :new)
|
410
|
+
|
411
|
+
|
412
|
+
=== Example 3
|
413
|
+
|
414
|
+
Opening a book.
|
415
|
+
|
416
|
+
book = Book.open('simple.xls')
|
417
|
+
|
418
|
+
Adding a copy of the first sheet after the second sheet.
|
254
419
|
|
255
420
|
book.add_sheet(book[0], :as => 'Sheet1_copy', :after => book[1])
|
256
421
|
|
257
|
-
|
422
|
+
Close the book.
|
423
|
+
|
424
|
+
Opening a new book with the same name in a new Excel. Leave the book that contains unsaved changes in the old Excel.
|
258
425
|
|
259
|
-
new_book.open('simple.xls', :if_unsaved => :
|
426
|
+
new_book = Book.open('simple.xls', :if_unsaved => :new_excel)
|
260
427
|
|
261
|
-
|
428
|
+
Accessing a sheet and change a cell.
|
262
429
|
|
263
430
|
sheet = new_book[0]
|
264
431
|
sheet[1,1] = "another"
|
265
432
|
|
266
|
-
|
433
|
+
Opening another book with the same name in the running Excel. The book that contains unsaved changes will be closed before.
|
267
434
|
|
268
|
-
third_book.open('simple.xls', :if_unsaved => :forget)
|
435
|
+
third_book = Book.open('simple.xls', :if_unsaved => :forget)
|
269
436
|
|
270
|
-
|
437
|
+
Adding a sheet.
|
271
438
|
|
272
439
|
third_book.add_sheet
|
273
440
|
|
274
|
-
|
441
|
+
Closing the book without saving it.
|
275
442
|
|
276
443
|
third_book.close(:if_unsaved => :forget)
|
277
444
|
|
278
|
-
|
445
|
+
Closing the first book and saving it before.
|
279
446
|
|
280
447
|
book.close(:if_unsaved => :save)
|
281
448
|
|
282
|
-
=== Example
|
449
|
+
=== Example 4
|
283
450
|
|
284
|
-
|
451
|
+
Opening a book.
|
285
452
|
|
286
453
|
book1 = Book.open('simple.xls')
|
287
454
|
|
288
|
-
|
455
|
+
Opening a book with the same name in a different path. Close the old book.
|
289
456
|
|
290
457
|
book2 = Book.open('more/simple.xls', :if_obstructed => :forget)
|
291
458
|
|
292
|
-
|
459
|
+
Changing its cell.
|
293
460
|
|
294
461
|
sheet = book2[0]
|
295
462
|
sheet[0,0] = "new"
|
296
463
|
|
297
|
-
|
464
|
+
Opening a book with the same name in a different path. The old book that was modified will be saved and closed before.
|
298
465
|
|
299
466
|
book3 = Book.open('simple.xls', :if_obstructed => :save)
|
300
467
|
|
301
|
-
|
468
|
+
Opening a book with the same name in a different path. The other book will be closed, because it does not contain unsaved changes.
|
302
469
|
|
303
470
|
book4 = Book.open('more/simple.xls', :if_obstructed => :close_if_unsaved)
|
304
471
|
|
305
|
-
|
472
|
+
Closing the book.
|
306
473
|
|
307
474
|
book4.close
|
308
475
|
|
309
476
|
|
477
|
+
=== Example 5
|
478
|
+
|
479
|
+
Opening a book.
|
480
|
+
|
481
|
+
book = Book.open('simple.xls')
|
482
|
+
|
483
|
+
Printing its first cell.
|
484
|
+
|
485
|
+
sheet = book[0]
|
486
|
+
p "1st cell: #{sheet[0,0].value}"
|
487
|
+
|
488
|
+
Unobtrusively modify the book.
|
489
|
+
|
490
|
+
Book.unobtrusively('simple.xls') do |book|
|
491
|
+
sheet = book[0]
|
492
|
+
sheet[0,0] = 'simple'
|
493
|
+
end
|
494
|
+
|
495
|
+
The book is modified, but its status is unchanged.
|
496
|
+
|
497
|
+
new_sheet = book[0]
|
498
|
+
not (new_sheet[0,0].value == sheet[0,0].value)
|
499
|
+
=> true
|
500
|
+
|
501
|
+
book.Saved
|
502
|
+
=> true
|
503
|
+
|
504
|
+
|
310
505
|
=== Want to do more things
|
311
506
|
|
312
507
|
All RobustExcelOle objects include the win32ole instance.
|