robust_excel_ole 0.6.2 → 1.0
Sign up to get free protection for your applications and to get access to all the features.
- data/README.rdoc +140 -175
- data/lib/robust_excel_ole/book.rb +3 -2
- data/lib/robust_excel_ole/excel.rb +162 -142
- data/lib/robust_excel_ole/reo_common.rb +2 -2
- data/lib/robust_excel_ole/version.rb +1 -1
- data/robust_excel_ole.gemspec +7 -2
- data/spec/book_spec.rb +2 -2
- data/spec/book_specs/book_open_spec.rb +5 -2
- data/spec/book_specs/book_save_spec.rb +5 -24
- data/spec/book_specs/book_sheet_spec.rb +1 -1
- data/spec/data/another_workbook.xls +0 -0
- data/spec/data/different_workbook.xls +0 -0
- data/spec/data/workbook.xls +0 -0
- data/spec/excel_spec.rb +232 -272
- data/spec/reo_common_spec.rb +1 -1
- metadata +12 -10
- data/README_detail.rdoc +0 -810
data/spec/reo_common_spec.rb
CHANGED
metadata
CHANGED
@@ -1,13 +1,12 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: robust_excel_ole
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
hash:
|
4
|
+
hash: 15
|
5
5
|
prerelease: false
|
6
6
|
segments:
|
7
|
+
- 1
|
7
8
|
- 0
|
8
|
-
|
9
|
-
- 2
|
10
|
-
version: 0.6.2
|
9
|
+
version: "1.0"
|
11
10
|
platform: ruby
|
12
11
|
authors:
|
13
12
|
- traths
|
@@ -15,7 +14,7 @@ autorequire:
|
|
15
14
|
bindir: bin
|
16
15
|
cert_chain: []
|
17
16
|
|
18
|
-
date: 2016-
|
17
|
+
date: 2016-12-07 00:00:00 +01:00
|
19
18
|
default_executable:
|
20
19
|
dependencies:
|
21
20
|
- !ruby/object:Gem::Dependency
|
@@ -34,7 +33,11 @@ dependencies:
|
|
34
33
|
version: 2.6.0
|
35
34
|
type: :development
|
36
35
|
version_requirements: *id001
|
37
|
-
description:
|
36
|
+
description: |-
|
37
|
+
RobustExcelOle automates modifying, reading and writing Excel files.
|
38
|
+
It supports simultaneously running Excel instances and user interactions.
|
39
|
+
RobustExcelOle deals with various cases of Excel (and user) behaviour,
|
40
|
+
supplies workarounds for some Excel bugs, and supports referenced libraries
|
38
41
|
email:
|
39
42
|
- Thomas.Raths@gmx.net
|
40
43
|
executables: []
|
@@ -52,7 +55,6 @@ files:
|
|
52
55
|
- Guardfile
|
53
56
|
- LICENSE
|
54
57
|
- README.rdoc
|
55
|
-
- README_detail.rdoc
|
56
58
|
- Rakefile
|
57
59
|
- TodoList.md
|
58
60
|
- examples/edit_sheets/example_access_sheets_and_cells.rb
|
@@ -132,8 +134,8 @@ files:
|
|
132
134
|
- version.rb
|
133
135
|
has_rdoc: true
|
134
136
|
homepage: https://github.com/Thomas008/robust_excel_ole
|
135
|
-
licenses:
|
136
|
-
|
137
|
+
licenses:
|
138
|
+
- MIT
|
137
139
|
post_install_message:
|
138
140
|
rdoc_options:
|
139
141
|
- --main
|
@@ -168,6 +170,6 @@ rubyforge_project: robust_excel_ole
|
|
168
170
|
rubygems_version: 1.3.7
|
169
171
|
signing_key:
|
170
172
|
specification_version: 3
|
171
|
-
summary: RobustExcelOle
|
173
|
+
summary: RobustExcelOle automates processing Excel files in Windows by using the win32ole library.
|
172
174
|
test_files: []
|
173
175
|
|
data/README_detail.rdoc
DELETED
@@ -1,810 +0,0 @@
|
|
1
|
-
= RobustExcelOle
|
2
|
-
|
3
|
-
robust_excel_ole helps to automate modifying and reading Excel files.
|
4
|
-
This is done by sending VBA methods via Win32OLE.
|
5
|
-
Moreover, robust_excel_ole implements a management system of Excel files and Excel instances and keeps track of all workbooks.
|
6
|
-
|
7
|
-
Goals:
|
8
|
-
- support both fully automated operations as well as simultaneous user interactions during the automation
|
9
|
-
- be able to cope with all cases of Excel (and user) behaviour, encapsulate errors
|
10
|
-
- provide convenient methods for frequent (common) tasks
|
11
|
-
- support the use of simultaneously running Excel instances
|
12
|
-
- allow the presence of referenced libraries and provide some support for that
|
13
|
-
- supports EXCEL 2010, EXCEL 2007
|
14
|
-
|
15
|
-
This is work in progress.
|
16
|
-
|
17
|
-
== Requirements
|
18
|
-
|
19
|
-
* Ruby 1.8.6 or higher
|
20
|
-
|
21
|
-
== Install
|
22
|
-
|
23
|
-
gem install robust_excel_ole
|
24
|
-
|
25
|
-
== Usage
|
26
|
-
|
27
|
-
include RobustExcelOle
|
28
|
-
|
29
|
-
=== Opening a workbook.
|
30
|
-
|
31
|
-
Example:
|
32
|
-
|
33
|
-
book = Book.open('workbook.xls')
|
34
|
-
|
35
|
-
Opening a workbook with a block.
|
36
|
-
The semantics is similar to, e.g., +File.open+.
|
37
|
-
|
38
|
-
Book.open('workbook.xls') do |book|
|
39
|
-
# do something
|
40
|
-
end
|
41
|
-
|
42
|
-
Options are the following:
|
43
|
-
|
44
|
-
+:default_excel+:: open the workbook in the Excel instance where it was opened before most recently,
|
45
|
-
if the book was opened before and this Excel instance is alive. Otherwise open it in the current (+:current+, or +:active+, or +:reuse+), a new (+:new+) or a given Excel instance (default: +:current+)
|
46
|
-
+:force_excel+:: open the workbook in the current (+:current+, or +:active+, or +:reuse+), a new (+:new+) or given Excel instance
|
47
|
-
+:if_absent+:: specify behaviour if the workbook with the given file name does not exist if the workbook does not exist (default: +create+)
|
48
|
-
+:if_unsaved+:: specify behaviour if the workbook was unsaved (default: +new_excel+)
|
49
|
-
+:if_obstructed+:: specidy behaviour if the workbook is blocked by another book (default: +new_excel+)
|
50
|
-
+:read_only+:: open in read-only mode (default: +false+)
|
51
|
-
+:check_compatibility:: check compatibility when saving
|
52
|
-
+:visible+:: makes the window of the workbook visible or invisible (default: +true+)
|
53
|
-
|
54
|
-
The option +:defaut_excel+ :
|
55
|
-
|
56
|
-
If the workbook was open before, then open it in the Excel instance where it was open before most recently. If the workbook cannot be reopened, i.e., the book was not opened before, or the Excel is not alive anymore,
|
57
|
-
then
|
58
|
-
|
59
|
-
+:current+ (or +:active+, or +:reuse+:): Connect to the current (the first opened) Excel instance, if it exists, otherwise open a new Excel.
|
60
|
-
+:new+:: Open in a new Excel.
|
61
|
-
[instance]:: Open in a given Excel instance.
|
62
|
-
|
63
|
-
The option +:force_excel :
|
64
|
-
|
65
|
-
No matter if the workbook was open before, or the Excel instance is alive
|
66
|
-
|
67
|
-
+:current+ (or +:active+, or +:reuse+): Open the current (the first opened) Excel instance
|
68
|
-
+:new+:: Open in a new Excel instance.
|
69
|
-
[instance]:: Open in a given Excel instance.
|
70
|
-
|
71
|
-
The option +:if_absent :
|
72
|
-
|
73
|
-
If the Excel file does not exists, then
|
74
|
-
|
75
|
-
+:create+:: Create a new Excel file
|
76
|
-
+:raise+:: Raise an exception.
|
77
|
-
|
78
|
-
The option +:if_unsaved+ :
|
79
|
-
|
80
|
-
If a workbook contains unsaved changes and a new workbook with the same file name shall be opened, then
|
81
|
-
|
82
|
-
+:raise+:: Raise an exeption. Don't open the workbook.
|
83
|
-
+:accept+:: Let the unsaved workbook open.
|
84
|
-
+:forget+:: Discard any changes and reopen the workbook.
|
85
|
-
+:new_excel+:: Open the new workbook in a new Excel instance
|
86
|
-
+:alert+:: Give control to Excel.
|
87
|
-
|
88
|
-
The option +:if_obstructed+ :
|
89
|
-
|
90
|
-
If a workbook is open and a new workbook with same name and a different path is open, then
|
91
|
-
|
92
|
-
+:raise+:: Raise an exception. Don't open the workbook.
|
93
|
-
+:forget+:: Close the old workbook, open the new workbook.
|
94
|
-
+:save+:: Save the old workbook, close it, open the new workbook
|
95
|
-
+:close_if_saved+:: Close the old workbook and open the new workbook, if the old workbook is saved, otherwise raise an exception.
|
96
|
-
+:new_excel+:: Open the new workbook in a new Excel instance.
|
97
|
-
|
98
|
-
Here are a few examples:
|
99
|
-
|
100
|
-
Opening a workbook in the Excel instance where it was opened before most recently, if it was opened before and this Excel instance is alive. Otherwise opening it in a running Excel, if it exists, or in a new Excel.
|
101
|
-
|
102
|
-
Opening a workbook in the Excel instance where it was opened before most recently, if it was opened before and this Excel instance is alive. Otherwise opening it in a new Excel instance.
|
103
|
-
|
104
|
-
book = Book.open('workbook.xls', :default_excel => :new)
|
105
|
-
|
106
|
-
Opening a workbook in the Excel instance where it was opened before most recently, if it was opened before and this Excel instance is alive. Otherwise opening it in a given Excel instance.
|
107
|
-
|
108
|
-
book = Book.open('workbook.xls', :default_excel => excel1)
|
109
|
-
|
110
|
-
Opening a workbook in a new Excel instance, no matter if the workbook was opened before and if the old Excel instance is alive.
|
111
|
-
|
112
|
-
book = Book.open('workbook.xls', :force_excel => :new)
|
113
|
-
|
114
|
-
Opening a workbook in a given Excel instance, no matter if the workbook was opened before and if the old Excel instance is alive.
|
115
|
-
|
116
|
-
book = Book.open('workbook.xls', :force_excel => excel1)
|
117
|
-
|
118
|
-
Opening a workbook in a new Excel instance and make it visible.
|
119
|
-
|
120
|
-
book = Book.open('workbook.xls', :force_excel => :new, :visible => true)
|
121
|
-
|
122
|
-
If a workbook contains unsaved changes and a workbook with the same filename shall be opened, then Excel gives an alert message.
|
123
|
-
The option +:if_unsaved+ manages this case. For example, +:if_unsaved+ => +:accept+ indicates that the workbook remains open, but no error is raised, i.e. the program can continue.
|
124
|
-
|
125
|
-
book = Book.open('workbook.xls', :if_unsaved => :accept)
|
126
|
-
|
127
|
-
If a workbook is open and a workbook with the same name but in different path shall be opened, then the first workbook blocks opening the other workbook. The option +:if_obstructed+ handles this situation. For example, +:if_obstructed+ => +:forget+ causes the old workbook to close and to open the new workbook.
|
128
|
-
|
129
|
-
book = Book.open('path/workbook.xls', :if_obstructed => :forget)
|
130
|
-
|
131
|
-
Opening linked workbooks for EXCEL 2007 is supported
|
132
|
-
|
133
|
-
=== Closing a workbook.
|
134
|
-
|
135
|
-
Simple close.
|
136
|
-
|
137
|
-
book.close
|
138
|
-
|
139
|
-
There is one option: +:if_unsaved+ . It can have one of the following values:
|
140
|
-
|
141
|
-
+:raise+ (default), +:save+, +:forget+, +:alert+
|
142
|
-
|
143
|
-
The option specifies: If the workbook is unsaved, then
|
144
|
-
|
145
|
-
+:save+:: Save the workbook before closing it.
|
146
|
-
+:raise+:: Raise an exception. Don't close the workbook.
|
147
|
-
+:forget+:: Close the workbook.
|
148
|
-
+:alert+:: Give control to Excel.
|
149
|
-
|
150
|
-
=== Reopening a workbook.
|
151
|
-
|
152
|
-
A special feature of robust_excel_ole is that it allows to reopen workbooks after closing them.
|
153
|
-
|
154
|
-
book = Book.open('workbook.xls')
|
155
|
-
book.close
|
156
|
-
book.reopen
|
157
|
-
|
158
|
-
The closed workbook is now alive again, i.e. is open and responds to Excel methods.
|
159
|
-
|
160
|
-
This feature is a result of providing identity transparence and storing the file name.
|
161
|
-
|
162
|
-
=== The Book objects and transperence identity
|
163
|
-
|
164
|
-
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.
|
165
|
-
Identity transparence means that the same Book objects refer to the same Excel files, and vice versa.
|
166
|
-
In other words, a Book objects is a proxy of an Excel file.
|
167
|
-
|
168
|
-
=== Promoting a workbook to a Book object
|
169
|
-
|
170
|
-
A Book object can be created when giving an Excel workbook.
|
171
|
-
|
172
|
-
book = Book.new(win32ole_workbook)
|
173
|
-
|
174
|
-
|
175
|
-
=== Saving a workbook.
|
176
|
-
|
177
|
-
Simple save.
|
178
|
-
|
179
|
-
book.save
|
180
|
-
|
181
|
-
Saving a workbook with a file name.
|
182
|
-
|
183
|
-
book.save_as('another_workbook.xls')
|
184
|
-
|
185
|
-
Options are the following:
|
186
|
-
|
187
|
-
+:if_exists+:: +:raise+ (default), +:overwrite+, +:alert+
|
188
|
-
+:if_obstruced+:: +:raise (default), +:forget+, +:save+, +close_if_saved
|
189
|
-
|
190
|
-
The option +:if_exists+ :
|
191
|
-
|
192
|
-
If a workbook with the file name already exists, then
|
193
|
-
|
194
|
-
+:raise+:: Raise an exeption. Don't write the file.
|
195
|
-
+:overwrite+:: Delete the existing file and write the file. If the workbook is open in an Excel instance, then raise an exception.
|
196
|
-
+:alert+:: Give the control to Excel.
|
197
|
-
|
198
|
-
Examples:
|
199
|
-
|
200
|
-
Saving a workbook and overwriting the file if it exists before.
|
201
|
-
|
202
|
-
book.save_as('another_workbook.xls', :if_exists => :overwrite)
|
203
|
-
|
204
|
-
If a workbook is blocking the workbook that should be saved, then the former one can be saved and closed before.
|
205
|
-
|
206
|
-
book = Book.open('workbook.xls')
|
207
|
-
book2 = Book.open('another_workbook.xls')
|
208
|
-
book2.save_as('dir/workbook.xls', :if_exists => :overwrite, :if_obstructed => :save)
|
209
|
-
|
210
|
-
=== Unobtrusively modifying a workbook
|
211
|
-
|
212
|
-
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.
|
213
|
-
|
214
|
-
One option chooses the Excel instance in which a closed workbook is opened. The option +:current+ (or +:active+, or +: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.
|
215
|
-
|
216
|
-
Options are the following:
|
217
|
-
|
218
|
-
+:current+ (or +:active, or +:reuse+:): (default) : open a closed workbook in the Excel instance where it was opened most recently, if such an Excel instance exists, otherwise open it in the current (first opened) Excel instance
|
219
|
-
+:hidden+:: : open a closed workbook in one separate Excel instance that is not visible and has no displayalerts
|
220
|
-
<excel-instance> : open a closed workbooks in the given Excel instance
|
221
|
-
|
222
|
-
+:read_only+:: Open the workbook unobtrusively for reading only (default: false)
|
223
|
-
+:readonly_excel+:: if the workbook is opened only as ReadOnly and shall be modified, then
|
224
|
-
true: close it and open it as writable in the excel instance where it was open so far
|
225
|
-
false (default) open it as writable in another running excel instance, if it exists,
|
226
|
-
otherwise open in a new excel instance
|
227
|
-
+:keep_open+:: let the workbook open after unobtrusively opening (default: false)
|
228
|
-
+:visible+:: make the window of the workbook visible (default: false)
|
229
|
-
+:check_compatibility+:: checks compatibility when saving
|
230
|
-
|
231
|
-
Book.unobtrusively('workbook.xls') do |book|
|
232
|
-
# some modification
|
233
|
-
sheet = book[0]
|
234
|
-
sheet[1,1] = "c"
|
235
|
-
end
|
236
|
-
|
237
|
-
The methods +for_reading+ and +for_modifying+ indicate unobtrusively reading or modifying.
|
238
|
-
|
239
|
-
Book.for_modifying('workbook.xls') do |book|
|
240
|
-
# some modification
|
241
|
-
sheet = book[0]
|
242
|
-
sheet[1,1] = "c"
|
243
|
-
end
|
244
|
-
|
245
|
-
|
246
|
-
=== Checking whether the referenced Excel workbook responds to methods.
|
247
|
-
|
248
|
-
book.alive?
|
249
|
-
|
250
|
-
=== Getting and setting the contents of a range.
|
251
|
-
|
252
|
-
|
253
|
-
Getting the contents of a range.
|
254
|
-
|
255
|
-
book["name"]
|
256
|
-
=> "value"
|
257
|
-
|
258
|
-
or
|
259
|
-
|
260
|
-
book.nameval("name")
|
261
|
-
=> "value"
|
262
|
-
|
263
|
-
Setting the contents of a range.
|
264
|
-
|
265
|
-
book["name"] = "value"
|
266
|
-
|
267
|
-
or
|
268
|
-
|
269
|
-
book.set_nameval("name") = "value"
|
270
|
-
|
271
|
-
=== Bringing a workbook to the focus.
|
272
|
-
|
273
|
-
Make the Excel instance and the workbook visible and make it available for keyboard inputs.
|
274
|
-
|
275
|
-
book.focus
|
276
|
-
|
277
|
-
=== Make the window of the workbook visible.
|
278
|
-
|
279
|
-
Open a workbook and make the Excel instance visible.
|
280
|
-
|
281
|
-
book = Book.open('workbook.xls', :visivble => true)
|
282
|
-
|
283
|
-
Make the window of the workbook visible.
|
284
|
-
|
285
|
-
book.visible = false
|
286
|
-
|
287
|
-
Makes the window of the workbook visible.
|
288
|
-
|
289
|
-
book.visible = true
|
290
|
-
|
291
|
-
=== Making an Excel visible or invisible, and enable and disable DisplayAlerts.
|
292
|
-
|
293
|
-
Make an Excel visible.
|
294
|
-
|
295
|
-
book.excel.visible = true
|
296
|
-
|
297
|
-
Enable DisplayAlerts.
|
298
|
-
|
299
|
-
book.excel.displayalerts = true
|
300
|
-
|
301
|
-
Options: +true+ -> enable DisplayAlerts , +false+ -> Disable DisplayAlerts
|
302
|
-
|
303
|
-
|
304
|
-
=== Accessing a sheet.
|
305
|
-
|
306
|
-
Accessing the first sheet.
|
307
|
-
|
308
|
-
sheet = book.sheet(1)
|
309
|
-
|
310
|
-
or
|
311
|
-
|
312
|
-
sheet = book.first_sheet
|
313
|
-
|
314
|
-
Accessing the last sheet.
|
315
|
-
|
316
|
-
sheet = book.last_sheet
|
317
|
-
|
318
|
-
Accessing a sheet with the sheet name.
|
319
|
-
|
320
|
-
sheet = book.sheet('Sheet1')
|
321
|
-
|
322
|
-
Accessing sheet objects using the methods Book#each.
|
323
|
-
|
324
|
-
book.each do |sheet|
|
325
|
-
# do something with sheet
|
326
|
-
end
|
327
|
-
|
328
|
-
|
329
|
-
=== Accessing a row or a column.
|
330
|
-
|
331
|
-
A sheet object is enumerable. Use the methods Sheet#each_column, Sheet#each_row or Sheet#each.
|
332
|
-
|
333
|
-
sheet.each do |cell|
|
334
|
-
# do something with cell
|
335
|
-
# read every row every column
|
336
|
-
end
|
337
|
-
|
338
|
-
sheet.each_row do |row|
|
339
|
-
# do something with row
|
340
|
-
end
|
341
|
-
|
342
|
-
sheet.each_column do |column|
|
343
|
-
# do something with column
|
344
|
-
end
|
345
|
-
|
346
|
-
=== Accessing a cell.
|
347
|
-
|
348
|
-
Reading a cell from a sheet object.
|
349
|
-
|
350
|
-
sheet[1, 1] => first cell.
|
351
|
-
|
352
|
-
Reading a cell from a range object.
|
353
|
-
|
354
|
-
row_range[1] => first cell in row_range
|
355
|
-
column_range[1] => second cell in column_range
|
356
|
-
|
357
|
-
Methods to cell are just delegated as VBA methods. Example:
|
358
|
-
|
359
|
-
Reading the value of a cell.
|
360
|
-
|
361
|
-
cell = sheet[1,1]
|
362
|
-
cell.Value => value of the cell.
|
363
|
-
|
364
|
-
Writing a cell
|
365
|
-
|
366
|
-
sheet[1,1] = "new_value"
|
367
|
-
|
368
|
-
|
369
|
-
=== Accessing a range of a row or column.
|
370
|
-
|
371
|
-
Accessing a range of a row.
|
372
|
-
|
373
|
-
sheet.row_range(1) => first row
|
374
|
-
sheet.row_range(1, 1..3 ) => first three cells of the first row
|
375
|
-
|
376
|
-
Accessing a range of a column.
|
377
|
-
|
378
|
-
sheet.col_range(3) => third column
|
379
|
-
sheet.col_range(3, 1..2) => first two cells of the third column
|
380
|
-
|
381
|
-
=== Naming a cell
|
382
|
-
|
383
|
-
Naming or renaming a cell range given its address.
|
384
|
-
|
385
|
-
book.set_name(1,1,"name")
|
386
|
-
|
387
|
-
=== Getting and setting the contents of a named range
|
388
|
-
|
389
|
-
Getting the value of a range.
|
390
|
-
|
391
|
-
sheet[name]
|
392
|
-
|
393
|
-
or
|
394
|
-
|
395
|
-
sheet.nameval(name)
|
396
|
-
|
397
|
-
Setting the value of a range.
|
398
|
-
|
399
|
-
book[name] = value
|
400
|
-
|
401
|
-
or
|
402
|
-
|
403
|
-
book.set_nameval(name,value)
|
404
|
-
|
405
|
-
=== Getting and setting the contents of a named range directly
|
406
|
-
|
407
|
-
Getting the value of a range.
|
408
|
-
|
409
|
-
sheet.rangeval(name)
|
410
|
-
|
411
|
-
Setting the value of a range.
|
412
|
-
|
413
|
-
book.set_rangeval(name,value)
|
414
|
-
|
415
|
-
=== Copying or Adding an sheet.
|
416
|
-
|
417
|
-
Adding (appending) an empty sheet.
|
418
|
-
|
419
|
-
book.add_empty_sheet
|
420
|
-
|
421
|
-
Adding an empty sheet and naming it.
|
422
|
-
|
423
|
-
book.add_empty_sheet(:as => 'sheet_name')
|
424
|
-
|
425
|
-
Adding an empty sheet with a name before another sheet.
|
426
|
-
|
427
|
-
book.add_empty_sheet(:as => 'new_name', :before => another_sheet)
|
428
|
-
|
429
|
-
Copying a sheet and adding (appending) it.
|
430
|
-
|
431
|
-
book.copy_sheet sheet
|
432
|
-
|
433
|
-
Copying a sheet after a another sheet and naming it.
|
434
|
-
|
435
|
-
book.copy_sheet(sheet, :as => 'new_name', :after => another_sheet)
|
436
|
-
|
437
|
-
Copying a sheet, if a sheet is given, adding an empty sheet, if no sheet is given.
|
438
|
-
|
439
|
-
book.add_or_copy_sheet
|
440
|
-
|
441
|
-
book.add_or_copy_sheet(sheet, :as => 'new_name', :after => another_sheet)
|
442
|
-
|
443
|
-
=== Creating and reusing an Excel instance.
|
444
|
-
|
445
|
-
Creating a new Excel.
|
446
|
-
|
447
|
-
excel1 = Excel.create
|
448
|
-
|
449
|
-
or
|
450
|
-
|
451
|
-
excel1 = Excel.new(:reuse => false)
|
452
|
-
|
453
|
-
Resusing a runnin Excel instance.
|
454
|
-
|
455
|
-
excel2 = Excel.current
|
456
|
-
|
457
|
-
or
|
458
|
-
|
459
|
-
excel2 = Excel.new(:reuse => true)
|
460
|
-
|
461
|
-
Options are +:reuse+ (+true+, +false+), +:visible+ (+true+, +false+) and +:displayalerts+ (+true+, +false+, +:if_visible+).
|
462
|
-
|
463
|
-
Promoting an Excel instance represented as WIN32OLE object to an Excel object
|
464
|
-
|
465
|
-
excel = Excel.new(win32ole_object)
|
466
|
-
|
467
|
-
=== Making a Excel visible or invisible
|
468
|
-
|
469
|
-
Creating a new Excel and making it visible.
|
470
|
-
|
471
|
-
excel1 = Excel.create(:visible => true)
|
472
|
-
|
473
|
-
or
|
474
|
-
|
475
|
-
excel1 = Excel.new(:reuse => false, :visible => true)
|
476
|
-
|
477
|
-
Reusing a Excel and making it invisible.
|
478
|
-
|
479
|
-
excel2 = Excel.current(:reuse => false, :visible => false)
|
480
|
-
|
481
|
-
or
|
482
|
-
|
483
|
-
excel2 = Excel.new(:reuse => false, :visible => false)
|
484
|
-
|
485
|
-
=== Enabling or disabling DisplayAlerts
|
486
|
-
|
487
|
-
Enabling DisplayAlerts.
|
488
|
-
|
489
|
-
excel3 = Excel.new(:reuse => true, :displayalerts => true)
|
490
|
-
|
491
|
-
Disabling DisplayAlerts.
|
492
|
-
|
493
|
-
excel3 = Excel.current(:reuse => true, :displayalerts => false)
|
494
|
-
|
495
|
-
Enabling DisplayAlerts whenever the Excel instance is visible.
|
496
|
-
|
497
|
-
excel3 = Excel.current(:reuse => true, :displayalerts => :if_visible)
|
498
|
-
|
499
|
-
=== Bringing an Excel instance to the focus
|
500
|
-
|
501
|
-
Set the window of an Excel instance to the foreground.
|
502
|
-
|
503
|
-
=== Closing an Excel
|
504
|
-
|
505
|
-
excel = Excel.current
|
506
|
-
excel.close
|
507
|
-
|
508
|
-
The options are +:if_unsaved+ and +:hard+ . Values for :if_unsaved+ are +:raise+, +:save+, +:forget+ and +:keep_open+.
|
509
|
-
|
510
|
-
Closing the Excel instance, saving unsaved workbooks and terminating the Excel process hard.
|
511
|
-
|
512
|
-
excel.close(:if_unsaved => :save, :hard => true)
|
513
|
-
|
514
|
-
=== Closing Excel instances opened via RobustExcelOle
|
515
|
-
|
516
|
-
Excel.close_all
|
517
|
-
|
518
|
-
The options are +:if_unsaved+ and +:hard+ . Values for :if_unsaved+ are +:raise+, +:save+, and +:forget+. Example:
|
519
|
-
|
520
|
-
Closing all Excel instances, saving unsaved workbooks and terminating the Excel processes softly.
|
521
|
-
|
522
|
-
Excel.close_all(:if_unsaved => :save, :hard => false)
|
523
|
-
|
524
|
-
=== Recreating an Excel instance
|
525
|
-
|
526
|
-
Reopening the closed Excel instance. This includes reopening all workbooks that were open in that Excel instance.
|
527
|
-
|
528
|
-
excel.close
|
529
|
-
excel.recreate
|
530
|
-
|
531
|
-
Options are :visible and :displayalerts
|
532
|
-
|
533
|
-
excel.recreate(:visible => true, :displayalerts => true)
|
534
|
-
|
535
|
-
=== Providing Excel instances
|
536
|
-
|
537
|
-
Providing all Excel instances (opened via RobustExcelOle) as objects of the class Excel
|
538
|
-
|
539
|
-
Excel.excel_objects
|
540
|
-
|
541
|
-
|
542
|
-
=== Making Excel visible or invisible
|
543
|
-
|
544
|
-
Making Excel visible.
|
545
|
-
|
546
|
-
excel = Excel.create
|
547
|
-
excel.visible = true
|
548
|
-
|
549
|
-
Making Excel invisible
|
550
|
-
|
551
|
-
excel.visible = false
|
552
|
-
|
553
|
-
=== Turning on or off Displayalerts.
|
554
|
-
|
555
|
-
Turning DisplayAlerts on.
|
556
|
-
|
557
|
-
excel = Excel.create
|
558
|
-
excel.displayalerts = true
|
559
|
-
|
560
|
-
Turning DisplayAlerts off.
|
561
|
-
|
562
|
-
excel.displayalerts = false
|
563
|
-
|
564
|
-
Turning on and off in a block.
|
565
|
-
|
566
|
-
excel = Excel.create
|
567
|
-
excel.with_displayalerts true do
|
568
|
-
book = Book.open('workbook.xls')
|
569
|
-
end
|
570
|
-
|
571
|
-
=== Setting Calculation mode.
|
572
|
-
|
573
|
-
Setting calculation mode to manual. Options are +:manual+ and +:automatic+
|
574
|
-
The calculation mode is not reset after the block.
|
575
|
-
|
576
|
-
excel = Excel.create
|
577
|
-
book = Book.open('workbook.xls')
|
578
|
-
excel.with_calculation(:manual) do
|
579
|
-
# do something
|
580
|
-
end
|
581
|
-
|
582
|
-
=== Getting and setting the contents of a named range in an Excel application
|
583
|
-
|
584
|
-
excel = Excel.create
|
585
|
-
book = Book.open('another_workbook.xls')
|
586
|
-
|
587
|
-
Getting the value of a range.
|
588
|
-
|
589
|
-
excel[name]
|
590
|
-
|
591
|
-
or
|
592
|
-
|
593
|
-
excel.nameval(name)
|
594
|
-
|
595
|
-
Setting the value of a range.
|
596
|
-
|
597
|
-
excel[name] = value
|
598
|
-
|
599
|
-
or
|
600
|
-
|
601
|
-
excel.set_nameval(name,value)
|
602
|
-
|
603
|
-
=== Getting and setting the contents of a named range in an Excel application directly
|
604
|
-
|
605
|
-
Getting the value of a range.
|
606
|
-
|
607
|
-
excel.rangeval(name)
|
608
|
-
|
609
|
-
Setting the value of a range.
|
610
|
-
|
611
|
-
excel.set_rangeval(name,value)
|
612
|
-
|
613
|
-
|
614
|
-
=== Examples
|
615
|
-
|
616
|
-
Including robust_excel_ole.
|
617
|
-
|
618
|
-
include RobustExcelOle
|
619
|
-
|
620
|
-
=== Example 1
|
621
|
-
|
622
|
-
Opening a workbook.
|
623
|
-
|
624
|
-
book = Book.open('workbook.xls')
|
625
|
-
|
626
|
-
Accessing a sheet via its name.
|
627
|
-
|
628
|
-
sheet = book['Sheet1']
|
629
|
-
|
630
|
-
Changing the first cell.
|
631
|
-
|
632
|
-
sheet[1,1] = "new"
|
633
|
-
|
634
|
-
Saving the workbook.
|
635
|
-
|
636
|
-
book.save
|
637
|
-
|
638
|
-
Saving the workbook with a different name, and overwrite if a file with this name exists.
|
639
|
-
|
640
|
-
book.save_as('different_workbook.xls', :if_exists => :overwrite)
|
641
|
-
|
642
|
-
Closing the workbook.
|
643
|
-
|
644
|
-
book.close
|
645
|
-
|
646
|
-
=== Example 2
|
647
|
-
|
648
|
-
Opening a workbook.
|
649
|
-
|
650
|
-
book = Book.open('workbook.xls')
|
651
|
-
|
652
|
-
Opening the workbook in a new Excel instance and make it visible.
|
653
|
-
|
654
|
-
new_book = Book.open('workbook.xls', :force_excel => :new, :visible => true)
|
655
|
-
|
656
|
-
Opening the workbook in a given Excel instance.
|
657
|
-
|
658
|
-
another_book = Book.open('workbook.xls', :force_excel => book.excel)
|
659
|
-
|
660
|
-
Closing the workbooks.
|
661
|
-
|
662
|
-
book.close
|
663
|
-
new_book.close
|
664
|
-
another_book.close
|
665
|
-
|
666
|
-
Reopening the workbook.
|
667
|
-
|
668
|
-
reopened_book = book.reopen
|
669
|
-
|
670
|
-
The writable book is being prefered.
|
671
|
-
|
672
|
-
reopened_book == book
|
673
|
-
=> true
|
674
|
-
|
675
|
-
Opening another workbook.
|
676
|
-
Since the workbook was not open before, reopening the workbook fails and the :default_excel option applies.
|
677
|
-
According to :default_excel => :new a new Excel is created, and the workbook is opened there.
|
678
|
-
|
679
|
-
different_book = Book.open('different.xls', :default_excel => :new)
|
680
|
-
|
681
|
-
|
682
|
-
=== Example 3
|
683
|
-
|
684
|
-
Opening a workbook.
|
685
|
-
|
686
|
-
book = Book.open('workbook.xls')
|
687
|
-
|
688
|
-
Adding a copy of the first sheet after the second sheet.
|
689
|
-
|
690
|
-
book.add_sheet(book[0], :as => 'Sheet1_copy', :after => book[1])
|
691
|
-
|
692
|
-
Close the workbook.
|
693
|
-
|
694
|
-
Opening a new workbook with the same name in a new Excel. Leave the workbook that contains unsaved changes in the old Excel.
|
695
|
-
|
696
|
-
new_book = Book.open('workbook.xls', :if_unsaved => :new_excel)
|
697
|
-
|
698
|
-
Accessing a sheet and change a cell.
|
699
|
-
|
700
|
-
sheet = new_book[0]
|
701
|
-
sheet[1,1] = "another"
|
702
|
-
|
703
|
-
Opening another workbook with the same name in the running Excel. The workbook that contains unsaved changes will be closed before.
|
704
|
-
|
705
|
-
third_book = Book.open('workbook.xls', :if_unsaved => :forget)
|
706
|
-
|
707
|
-
Adding a sheet.
|
708
|
-
|
709
|
-
third_book.add_sheet
|
710
|
-
|
711
|
-
Closing the workbook without saving it.
|
712
|
-
|
713
|
-
third_book.close(:if_unsaved => :forget)
|
714
|
-
|
715
|
-
Closing the first workbook and saving it before.
|
716
|
-
|
717
|
-
book.close(:if_unsaved => :save)
|
718
|
-
|
719
|
-
=== Example 4
|
720
|
-
|
721
|
-
Opening a workbook.
|
722
|
-
|
723
|
-
book1 = Book.open('workbook.xls')
|
724
|
-
|
725
|
-
Opening a workbook with the same name in a different path. Close the old workbook.
|
726
|
-
|
727
|
-
book2 = Book.open('more/workbook.xls', :if_obstructed => :forget)
|
728
|
-
|
729
|
-
Changing its cell.
|
730
|
-
|
731
|
-
sheet = book2[0]
|
732
|
-
sheet[1,1] = "new"
|
733
|
-
|
734
|
-
Opening a workbook with the same name in a different path. The old workbook that was modified will be saved and closed before.
|
735
|
-
|
736
|
-
book3 = Book.open('workbook.xls', :if_obstructed => :save)
|
737
|
-
|
738
|
-
Opening a workbook with the same name in a different path. The other workbook will be closed, because it does not contain unsaved changes.
|
739
|
-
|
740
|
-
book4 = Book.open('more/workbook.xls', :if_obstructed => :close_if_unsaved)
|
741
|
-
|
742
|
-
Closing the workbook.
|
743
|
-
|
744
|
-
book4.close
|
745
|
-
|
746
|
-
|
747
|
-
=== Example 5
|
748
|
-
|
749
|
-
Opening a workbook.
|
750
|
-
|
751
|
-
book = Book.open('workbook.xls')
|
752
|
-
|
753
|
-
Printing its first cell.
|
754
|
-
|
755
|
-
sheet = book[0]
|
756
|
-
p "1st cell: #{sheet[1,1].Value}"
|
757
|
-
|
758
|
-
Unobtrusively modify the workbook.
|
759
|
-
|
760
|
-
Book.unobtrusively('workbook.xls') do |book|
|
761
|
-
sheet = book[0]
|
762
|
-
sheet[1,1] = 'simple'
|
763
|
-
end
|
764
|
-
|
765
|
-
The workbook is modified, but its status is unchanged.
|
766
|
-
|
767
|
-
new_sheet = book[0]
|
768
|
-
not (new_sheet[1,1].Value == sheet[1,1].Value)
|
769
|
-
=> true
|
770
|
-
|
771
|
-
book.saved
|
772
|
-
=> true
|
773
|
-
|
774
|
-
|
775
|
-
=== Development
|
776
|
-
|
777
|
-
robust_excel_ole started as a simple fork from tomiacannondale's wrap_excel adapted to Ruby 1.8.6.
|
778
|
-
The functionality of wrap_excel is optimised and extended by new features.
|
779
|
-
Most notable extensions include:
|
780
|
-
* workbooks can be opened in already running Excel instances (instead of opening a new Excel whenever a workbook is opened)
|
781
|
-
* 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.
|
782
|
-
|
783
|
-
Some features in robust_excel_ole that are not compatible with wrap_excel:
|
784
|
-
* +open+ uses by default a running Excel instance instead of creating a new one,
|
785
|
-
and opens a workbook by default in writable mode instead of read_only
|
786
|
-
* +close+ closes the workbook instead of closing all workbooks and the Excel instance.
|
787
|
-
* +save_as+ instead of +save+.
|
788
|
-
|
789
|
-
|
790
|
-
=== Want to do more things
|
791
|
-
|
792
|
-
All RobustExcelOle objects include the win32ole instance.
|
793
|
-
If you want to do something that not provide a function, you can use win32ole methods.
|
794
|
-
|
795
|
-
== Support
|
796
|
-
|
797
|
-
This is work in progress. Please contact us and to report issues and feature requests to github Issues.
|
798
|
-
https://github.com/Thomas008/robust_excel_ole/issues
|
799
|
-
|
800
|
-
== Collaborate
|
801
|
-
|
802
|
-
Please pull request on github.
|
803
|
-
|
804
|
-
== Author
|
805
|
-
|
806
|
-
thomas mailto:Thomas.Raths@gmx.net
|
807
|
-
|
808
|
-
== License
|
809
|
-
|
810
|
-
MIT License. For more imformation, please see LICENSE.
|