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.
Files changed (34) hide show
  1. data/README.rdoc +266 -71
  2. data/TodoList.md +33 -0
  3. data/examples/edit_sheets/example_adding_sheets.rb +7 -0
  4. data/examples/open_save_close/example_control_to_excel.rb +4 -4
  5. data/examples/open_save_close/example_default_excel.rb +49 -0
  6. data/examples/open_save_close/example_force_excel.rb +34 -0
  7. data/examples/open_save_close/example_if_obstructed_closeifsaved.rb +1 -1
  8. data/examples/open_save_close/example_if_obstructed_forget.rb +3 -3
  9. data/examples/open_save_close/example_if_unsaved_accept.rb +1 -1
  10. data/examples/open_save_close/example_if_unsaved_forget.rb +3 -3
  11. data/examples/open_save_close/example_if_unsaved_forget_more.rb +3 -3
  12. data/examples/open_save_close/example_read_only.rb +1 -1
  13. data/examples/open_save_close/example_rename_cells.rb +69 -0
  14. data/examples/open_save_close/example_reuse.rb +8 -8
  15. data/examples/open_save_close/example_simple.rb +3 -3
  16. data/examples/open_save_close/example_unobtrusively.rb +28 -0
  17. data/examples/save_sheets/example_save_sheets.rb +2 -6
  18. data/lib/robust_excel_ole.rb +18 -0
  19. data/lib/robust_excel_ole/book.rb +356 -123
  20. data/lib/robust_excel_ole/book_store.rb +75 -0
  21. data/lib/robust_excel_ole/excel.rb +105 -53
  22. data/lib/robust_excel_ole/robustexcelole.sublime-project +8 -8
  23. data/lib/robust_excel_ole/sheet.rb +29 -1
  24. data/lib/robust_excel_ole/version.rb +1 -1
  25. data/robust_excel_ole.gemspec +3 -3
  26. data/spec/book_spec.rb +1031 -247
  27. data/spec/book_store_spec.rb +306 -0
  28. data/spec/data/book_with_blank.xls +0 -0
  29. data/spec/data/merge_cells.xls +0 -0
  30. data/spec/data/more_simple.xls +0 -0
  31. data/spec/data/simple.xls +0 -0
  32. data/spec/excel_spec.rb +145 -90
  33. data/spec/sheet_spec.rb +31 -7
  34. 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 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
+ 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
- Thus some features in robust_excel_ole that are not compatible with wrap_excel:
12
- * +open+ uses by default a running Excel application instead of creating a new one,
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 application.
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
- === Open a book.
31
+ === Including robust_excel_ole.
32
+
33
+ include RobustExcelOle
34
+
35
+ === Opening a book.
30
36
 
31
37
  Example:
32
38
 
33
- book = RobustExcelOle::Book.open('simple.xls')
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
- RobustExcelOle::Book.open('./sample.xls') do |book|
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
- +:read_only+:: open in read-only mode (default: +false+)
45
- +:if_unsaved+:: +:raise+ (default), +:accept+, +:forget+, +:new_app+, +:alert+
46
- +:if_obstructed+:: :raise (default), +:forget+, +:save+, +:close_if_unsaved+, +:new_app+
47
- +:reuse+:: use an already open Excel-application (default: +true+)
48
- +:excel+:: an Excel appication (default: +nil+)
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+:: Close the unsaved book, open the new book.
59
- +:new_app+:: Open the new book in a new Excel application
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
- +:new_app+:: Open the new book in a new Excel application.
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 of Excel applications.
93
+ The values :displayalerts and :visible are reached to the class Excel that controls opening and closing Excel instances.
73
94
 
74
- === Close a book.
95
+ === Closing a book.
75
96
 
76
97
  Simple close.
77
98
 
78
99
  book.close
79
100
 
80
- Options are the following:
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
- === Save a book.
113
+ === Saving a book.
93
114
 
94
115
  Simple save.
95
116
 
96
117
  book.save
97
118
 
98
- Save a book with a file name.
119
+ Saving a book with a file name.
99
120
 
100
- book.save_as('./another_sample.xls')
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 application, then raise an exception.
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
- Check whether two referenced Excel workbooks are identical.
157
+ if book1 == book2 then puts "Both referenced Excel workbooks are identical."
118
158
 
