robust_excel_ole 0.3.5 → 0.3.6
Sign up to get free protection for your applications and to get access to all the features.
- data/Changelog +33 -0
- data/README.rdoc +97 -35
- data/README_detail.rdoc +121 -53
- data/examples/edit_sheets/example_naming.rb +1 -0
- data/lib/reo_console.rb +52 -0
- data/lib/robust_excel_ole.rb +41 -7
- data/lib/robust_excel_ole/book.rb +327 -193
- data/lib/robust_excel_ole/bookstore.rb +33 -17
- data/lib/robust_excel_ole/excel.rb +280 -188
- data/lib/robust_excel_ole/sheet.rb +29 -16
- data/lib/robust_excel_ole/version.rb +1 -1
- data/lib/spec_helper.rb +1 -1
- data/reo.bat +1 -1
- data/spec/book_specs/book_all_spec.rb +22 -0
- data/spec/{book_close_spec.rb → book_specs/book_close_spec.rb} +14 -14
- data/spec/{book_misc_spec.rb → book_specs/book_misc_spec.rb} +38 -29
- data/spec/{book_open_spec.rb → book_specs/book_open_spec.rb} +40 -16
- data/spec/{book_save_spec.rb → book_specs/book_save_spec.rb} +173 -12
- data/spec/{book_sheet_spec.rb → book_specs/book_sheet_spec.rb} +8 -4
- data/spec/{book_spec.rb → book_specs/book_spec.rb} +456 -187
- data/spec/{book_subclass_spec.rb → book_specs/book_subclass_spec.rb} +4 -4
- data/spec/{book_unobtr_spec.rb → book_specs/book_unobtr_spec.rb} +64 -4
- data/spec/bookstore_spec.rb +11 -4
- data/spec/cell_spec.rb +7 -5
- data/spec/data/another_workbook.xls +0 -0
- data/spec/data/different_workbook.xls +0 -0
- data/spec/data/more_data/workbook.xls +0 -0
- data/spec/data/workbook.xls +0 -0
- data/spec/excel_spec.rb +367 -87
- data/spec/range_spec.rb +6 -4
- data/spec/robust_excel_ole_spec.rb +113 -0
- data/spec/sheet_spec.rb +42 -6
- metadata +16 -12
data/Changelog
ADDED
@@ -0,0 +1,33 @@
|
|
1
|
+
# Change Log
|
2
|
+
All notable changes to this project will be documented in this file.
|
3
|
+
|
4
|
+
## [0.3.6] - 2015-10-25
|
5
|
+
|
6
|
+
### Added
|
7
|
+
- Excel#recreate: reopening a closed Excel
|
8
|
+
- Excel::new(:reuse => <WIN32OLE_excel>):
|
9
|
+
uplifting an Excel represented as object of the class WIN32OLE to an object of the class Excel
|
10
|
+
- Excel#close, Excel::close_all: with managing unsaved workbooks
|
11
|
+
- Excel::kill_all
|
12
|
+
- Excel::excel_processes: yield Excel objects opened with RobustExcelOle
|
13
|
+
- Book::new: uplifting a WIN32OLE object to a Book object
|
14
|
+
- Subclassing for Sheet
|
15
|
+
- Method missing: error messages for dead objects
|
16
|
+
- trace to stdout or file
|
17
|
+
|
18
|
+
|
19
|
+
### Changed
|
20
|
+
|
21
|
+
## [0.3.5] - 2015-08-13
|
22
|
+
|
23
|
+
### Added
|
24
|
+
- Subclassing of Excel and Book
|
25
|
+
- Book#reopen: allows to reopen workbooks
|
26
|
+
- Book.inspect, Excel.inspect
|
27
|
+
- Excel#close
|
28
|
+
- Book_spec separated in managable pieces
|
29
|
+
|
30
|
+
### Changed
|
31
|
+
- removed cashing from Ranges.rb and Sheet.rb
|
32
|
+
- cells: (1,1) as origin (instead (0,0))
|
33
|
+
- bug fixes in application examples
|
data/README.rdoc
CHANGED
@@ -10,6 +10,7 @@ Goals:
|
|
10
10
|
- provide convenient methods for frequent (common) tasks
|
11
11
|
- support the use of simultaneously running Excel instances
|
12
12
|
- allow the presence of referenced libraries and provide some support for that
|
13
|
+
- supports EXCEL 2010, EXCEL 2007
|
13
14
|
|
14
15
|
This is work in progress.
|
15
16
|
|
@@ -73,18 +74,26 @@ Closing the workbook and saving it before if it has unsaved changes.
|
|
73
74
|
|
74
75
|
=== Reopening a workbook.
|
75
76
|
|
76
|
-
A special feature of robust_excel_ole is that it allows to reopen
|
77
|
+
A special feature of robust_excel_ole is that it allows to reopen workbooks after closing them.
|
77
78
|
|
78
79
|
book = Book.open('workbook.xls')
|
79
80
|
book.close
|
80
81
|
book.reopen
|
81
82
|
|
82
|
-
The closed
|
83
|
+
The closed workbook is now alive again, i.e. is open and responds to Excel methods.
|
84
|
+
This feature is a result of providing identity transparence and storing the file name.
|
83
85
|
|
84
|
-
|
85
|
-
|
86
|
+
=== The Book objects and transperence identity
|
87
|
+
|
88
|
+
An Excel file (or workbook) is represented by a Book object. A Book object is defined by the full name of the workbook and the Excel instance in which it is opened. RobustExcelOle aims to ensure identity transperency.
|
89
|
+
Identity transparence means that the same Book objects refer to the same Excel files, and vice versa.
|
86
90
|
In other words, a Book objects is a proxy of an Excel file.
|
87
91
|
|
92
|
+
=== Uplifting a workbook to a Book object
|
93
|
+
|
94
|
+
A Book object can be created when giving an Excel workbook.
|
95
|
+
|
96
|
+
book = Book.new(win32ole_workbook)
|
88
97
|
|
89
98
|
=== Saving a workbook.
|
90
99
|
|
@@ -94,18 +103,23 @@ Saving a workbook with a file name.
|
|
94
103
|
|
95
104
|
book.save_as('another_workbook.xls')
|
96
105
|
|
97
|
-
The
|
106
|
+
The options are +:if_exists+ and +if_obstructed+.
|
98
107
|
|
99
108
|
Saving a workbook and overwriting the file if it exists before.
|
100
109
|
|
101
110
|
book.save_as('another_workbook.xls', :if_exists => :overwrite)
|
102
111
|
|
112
|
+
If a workbook is blocking the workbook that should be saved, then the former one can be saved and closed before.
|
113
|
+
|
114
|
+
book = Book.open('workbook.xls')
|
115
|
+
book2 = Book.open('another_workbook.xls')
|
116
|
+
book2.save_as('dir/workbook.xls', :if_exists => :overwrite, :if_obstructed => :save)
|
103
117
|
|
104
118
|
=== Unobtrusively opening a workbook
|
105
119
|
|
106
|
-
The method +unobtrusively+ enables the user to read or modify a workbook, no matter if it is open in some Excel instance, if it is saved or unsaved, and if it is writable or not. When opening a workbook unobtrusively, its status remains unchanged. This status includes, whether the
|
120
|
+
The method +unobtrusively+ enables the user to read or modify a workbook, no matter if it is open in some Excel instance, if it is saved or unsaved, and if it is writable or not. When opening a workbook unobtrusively, its status remains unchanged. This status includes, whether the workbook is opened or closed, saved or unsaved, readonly or writable.
|
107
121
|
|
108
|
-
One option chooses the Excel instance in which a closed
|
122
|
+
One option chooses the Excel instance in which a closed workbook is opened. The options +:reuse (default) indicates that the closed workbook is opened in the Excel instance of the workbook, if it exists, or that another Excel instance is reused. The option +:hidden+ provokes that the closed workbook is opened in a separate Excel instance that is not visible and has no DisplayAlerts. Any following closed workbook would be opened in this Excel instance as well when using this option. Moreover, an Excel instance can be given directly where to open the closed workbook.
|
109
123
|
|
110
124
|
Further options are +:read_only+, +:readonly_excel+, and +:keep_open. The option +:readonly_excel+ chooses whether a book that is opened as ReadOnly and that shall be modified shall be opned as writable in the Excel instance where it was open so far, or if it shall be opened as writable in another running Excel instance, if such an Excel exists, or opened in a new Excel instance.
|
111
125
|
|
@@ -149,6 +163,27 @@ or
|
|
149
163
|
book.nvalue("name")
|
150
164
|
=> "value"
|
151
165
|
|
166
|
+
=== Activating a workbook.
|
167
|
+
|
168
|
+
Brings the window of a workbook to the foreground . Make it available for keyboard inputs and make the Excel instance visible.
|
169
|
+
|
170
|
+
book.activate
|
171
|
+
|
172
|
+
|
173
|
+
=== Making a workbook visible or invisible
|
174
|
+
|
175
|
+
Open a workbook and make the Excel instance visible.
|
176
|
+
|
177
|
+
book = Book.open('workbook.xls', :visivble => true)
|
178
|
+
|
179
|
+
Make the workbook invisible.
|
180
|
+
|
181
|
+
book.visible = false
|
182
|
+
|
183
|
+
Make the workbook visible
|
184
|
+
|
185
|
+
book.visible = true
|
186
|
+
|
152
187
|
=== Making an Excel visible or invisible, and enable and disable DisplayAlerts.
|
153
188
|
|
154
189
|
Make an Excel visible
|
@@ -287,11 +322,11 @@ Getting a running Excel instance and reusing it.
|
|
287
322
|
|
288
323
|
Reusing a running Excel instance, making it visible and turning on displayalerts.
|
289
324
|
|
290
|
-
|
325
|
+
excel2 = Excel.new(:reuse => true, :visible => true, :displayalerts => true).
|
291
326
|
|
292
|
-
|
327
|
+
Uplifting an Excel instance represented as WIN32OLE object to an Excel object
|
293
328
|
|
294
|
-
|
329
|
+
excel = Excel.new(:reuse => win32ole_object)
|
295
330
|
|
296
331
|
=== Making Excel visible or invisible
|
297
332
|
|
@@ -316,8 +351,6 @@ Turning DisplayAlerts off.
|
|
316
351
|
excel.displayalerts = false
|
317
352
|
|
318
353
|
Turning on and off in a block.
|
319
|
-
|
320
|
-
with_displayalerts
|
321
354
|
|
322
355
|
excel = Excel.create
|
323
356
|
excel.with_displayalerts true do
|
@@ -329,10 +362,39 @@ Turning on and off in a block.
|
|
329
362
|
excel = Excel.current
|
330
363
|
excel.close
|
331
364
|
|
365
|
+
Closing the Excel instance and terminating the Excel process
|
366
|
+
|
367
|
+
excel.close(:hard => true)
|
368
|
+
|
332
369
|
=== Closing all Excel instances.
|
333
370
|
|
334
371
|
Excel.close_all
|
335
372
|
|
373
|
+
Closing the Excel instances and terminating the Excel processes
|
374
|
+
|
375
|
+
Excel.close_all(:hard => true)
|
376
|
+
|
377
|
+
=== Terminating all Excel processes
|
378
|
+
|
379
|
+
Excel.kill_all
|
380
|
+
|
381
|
+
=== Recreating an Excel instance
|
382
|
+
|
383
|
+
Reopening the closed Excel instance. This includes reopening all workbooks that were open in that Excel instance.
|
384
|
+
|
385
|
+
excel.close
|
386
|
+
excel.recreate
|
387
|
+
|
388
|
+
Options are :visible and :displayalerts
|
389
|
+
|
390
|
+
excel.recreate(:visible => true, :displayalerts => true)
|
391
|
+
|
392
|
+
=== Providing Excel instances
|
393
|
+
|
394
|
+
Providing all Excel instances (opened via RobustExcelOle) as objects of the class Excel
|
395
|
+
|
396
|
+
Excel.excel_objects
|
397
|
+
|
336
398
|
=== Examples
|
337
399
|
|
338
400
|
=== Example 1
|
@@ -363,7 +425,7 @@ Closing the book.
|
|
363
425
|
|
364
426
|
=== Example 2
|
365
427
|
|
366
|
-
Opening a
|
428
|
+
Opening a workbook.
|
367
429
|
|
368
430
|
book = Book.open('workbook.xls')
|
369
431
|
|
@@ -381,25 +443,25 @@ Closing the books.
|
|
381
443
|
new_book.close
|
382
444
|
another_book.close
|
383
445
|
|
384
|
-
Reopening the
|
446
|
+
Reopening the workbook.
|
385
447
|
|
386
|
-
reopened_book =
|
448
|
+
reopened_book = book.reopen
|
387
449
|
|
388
|
-
The writable
|
450
|
+
The writable workbook is being prefered.
|
389
451
|
|
390
452
|
reopened_book === book
|
391
453
|
=> true
|
392
454
|
|
393
|
-
Opening another
|
394
|
-
Since the
|
395
|
-
According to :default_excel => :new a new Excel is created, and the
|
455
|
+
Opening another workbook.
|
456
|
+
Since the workbook was not open before, reopening the workbook fails and the :default_excel option applies.
|
457
|
+
According to :default_excel => :new a new Excel is created, and the workbook is opened there.
|
396
458
|
|
397
459
|
different_book = Book.open('different.xls', :default_excel => :new)
|
398
460
|
|
399
461
|
|
400
462
|
=== Example 3
|
401
463
|
|
402
|
-
Opening a
|
464
|
+
Opening a workbook.
|
403
465
|
|
404
466
|
book = Book.open('workbook.xls')
|
405
467
|
|
@@ -407,7 +469,7 @@ Adding a copy of the first sheet after the second sheet.
|
|
407
469
|
|
408
470
|
book.add_sheet(book[0], :as => 'Sheet1_copy', :after => book[1])
|
409
471
|
|
410
|
-
Opening a new
|
472
|
+
Opening a new workbook with the same name in a new Excel. Leave the workbook that contains unsaved changes in the old Excel.
|
411
473
|
|
412
474
|
new_book = Book.open('workbook.xls', :if_unsaved => :new_excel)
|
413
475
|
|
@@ -416,7 +478,7 @@ Accessing a sheet and change a cell.
|
|
416
478
|
sheet = new_book[0]
|
417
479
|
sheet[1,1] = "another"
|
418
480
|
|
419
|
-
Opening another
|
481
|
+
Opening another workbook with the same name in the running Excel. The book that contains unsaved changes will be closed before.
|
420
482
|
|
421
483
|
third_book = Book.open('workbook.xls', :if_unsaved => :forget)
|
422
484
|
|
@@ -424,21 +486,21 @@ Adding a sheet.
|
|
424
486
|
|
425
487
|
third_book.add_sheet
|
426
488
|
|
427
|
-
Closing the
|
489
|
+
Closing the workbook without saving it.
|
428
490
|
|
429
491
|
third_book.close(:if_unsaved => :forget)
|
430
492
|
|
431
|
-
Closing the first
|
493
|
+
Closing the first workbook and saving it before.
|
432
494
|
|
433
495
|
book.close(:if_unsaved => :save)
|
434
496
|
|
435
497
|
=== Example 4
|
436
498
|
|
437
|
-
Opening a
|
499
|
+
Opening a workbook.
|
438
500
|
|
439
501
|
book1 = Book.open('workbook.xls')
|
440
502
|
|
441
|
-
Opening a book with the same name in a different path. Close the old
|
503
|
+
Opening a book with the same name in a different path. Close the old workbook.
|
442
504
|
|
443
505
|
book2 = Book.open('more/workbook.xls', :if_obstructed => :forget)
|
444
506
|
|
@@ -447,22 +509,22 @@ Changing its cell.
|
|
447
509
|
sheet = book2[0]
|
448
510
|
sheet[1,1] = "new"
|
449
511
|
|
450
|
-
Opening a
|
512
|
+
Opening a workbook with the same name in a different path. The old workbook that was modified will be saved and closed before.
|
451
513
|
|
452
514
|
book3 = Book.open('workbook.xls', :if_obstructed => :save)
|
453
515
|
|
454
|
-
Opening a
|
516
|
+
Opening a workbook with the same name in a different path. The other workbook will be closed, because it does not contain unsaved changes.
|
455
517
|
|
456
518
|
book4 = Book.open('more/workbook.xls', :if_obstructed => :close_if_unsaved)
|
457
519
|
|
458
|
-
Closing the
|
520
|
+
Closing the workbook.
|
459
521
|
|
460
522
|
book4.close
|
461
523
|
|
462
524
|
|
463
525
|
=== Example 5
|
464
526
|
|
465
|
-
Opening a
|
527
|
+
Opening a workbook.
|
466
528
|
|
467
529
|
book = Book.open('workbook.xls')
|
468
530
|
|
@@ -471,14 +533,14 @@ Printing its first cell.
|
|
471
533
|
sheet = book[0]
|
472
534
|
p "1st cell: #{sheet[1,1].Value}"
|
473
535
|
|
474
|
-
Unobtrusively modify the
|
536
|
+
Unobtrusively modify the workbook.
|
475
537
|
|
476
538
|
Book.unobtrusively('workbook.xls') do |book|
|
477
539
|
sheet = book[0]
|
478
540
|
sheet[1,1] = 'simple'
|
479
541
|
end
|
480
542
|
|
481
|
-
The
|
543
|
+
The workbook is modified, but its status is unchanged.
|
482
544
|
|
483
545
|
new_sheet = book[0]
|
484
546
|
not (new_sheet[1,1].Value == sheet[1,1].Value)
|
@@ -497,12 +559,12 @@ For more details about usage: see link:https://github.com/Thomas008/robust_excel
|
|
497
559
|
robust_excel_ole started as a simple fork from tomiacannondale's wrap_excel adapted to Ruby 1.8.6.
|
498
560
|
The functionality of wrap_excel is optimised and extended by new features.
|
499
561
|
Most notable extensions include:
|
500
|
-
*
|
501
|
-
* a
|
562
|
+
* workbooks can be opened in already running Excel instances (instead of opening a new Excel whenever a book is opened)
|
563
|
+
* a workbook management system stores all workbooks that have been open. This workbook store is being used, e.g., for reopening a workbook that has been closed before. It provides transparency identity, i.e., equal Excel workbooks correspond to equal Book objects of RobustExcelOle.
|
502
564
|
|
503
565
|
Some features in robust_excel_ole that are not compatible with wrap_excel:
|
504
566
|
* +open+ uses by default a running Excel instance instead of creating a new one,
|
505
|
-
and opens a
|
567
|
+
and opens a workbook by default in writable mode instead of read_only
|
506
568
|
* +close+ closes the workbook instead of closing all workbooks and the Excel instance.
|
507
569
|
* +save_as+ instead of +save+.
|
508
570
|
|
data/README_detail.rdoc
CHANGED
@@ -10,6 +10,7 @@ Goals:
|
|
10
10
|
- provide convenient methods for frequent (common) tasks
|
11
11
|
- support the use of simultaneously running Excel instances
|
12
12
|
- allow the presence of referenced libraries and provide some support for that
|
13
|
+
- supports EXCEL 2010, EXCEL 2007
|
13
14
|
|
14
15
|
This is work in progress.
|
15
16
|
|
@@ -112,18 +113,28 @@ The option specifies: If the workbook is unsaved, then
|
|
112
113
|
|
113
114
|
=== Reopening a workbook.
|
114
115
|
|
115
|
-
A special feature of robust_excel_ole is that it allows to reopen
|
116
|
+
A special feature of robust_excel_ole is that it allows to reopen workbooks after closing them.
|
116
117
|
|
117
118
|
book = Book.open('workbook.xls')
|
118
119
|
book.close
|
119
120
|
book.reopen
|
120
121
|
|
121
|
-
The closed
|
122
|
+
The closed workbook is now alive again, i.e. is open and responds to Excel methods.
|
122
123
|
|
123
|
-
This feature is
|
124
|
-
|
124
|
+
This feature is a result of providing identity transparence and storing the file name.
|
125
|
+
|
126
|
+
=== The Book objects and transperence identity
|
127
|
+
|
128
|
+
An Excel file (or workbook) is represented by a Book object. A Book object is defined by the full name of the workbook and the Excel instance in which it is opened. RobustExcelOle aims to ensure identity transperency.
|
129
|
+
Identity transparence means that the same Book objects refer to the same Excel files, and vice versa.
|
125
130
|
In other words, a Book objects is a proxy of an Excel file.
|
126
131
|
|
132
|
+
=== Uplifting a workbook to a Book object
|
133
|
+
|
134
|
+
A Book object can be created when giving an Excel workbook.
|
135
|
+
|
136
|
+
book = Book.new(win32ole_workbook)
|
137
|
+
|
127
138
|
|
128
139
|
=== Saving a workbook.
|
129
140
|
|
@@ -131,41 +142,53 @@ Simple save.
|
|
131
142
|
|
132
143
|
book.save
|
133
144
|
|
134
|
-
Saving a
|
145
|
+
Saving a workbook with a file name.
|
135
146
|
|
136
147
|
book.save_as('another_workbook.xls')
|
137
148
|
|
138
149
|
Options are the following:
|
139
150
|
|
140
151
|
+:if_exists+:: +:raise+ (default), +:overwrite+, +:alert+
|
152
|
+
+:if_obstruced+:: +:raise (default), +:forget+, +:save+, +close_if_saved
|
141
153
|
|
142
154
|
The option +:if_exists+ :
|
143
155
|
|
144
|
-
If a
|
156
|
+
If a workbook with the file name already exists, then
|
145
157
|
|
146
158
|
+:raise+:: Raise an exeption. Don't write the file.
|
147
|
-
+:overwrite+:: Delete the existing file and write the file. If the
|
159
|
+
+:overwrite+:: Delete the existing file and write the file. If the workbook is open in an Excel instance, then raise an exception.
|
148
160
|
+:alert+:: Give the control to Excel.
|
149
161
|
|
162
|
+
Examples:
|
163
|
+
|
164
|
+
Saving a workbook and overwriting the file if it exists before.
|
165
|
+
|
166
|
+
book.save_as('another_workbook.xls', :if_exists => :overwrite)
|
167
|
+
|
168
|
+
If a workbook is blocking the workbook that should be saved, then the former one can be saved and closed before.
|
169
|
+
|
170
|
+
book = Book.open('workbook.xls')
|
171
|
+
book2 = Book.open('another_workbook.xls')
|
172
|
+
book2.save_as('dir/workbook.xls', :if_exists => :overwrite, :if_obstructed => :save)
|
150
173
|
|
151
174
|
=== Unobtrusively modifying a workbook
|
152
175
|
|
153
|
-
The method +unobtrusively+ enables the user to read or modify a workbook, no matter if it is open in some Excel instance, if it is saved or unsaved, and if it is writable or not. When opening a workbook unobtrusively, its status remains unchanged. This status includes, whether the
|
176
|
+
The method +unobtrusively+ enables the user to read or modify a workbook, no matter if it is open in some Excel instance, if it is saved or unsaved, and if it is writable or not. When opening a workbook unobtrusively, its status remains unchanged. This status includes, whether the workbook is opened or closed, saved or unsaved, readonly or writable.
|
154
177
|
|
155
|
-
One option chooses the Excel instance in which a closed
|
178
|
+
One option chooses the Excel instance in which a closed workbook is opened. The options +:reuse (default) indicates that the closed workbook is opened in the Excel instance of the workbook, if it exists, or that another Excel instance is reused. The option +:hidden+ provokes that the closed workbook is opened in a separate Excel instance that is not visible and has no DisplayAlerts. Any following closed workbook would be opened in this Excel instance as well when using this option. Moreover, an Excel instance can be given directly where to open the closed workbook.
|
156
179
|
|
157
180
|
Options are the following:
|
158
181
|
|
159
|
-
:reuse (default) : open a closed
|
160
|
-
:hidden : open a closed
|
182
|
+
:reuse (default) : open a closed workbook in the Excel instance of the workbook, if it exists, otherwise reuse another Excel
|
183
|
+
:hidden : open a closed workbook in one separate Excel instance that is not visible and has no displayaslerts
|
161
184
|
<excel-instance> : open a closed workbooks in the given Excel instance
|
162
185
|
|
163
|
-
+:read_only+:: Open the
|
164
|
-
+:readonly_excel+:: if the
|
186
|
+
+:read_only+:: Open the workbook unobtrusively for reading only (default: false)
|
187
|
+
+:readonly_excel+:: if the workbook is opened only as ReadOnly and shall be modified, then
|
165
188
|
true: close it and open it as writable in the excel instance where it was open so far
|
166
189
|
false (default) open it as writable in another running excel instance, if it exists,
|
167
190
|
otherwise open in a new excel instance
|
168
|
-
+:keep_open+:: let the
|
191
|
+
+:keep_open+:: let the workbook open after unobtrusively opening (default: false)
|
169
192
|
|
170
193
|
Book.unobtrusively('workbook.xls') do |book|
|
171
194
|
# some modification
|
@@ -206,6 +229,26 @@ or
|
|
206
229
|
book.nvalue("name")
|
207
230
|
=> "value"
|
208
231
|
|
232
|
+
=== Activating a workbook.
|
233
|
+
|
234
|
+
Bring the focus to a workbook. Make it available for keyboard inputs and make the Excel instance visible.
|
235
|
+
|
236
|
+
book.activate
|
237
|
+
|
238
|
+
=== Making a workbook visible or invisible
|
239
|
+
|
240
|
+
Open a workbook and make the Excel instance visible.
|
241
|
+
|
242
|
+
book = Book.open('workbook.xls', :visivble => true)
|
243
|
+
|
244
|
+
Make the workbook invisible.
|
245
|
+
|
246
|
+
book.visible = false
|
247
|
+
|
248
|
+
Make the workbook visible
|
249
|
+
|
250
|
+
book.visible = true
|
251
|
+
|
209
252
|
=== Making an Excel visible or invisible, and enable and disable DisplayAlerts.
|
210
253
|
|
211
254
|
Make an Excel visible
|
@@ -347,11 +390,11 @@ Getting a running Excel instance and reusing it.
|
|
347
390
|
|
348
391
|
Reusing a running Excel instance, making it visible and turning on displayalerts.
|
349
392
|
|
350
|
-
|
393
|
+
excel2 = Excel.new(:reuse => true, :visible => true, :displayalerts => true).
|
351
394
|
|
352
|
-
|
395
|
+
Uplifting an Excel instance represented as WIN32OLE object to an Excel object
|
353
396
|
|
354
|
-
|
397
|
+
excel = Excel.new(:reuse => win32ole_object)
|
355
398
|
|
356
399
|
=== Making Excel visible or invisible
|
357
400
|
|
@@ -359,7 +402,6 @@ Making Excel visible.
|
|
359
402
|
|
360
403
|
excel = Excel.create
|
361
404
|
excel.visible = true
|
362
|
-
puts "visible" if excel.visible
|
363
405
|
|
364
406
|
Making Excel invisible
|
365
407
|
|
@@ -371,29 +413,55 @@ Turning DisplayAlerts on.
|
|
371
413
|
|
372
414
|
excel = Excel.create
|
373
415
|
excel.displayalerts = true
|
374
|
-
puts "allows displayalerts" if excel.displayalerts
|
375
416
|
|
376
417
|
Turning DisplayAlerts off.
|
377
418
|
|
378
419
|
excel.displayalerts = false
|
379
420
|
|
380
421
|
Turning on and off in a block.
|
381
|
-
|
382
|
-
with_displayalerts
|
383
422
|
|
384
423
|
excel = Excel.create
|
385
424
|
excel.with_displayalerts true do
|
386
425
|
book = Book.open('workbook.xls')
|
387
426
|
end
|
388
427
|
|
428
|
+
=== Closing an Excel
|
429
|
+
|
430
|
+
excel = Excel.current
|
431
|
+
excel.close
|
432
|
+
|
433
|
+
Closing the Excel instance and terminating the Excel process
|
434
|
+
|
435
|
+
excel.close(:hard => true)
|
436
|
+
|
389
437
|
=== Closing all Excel instances.
|
390
438
|
|
391
439
|
Excel.close_all
|
392
440
|
|
393
|
-
|
441
|
+
Closing the Excel instances and terminating the Excel processes
|
442
|
+
|
443
|
+
Excel.close_all(:hard => true)
|
444
|
+
|
445
|
+
=== Terminating all Excel processes
|
446
|
+
|
447
|
+
Excel.kill_all
|
448
|
+
|
449
|
+
=== Recreating an Excel instance
|
450
|
+
|
451
|
+
Reopening the closed Excel instance. This includes reopening all workbooks that were open in that Excel instance.
|
394
452
|
|
395
|
-
excel = Excel.current
|
396
453
|
excel.close
|
454
|
+
excel.recreate
|
455
|
+
|
456
|
+
Options are :visible and :displayalerts
|
457
|
+
|
458
|
+
excel.recreate(:visible => true, :displayalerts => true)
|
459
|
+
|
460
|
+
=== Providing Excel instances
|
461
|
+
|
462
|
+
Providing all Excel instances (opened via RobustExcelOle) as objects of the class Excel
|
463
|
+
|
464
|
+
Excel.excel_objects
|
397
465
|
|
398
466
|
|
399
467
|
=== Examples
|
@@ -404,7 +472,7 @@ Including robust_excel_ole.
|
|
404
472
|
|
405
473
|
=== Example 1
|
406
474
|
|
407
|
-
Opening a
|
475
|
+
Opening a workbook.
|
408
476
|
|
409
477
|
book = Book.open('workbook.xls')
|
410
478
|
|
@@ -416,57 +484,57 @@ Changing the first cell.
|
|
416
484
|
|
417
485
|
sheet[1,1] = "new"
|
418
486
|
|
419
|
-
Saving the
|
487
|
+
Saving the workbook.
|
420
488
|
|
421
489
|
book.save
|
422
490
|
|
423
|
-
Saving the
|
491
|
+
Saving the workbook with a different name, and overwrite if a file with this name exists.
|
424
492
|
|
425
493
|
book.save_as('different_workbook.xls', :if_exists => :overwrite)
|
426
494
|
|
427
|
-
Closing the
|
495
|
+
Closing the workbook.
|
428
496
|
|
429
497
|
book.close
|
430
498
|
|
431
499
|
=== Example 2
|
432
500
|
|
433
|
-
Opening a
|
501
|
+
Opening a workbook.
|
434
502
|
|
435
503
|
book = Book.open('workbook.xls')
|
436
504
|
|
437
|
-
Opening the
|
505
|
+
Opening the workbook in a new Excel instance and make it visible.
|
438
506
|
|
439
507
|
new_book = Book.open('workbook.xls', :force_excel => :new, :visible => true)
|
440
508
|
|
441
|
-
Opening the
|
509
|
+
Opening the workbook in a given Excel instance.
|
442
510
|
|
443
511
|
another_book = Book.open('workbook.xls', :force_excel => book.excel)
|
444
512
|
|
445
|
-
Closing the
|
513
|
+
Closing the workbooks.
|
446
514
|
|
447
515
|
book.close
|
448
516
|
new_book.close
|
449
517
|
another_book.close
|
450
518
|
|
451
|
-
Reopening the
|
519
|
+
Reopening the workbook.
|
452
520
|
|
453
|
-
reopened_book =
|
521
|
+
reopened_book = book.reopen
|
454
522
|
|
455
523
|
The writable book is being prefered.
|
456
524
|
|
457
525
|
reopened_book == book
|
458
526
|
=> true
|
459
527
|
|
460
|
-
Opening another
|
461
|
-
Since the
|
462
|
-
According to :default_excel => :new a new Excel is created, and the
|
528
|
+
Opening another workbook.
|
529
|
+
Since the workbook was not open before, reopening the workbook fails and the :default_excel option applies.
|
530
|
+
According to :default_excel => :new a new Excel is created, and the workbook is opened there.
|
463
531
|
|
464
532
|
different_book = Book.open('different.xls', :default_excel => :new)
|
465
533
|
|
466
534
|
|
467
535
|
=== Example 3
|
468
536
|
|
469
|
-
Opening a
|
537
|
+
Opening a workbook.
|
470
538
|
|
471
539
|
book = Book.open('workbook.xls')
|
472
540
|
|
@@ -474,9 +542,9 @@ Adding a copy of the first sheet after the second sheet.
|
|
474
542
|
|
475
543
|
book.add_sheet(book[0], :as => 'Sheet1_copy', :after => book[1])
|
476
544
|
|
477
|
-
Close the
|
545
|
+
Close the workbook.
|
478
546
|
|
479
|
-
Opening a new
|
547
|
+
Opening a new workbook with the same name in a new Excel. Leave the workbook that contains unsaved changes in the old Excel.
|
480
548
|
|
481
549
|
new_book = Book.open('workbook.xls', :if_unsaved => :new_excel)
|
482
550
|
|
@@ -485,7 +553,7 @@ Accessing a sheet and change a cell.
|
|
485
553
|
sheet = new_book[0]
|
486
554
|
sheet[1,1] = "another"
|
487
555
|
|
488
|
-
Opening another
|
556
|
+
Opening another workbook with the same name in the running Excel. The workbook that contains unsaved changes will be closed before.
|
489
557
|
|
490
558
|
third_book = Book.open('workbook.xls', :if_unsaved => :forget)
|
491
559
|
|
@@ -493,21 +561,21 @@ Adding a sheet.
|
|
493
561
|
|
494
562
|
third_book.add_sheet
|
495
563
|
|
496
|
-
Closing the
|
564
|
+
Closing the workbook without saving it.
|
497
565
|
|
498
566
|
third_book.close(:if_unsaved => :forget)
|
499
567
|
|
500
|
-
Closing the first
|
568
|
+
Closing the first workbook and saving it before.
|
501
569
|
|
502
570
|
book.close(:if_unsaved => :save)
|
503
571
|
|
504
572
|
=== Example 4
|
505
573
|
|
506
|
-
Opening a
|
574
|
+
Opening a workbook.
|
507
575
|
|
508
576
|
book1 = Book.open('workbook.xls')
|
509
577
|
|
510
|
-
Opening a
|
578
|
+
Opening a workbook with the same name in a different path. Close the old workbook.
|
511
579
|
|
512
580
|
book2 = Book.open('more/workbook.xls', :if_obstructed => :forget)
|
513
581
|
|
@@ -516,22 +584,22 @@ Changing its cell.
|
|
516
584
|
sheet = book2[0]
|
517
585
|
sheet[1,1] = "new"
|
518
586
|
|
519
|
-
Opening a
|
587
|
+
Opening a workbook with the same name in a different path. The old workbook that was modified will be saved and closed before.
|
520
588
|
|
521
589
|
book3 = Book.open('workbook.xls', :if_obstructed => :save)
|
522
590
|
|
523
|
-
Opening a
|
591
|
+
Opening a workbook with the same name in a different path. The other workbook will be closed, because it does not contain unsaved changes.
|
524
592
|
|
525
593
|
book4 = Book.open('more/workbook.xls', :if_obstructed => :close_if_unsaved)
|
526
594
|
|
527
|
-
Closing the
|
595
|
+
Closing the workbook.
|
528
596
|
|
529
597
|
book4.close
|
530
598
|
|
531
599
|
|
532
600
|
=== Example 5
|
533
601
|
|
534
|
-
Opening a
|
602
|
+
Opening a workbook.
|
535
603
|
|
536
604
|
book = Book.open('workbook.xls')
|
537
605
|
|
@@ -540,14 +608,14 @@ Printing its first cell.
|
|
540
608
|
sheet = book[0]
|
541
609
|
p "1st cell: #{sheet[1,1].Value}"
|
542
610
|
|
543
|
-
Unobtrusively modify the
|
611
|
+
Unobtrusively modify the workbook.
|
544
612
|
|
545
613
|
Book.unobtrusively('workbook.xls') do |book|
|
546
614
|
sheet = book[0]
|
547
615
|
sheet[1,1] = 'simple'
|
548
616
|
end
|
549
617
|
|
550
|
-
The
|
618
|
+
The workbook is modified, but its status is unchanged.
|
551
619
|
|
552
620
|
new_sheet = book[0]
|
553
621
|
not (new_sheet[1,1].Value == sheet[1,1].Value)
|
@@ -562,12 +630,12 @@ The book is modified, but its status is unchanged.
|
|
562
630
|
robust_excel_ole started as a simple fork from tomiacannondale's wrap_excel adapted to Ruby 1.8.6.
|
563
631
|
The functionality of wrap_excel is optimised and extended by new features.
|
564
632
|
Most notable extensions include:
|
565
|
-
*
|
566
|
-
* a
|
633
|
+
* workbooks can be opened in already running Excel instances (instead of opening a new Excel whenever a workbook is opened)
|
634
|
+
* a workbook management system stores all workbooks that have been open. This book store is being used, e.g., for reopening a workbook that has been closed before. It provides transparency identity, i.e., equal Excel workbooks correspond to equal Book objects of RobustExcelOle.
|
567
635
|
|
568
636
|
Some features in robust_excel_ole that are not compatible with wrap_excel:
|
569
637
|
* +open+ uses by default a running Excel instance instead of creating a new one,
|
570
|
-
and opens a
|
638
|
+
and opens a workbook by default in writable mode instead of read_only
|
571
639
|
* +close+ closes the workbook instead of closing all workbooks and the Excel instance.
|
572
640
|
* +save_as+ instead of +save+.
|
573
641
|
|