@borgar/fx 4.4.0 → 4.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.eslintrc +3 -12
- package/dist/fx.d.ts +153 -34
- package/dist/fx.js +1 -1
- package/docs/API.md +248 -119
- package/lib/a1.js +32 -23
- package/lib/addTokenMeta.js +6 -6
- package/lib/constants.js +2 -2
- package/lib/extraTypes.js +73 -0
- package/lib/fixRanges.js +8 -8
- package/lib/isType.js +16 -16
- package/lib/lexer-srefs.spec.js +5 -0
- package/lib/lexer.js +2 -2
- package/lib/lexerParts.js +24 -12
- package/lib/mergeRefTokens.js +2 -2
- package/lib/parseRef.spec.js +22 -11
- package/lib/parser.js +8 -8
- package/lib/parser.spec.js +90 -39
- package/lib/rc.js +14 -12
- package/lib/sr.js +22 -22
- package/lib/sr.spec.js +7 -0
- package/lib/translate-toA1.spec.js +5 -1
- package/lib/translate-toRC.spec.js +4 -1
- package/lib/translate.js +16 -13
- package/lib/translate.spec.js +21 -0
- package/package.json +9 -8
package/docs/API.md
CHANGED
|
@@ -36,9 +36,19 @@
|
|
|
36
36
|
- [nodeTypes](#nodeTypes)
|
|
37
37
|
- [tokenTypes](#tokenTypes)
|
|
38
38
|
|
|
39
|
+
**Types**
|
|
40
|
+
|
|
41
|
+
- [RangeA1](#RangeA1)
|
|
42
|
+
- [RangeR1C1](#RangeR1C1)
|
|
43
|
+
- [ReferenceA1](#ReferenceA1)
|
|
44
|
+
- [ReferenceR1C1](#ReferenceR1C1)
|
|
45
|
+
- [ReferenceStruct](#ReferenceStruct)
|
|
46
|
+
- [Token](#Token)
|
|
47
|
+
- [TokenEnhanced](#TokenEnhanced)
|
|
48
|
+
|
|
39
49
|
## Functions
|
|
40
50
|
|
|
41
|
-
### <a id="addA1RangeBounds" href="#addA1RangeBounds">#</a> addA1RangeBounds( range ) ⇒ `
|
|
51
|
+
### <a id="addA1RangeBounds" href="#addA1RangeBounds">#</a> addA1RangeBounds( range ) ⇒ [`RangeA1`](#RangeA1)
|
|
42
52
|
|
|
43
53
|
Fill the any missing bounds in range objects. Top will be set to 0, bottom to 1048575, left to 0, and right to 16383, if they are `null` or `undefined`.
|
|
44
54
|
|
|
@@ -71,17 +81,17 @@ addA1RangeBounds({
|
|
|
71
81
|
|
|
72
82
|
##### Parameters
|
|
73
83
|
|
|
74
|
-
| Name | Type
|
|
75
|
-
| ----- |
|
|
76
|
-
| range | `
|
|
84
|
+
| Name | Type | Description |
|
|
85
|
+
| ----- | --------------------- | ------------------------------------- |
|
|
86
|
+
| range | [`RangeA1`](#RangeA1) | The range part of a reference object. |
|
|
77
87
|
|
|
78
88
|
##### Returns
|
|
79
89
|
|
|
80
|
-
`
|
|
90
|
+
[`RangeA1`](#RangeA1) – same range with missing bounds filled in.
|
|
81
91
|
|
|
82
92
|
---
|
|
83
93
|
|
|
84
|
-
### <a id="addTokenMeta" href="#addTokenMeta">#</a> addTokenMeta( tokenlist, _[context = `{}`]_ ) ⇒ `Array<
|
|
94
|
+
### <a id="addTokenMeta" href="#addTokenMeta">#</a> addTokenMeta( tokenlist, _[context = `{}`]_ ) ⇒ `Array<TokenEnhanced>`
|
|
85
95
|
|
|
86
96
|
Runs through a list of tokens and adds extra attributes such as matching parens and ranges.
|
|
87
97
|
|
|
@@ -113,20 +123,20 @@ All will be tagged with `.error` (boolean `true`).
|
|
|
113
123
|
|
|
114
124
|
##### Parameters
|
|
115
125
|
|
|
116
|
-
| Name | Type
|
|
117
|
-
| ---------------------- |
|
|
118
|
-
| tokenlist | `Array<
|
|
119
|
-
| [context] | `object`
|
|
120
|
-
| [context].sheetName | `string`
|
|
121
|
-
| [context].workbookName | `string`
|
|
126
|
+
| Name | Type | Default | Description |
|
|
127
|
+
| ---------------------- | -------------- | ------- | -------------------------------------------- |
|
|
128
|
+
| tokenlist | `Array<Token>` | | An array of tokens (from `tokenize()`) |
|
|
129
|
+
| [context] | `object` | `{}` | A contest used to match `A1` to `Sheet1!A1`. |
|
|
130
|
+
| [context].sheetName | `string` | `""` | An implied sheet name ('Sheet1') |
|
|
131
|
+
| [context].workbookName | `string` | `""` | An implied workbook name ('report.xlsx') |
|
|
122
132
|
|
|
123
133
|
##### Returns
|
|
124
134
|
|
|
125
|
-
`Array<
|
|
135
|
+
`Array<TokenEnhanced>` – The input array with the enchanced tokens
|
|
126
136
|
|
|
127
137
|
---
|
|
128
138
|
|
|
129
|
-
### <a id="fixRanges" href="#fixRanges">#</a> fixRanges( formula, _[options = `{}`]_ ) ⇒ `string` | `Array<
|
|
139
|
+
### <a id="fixRanges" href="#fixRanges">#</a> fixRanges( formula, _[options = `{}`]_ ) ⇒ `string` | `Array<Token>`
|
|
130
140
|
|
|
131
141
|
Normalizes A1 style ranges and structured references in a formula or list of tokens.
|
|
132
142
|
|
|
@@ -154,20 +164,20 @@ Returns the same formula with the ranges updated. If an array of tokens was supp
|
|
|
154
164
|
|
|
155
165
|
##### Parameters
|
|
156
166
|
|
|
157
|
-
| Name | Type
|
|
158
|
-
| ------------------- |
|
|
159
|
-
| formula | `string` \| `Array<
|
|
160
|
-
| [options] | `object`
|
|
161
|
-
| [options].addBounds | `boolean`
|
|
162
|
-
| [options].xlsx | `boolean`
|
|
167
|
+
| Name | Type | Default | Description |
|
|
168
|
+
| ------------------- | -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
169
|
+
| formula | `string` \| `Array<Token>` | | A string (an Excel formula) or a token list that should be adjusted. |
|
|
170
|
+
| [options] | `object` | `{}` | Options |
|
|
171
|
+
| [options].addBounds | `boolean` | `false` | Fill in any undefined bounds of range objects. Top to 0, bottom to 1048575, left to 0, and right to 16383. |
|
|
172
|
+
| [options].xlsx | `boolean` | `false` | Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) |
|
|
163
173
|
|
|
164
174
|
##### Returns
|
|
165
175
|
|
|
166
|
-
`string` | `Array<
|
|
176
|
+
`string` | `Array<Token>` – A formula string or token list (depending on which was input)
|
|
167
177
|
|
|
168
178
|
---
|
|
169
179
|
|
|
170
|
-
### <a id="fromA1" href="#fromA1">#</a> fromA1( rangeString ) ⇒ `
|
|
180
|
+
### <a id="fromA1" href="#fromA1">#</a> fromA1( rangeString ) ⇒ [`RangeA1`](#RangeA1) | `null`
|
|
171
181
|
|
|
172
182
|
Parse a simple string reference to an A1 range into a range object. Will accept `A1`, `A2`, `A:A`, or `1:1`.
|
|
173
183
|
|
|
@@ -181,7 +191,7 @@ Parse a simple string reference to an A1 range into a range object. Will accept
|
|
|
181
191
|
|
|
182
192
|
##### Returns
|
|
183
193
|
|
|
184
|
-
`
|
|
194
|
+
[`RangeA1`](#RangeA1) | `null` – An object representing a valid range or null if it is invalid.
|
|
185
195
|
|
|
186
196
|
---
|
|
187
197
|
|
|
@@ -203,7 +213,7 @@ The method expects a valid column identifier made up of _only_ A-Z letters, whic
|
|
|
203
213
|
|
|
204
214
|
---
|
|
205
215
|
|
|
206
|
-
### <a id="fromR1C1" href="#fromR1C1">#</a> fromR1C1( rangeString ) ⇒ `
|
|
216
|
+
### <a id="fromR1C1" href="#fromR1C1">#</a> fromR1C1( rangeString ) ⇒ [`RangeR1C1`](#RangeR1C1) | `null`
|
|
207
217
|
|
|
208
218
|
Parse a simple string reference to an R1C1 range into a range object.
|
|
209
219
|
|
|
@@ -217,7 +227,7 @@ Parse a simple string reference to an R1C1 range into a range object.
|
|
|
217
227
|
|
|
218
228
|
##### Returns
|
|
219
229
|
|
|
220
|
-
`
|
|
230
|
+
[`RangeR1C1`](#RangeR1C1) | `null` – An object representing a valid reference or null if it is invalid.
|
|
221
231
|
|
|
222
232
|
---
|
|
223
233
|
|
|
@@ -229,9 +239,9 @@ Returns `true` if the input is a token of type ERROR (`#VALUE!`). In all other c
|
|
|
229
239
|
|
|
230
240
|
##### Parameters
|
|
231
241
|
|
|
232
|
-
| Name | Type
|
|
233
|
-
| ----- |
|
|
234
|
-
| token | `
|
|
242
|
+
| Name | Type | Description |
|
|
243
|
+
| ----- | ----- | ----------- |
|
|
244
|
+
| token | `any` | The token |
|
|
235
245
|
|
|
236
246
|
##### Returns
|
|
237
247
|
|
|
@@ -247,9 +257,9 @@ Returns `true` if the input is a token of type FUNCTION. In all other cases `fal
|
|
|
247
257
|
|
|
248
258
|
##### Parameters
|
|
249
259
|
|
|
250
|
-
| Name | Type
|
|
251
|
-
| ----- |
|
|
252
|
-
| token | `
|
|
260
|
+
| Name | Type | Description |
|
|
261
|
+
| ----- | ----- | ----------- |
|
|
262
|
+
| token | `any` | The token |
|
|
253
263
|
|
|
254
264
|
##### Returns
|
|
255
265
|
|
|
@@ -263,9 +273,9 @@ Returns `true` if the input is a token of type FX_PREFIX (leading `=` in formula
|
|
|
263
273
|
|
|
264
274
|
##### Parameters
|
|
265
275
|
|
|
266
|
-
| Name | Type
|
|
267
|
-
| ----- |
|
|
268
|
-
| token | `
|
|
276
|
+
| Name | Type | Description |
|
|
277
|
+
| ----- | ----- | ----------- |
|
|
278
|
+
| token | `any` | The token |
|
|
269
279
|
|
|
270
280
|
##### Returns
|
|
271
281
|
|
|
@@ -281,9 +291,9 @@ Returns `true` if the input is a token of type BOOLEAN (`TRUE` or `FALSE`), ERRO
|
|
|
281
291
|
|
|
282
292
|
##### Parameters
|
|
283
293
|
|
|
284
|
-
| Name | Type
|
|
285
|
-
| ----- |
|
|
286
|
-
| token | `
|
|
294
|
+
| Name | Type | Description |
|
|
295
|
+
| ----- | ----- | ----------- |
|
|
296
|
+
| token | `any` | The token |
|
|
287
297
|
|
|
288
298
|
##### Returns
|
|
289
299
|
|
|
@@ -299,9 +309,9 @@ Returns `true` if the input is a token of type OPERATOR (`+` or `:`). In all oth
|
|
|
299
309
|
|
|
300
310
|
##### Parameters
|
|
301
311
|
|
|
302
|
-
| Name | Type
|
|
303
|
-
| ----- |
|
|
304
|
-
| token | `
|
|
312
|
+
| Name | Type | Description |
|
|
313
|
+
| ----- | ----- | ----------- |
|
|
314
|
+
| token | `any` | The token |
|
|
305
315
|
|
|
306
316
|
##### Returns
|
|
307
317
|
|
|
@@ -317,9 +327,9 @@ Returns `true` if the input is a token that has a type of either REF_RANGE (`A1`
|
|
|
317
327
|
|
|
318
328
|
##### Parameters
|
|
319
329
|
|
|
320
|
-
| Name | Type
|
|
321
|
-
| ----- |
|
|
322
|
-
| token | `
|
|
330
|
+
| Name | Type | Description |
|
|
331
|
+
| ----- | ----- | ----------- |
|
|
332
|
+
| token | `any` | A token |
|
|
323
333
|
|
|
324
334
|
##### Returns
|
|
325
335
|
|
|
@@ -335,9 +345,9 @@ Returns `true` if the input is a token of type REF_RANGE (`A1` or `A1:B2`), REF_
|
|
|
335
345
|
|
|
336
346
|
##### Parameters
|
|
337
347
|
|
|
338
|
-
| Name | Type
|
|
339
|
-
| ----- |
|
|
340
|
-
| token | `
|
|
348
|
+
| Name | Type | Description |
|
|
349
|
+
| ----- | ----- | ----------- |
|
|
350
|
+
| token | `any` | The token |
|
|
341
351
|
|
|
342
352
|
##### Returns
|
|
343
353
|
|
|
@@ -353,9 +363,9 @@ Returns `true` if the input is a token of type WHITESPACE (` `) or NEWLINE (`\n`
|
|
|
353
363
|
|
|
354
364
|
##### Parameters
|
|
355
365
|
|
|
356
|
-
| Name | Type
|
|
357
|
-
| ----- |
|
|
358
|
-
| token | `
|
|
366
|
+
| Name | Type | Description |
|
|
367
|
+
| ----- | ----- | ----------- |
|
|
368
|
+
| token | `any` | The token |
|
|
359
369
|
|
|
360
370
|
##### Returns
|
|
361
371
|
|
|
@@ -363,7 +373,7 @@ Returns `true` if the input is a token of type WHITESPACE (` `) or NEWLINE (`\n`
|
|
|
363
373
|
|
|
364
374
|
---
|
|
365
375
|
|
|
366
|
-
### <a id="mergeRefTokens" href="#mergeRefTokens">#</a> mergeRefTokens( tokenlist ) ⇒ `Array<
|
|
376
|
+
### <a id="mergeRefTokens" href="#mergeRefTokens">#</a> mergeRefTokens( tokenlist ) ⇒ `Array<Token>`
|
|
367
377
|
|
|
368
378
|
Merges context with reference tokens as possible in a list of tokens.
|
|
369
379
|
|
|
@@ -371,13 +381,13 @@ When given a tokenlist, this function returns a new list with ranges returned as
|
|
|
371
381
|
|
|
372
382
|
##### Parameters
|
|
373
383
|
|
|
374
|
-
| Name | Type
|
|
375
|
-
| --------- |
|
|
376
|
-
| tokenlist | `Array<
|
|
384
|
+
| Name | Type | Description |
|
|
385
|
+
| --------- | -------------- | -------------------------------------- |
|
|
386
|
+
| tokenlist | `Array<Token>` | An array of tokens (from `tokenize()`) |
|
|
377
387
|
|
|
378
388
|
##### Returns
|
|
379
389
|
|
|
380
|
-
`Array<
|
|
390
|
+
`Array<Token>` – A new list of tokens with range parts merged.
|
|
381
391
|
|
|
382
392
|
---
|
|
383
393
|
|
|
@@ -393,18 +403,18 @@ The AST Abstract Syntax Tree's format is documented in [AST_format.md](./AST_for
|
|
|
393
403
|
|
|
394
404
|
##### Parameters
|
|
395
405
|
|
|
396
|
-
| Name | Type
|
|
397
|
-
| --------------------------- |
|
|
398
|
-
| formula | `string` \| `Array<
|
|
399
|
-
| [options] | `object`
|
|
400
|
-
| [options].allowNamed | `boolean`
|
|
401
|
-
| [options].allowTernary | `boolean`
|
|
402
|
-
| [options].negativeNumbers | `boolean`
|
|
403
|
-
| [options].permitArrayCalls | `boolean`
|
|
404
|
-
| [options].permitArrayRanges | `boolean`
|
|
405
|
-
| [options].r1c1 | `boolean`
|
|
406
|
-
| [options].withLocation | `boolean`
|
|
407
|
-
| [options].xlsx | `boolean`
|
|
406
|
+
| Name | Type | Default | Description |
|
|
407
|
+
| --------------------------- | -------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
408
|
+
| formula | `string` \| `Array<Token>` | | An Excel formula string (an Excel expression) or an array of tokens. |
|
|
409
|
+
| [options] | `object` | `{}` | Options |
|
|
410
|
+
| [options].allowNamed | `boolean` | `true` | Enable parsing names as well as ranges. |
|
|
411
|
+
| [options].allowTernary | `boolean` | `false` | Enables the recognition of ternary ranges in the style of `A1:A` or `A1:1`. These are supported by Google Sheets but not Excel. See: References.md. |
|
|
412
|
+
| [options].negativeNumbers | `boolean` | `true` | Merges unary minuses with their immediately following number tokens (`-`,`1`) => `-1` (alternatively these will be unary operations in the tree). |
|
|
413
|
+
| [options].permitArrayCalls | `boolean` | `false` | Function calls are allowed as elements of arrays. This is a feature in Google Sheets while Excel does not allow it. |
|
|
414
|
+
| [options].permitArrayRanges | `boolean` | `false` | Ranges are allowed as elements of arrays. This is a feature in Google Sheets while Excel does not allow it. |
|
|
415
|
+
| [options].r1c1 | `boolean` | `false` | Ranges are expected to be in the R1C1 style format rather than the more popular A1 style. |
|
|
416
|
+
| [options].withLocation | `boolean` | `false` | Nodes will include source position offsets to the tokens: `{ loc: [ start, end ] }` |
|
|
417
|
+
| [options].xlsx | `boolean` | `false` | Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) |
|
|
408
418
|
|
|
409
419
|
##### Returns
|
|
410
420
|
|
|
@@ -412,7 +422,7 @@ The AST Abstract Syntax Tree's format is documented in [AST_format.md](./AST_for
|
|
|
412
422
|
|
|
413
423
|
---
|
|
414
424
|
|
|
415
|
-
### <a id="parseA1Ref" href="#parseA1Ref">#</a> parseA1Ref( refString, _[options = `{}`]_ ) ⇒ `
|
|
425
|
+
### <a id="parseA1Ref" href="#parseA1Ref">#</a> parseA1Ref( refString, _[options = `{}`]_ ) ⇒ [`ReferenceA1`](#ReferenceA1) | `null`
|
|
416
426
|
|
|
417
427
|
Parse a string reference into an object representing it.
|
|
418
428
|
|
|
@@ -447,11 +457,11 @@ For A:A or A1:A style ranges, `null` will be used for any dimensions that the sy
|
|
|
447
457
|
|
|
448
458
|
##### Returns
|
|
449
459
|
|
|
450
|
-
`
|
|
460
|
+
[`ReferenceA1`](#ReferenceA1) | `null` – An object representing a valid reference or null if it is invalid.
|
|
451
461
|
|
|
452
462
|
---
|
|
453
463
|
|
|
454
|
-
### <a id="parseR1C1Ref" href="#parseR1C1Ref">#</a> parseR1C1Ref( refString, _[options = `{}`]_ ) ⇒ `
|
|
464
|
+
### <a id="parseR1C1Ref" href="#parseR1C1Ref">#</a> parseR1C1Ref( refString, _[options = `{}`]_ ) ⇒ [`ReferenceR1C1`](#ReferenceR1C1) | `null`
|
|
455
465
|
|
|
456
466
|
Parse a string reference into an object representing it.
|
|
457
467
|
|
|
@@ -484,11 +494,11 @@ parseR1C1Ref('Sheet1!R[9]C9:R[9]C9');
|
|
|
484
494
|
|
|
485
495
|
##### Returns
|
|
486
496
|
|
|
487
|
-
`
|
|
497
|
+
[`ReferenceR1C1`](#ReferenceR1C1) | `null` – An object representing a valid reference or null if it is invalid.
|
|
488
498
|
|
|
489
499
|
---
|
|
490
500
|
|
|
491
|
-
### <a id="parseStructRef" href="#parseStructRef">#</a> parseStructRef( ref, _[options = `{}`]_ ) ⇒ `
|
|
501
|
+
### <a id="parseStructRef" href="#parseStructRef">#</a> parseStructRef( ref, _[options = `{}`]_ ) ⇒ [`ReferenceStruct`](#ReferenceStruct) | `null`
|
|
492
502
|
|
|
493
503
|
Parse a structured reference string into an object representing it.
|
|
494
504
|
|
|
@@ -514,11 +524,11 @@ For A:A or A1:A style ranges, `null` will be used for any dimensions that the sy
|
|
|
514
524
|
|
|
515
525
|
##### Returns
|
|
516
526
|
|
|
517
|
-
`
|
|
527
|
+
[`ReferenceStruct`](#ReferenceStruct) | `null` – An object representing a valid reference or null if it is invalid.
|
|
518
528
|
|
|
519
529
|
---
|
|
520
530
|
|
|
521
|
-
### <a id="stringifyA1Ref" href="#stringifyA1Ref">#</a> stringifyA1Ref( refObject, _[options = `{}`]_ ) ⇒ `
|
|
531
|
+
### <a id="stringifyA1Ref" href="#stringifyA1Ref">#</a> stringifyA1Ref( refObject, _[options = `{}`]_ ) ⇒ `string`
|
|
522
532
|
|
|
523
533
|
Get an A1-style string representation of a reference object.
|
|
524
534
|
|
|
@@ -541,19 +551,19 @@ stringifyA1Ref({
|
|
|
541
551
|
|
|
542
552
|
##### Parameters
|
|
543
553
|
|
|
544
|
-
| Name | Type
|
|
545
|
-
| -------------- |
|
|
546
|
-
| refObject | `
|
|
547
|
-
| [options] | `object`
|
|
548
|
-
| [options].xlsx | `boolean`
|
|
554
|
+
| Name | Type | Default | Description |
|
|
555
|
+
| -------------- | ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
556
|
+
| refObject | [`ReferenceA1`](#ReferenceA1) | | A reference object |
|
|
557
|
+
| [options] | `object` | `{}` | Options |
|
|
558
|
+
| [options].xlsx | `boolean` | `false` | Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) |
|
|
549
559
|
|
|
550
560
|
##### Returns
|
|
551
561
|
|
|
552
|
-
`
|
|
562
|
+
`string` – The reference in A1-style string format
|
|
553
563
|
|
|
554
564
|
---
|
|
555
565
|
|
|
556
|
-
### <a id="stringifyR1C1Ref" href="#stringifyR1C1Ref">#</a> stringifyR1C1Ref( refObject, _[options = `{}`]_ ) ⇒ `
|
|
566
|
+
### <a id="stringifyR1C1Ref" href="#stringifyR1C1Ref">#</a> stringifyR1C1Ref( refObject, _[options = `{}`]_ ) ⇒ `string`
|
|
557
567
|
|
|
558
568
|
Get an R1C1-style string representation of a reference object.
|
|
559
569
|
|
|
@@ -576,19 +586,19 @@ stringifyR1C1Ref({
|
|
|
576
586
|
|
|
577
587
|
##### Parameters
|
|
578
588
|
|
|
579
|
-
| Name | Type
|
|
580
|
-
| -------------- |
|
|
581
|
-
| refObject | `
|
|
582
|
-
| [options] | `object`
|
|
583
|
-
| [options].xlsx | `boolean`
|
|
589
|
+
| Name | Type | Default | Description |
|
|
590
|
+
| -------------- | --------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
591
|
+
| refObject | [`ReferenceR1C1`](#ReferenceR1C1) | | A reference object |
|
|
592
|
+
| [options] | `object` | `{}` | Options |
|
|
593
|
+
| [options].xlsx | `boolean` | `false` | Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) |
|
|
584
594
|
|
|
585
595
|
##### Returns
|
|
586
596
|
|
|
587
|
-
`
|
|
597
|
+
`string` – The reference in R1C1-style string format
|
|
588
598
|
|
|
589
599
|
---
|
|
590
600
|
|
|
591
|
-
### <a id="stringifyStructRef" href="#stringifyStructRef">#</a> stringifyStructRef( refObject, _[options = `{}`]_ ) ⇒ `
|
|
601
|
+
### <a id="stringifyStructRef" href="#stringifyStructRef">#</a> stringifyStructRef( refObject, _[options = `{}`]_ ) ⇒ `string`
|
|
592
602
|
|
|
593
603
|
Get a string representation of a structured reference object.
|
|
594
604
|
|
|
@@ -604,15 +614,15 @@ stringifyStructRef({
|
|
|
604
614
|
|
|
605
615
|
##### Parameters
|
|
606
616
|
|
|
607
|
-
| Name | Type
|
|
608
|
-
| -------------- |
|
|
609
|
-
| refObject | `
|
|
610
|
-
| [options] | `object`
|
|
611
|
-
| [options].xlsx | `boolean`
|
|
617
|
+
| Name | Type | Default | Description |
|
|
618
|
+
| -------------- | ------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
619
|
+
| refObject | [`ReferenceStruct`](#ReferenceStruct) | | A structured reference object |
|
|
620
|
+
| [options] | `object` | `{}` | Options |
|
|
621
|
+
| [options].xlsx | `boolean` | `false` | Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) |
|
|
612
622
|
|
|
613
623
|
##### Returns
|
|
614
624
|
|
|
615
|
-
`
|
|
625
|
+
`string` – The structured reference in string format
|
|
616
626
|
|
|
617
627
|
---
|
|
618
628
|
|
|
@@ -624,9 +634,9 @@ Stringify a range object into A1 syntax.
|
|
|
624
634
|
|
|
625
635
|
##### Parameters
|
|
626
636
|
|
|
627
|
-
| Name | Type
|
|
628
|
-
| ----- |
|
|
629
|
-
| range | `
|
|
637
|
+
| Name | Type | Description |
|
|
638
|
+
| ----- | --------------------- | -------------- |
|
|
639
|
+
| range | [`RangeA1`](#RangeA1) | A range object |
|
|
630
640
|
|
|
631
641
|
##### Returns
|
|
632
642
|
|
|
@@ -660,9 +670,9 @@ Stringify a range object into R1C1 syntax.
|
|
|
660
670
|
|
|
661
671
|
##### Parameters
|
|
662
672
|
|
|
663
|
-
| Name | Type
|
|
664
|
-
| ----- |
|
|
665
|
-
| range | `
|
|
673
|
+
| Name | Type | Description |
|
|
674
|
+
| ----- | ------------------------- | -------------- |
|
|
675
|
+
| range | [`RangeR1C1`](#RangeR1C1) | A range object |
|
|
666
676
|
|
|
667
677
|
##### Returns
|
|
668
678
|
|
|
@@ -670,7 +680,7 @@ Stringify a range object into R1C1 syntax.
|
|
|
670
680
|
|
|
671
681
|
---
|
|
672
682
|
|
|
673
|
-
### <a id="tokenize" href="#tokenize">#</a> tokenize( formula, _[options = `{}`]_ ) ⇒ `Array<
|
|
683
|
+
### <a id="tokenize" href="#tokenize">#</a> tokenize( formula, _[options = `{}`]_ ) ⇒ `Array<Token>`
|
|
674
684
|
|
|
675
685
|
Breaks a string formula into a list of tokens.
|
|
676
686
|
|
|
@@ -714,11 +724,11 @@ To support syntax highlighting as you type, `STRING` tokens are allowed to be "u
|
|
|
714
724
|
|
|
715
725
|
##### Returns
|
|
716
726
|
|
|
717
|
-
`Array<
|
|
727
|
+
`Array<Token>` – An AST of nodes
|
|
718
728
|
|
|
719
729
|
---
|
|
720
730
|
|
|
721
|
-
### <a id="translateToA1" href="#translateToA1">#</a> translateToA1( formula, anchorCell, _[options = `{}`]_ ) ⇒ `string` | `Array<
|
|
731
|
+
### <a id="translateToA1" href="#translateToA1">#</a> translateToA1( formula, anchorCell, _[options = `{}`]_ ) ⇒ `string` | `Array<Token>`
|
|
722
732
|
|
|
723
733
|
Translates ranges in a formula or list of tokens from relative R1C1 syntax to absolute A1 syntax.
|
|
724
734
|
|
|
@@ -743,22 +753,23 @@ Note that if you are passing in a list of tokens that was not created using `mer
|
|
|
743
753
|
|
|
744
754
|
##### Parameters
|
|
745
755
|
|
|
746
|
-
| Name
|
|
747
|
-
|
|
|
748
|
-
| formula
|
|
749
|
-
| anchorCell
|
|
750
|
-
| [options]
|
|
751
|
-
| [options].
|
|
752
|
-
| [options].
|
|
753
|
-
| [options].
|
|
756
|
+
| Name | Type | Default | Description |
|
|
757
|
+
| ---------------------- | -------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
758
|
+
| formula | `string` \| `Array<Token>` | | A string (an Excel formula) or a token list that should be adjusted. |
|
|
759
|
+
| anchorCell | `string` | | A simple string reference to an A1 cell ID (`AF123` or`$C$5`). |
|
|
760
|
+
| [options] | `object` | `{}` | The options |
|
|
761
|
+
| [options].allowTernary | `boolean` | `true` | Enables the recognition of ternary ranges in the style of `A1:A` or `A1:1`. These are supported by Google Sheets but not Excel. See: References.md. |
|
|
762
|
+
| [options].mergeRefs | `boolean` | `true` | Should ranges be treated as whole references (`Sheet1!A1:B2`) or as separate tokens for each part: (`Sheet1`,`!`,`A1`,`:`,`B2`). |
|
|
763
|
+
| [options].wrapEdges | `boolean` | `true` | Wrap out-of-bounds ranges around sheet edges rather than turning them to #REF! errors |
|
|
764
|
+
| [options].xlsx | `boolean` | `false` | Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) |
|
|
754
765
|
|
|
755
766
|
##### Returns
|
|
756
767
|
|
|
757
|
-
`string` | `Array<
|
|
768
|
+
`string` | `Array<Token>` – A formula string or token list (depending on which was input)
|
|
758
769
|
|
|
759
770
|
---
|
|
760
771
|
|
|
761
|
-
### <a id="translateToR1C1" href="#translateToR1C1">#</a> translateToR1C1( formula, anchorCell, _[options = `{}`]_ ) ⇒ `string` | `Array<
|
|
772
|
+
### <a id="translateToR1C1" href="#translateToR1C1">#</a> translateToR1C1( formula, anchorCell, _[options = `{}`]_ ) ⇒ `string` | `Array<Token>`
|
|
762
773
|
|
|
763
774
|
Translates ranges in a formula or list of tokens from absolute A1 syntax to relative R1C1 syntax.
|
|
764
775
|
|
|
@@ -771,16 +782,17 @@ translateToR1C1("=SUM(E10,$E$2,Sheet!$E$3)", "D10");
|
|
|
771
782
|
|
|
772
783
|
##### Parameters
|
|
773
784
|
|
|
774
|
-
| Name
|
|
775
|
-
|
|
|
776
|
-
| formula
|
|
777
|
-
| anchorCell
|
|
778
|
-
| [options]
|
|
779
|
-
| [options].
|
|
785
|
+
| Name | Type | Default | Description |
|
|
786
|
+
| ---------------------- | -------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
787
|
+
| formula | `string` \| `Array<Token>` | | A string (an Excel formula) or a token list that should be adjusted. |
|
|
788
|
+
| anchorCell | `string` | | A simple string reference to an A1 cell ID (`AF123` or`$C$5`). |
|
|
789
|
+
| [options] | `object` | `{}` | The options |
|
|
790
|
+
| [options].allowTernary | `boolean` | `true` | Enables the recognition of ternary ranges in the style of `A1:A` or `A1:1`. These are supported by Google Sheets but not Excel. See: References.md. |
|
|
791
|
+
| [options].xlsx | `boolean` | `false` | Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) |
|
|
780
792
|
|
|
781
793
|
##### Returns
|
|
782
794
|
|
|
783
|
-
`string` | `Array<
|
|
795
|
+
`string` | `Array<Token>` – A formula string or token list (depending on which was input)
|
|
784
796
|
|
|
785
797
|
---
|
|
786
798
|
|
|
@@ -837,4 +849,121 @@ A dictionary of the types used to identify token variants.
|
|
|
837
849
|
|
|
838
850
|
---
|
|
839
851
|
|
|
852
|
+
## Types
|
|
853
|
+
|
|
854
|
+
### <a id="RangeA1" href="#RangeA1">#</a> RangeA1
|
|
855
|
+
|
|
856
|
+
A range in A1 style coordinates.
|
|
857
|
+
|
|
858
|
+
##### Properties
|
|
859
|
+
|
|
860
|
+
| Name | Type | Description |
|
|
861
|
+
| --------- | ------------------- | ----------------------------------------- |
|
|
862
|
+
| [$bottom] | `boolean` \| `null` | Signifies that bottom is a "locked" value |
|
|
863
|
+
| [$left] | `boolean` \| `null` | Signifies that left is a "locked" value |
|
|
864
|
+
| [$right] | `boolean` \| `null` | Signifies that right is a "locked" value |
|
|
865
|
+
| [$top] | `boolean` \| `null` | Signifies that top is a "locked" value |
|
|
866
|
+
| [bottom] | `number` \| `null` | Bottom row of the range |
|
|
867
|
+
| [left] | `number` \| `null` | Left column of the range |
|
|
868
|
+
| [right] | `number` \| `null` | Right column of the range |
|
|
869
|
+
| [top] | `number` \| `null` | Top row of the range |
|
|
870
|
+
|
|
871
|
+
---
|
|
872
|
+
|
|
873
|
+
### <a id="RangeR1C1" href="#RangeR1C1">#</a> RangeR1C1
|
|
874
|
+
|
|
875
|
+
A range in R1C1 style coordinates.
|
|
876
|
+
|
|
877
|
+
##### Properties
|
|
878
|
+
|
|
879
|
+
| Name | Type | Description |
|
|
880
|
+
| ----- | ------------------- | -------------------------------------- |
|
|
881
|
+
| [$c0] | `boolean` \| `null` | Signifies that c0 is an absolute value |
|
|
882
|
+
| [$c1] | `boolean` \| `null` | Signifies that c1 is an absolute value |
|
|
883
|
+
| [$r0] | `boolean` \| `null` | Signifies that r0 is an absolute value |
|
|
884
|
+
| [$r1] | `boolean` \| `null` | Signifies that r1 is an absolute value |
|
|
885
|
+
| [c0] | `number` \| `null` | Left column of the range |
|
|
886
|
+
| [c1] | `number` \| `null` | Right column of the range |
|
|
887
|
+
| [r0] | `number` \| `null` | Top row of the range |
|
|
888
|
+
| [r1] | `number` \| `null` | Bottom row of the range |
|
|
889
|
+
|
|
890
|
+
---
|
|
891
|
+
|
|
892
|
+
### <a id="ReferenceA1" href="#ReferenceA1">#</a> ReferenceA1
|
|
893
|
+
|
|
894
|
+
A reference containing an A1 style range. See [Prefixes.md] for documentation on how scopes work in Fx.
|
|
895
|
+
|
|
896
|
+
##### Properties
|
|
897
|
+
|
|
898
|
+
| Name | Type | Description |
|
|
899
|
+
| -------------- | --------------------- | ---------------------------------------- |
|
|
900
|
+
| [context] | `Array<string>` | A collection of scopes for the reference |
|
|
901
|
+
| [range] | [`RangeA1`](#RangeA1) | The reference's range |
|
|
902
|
+
| [sheetName] | `string` | A context sheet scope |
|
|
903
|
+
| [workbookName] | `string` | A context workbook scope |
|
|
904
|
+
|
|
905
|
+
---
|
|
906
|
+
|
|
907
|
+
### <a id="ReferenceR1C1" href="#ReferenceR1C1">#</a> ReferenceR1C1
|
|
908
|
+
|
|
909
|
+
A reference containing a R1C1 style range. See [Prefixes.md] for documentation on how scopes work in Fx.
|
|
910
|
+
|
|
911
|
+
##### Properties
|
|
912
|
+
|
|
913
|
+
| Name | Type | Description |
|
|
914
|
+
| -------------- | ------------------------- | ---------------------------------------- |
|
|
915
|
+
| [context] | `Array<string>` | A collection of scopes for the reference |
|
|
916
|
+
| [range] | [`RangeR1C1`](#RangeR1C1) | The reference's range |
|
|
917
|
+
| [sheetName] | `string` | A context sheet scope |
|
|
918
|
+
| [workbookName] | `string` | A context workbook scope |
|
|
919
|
+
|
|
920
|
+
---
|
|
921
|
+
|
|
922
|
+
### <a id="ReferenceStruct" href="#ReferenceStruct">#</a> ReferenceStruct
|
|
923
|
+
|
|
924
|
+
A reference containing a table slice definition. See [Prefixes.md] for documentation on how scopes work in Fx.
|
|
925
|
+
|
|
926
|
+
##### Properties
|
|
927
|
+
|
|
928
|
+
| Name | Type | Description |
|
|
929
|
+
| -------------- | --------------- | ---------------------------------------- |
|
|
930
|
+
| [columns] | `Array<string>` | The sections this reference targets |
|
|
931
|
+
| [context] | `Array<string>` | A collection of scopes for the reference |
|
|
932
|
+
| [sections] | `Array<string>` | The sections this reference targets |
|
|
933
|
+
| [sheetName] | `string` | A context sheet scope |
|
|
934
|
+
| [table] | `string` | The table this reference targets |
|
|
935
|
+
| [workbookName] | `string` | A context workbook scope |
|
|
936
|
+
|
|
937
|
+
---
|
|
938
|
+
|
|
939
|
+
### <a id="Token" href="#Token">#</a> Token extends `Record<string, any>`
|
|
940
|
+
|
|
941
|
+
A formula language token.
|
|
942
|
+
|
|
943
|
+
##### Properties
|
|
944
|
+
|
|
945
|
+
| Name | Type | Description |
|
|
946
|
+
| -------------- | --------------- | -------------------------------------- |
|
|
947
|
+
| [loc] | `Array<number>` | Source position offsets to the token |
|
|
948
|
+
| type | `string` | The type of the token |
|
|
949
|
+
| [unterminated] | `boolean` | Signifies an unterminated string token |
|
|
950
|
+
| value | `string` | The value of the token |
|
|
951
|
+
|
|
952
|
+
---
|
|
953
|
+
|
|
954
|
+
### <a id="TokenEnhanced" href="#TokenEnhanced">#</a> TokenEnhanced extends [`Token`](#Token)
|
|
955
|
+
|
|
956
|
+
A token with extra meta data.
|
|
957
|
+
|
|
958
|
+
##### Properties
|
|
959
|
+
|
|
960
|
+
| Name | Type | Description |
|
|
961
|
+
| --------- | --------- | ----------------------------------------------------------------- |
|
|
962
|
+
| [depth] | `number` | This token's level of nesting inside parentheses |
|
|
963
|
+
| [error] | `boolean` | Token is of unknown type or a paren without a match |
|
|
964
|
+
| [groupId] | `string` | The ID of a group which this token belongs (e.g. matching parens) |
|
|
965
|
+
| index | `number` | A zero based position in a token list |
|
|
966
|
+
|
|
967
|
+
---
|
|
968
|
+
|
|
840
969
|
|