119
- === alive?
159
+ === Alive.
120
160
 
121
- Check whether the referenced Excel workbook responds to methods.
161
+ Checking whether the referenced Excel workbook responds to methods.
122
162
 
123
- === filename
163
+ if book.alive? then puts "book is responding."
124
164
 
125
- Return the file name of the book with the absolute path that contains slash (/) instead of back slash (\)
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
- === Access a sheet.
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
- Access a sheet object with the sheet name.
204
+ Accessing a sheet object with the sheet name.
136
205
 
137
206
  sheet = book['Sheet1']
138
207
 
139
- Access sheet objects using the methods Book#each.
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
- === Access a row or a column.
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
- === Access a cell.
231
+ === Accessing a cell.
163
232
 
164
- Read a cell from a sheet object.
233
+ Reading a cell from a sheet object.
165
234
 
166
235
  sheet[0, 0] => first cell.
167
236
 
168
- Read a cell from a range object.
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
- Read the value of a cell.
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
- Write a cell
247
+ Writing a cell
179
248
 
180
249
  sheet[0,0] = "new_value"
181
250
 
182
251
 
183
- === Access a range of a row or column.
252
+ === Accessing a range of a row or column.
184
253
 
185
- Access a range of a row.
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
- Access a range of a column.
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
- === Add a sheet
265
+ === Adding a sheet.
197
266
 
198
- Add a new sheet.
267
+ Adding a new sheet.
199
268
 
200
269
  book.add_sheet
201
270
 
202
- Add a new sheet with a name.
271
+ Adding a new sheet with a name.
203
272
 
204
273
  book.add_sheet(:as => 'new_sheet')
205
274
 
206
- Add a new sheet with a name before another sheet.
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
- Add a copy of a sheet with a name after another sheet.
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
- Include robust_excel_ole.
346
+ Including robust_excel_ole.
218
347
 
219
348
  include RobustExcelOle
220
349
 
221
350
  === Example 1
222
351
 
223
- Open a book.
352
+ Opening a book.
224
353
 
225
354
  book = Book.open('simple.xls')
226
355
 
227
- Access a sheet via its name.
356
+ Accessing a sheet via its name.
228
357
 
229
358
  sheet = book['Sheet1']
230
359
 
231
- Change the first cell.
360
+ Changing the first cell.
232
361
 
233
362
  sheet[0,0] = "new"
234
363
 
235
- Save the book.
364
+ Saving the book.
236
365
 
237
366
  book.save
238
367
 
239
- Save the book with a different name, and overwrite if a file with this name exists.
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
- Close the book.
372
+ Closing the book.
244
373
 
245
374
  book.close
246
375
 
247
376
  === Example 2
248
377
 
249
- Open the book in a new Excel application and make it visible.
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
- book.open('simple.xls', :reuse => false, :visible => true)
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
- Add a copy of the first sheet after the second sheet.
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
- Open a new book with the same name in a new Excel. Leave the book that contains unsaved changes in the old Excel.
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 => :new_app)
426
+ new_book = Book.open('simple.xls', :if_unsaved => :new_excel)
260
427
 
261
- Access a sheet and change a cell.
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
- Open another book with the same name in the running Excel. The book that contains unsaved changes will be closed before.
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
- Add a sheet.
437
+ Adding a sheet.
271
438
 
272
439
  third_book.add_sheet
273
440
 
274
- Close the book without saving it.
441
+ Closing the book without saving it.
275
442
 
276
443
  third_book.close(:if_unsaved => :forget)
277
444
 
278
- Close the first book and save it before.
445
+ Closing the first book and saving it before.
279
446
 
280
447
  book.close(:if_unsaved => :save)
281
448
 
282
- === Example 3
449
+ === Example 4
283
450
 
284
- Open a book.
451
+ Opening a book.
285
452
 
286
453
  book1 = Book.open('simple.xls')
287
454
 
288
- Open a book with the same name in a different path. Close the old book.
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
- Change its cell.
459
+ Changing its cell.
293
460
 
294
461
  sheet = book2[0]
295
462
  sheet[0,0] = "new"
296
463
 
297
- Open a book with the same name in a different path. The old book that was modified will be saved and closed before.
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
- Open a book with the same name in a different path. The other book will be closed, because it does not contain unsaved changes.
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
- Close the book.
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.