robust_excel_ole 0.2.3 → 0.3.0
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 +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.
|