robust_excel_ole 1.33 → 1.37
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.gitignore +1 -0
- data/Changelog +25 -2
- data/README.rdoc +44 -205
- data/docs/README_excel.rdoc +5 -6
- data/docs/README_listobjects.rdoc +8 -15
- data/docs/README_open.rdoc +53 -27
- data/docs/README_ranges.rdoc +7 -10
- data/docs/README_save_close.rdoc +4 -5
- data/docs/README_sheet.rdoc +4 -8
- data/examples/introductory_examples/example_introductory.rb +1 -1
- data/examples/introductory_examples/example_open.rb +1 -1
- data/examples/modifying_sheets/example_access_sheets_and_cells.rb +1 -1
- data/examples/modifying_sheets/example_add_names.rb +1 -1
- data/examples/modifying_sheets/example_listobjects.rb +2 -2
- data/examples/modifying_sheets/example_ranges.rb +1 -1
- data/lib/robust_excel_ole/excel.rb +128 -32
- data/lib/robust_excel_ole/general.rb +18 -6
- data/lib/robust_excel_ole/list_object.rb +30 -5
- data/lib/robust_excel_ole/list_row.rb +75 -20
- data/lib/robust_excel_ole/range.rb +13 -27
- data/lib/robust_excel_ole/range_owners.rb +24 -17
- data/lib/robust_excel_ole/version.rb +1 -1
- data/lib/robust_excel_ole/workbook.rb +173 -91
- data/lib/robust_excel_ole/worksheet.rb +3 -1
- data/robust_excel_ole.gemspec +0 -1
- data/spec/bookstore_spec.rb +1 -2
- data/spec/data/more_data/workbook.xls +0 -0
- data/spec/data/workbook.xls +0 -0
- data/spec/data/workbook_linked3.xlsm +0 -0
- data/spec/data/workbook_listobjects.xlsx +0 -0
- data/spec/data/workbook_unsaved.xlsm +0 -0
- data/spec/excel_spec.rb +16 -6
- data/spec/general_spec.rb +1 -2
- data/spec/list_object_spec.rb +26 -9
- data/spec/list_row_spec.rb +34 -6
- data/spec/more_data/workbook.xls +0 -0
- data/spec/range_spec.rb +12 -3
- data/spec/workbook_spec.rb +3 -3
- data/spec/workbook_specs/workbook_misc_spec.rb +258 -4
- data/spec/workbook_specs/workbook_open_spec.rb +369 -20
- data/spec/workbook_specs/workbook_unobtr_spec.rb +226 -61
- data/spec/worksheet_spec.rb +10 -2
- metadata +5 -16
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 646308c3740c8716d9fb91b9c0288edc6e915c060bdd713401980608d412119a
|
4
|
+
data.tar.gz: 379a3bd099724e9cd6adc2542d804d4f4737eafc47742892dbc1ba4914f7b7c2
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: '02308d88008a6e7d5362b0c793f1ab4e55025b7df0d19741dbe66775450f672b654c9766ac3e49d6ec840d497b9fa39befd1f66e6d20e5a5539d6cf3eefbc276'
|
7
|
+
data.tar.gz: 874eaf4089951eb94ac101699198e35981b72084036eb171ec70eb69dc2c135951138f773844b945ff7f4ebbd8d3a4020f3bdaf3f4286f165334e270ada23118
|
data/.gitignore
CHANGED
data/Changelog
CHANGED
@@ -1,6 +1,29 @@
|
|
1
1
|
# Change Log
|
2
2
|
All notable changes to this project will be documented in this file.
|
3
3
|
|
4
|
+
## [1.37] 2021-30-11
|
5
|
+
|
6
|
+
### Added
|
7
|
+
- Excel#visible,displayalerts
|
8
|
+
|
9
|
+
## [1.36] 2021-29-10
|
10
|
+
|
11
|
+
### Added
|
12
|
+
- Workbook.open: option if_blocked: :accept
|
13
|
+
- ListRow#methods, respond_to?, alive?
|
14
|
+
- Range#workbook, ListObject#workbook, ListRow#workbook
|
15
|
+
- Workbook#writable=
|
16
|
+
|
17
|
+
### Changed
|
18
|
+
- Workbook#open instead of Workbook#reopen
|
19
|
+
|
20
|
+
|
21
|
+
## [1.35] 2021-24-07
|
22
|
+
|
23
|
+
## [1.34] 2021-21-06
|
24
|
+
|
25
|
+
## [1.34] 2021-15-06
|
26
|
+
|
4
27
|
## [1.33] 2021-01-06
|
5
28
|
|
6
29
|
## [1.32] 2021-23-04
|
@@ -125,14 +148,14 @@ All notable changes to this project will be documented in this file.
|
|
125
148
|
- Workbook#save, save_as: removed parameter :discoloring
|
126
149
|
- RangeOwners#set_namevalue, set_namevalue_glob, Worksheet#set_cellval:
|
127
150
|
removed optional parameter for color
|
128
|
-
- Workbook
|
151
|
+
- Workbook.open: removed option :excel => :reserved_new
|
129
152
|
|
130
153
|
|
131
154
|
## [1.11]
|
132
155
|
|
133
156
|
### Added
|
134
157
|
- Range#==, Worksheet#==
|
135
|
-
- Workbook
|
158
|
+
- Workbook.open: options :if_blocked is synonym to :if_obstructed
|
136
159
|
- Simplified Code
|
137
160
|
|
138
161
|
## [1.10]
|
data/README.rdoc
CHANGED
@@ -1,39 +1,19 @@
|
|
1
|
-
= News
|
2
|
-
|
3
|
-
== New Interface of #[]
|
4
|
-
|
5
|
-
Worksheet#[] now returns a value instead of a range, e.g.
|
6
|
-
|
7
|
-
worksheet[1,1]
|
8
|
-
# => "foo"
|
9
|
-
|
10
|
-
Transformation: To yield the range, write range() instead of (). For example,
|
11
|
-
|
12
|
-
worksheet.range(1,1)
|
13
|
-
|
14
|
-
or
|
15
|
-
|
16
|
-
worksheet.range([1,1])
|
17
|
-
|
18
|
-
This returns the range of cell with address 1,1.
|
19
|
-
|
20
|
-
With this new interface, we want to be compatible with the standard syntax of other known Excel libraries, e.g. +spreadsheet+ or +axlsx+.
|
21
|
-
|
22
1
|
= RobustExcelOle
|
23
2
|
|
24
3
|
RobustExcelOle helps controlling Excel.
|
25
4
|
This obviously includes standard tasks like reading and writing Excel workbooks.
|
5
|
+
|
6
|
+
RobustExcelOle objects wrap WIN32OLE objects, like workbooks, worksheets and ranges.
|
7
|
+
All applicable VBA methods can be sent to those objects.
|
8
|
+
For solving complex tasks, convenient methods are added.
|
9
|
+
|
26
10
|
The gem is designed to manage simultaneously running Excel instances, even with simultanously happening user interactions.
|
11
|
+
It supports handling workbooks across those Excel instances by keeping track of workbooks and instances. Conflicts are managed before Excel notices.
|
27
12
|
|
28
13
|
RobustExcelOle deals with various cases of Excel (and user) behaviour, and
|
29
14
|
supplies workarounds for some Excel and JRuby bugs.
|
30
15
|
|
31
|
-
|
32
|
-
|
33
|
-
Library references are supported.
|
34
|
-
|
35
|
-
RobustExcelOle works by sending VBA methods via WIN32OlE.
|
36
|
-
Therefore, it runs on Windows only.
|
16
|
+
Because it uses VBA methods, RobustExcelOle runs on Windows only.
|
37
17
|
|
38
18
|
== Features
|
39
19
|
|
@@ -122,27 +102,26 @@ Now we want to write a new value into this cell.
|
|
122
102
|
|
123
103
|
workbook['firstcell'] = "new"
|
124
104
|
|
125
|
-
Then we'll save the workbook.
|
105
|
+
Then we'll save and close the workbook.
|
126
106
|
|
127
107
|
workbook.save
|
108
|
+
workbook.close
|
128
109
|
|
129
|
-
===
|
110
|
+
=== Unobtrusively opening workbooks
|
130
111
|
|
131
112
|
RobustExcelOle allows unobtrusively reading and modifying workbooks, i.e. accessing workbooks without changing their "status". The status comprises whether the workbook is open or closed, saved or unsaved, read-only or writable, visible or invisible, whether the calculation mode is manual or automatic, and checking compatibility is done or not done.
|
132
113
|
|
133
|
-
Workbook.unobtrusively('spec/data/workbook.xls') do |workbook|
|
134
|
-
# do something
|
135
|
-
end
|
136
|
-
|
137
114
|
Workbook.for_modifying('spec/data/workbook.xls') do |workbook|
|
138
|
-
|
115
|
+
workbook.sheet(1)[1,1] = "bar"
|
139
116
|
end
|
140
117
|
|
141
118
|
Workbook.for_reading('spec/data/workbook.xls') do |workbook|
|
142
|
-
|
119
|
+
value = workbook.sheet(1)[1,1]
|
143
120
|
end
|
144
121
|
|
145
|
-
|
122
|
+
=== More features about creating and opening workbooks
|
123
|
+
|
124
|
+
We can create a new, empty workbook.
|
146
125
|
|
147
126
|
Workbook.create('spec/data/new_workbook.xls', visible: true)
|
148
127
|
|
@@ -152,77 +131,25 @@ Moreover, we can open the workbook using a block, similar to, e.g., +File.open+.
|
|
152
131
|
# do something
|
153
132
|
end
|
154
133
|
|
155
|
-
Once we have a workbook, we can set some options, e.g.
|
156
|
-
|
157
|
-
workbook.for_this_workbook(visible: true, read_only: false)
|
158
|
-
|
159
|
-
We can also open the workbook and provide the options in one step, e.g.
|
160
|
-
|
161
|
-
workbook = Workbook.open('spec/data/workbook.xls', visible: true)
|
162
|
-
|
163
|
-
or, using abbreviations,
|
164
|
-
|
165
|
-
workbook = Workbook.open('spec/data/workbook.xls', v: true)
|
166
|
-
|
167
134
|
Note that +Workbook.open+ can also connect to workbooks which were not opened via RobustExcelOle (but had been opened before by some user).
|
168
135
|
|
169
|
-
For more details about opening workbooks see {README_open}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_open.rdoc]
|
170
|
-
|
171
|
-
|
136
|
+
For more details about opening workbooks see {README_open}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_open.rdoc].
|
137
|
+
For saving and closing workbooks see
|
138
|
+
{README_save_close}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_save_close.rdoc].
|
172
139
|
|
173
|
-
|
174
|
-
|
175
|
-
or save the workbook under a different name.
|
176
|
-
|
177
|
-
workbook.save_as('spec/data/new_workbook.xls')
|
178
|
-
|
179
|
-
Finally we can close the workbook
|
180
|
-
|
181
|
-
workbook.save
|
182
|
-
|
183
|
-
or save and close the workbook in one step.
|
184
|
-
|
185
|
-
workbook.close(if_unsaved: :save)
|
186
|
-
|
187
|
-
For more details about saving and closing workbooks see
|
188
|
-
{README_save_close}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_save_close.rdoc]
|
189
|
-
|
190
|
-
|
191
|
-
=== Using Excel instances
|
192
|
-
|
193
|
-
We can start a new Excel instance with
|
194
|
-
|
195
|
-
excel1 = Excel.create
|
196
|
-
|
197
|
-
or
|
198
|
-
|
199
|
-
excel1 = Excel.new(reuse: false)
|
200
|
-
|
201
|
-
We can also obtain an Excel object by connecting to the already running Excel instance.
|
202
|
-
|
203
|
-
excel2 = Excel.current
|
204
|
-
|
205
|
-
or
|
206
|
-
|
207
|
-
excel2 = Excel.new(reuse: true)
|
208
|
-
|
209
|
-
We close the Excel instance using
|
210
|
-
|
211
|
-
excel1.close
|
212
|
-
|
213
|
-
Closed Excel instances can be reopened.
|
214
|
-
|
215
|
-
excel1.recreate(reopen_workbooks: true, visible: true)
|
140
|
+
=== Managing conflicts with unsaved and blocking workbooks
|
216
141
|
|
217
|
-
|
142
|
+
RobustExcelOle enables processing workbooks, while supporting user's interactions: The commands enable to open, close, reopen, read, modify, write and save Excel workbooks, without the need of the user's interaction, and even without the user noticing. Thus, while running a script containing RobustExcelOle commands, the user can open and process workbooks in any Excel instances at any time. RobustExcelOle manages the complex cases of conflicts that might occur such that the user does not need to interfere and the script can continue.
|
218
143
|
|
219
|
-
|
144
|
+
For example, suppose we want to process a list of workbooks. RobustExcelOle allows to rapidly open, manipulate, close and save these workbooks. Now assume, the workbook "workbook.xls" is being processed, while the user has already opened this workbook, has modified but not saved it yet. Excel would prompt a message and ask the user what to do. RobustExcelOle solves this conflict by using an option that states whether the changes of the user should be saved (accepted) or discarded (forgotten) before opening the workbook, e.g.
|
220
145
|
|
221
|
-
|
146
|
+
workbook = Workbook.open('workbook.xls', if_unsaved: :accept)
|
222
147
|
|
223
|
-
|
148
|
+
Similarly, if the user has opened a workbook that has the same name but a different path, the conflict can be solved via an option.
|
224
149
|
|
225
|
-
|
150
|
+
workbook1 = Workbook.open('spec/data/workbook.xls')
|
151
|
+
# do something
|
152
|
+
workbook2 = Workbook.open('spec/data/more/workbook.xls', if_blocked: :forget)
|
226
153
|
|
227
154
|
|
228
155
|
=== Opening workbooks in several Excel instances
|
@@ -237,39 +164,20 @@ Now we want to open another workbook in a different Excel instance.
|
|
237
164
|
|
238
165
|
workbook2 = Workbook.open('spec/data/different_workbook.xls', excel: :new)
|
239
166
|
|
240
|
-
We can also create a third Excel instance and open another workbook in this instance.
|
241
|
-
|
242
|
-
excel1 = Excel.create
|
243
|
-
workbook3 = Workbook.open('spec/data/another_workbook.xls', excel: excel1)
|
244
|
-
|
245
167
|
A workbook is opened by default in the Excel instance where it was open before most recently.
|
246
168
|
|
247
169
|
workbook1.close
|
248
170
|
workbook1 = Workbook.open('spec/data/workbook.xls')
|
249
171
|
|
250
|
-
If
|
172
|
+
If the Excel instance is damaged or closed, then options control whether the workbook shall be opened in the current (active), a new or a given Excel instance.
|
251
173
|
|
252
174
|
workbook1 = Workbook.open('spec/data/workbook.xls', default: {excel: new})
|
253
175
|
|
254
|
-
Without the option +:default+, the workbook can be forced to be opened in the current, new or given Excel instance, no matter if and where it was opened before, e.g.
|
255
|
-
|
256
|
-
workbook2 = Workbook.open('spec/data/workbook.xls', excel: excel1)
|
257
|
-
|
258
|
-
=== Managing conflicts with unsaved and blocking workbooks
|
259
|
-
|
260
|
-
RobustExcelOle enables processing workbooks, while still supporting user's interactions: The commands enable to open, close, reopen, read, modify, write and save Excel workbooks, without the need of the user's interaction, and even without the user noticing. Thus, while running a script containing RobustExcelOle commands, the user can open and process workbooks in any Excel instances at any time. RobustExcelOle manages the complex cases of conflicts that might occur such that the user does not need to interfere and the script can continue.
|
176
|
+
Without the option +:default+, the workbook can be forced to be opened in the current, a new or a given Excel instance, no matter if and where it was opened before, e.g.
|
261
177
|
|
262
|
-
|
263
|
-
|
264
|
-
workbook = Workbook.open('workbook.xls', if_unsaved: :accept)
|
265
|
-
|
266
|
-
Similarly, if the user has opened a workbook that has the same name but a different path, the conflict can be solved via an option.
|
267
|
-
|
268
|
-
workbook1 = Workbook.open('spec/data/workbook.xls')
|
269
|
-
# do something
|
270
|
-
workbook2 = Workbook.open('spec/data/more/workbook.xls', if_blocked: :forget)
|
178
|
+
workbook2 = Workbook.open('spec/data/workbook.xls', excel: new)
|
271
179
|
|
272
|
-
For more details about opening
|
180
|
+
For more details about opening Excel instances see {README_open}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_open.rdoc] and {README_excel}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_excel.rdoc].
|
273
181
|
|
274
182
|
=== Operating on worksheets
|
275
183
|
|
@@ -281,14 +189,6 @@ We access the first worksheet by
|
|
281
189
|
|
282
190
|
worksheet = workbook.sheet(1)
|
283
191
|
|
284
|
-
or
|
285
|
-
|
286
|
-
worksheet = workbook.sheet('Sheet1')
|
287
|
-
|
288
|
-
or
|
289
|
-
|
290
|
-
worksheet = workbook.first_sheet
|
291
|
-
|
292
192
|
We can read and change the worksheet name.
|
293
193
|
|
294
194
|
worksheet.name
|
@@ -300,7 +200,7 @@ We can copy the first worksheet, name it and add it before the third worksheet.
|
|
300
200
|
|
301
201
|
workbook.add_or_copy_sheet(sheet, as: "copied_name, before: workbook.last_sheet)
|
302
202
|
|
303
|
-
For more details about processing worksheets see {README_sheet}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_sheet.rdoc]
|
203
|
+
For more details about processing worksheets see {README_sheet}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_sheet.rdoc].
|
304
204
|
|
305
205
|
=== Reading and writing ranges in worksheets
|
306
206
|
|
@@ -308,24 +208,10 @@ We can define a rectangular range by providing the top left and the bottum down
|
|
308
208
|
|
309
209
|
worksheet.range([1..3,1..4])
|
310
210
|
|
311
|
-
We can read
|
312
|
-
|
313
|
-
worksheet.row_range(1, 1..3).values # => ["foo","workbook","sheet1"]
|
314
|
-
|
315
|
-
and the third column
|
316
|
-
|
317
|
-
worksheet.col_range(3).values # => ["sheet1", 2.0, 4.0]
|
318
|
-
|
319
|
-
We can read the first cell, using
|
320
|
-
|
321
|
-
worksheet[1,1]. # => "foo"
|
322
|
-
|
323
|
-
or
|
324
|
-
|
325
|
-
worksheet.row_range(1)[0].value # => "foo"
|
326
|
-
|
327
|
-
Then we modify it.
|
211
|
+
We can read and modify the first cell, e.g.
|
328
212
|
|
213
|
+
worksheet[1,1]
|
214
|
+
# => "foo"
|
329
215
|
worksheet[1,1] = "hello"
|
330
216
|
|
331
217
|
We get the value of a named range
|
@@ -338,20 +224,15 @@ and set another value to that range.
|
|
338
224
|
|
339
225
|
For more details about reading and writing contents of cells and ranges see {README_ranges}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_ranges.rdoc]
|
340
226
|
|
341
|
-
|
342
227
|
=== List Objects (Tables)
|
343
228
|
|
344
|
-
We
|
345
|
-
|
346
|
-
table = ListObject.new(worksheet, "table 1", [1,1], 3, ["Person","AmountSales"])
|
347
|
-
|
348
|
-
or get a given list object in a worksheet given its table number or name.
|
229
|
+
We obtain a given list object in a worksheet given its table number or name.
|
349
230
|
|
350
231
|
table = worksheet.table(1)
|
351
232
|
|
352
|
-
|
233
|
+
We can also define a list object from scratch
|
353
234
|
|
354
|
-
table =
|
235
|
+
table = ListObject.new(worksheet, "table 1", [1,1], 3, ["Person","AmountSales"])
|
355
236
|
|
356
237
|
A list row can be accessed by providing either the row number or a key, i.e. hash of column name - value pairs, e.g.
|
357
238
|
|
@@ -361,18 +242,18 @@ A list row can be accessed by providing either the row number or a key, i.e. has
|
|
361
242
|
|
362
243
|
You can get all or a maximal number of list rows matching the key.
|
363
244
|
|
364
|
-
rows = table[{"Number": 1}, limit: 2]
|
365
245
|
rows = table[{"Number": 1}, limit: nil]
|
246
|
+
rows = table[{"Number": 1}, limit: 2]
|
366
247
|
|
367
|
-
Now we can set value of a cell of the table with help of methods that are
|
248
|
+
Now we can read and set the value of a cell of the table with help of methods that are underscored variants of the column names, e.g.
|
368
249
|
|
369
250
|
row1.person = "John"
|
370
251
|
|
371
|
-
or
|
252
|
+
or with help of the column name
|
372
253
|
|
373
254
|
row1["Person"] = "John"
|
374
255
|
|
375
|
-
|
256
|
+
We can also read all values in a row.
|
376
257
|
|
377
258
|
table[1].to_a
|
378
259
|
# => ["John", 40]
|
@@ -380,57 +261,15 @@ Similarly you can get the values. We can also read all values in a row.
|
|
380
261
|
table[1].to_h
|
381
262
|
# => {"Person": "John", "AmountSales": 40}
|
382
263
|
|
383
|
-
|
384
|
-
|
385
|
-
table[1].values = ["Herber", 80]
|
386
|
-
|
387
|
-
Similarly, we can read and set the values in a whole column, e.g.
|
388
|
-
|
389
|
-
table.column_values("Person")
|
390
|
-
# => ["John", "Peter"]
|
391
|
-
|
392
|
-
and
|
393
|
-
|
394
|
-
table.set_column_values(1, ["Herbert","Paul"])
|
395
|
-
|
396
|
-
We can add and delete rows and columns, supplying optionally their name, the position and contents.
|
397
|
-
|
398
|
-
table.add_column("column_name", 3, ["John", "Paul"])
|
399
|
-
table.add_row(3, ["John", 40, 2, 2004])
|
400
|
-
|
401
|
-
table.delete_column_values("column_name")
|
402
|
-
table[2].delete_values
|
403
|
-
|
404
|
-
Finally we can delete empty rows and columns.
|
405
|
-
|
406
|
-
table.delete_empty_rows
|
407
|
-
table.delete_empty_columns
|
408
|
-
|
409
|
-
For more details about using and processing list objects see {README_listobjects}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_listobjects.rdoc]
|
410
|
-
|
264
|
+
For more details about using and processing list objects see {README_listobjects}[https://github.com/Thomas008/robust_excel_ole/blob/master/docs/README_listobjects.rdoc].
|
411
265
|
|
412
266
|
=== More features
|
413
267
|
|
414
|
-
|
415
|
-
|
416
|
-
General.change_current_binding(object)
|
417
|
-
|
418
|
-
Without this method, the ruby shell 'pry' allows to change the value of 'self' in the console as well, e.g.
|
419
|
-
|
420
|
-
object.pry
|
421
|
-
|
422
|
-
or
|
423
|
-
|
424
|
-
cd object
|
425
|
-
|
426
|
-
However, this command also starts another pry repl (with another binding). Moreover, local variables in the previous binding are forgotten.
|
427
|
-
|
428
|
-
|
429
|
-
2. The class Win32Ole is being extended such that RobustExcelOle methods can be applied to WIN32OLE objects. As mentioned above, the RobustExcelOle objects are wrapper of corresponding WIN32OLE objects. So the RobustExcelOle objects and their wrapped WIN32OLE objects are interchangeable. One example would be
|
268
|
+
The class WIN32OLE is being extended such that RobustExcelOle methods can be applied to WIN32OLE objects. As mentioned above, the RobustExcelOle objects are wrapper of corresponding WIN32OLE objects. So now the RobustExcelOle objects and their wrapped WIN32OLE objects are interchangeable. One example would be
|
430
269
|
|
431
270
|
range.ole_range.copy([4,3])
|
432
271
|
|
433
|
-
Likewise it is possible to convert ("type-lift")
|
272
|
+
Likewise it is possible to convert ("type-lift") WIN32OLE objects into the corresponding RobustExcelOle object, using the method +to_reo+. It is a refinement of the class WIN32OLE. So you can write
|
434
273
|
|
435
274
|
using ToReoRefinement
|
436
275
|
|
data/docs/README_excel.rdoc
CHANGED
@@ -1,10 +1,11 @@
|
|
1
|
-
|
1
|
+
== Managing Excel instances
|
2
2
|
|
3
|
-
|
3
|
+
Details are essentially covered in the ruby documentation of the class
|
4
|
+
Excel[https://www.rubydoc.info/gems/robust_excel_ole/RobustExcelOle/Excel].
|
4
5
|
|
5
|
-
|
6
|
+
=== Creating, using and closing Excel instances
|
6
7
|
|
7
|
-
|
8
|
+
RobustExcelOle enables simultanously running Excel instances. An Excel application is represented by an Excel object.
|
8
9
|
|
9
10
|
You can create a new Excel instance by
|
10
11
|
|
@@ -168,6 +169,4 @@ This method has the option +:if_unsaved+ as described above. For example, if you
|
|
168
169
|
|
169
170
|
This method kills all Excel instances no matter whether they contain unsaved workbooks.
|
170
171
|
|
171
|
-
== Code
|
172
172
|
|
173
|
-
excel.rb[https://github.com/Thomas008/robust_excel_ole/blob/master/lib/robust_excel_ole/excel.rb]
|
@@ -1,7 +1,9 @@
|
|
1
|
-
= RobustExcelOle
|
2
|
-
|
3
1
|
== List Objects
|
4
2
|
|
3
|
+
A List object in a worksheet represents a table.
|
4
|
+
The details are essentially covered in the ruby docmentation of the class
|
5
|
+
ListObject[https://www.rubydoc.info/gems/robust_excel_ole/RobustExcelOle/ListObject].
|
6
|
+
|
5
7
|
=== Creating List Objects
|
6
8
|
|
7
9
|
We can define a list object (or table) from scratch.
|
@@ -54,20 +56,14 @@ or
|
|
54
56
|
or
|
55
57
|
|
56
58
|
row1["AmountSales"] = 40
|
57
|
-
|
58
|
-
Similarly you can get the values.
|
59
|
-
|
60
|
-
row1.AmountSales
|
61
|
-
# => 40
|
62
59
|
|
63
60
|
or
|
64
61
|
|
65
|
-
row1
|
66
|
-
|
67
|
-
|
68
|
-
or
|
62
|
+
row1[:AmountSales] = 40
|
63
|
+
|
64
|
+
Similarly you can get the values, e.g.
|
69
65
|
|
70
|
-
row1
|
66
|
+
row1.amount_sales
|
71
67
|
# => 40
|
72
68
|
|
73
69
|
We can also read the values in a whole row.
|
@@ -170,7 +166,4 @@ You can sort a table according to a given column and sort order, e.g.
|
|
170
166
|
|
171
167
|
table.sort("Person", :ascending)
|
172
168
|
|
173
|
-
== Code
|
174
|
-
|
175
|
-
listobjects.rb[https://github.com/Thomas008/robust_excel_ole/blob/master/lib/robust_excel_ole/listobjects.rb]
|
176
169
|
|
data/docs/README_open.rdoc
CHANGED
@@ -1,6 +1,9 @@
|
|
1
|
-
|
1
|
+
== Opening workbooks
|
2
2
|
|
3
|
-
|
3
|
+
The details are essentially covered in the ruby documentation of the
|
4
|
+
class Workbook[https://www.rubydoc.info/gems/robust_excel_ole/RobustExcelOle/Workbook].
|
5
|
+
|
6
|
+
=== How to open a workbook
|
4
7
|
|
5
8
|
If you want to open a workbook, you can use the methods +open+ or +new+.
|
6
9
|
|
@@ -36,12 +39,12 @@ The options are the following:
|
|
36
39
|
|
37
40
|
+:if_unsaved+:: specifies behaviour if the workbook was unsaved (default: +:raise+)
|
38
41
|
|
39
|
-
+:if_blocked
|
42
|
+
+:if_blocked+:: specifies behaviour if the workbook is blocked by another book (default: +:raise+)
|
40
43
|
|
41
44
|
|
42
|
-
+:read_only+:: opens in read-only mode (default: +false+)
|
45
|
+
+:read_only+:: opens in read-only (+true+) or read-write mode (+false+) (default: +false+)
|
43
46
|
|
44
|
-
+:check_compatibility
|
47
|
+
+:check_compatibility+:: checks compatibility when saving
|
45
48
|
|
46
49
|
+:calculation+:: forces the calculation mode to be manual (:manual) or automatic (:automatic)
|
47
50
|
|
@@ -49,39 +52,40 @@ The options are the following:
|
|
49
52
|
|
50
53
|
You can use the following abbreviations or synonyms: +:f+ for +:force+, +:d+ for +:default+, +:e+ for +:excel+, and +:v+ for +:visible+, +:if_obstructed+ for +:if_blocked+. Finally you can leave out the option +:force+ or +:f+.
|
51
54
|
|
52
|
-
The option +:excel+ :
|
55
|
+
=== The option +:excel+ :
|
53
56
|
|
54
57
|
Valid values are : +:current+ (or +:active+ or +:reuse+), +:new+, or a given Excel instance (default: +:current).
|
55
58
|
|
56
|
-
The option +:if_unsaved+ :
|
59
|
+
=== The option +:if_unsaved+ :
|
57
60
|
|
58
|
-
If a workbook contains unsaved changes and
|
61
|
+
If a workbook contains unsaved changes and the workbook shall be re-opened, then
|
59
62
|
|
60
|
-
+:raise+:: Raise an exeption.
|
61
|
-
+:accept+::
|
63
|
+
+:raise+:: Raise an exeption. Leave the unsaved workbook open.
|
64
|
+
+:accept+:: Leave the unsaved workbook open.
|
62
65
|
+:forget+:: Discard any changes and reopen the workbook.
|
63
66
|
+:save+:: Save any changes and reopen the workbook
|
64
|
-
+:new_excel+:: Open the
|
67
|
+
+:new_excel+:: Open the workbook in a new Excel instance
|
65
68
|
+:alert+:: Give control to Excel.
|
66
69
|
|
67
|
-
The option +:if_blocked+ :
|
70
|
+
=== The option +:if_blocked+ :
|
68
71
|
|
69
|
-
If a workbook is open and a
|
72
|
+
If a workbook is open and a workbook with same base name but in a different path shall be opened, then the first workbook blocks opening the latter one. In this case:
|
70
73
|
|
71
|
-
+:raise+:: Raise an exception. Don't open the workbook.
|
72
|
-
+:forget+:: Close the
|
73
|
-
+:
|
74
|
-
+:
|
74
|
+
+:raise+:: Raise an exception. Don't open the workbook. Leave the blocking workbook open.
|
75
|
+
+:forget+:: Close the blocking workbook, open the new workbook.
|
76
|
+
+:accept+:: Leave the blocking workbook open.
|
77
|
+
+:save+:: Save the blocking workbook, close it, open the new workbook
|
78
|
+
+:close_if_saved+:: Close the blocking workbook and open the new workbook, if the blocking workbook is saved, otherwise raise an exception.
|
75
79
|
+:new_excel+:: Open the new workbook in a new Excel instance.
|
76
80
|
|
77
|
-
The option +:if_absent
|
81
|
+
=== The option +:if_absent+ :
|
78
82
|
|
79
83
|
If the Excel file does not exists, then
|
80
84
|
|
81
85
|
+:create+:: Create a new Excel file
|
82
86
|
+:raise+:: Raise an exception.
|
83
87
|
|
84
|
-
|
88
|
+
=== Examples:
|
85
89
|
|
86
90
|
If you want to open a workbook that was not opened before, or reopen a workbook that was open in an Excel instance that is now closed, in the current (active) Excel instance, then use
|
87
91
|
|
@@ -129,21 +133,23 @@ If a workbook is open and a workbook with the same name but in different path sh
|
|
129
133
|
|
130
134
|
workbook = Workbook.open('path/workbook.xls', if_blocked: :forget)
|
131
135
|
|
132
|
-
Remarks
|
136
|
+
=== Remarks
|
133
137
|
|
134
138
|
The methods +open+ and +new+ connect to workbooks opened outside of RobustExcelOle as well.
|
135
139
|
|
136
|
-
Opening linked workbooks for EXCEL 2007 is supported
|
140
|
+
Opening linked workbooks for EXCEL 2007 is supported. Changing linked, unsaved workbooks from read-only to read-write causes a query whether to save the changes. This case cannot be
|
141
|
+
controlled (e.g. with help of some options) so far.
|
137
142
|
|
138
143
|
Doing updating links seems to be dependent on calculation mode: updates happen, if the calcultion mode is automatic, and does not happen, if calculation mode is manual.
|
139
144
|
|
140
|
-
|
145
|
+
|
146
|
+
=== Reopening a workbook
|
141
147
|
|
142
148
|
A special feature of RobustExcelOle is that it allows to reopen workbooks after closing them.
|
143
149
|
|
144
150
|
workbook = Workbook.open('spec/data/workbook.xls')
|
145
151
|
workbook.close
|
146
|
-
workbook.
|
152
|
+
workbook.open
|
147
153
|
|
148
154
|
The closed workbook is now alive again, i.e. is open and responds to Excel methods.
|
149
155
|
|
@@ -176,7 +182,7 @@ You can also supply a workbook and options, e.g.
|
|
176
182
|
|
177
183
|
new_workbook = Workbook.new(workbook, visible: true)
|
178
184
|
|
179
|
-
=== Identity transperence
|
185
|
+
=== Identity transperence
|
180
186
|
|
181
187
|
A RobustExcelOle Workbook object is a proxy of an Excel WIN32OLE workbook. A Workbook object is defined by the full workbook name and the Excel instance in which it is opened. RobustExcelOle ensures identity transparency which means that identical Workbook objects refer to identical Excel workbooks, and vice versa. Identity transperence ensures that, no matter how a Workbook object was created - by filename or by type-lifting an Excel workbook - two Workbook objects are identical, if and only if the Excel workbooks, they are referring to, are identical.
|
182
188
|
|
@@ -245,13 +251,33 @@ This method ensures keeping the save status of the workbook
|
|
245
251
|
# some reading or modifying
|
246
252
|
end
|
247
253
|
|
248
|
-
===
|
254
|
+
=== Changing ReadOnly-mode
|
255
|
+
|
256
|
+
When you want to change the read-only mode, you can use the method +writable=+.
|
257
|
+
|
258
|
+
workbook = Workbook('spec/data/workbook.xls')
|
259
|
+
workbook.writable = false
|
260
|
+
workbook.writable
|
261
|
+
# => false
|
262
|
+
workbook.ReadOnly
|
263
|
+
# => true
|
264
|
+
workbook.writable = true
|
265
|
+
|
266
|
+
If the workbook is unsaved, use the option +if_unsaved+ as desribed above.
|
267
|
+
|
268
|
+
workbook.writable = false, {if_unsaved: :forget}
|
269
|
+
|
270
|
+
Changing from read-only to read-write for linked, unsaved workbooks is not being supported yet.
|
271
|
+
|
272
|
+
=== Checking whether the workbook is alive
|
249
273
|
|
250
274
|
The method +alive?+ finds out whether the Excel workbook that is referenced by the Workbook object responds to methods. For example
|
251
275
|
|
252
276
|
workbook.alive?
|
253
277
|
# => true
|
254
278
|
|
255
|
-
|
279
|
+
=== Setting options
|
280
|
+
|
281
|
+
Once we have a workbook, we can set some options, e.g.
|
256
282
|
|
257
|
-
workbook.
|
283
|
+
workbook.for_this_workbook(visible: true, read_only: false)
|