@borgar/fx 4.3.0 → 4.4.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/dist/fx.d.ts +647 -0
- package/dist/fx.js +1 -1
- package/docs/API.md +361 -280
- package/lib/addTokenMeta.js +8 -15
- package/lib/addTokenMeta.spec.js +24 -2
- package/lib/parser.js +1 -1
- package/package.json +14 -10
- package/tsd.json +12 -0
- package/.jsdoc/config.json +0 -17
- package/.jsdoc/publish.js +0 -217
package/docs/API.md
CHANGED
|
@@ -1,91 +1,44 @@
|
|
|
1
1
|
# _Fx_ API
|
|
2
2
|
|
|
3
|
-
**Constants**
|
|
4
|
-
|
|
5
|
-
- [nodeTypes](#nodeTypes)
|
|
6
|
-
- [tokenTypes](#tokenTypes)
|
|
7
|
-
|
|
8
3
|
**Functions**
|
|
9
4
|
|
|
10
|
-
- [addA1RangeBounds(
|
|
11
|
-
- [addTokenMeta(
|
|
12
|
-
- [fixRanges(
|
|
13
|
-
- [
|
|
14
|
-
- [
|
|
15
|
-
- [
|
|
16
|
-
- [
|
|
17
|
-
- [
|
|
18
|
-
- [
|
|
19
|
-
- [
|
|
20
|
-
- [
|
|
21
|
-
- [
|
|
22
|
-
- [
|
|
23
|
-
- [
|
|
24
|
-
- [
|
|
25
|
-
- [
|
|
26
|
-
- [
|
|
27
|
-
- [
|
|
28
|
-
- [
|
|
29
|
-
- [
|
|
30
|
-
- [
|
|
31
|
-
- [
|
|
32
|
-
- [
|
|
33
|
-
- [
|
|
5
|
+
- [addA1RangeBounds( range )](#addA1RangeBounds)
|
|
6
|
+
- [addTokenMeta( tokenlist, _\[context\]_ )](#addTokenMeta)
|
|
7
|
+
- [fixRanges( formula, _\[options\]_ )](#fixRanges)
|
|
8
|
+
- [fromA1( rangeString )](#fromA1)
|
|
9
|
+
- [fromCol( columnString )](#fromCol)
|
|
10
|
+
- [fromR1C1( rangeString )](#fromR1C1)
|
|
11
|
+
- [isError( token )](#isError)
|
|
12
|
+
- [isFunction( token )](#isFunction)
|
|
13
|
+
- [isFxPrefix( token )](#isFxPrefix)
|
|
14
|
+
- [isLiteral( token )](#isLiteral)
|
|
15
|
+
- [isOperator( token )](#isOperator)
|
|
16
|
+
- [isRange( token )](#isRange)
|
|
17
|
+
- [isReference( token )](#isReference)
|
|
18
|
+
- [isWhitespace( token )](#isWhitespace)
|
|
19
|
+
- [mergeRefTokens( tokenlist )](#mergeRefTokens)
|
|
20
|
+
- [parse( formula, _\[options\]_ )](#parse)
|
|
21
|
+
- [parseA1Ref( refString, _\[options\]_ )](#parseA1Ref)
|
|
22
|
+
- [parseR1C1Ref( refString, _\[options\]_ )](#parseR1C1Ref)
|
|
23
|
+
- [parseStructRef( ref, _\[options\]_ )](#parseStructRef)
|
|
24
|
+
- [stringifyA1Ref( refObject, _\[options\]_ )](#stringifyA1Ref)
|
|
25
|
+
- [stringifyR1C1Ref( refObject, _\[options\]_ )](#stringifyR1C1Ref)
|
|
26
|
+
- [stringifyStructRef( refObject, _\[options\]_ )](#stringifyStructRef)
|
|
27
|
+
- [toA1( range )](#toA1)
|
|
28
|
+
- [toCol( columnIndex )](#toCol)
|
|
29
|
+
- [toR1C1( range )](#toR1C1)
|
|
30
|
+
- [tokenize( formula, _\[options\]_ )](#tokenize)
|
|
31
|
+
- [translateToA1( formula, anchorCell, _\[options\]_ )](#translateToA1)
|
|
32
|
+
- [translateToR1C1( formula, anchorCell, _\[options\]_ )](#translateToR1C1)
|
|
34
33
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
### <a name="nodeTypes" href="#nodeTypes">#</a> nodeTypes ⇒ `Object.<string>`
|
|
38
|
-
|
|
39
|
-
A dictionary of the types used to identify AST node variants.
|
|
40
|
-
|
|
41
|
-
**See also:** [parse](#parse).
|
|
42
|
-
|
|
43
|
-
#### Properties
|
|
44
|
-
|
|
45
|
-
| Name | Type | Description |
|
|
46
|
-
| ---- | ---- | ----------- |
|
|
47
|
-
| UNARY | `string` | A unary operation (`10%`) |
|
|
48
|
-
| BINARY | `string` | A binary operation (`10+10`) |
|
|
49
|
-
| REFERENCE | `string` | A range identifier (`A1`) |
|
|
50
|
-
| LITERAL | `string` | A literal (number, string, or boolean) (`123`, `"foo"`, `false`) |
|
|
51
|
-
| ERROR | `string` | An error literal (`#VALUE!`) |
|
|
52
|
-
| CALL | `string` | A function call expression (`SUM(1,2)`) |
|
|
53
|
-
| ARRAY | `string` | An array expression (`{1,2;3,4}`) |
|
|
54
|
-
| IDENTIFIER | `string` | A function name identifier (`SUM`) |
|
|
55
|
-
|
|
56
|
-
---
|
|
57
|
-
|
|
58
|
-
### <a name="tokenTypes" href="#tokenTypes">#</a> tokenTypes ⇒ `Object.<string>`
|
|
59
|
-
|
|
60
|
-
A dictionary of the types used to identify token variants.
|
|
61
|
-
|
|
62
|
-
**See also:** [tokenize](#tokenize).
|
|
34
|
+
**Constants**
|
|
63
35
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
| Name | Type | Description |
|
|
67
|
-
| ---- | ---- | ----------- |
|
|
68
|
-
| OPERATOR | `string` | Newline (`\n`) |
|
|
69
|
-
| BOOLEAN | `string` | Boolean literal (`TRUE`) |
|
|
70
|
-
| ERROR | `string` | Error literal (`#VALUE!`) |
|
|
71
|
-
| NUMBER | `string` | Number literal (`123.4`, `-1.5e+2`) |
|
|
72
|
-
| FUNCTION | `string` | Function name (`SUM`) |
|
|
73
|
-
| NEWLINE | `string` | Newline character (`\n`) |
|
|
74
|
-
| WHITESPACE | `string` | Whitespace character sequence (` `) |
|
|
75
|
-
| STRING | `string` | String literal (`"Lorem ipsum"`) |
|
|
76
|
-
| CONTEXT | `string` | Reference context ([Workbook.xlsx]Sheet1) |
|
|
77
|
-
| CONTEXT_QUOTE | `string` | Quoted reference context (`'[My workbook.xlsx]Sheet1'`) |
|
|
78
|
-
| REF_RANGE | `string` | A range identifier (`A1`) |
|
|
79
|
-
| REF_BEAM | `string` | A range "beam" identifier (`A:A` or `1:1`) |
|
|
80
|
-
| REF_TERNARY | `string` | A ternary range identifier (`B2:B`) |
|
|
81
|
-
| REF_NAMED | `string` | A name / named range identifier (`income`) |
|
|
82
|
-
| REF_STRUCT | `string` | A structured reference identifier (`table[[Column1]:[Column2]]`) |
|
|
83
|
-
| FX_PREFIX | `string` | A leading equals sign at the start of a formula (`=`) |
|
|
84
|
-
| UNKNOWN | `string` | Any unidentifiable range of characters. |
|
|
36
|
+
- [nodeTypes](#nodeTypes)
|
|
37
|
+
- [tokenTypes](#tokenTypes)
|
|
85
38
|
|
|
86
39
|
## Functions
|
|
87
40
|
|
|
88
|
-
### <a
|
|
41
|
+
### <a id="addA1RangeBounds" href="#addA1RangeBounds">#</a> addA1RangeBounds( range ) ⇒ `object`
|
|
89
42
|
|
|
90
43
|
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`.
|
|
91
44
|
|
|
@@ -116,19 +69,19 @@ addA1RangeBounds({
|
|
|
116
69
|
// }
|
|
117
70
|
```
|
|
118
71
|
|
|
119
|
-
|
|
72
|
+
##### Parameters
|
|
120
73
|
|
|
121
|
-
| Name
|
|
122
|
-
|
|
|
123
|
-
| range | `
|
|
74
|
+
| Name | Type | Description |
|
|
75
|
+
| ----- | -------- | ------------------------------------- |
|
|
76
|
+
| range | `object` | The range part of a reference object. |
|
|
124
77
|
|
|
125
|
-
|
|
78
|
+
##### Returns
|
|
126
79
|
|
|
127
|
-
`
|
|
80
|
+
`object` – same range with missing bounds filled in.
|
|
128
81
|
|
|
129
82
|
---
|
|
130
83
|
|
|
131
|
-
### <a
|
|
84
|
+
### <a id="addTokenMeta" href="#addTokenMeta">#</a> addTokenMeta( tokenlist, _[context = `{}`]_ ) ⇒ `Array<object>`
|
|
132
85
|
|
|
133
86
|
Runs through a list of tokens and adds extra attributes such as matching parens and ranges.
|
|
134
87
|
|
|
@@ -158,22 +111,22 @@ All ranges will be tagged with `.groupId` string identifier regardless of the nu
|
|
|
158
111
|
|
|
159
112
|
All will be tagged with `.error` (boolean `true`).
|
|
160
113
|
|
|
161
|
-
|
|
114
|
+
##### Parameters
|
|
162
115
|
|
|
163
|
-
| Name
|
|
164
|
-
|
|
|
165
|
-
| tokenlist
|
|
166
|
-
|
|
|
167
|
-
|
|
|
168
|
-
|
|
|
116
|
+
| Name | Type | Default | Description |
|
|
117
|
+
| ---------------------- | --------------- | ------- | -------------------------------------------- |
|
|
118
|
+
| tokenlist | `Array<object>` | | An array of tokens (from `tokenize()`) |
|
|
119
|
+
| [context] | `object` | `{}` | A contest used to match `A1` to `Sheet1!A1`. |
|
|
120
|
+
| [context].sheetName | `string` | `""` | An implied sheet name ('Sheet1') |
|
|
121
|
+
| [context].workbookName | `string` | `""` | An implied workbook name ('report.xlsx') |
|
|
169
122
|
|
|
170
|
-
|
|
123
|
+
##### Returns
|
|
171
124
|
|
|
172
|
-
`Array
|
|
125
|
+
`Array<object>` – The input array with the enchanced tokens
|
|
173
126
|
|
|
174
127
|
---
|
|
175
128
|
|
|
176
|
-
### <a
|
|
129
|
+
### <a id="fixRanges" href="#fixRanges">#</a> fixRanges( formula, _[options = `{}`]_ ) ⇒ `string` | `Array<object>`
|
|
177
130
|
|
|
178
131
|
Normalizes A1 style ranges and structured references in a formula or list of tokens.
|
|
179
132
|
|
|
@@ -199,200 +152,236 @@ Structured ranges are normalized cleaned up to have consistent order and capital
|
|
|
199
152
|
|
|
200
153
|
Returns the same formula with the ranges updated. If an array of tokens was supplied, then a new array is returned.
|
|
201
154
|
|
|
202
|
-
|
|
155
|
+
##### Parameters
|
|
156
|
+
|
|
157
|
+
| Name | Type | Default | Description |
|
|
158
|
+
| ------------------- | --------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
159
|
+
| formula | `string` \| `Array<object>` | | A string (an Excel formula) or a token list that should be adjusted. |
|
|
160
|
+
| [options] | `object` | `{}` | Options |
|
|
161
|
+
| [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. |
|
|
162
|
+
| [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
|
+
|
|
164
|
+
##### Returns
|
|
165
|
+
|
|
166
|
+
`string` | `Array<object>` – A formula string or token list (depending on which was input)
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
### <a id="fromA1" href="#fromA1">#</a> fromA1( rangeString ) ⇒ `object` | `null`
|
|
171
|
+
|
|
172
|
+
Parse a simple string reference to an A1 range into a range object. Will accept `A1`, `A2`, `A:A`, or `1:1`.
|
|
173
|
+
|
|
174
|
+
**See also:** [parseA1Ref](#parseA1Ref).
|
|
203
175
|
|
|
204
|
-
|
|
205
|
-
| ---- | ---- | ------- | ----------- |
|
|
206
|
-
| formula | `string` \| `Array.<Object>` | | A string (an Excel formula) or a token list that should be adjusted. |
|
|
207
|
-
| _[options]_ | `Object` | `{}` | Options |
|
|
208
|
-
| _[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. |
|
|
209
|
-
| _[options]_.xlsx | `boolean` | `false` | Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) |
|
|
176
|
+
##### Parameters
|
|
210
177
|
|
|
211
|
-
|
|
178
|
+
| Name | Type | Description |
|
|
179
|
+
| ----------- | -------- | -------------- |
|
|
180
|
+
| rangeString | `string` | A range string |
|
|
212
181
|
|
|
213
|
-
|
|
182
|
+
##### Returns
|
|
183
|
+
|
|
184
|
+
`object` | `null` – An object representing a valid reference or null if it is invalid.
|
|
214
185
|
|
|
215
186
|
---
|
|
216
187
|
|
|
217
|
-
### <a
|
|
188
|
+
### <a id="fromCol" href="#fromCol">#</a> fromCol( columnString ) ⇒ `number`
|
|
218
189
|
|
|
219
190
|
Convert a column string representation to a 0 based offset number (`"C"` = `2`).
|
|
220
191
|
|
|
221
192
|
The method expects a valid column identifier made up of _only_ A-Z letters, which may be either upper or lower case. Other input will return garbage.
|
|
222
193
|
|
|
223
|
-
|
|
194
|
+
##### Parameters
|
|
224
195
|
|
|
225
|
-
| Name
|
|
226
|
-
|
|
|
196
|
+
| Name | Type | Description |
|
|
197
|
+
| ------------ | -------- | ---------------------------- |
|
|
227
198
|
| columnString | `string` | The column string identifier |
|
|
228
199
|
|
|
229
|
-
|
|
200
|
+
##### Returns
|
|
230
201
|
|
|
231
202
|
`number` – Zero based column index number
|
|
232
203
|
|
|
233
204
|
---
|
|
234
205
|
|
|
235
|
-
### <a
|
|
206
|
+
### <a id="fromR1C1" href="#fromR1C1">#</a> fromR1C1( rangeString ) ⇒ `object` | `null`
|
|
207
|
+
|
|
208
|
+
Parse a simple string reference to an R1C1 range into a range object.
|
|
209
|
+
|
|
210
|
+
**See also:** [parseA1Ref](#parseA1Ref).
|
|
211
|
+
|
|
212
|
+
##### Parameters
|
|
213
|
+
|
|
214
|
+
| Name | Type | Description |
|
|
215
|
+
| ----------- | -------- | -------------- |
|
|
216
|
+
| rangeString | `string` | A range string |
|
|
217
|
+
|
|
218
|
+
##### Returns
|
|
219
|
+
|
|
220
|
+
`object` | `null` – An object representing a valid reference or null if it is invalid.
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
### <a id="isError" href="#isError">#</a> isError( token ) ⇒ `boolean`
|
|
236
225
|
|
|
237
226
|
Determines whether the specified token is an error.
|
|
238
227
|
|
|
239
228
|
Returns `true` if the input is a token of type ERROR (`#VALUE!`). In all other cases `false` is returned.
|
|
240
229
|
|
|
241
|
-
|
|
230
|
+
##### Parameters
|
|
242
231
|
|
|
243
|
-
| Name
|
|
244
|
-
|
|
|
245
|
-
| token | `
|
|
232
|
+
| Name | Type | Description |
|
|
233
|
+
| ----- | -------- | ----------- |
|
|
234
|
+
| token | `object` | The token |
|
|
246
235
|
|
|
247
|
-
|
|
236
|
+
##### Returns
|
|
248
237
|
|
|
249
238
|
`boolean` – True if the specified token is error, False otherwise.
|
|
250
239
|
|
|
251
240
|
---
|
|
252
241
|
|
|
253
|
-
### <a
|
|
242
|
+
### <a id="isFunction" href="#isFunction">#</a> isFunction( token ) ⇒ `boolean`
|
|
254
243
|
|
|
255
244
|
Determines whether the specified token is a function.
|
|
256
245
|
|
|
257
246
|
Returns `true` if the input is a token of type FUNCTION. In all other cases `false` is returned.
|
|
258
247
|
|
|
259
|
-
|
|
248
|
+
##### Parameters
|
|
260
249
|
|
|
261
|
-
| Name
|
|
262
|
-
|
|
|
263
|
-
| token | `
|
|
250
|
+
| Name | Type | Description |
|
|
251
|
+
| ----- | -------- | ----------- |
|
|
252
|
+
| token | `object` | The token |
|
|
264
253
|
|
|
265
|
-
|
|
254
|
+
##### Returns
|
|
266
255
|
|
|
267
256
|
`boolean` – True if the specified token is function, False otherwise.
|
|
268
257
|
|
|
269
258
|
---
|
|
270
259
|
|
|
271
|
-
### <a
|
|
260
|
+
### <a id="isFxPrefix" href="#isFxPrefix">#</a> isFxPrefix( token ) ⇒ `boolean`
|
|
272
261
|
|
|
273
262
|
Returns `true` if the input is a token of type FX_PREFIX (leading `=` in formula). In all other cases `false` is returned.
|
|
274
263
|
|
|
275
|
-
|
|
264
|
+
##### Parameters
|
|
276
265
|
|
|
277
|
-
| Name
|
|
278
|
-
|
|
|
279
|
-
| token | `
|
|
266
|
+
| Name | Type | Description |
|
|
267
|
+
| ----- | -------- | ----------- |
|
|
268
|
+
| token | `object` | The token |
|
|
280
269
|
|
|
281
|
-
|
|
270
|
+
##### Returns
|
|
282
271
|
|
|
283
272
|
`boolean` – True if the specified token is effects prefix, False otherwise.
|
|
284
273
|
|
|
285
274
|
---
|
|
286
275
|
|
|
287
|
-
### <a
|
|
276
|
+
### <a id="isLiteral" href="#isLiteral">#</a> isLiteral( token ) ⇒ `boolean`
|
|
288
277
|
|
|
289
278
|
Determines whether the specified token is a literal.
|
|
290
279
|
|
|
291
280
|
Returns `true` if the input is a token of type BOOLEAN (`TRUE` or `FALSE`), ERROR (`#VALUE!`), NUMBER (123.4), or STRING (`"lorem ipsum"`). In all other cases `false` is returned.
|
|
292
281
|
|
|
293
|
-
|
|
282
|
+
##### Parameters
|
|
294
283
|
|
|
295
|
-
| Name
|
|
296
|
-
|
|
|
297
|
-
| token | `
|
|
284
|
+
| Name | Type | Description |
|
|
285
|
+
| ----- | -------- | ----------- |
|
|
286
|
+
| token | `object` | The token |
|
|
298
287
|
|
|
299
|
-
|
|
288
|
+
##### Returns
|
|
300
289
|
|
|
301
290
|
`boolean` – True if the specified token is literal, False otherwise.
|
|
302
291
|
|
|
303
292
|
---
|
|
304
293
|
|
|
305
|
-
### <a
|
|
294
|
+
### <a id="isOperator" href="#isOperator">#</a> isOperator( token ) ⇒ `boolean`
|
|
306
295
|
|
|
307
296
|
Determines whether the specified token is an operator.
|
|
308
297
|
|
|
309
298
|
Returns `true` if the input is a token of type OPERATOR (`+` or `:`). In all other cases `false` is returned.
|
|
310
299
|
|
|
311
|
-
|
|
300
|
+
##### Parameters
|
|
312
301
|
|
|
313
|
-
| Name
|
|
314
|
-
|
|
|
315
|
-
| token | `
|
|
302
|
+
| Name | Type | Description |
|
|
303
|
+
| ----- | -------- | ----------- |
|
|
304
|
+
| token | `object` | The token |
|
|
316
305
|
|
|
317
|
-
|
|
306
|
+
##### Returns
|
|
318
307
|
|
|
319
308
|
`boolean` – True if the specified token is operator, False otherwise.
|
|
320
309
|
|
|
321
310
|
---
|
|
322
311
|
|
|
323
|
-
### <a
|
|
312
|
+
### <a id="isRange" href="#isRange">#</a> isRange( token ) ⇒ `boolean`
|
|
324
313
|
|
|
325
314
|
Determines whether the specified token is a range.
|
|
326
315
|
|
|
327
316
|
Returns `true` if the input is a token that has a type of either REF_RANGE (`A1` or `A1:B2`), REF_TERNARY (`A1:A`, `A1:1`, `1:A1`, or `A:A1`), or REF_BEAM (`A:A` or `1:1`). In all other cases `false` is returned.
|
|
328
317
|
|
|
329
|
-
|
|
318
|
+
##### Parameters
|
|
330
319
|
|
|
331
|
-
| Name
|
|
332
|
-
|
|
|
333
|
-
| token | `
|
|
320
|
+
| Name | Type | Description |
|
|
321
|
+
| ----- | -------- | ----------- |
|
|
322
|
+
| token | `object` | A token |
|
|
334
323
|
|
|
335
|
-
|
|
324
|
+
##### Returns
|
|
336
325
|
|
|
337
326
|
`boolean` – True if the specified token is range, False otherwise.
|
|
338
327
|
|
|
339
328
|
---
|
|
340
329
|
|
|
341
|
-
### <a
|
|
330
|
+
### <a id="isReference" href="#isReference">#</a> isReference( token ) ⇒ `boolean`
|
|
342
331
|
|
|
343
332
|
Determines whether the specified token is a reference.
|
|
344
333
|
|
|
345
334
|
Returns `true` if the input is a token of type REF_RANGE (`A1` or `A1:B2`), REF_TERNARY (`A1:A`, `A1:1`, `1:A1`, or `A:A1`), REF_BEAM (`A:A` or `1:1`), or REF_NAMED (`myrange`). In all other cases `false` is returned.
|
|
346
335
|
|
|
347
|
-
|
|
336
|
+
##### Parameters
|
|
348
337
|
|
|
349
|
-
| Name
|
|
350
|
-
|
|
|
351
|
-
| token | `
|
|
338
|
+
| Name | Type | Description |
|
|
339
|
+
| ----- | -------- | ----------- |
|
|
340
|
+
| token | `object` | The token |
|
|
352
341
|
|
|
353
|
-
|
|
342
|
+
##### Returns
|
|
354
343
|
|
|
355
344
|
`boolean` – True if the specified token is reference, False otherwise.
|
|
356
345
|
|
|
357
346
|
---
|
|
358
347
|
|
|
359
|
-
### <a
|
|
348
|
+
### <a id="isWhitespace" href="#isWhitespace">#</a> isWhitespace( token ) ⇒ `boolean`
|
|
360
349
|
|
|
361
350
|
Determines whether the specified token is whitespace.
|
|
362
351
|
|
|
363
352
|
Returns `true` if the input is a token of type WHITESPACE (` `) or NEWLINE (`\n`). In all other cases `false` is returned.
|
|
364
353
|
|
|
365
|
-
|
|
354
|
+
##### Parameters
|
|
366
355
|
|
|
367
|
-
| Name
|
|
368
|
-
|
|
|
369
|
-
| token | `
|
|
356
|
+
| Name | Type | Description |
|
|
357
|
+
| ----- | -------- | ----------- |
|
|
358
|
+
| token | `object` | The token |
|
|
370
359
|
|
|
371
|
-
|
|
360
|
+
##### Returns
|
|
372
361
|
|
|
373
362
|
`boolean` – True if the specified token is whitespace, False otherwise.
|
|
374
363
|
|
|
375
364
|
---
|
|
376
365
|
|
|
377
|
-
### <a
|
|
366
|
+
### <a id="mergeRefTokens" href="#mergeRefTokens">#</a> mergeRefTokens( tokenlist ) ⇒ `Array<any>`
|
|
378
367
|
|
|
379
368
|
Merges context with reference tokens as possible in a list of tokens.
|
|
380
369
|
|
|
381
370
|
When given a tokenlist, this function returns a new list with ranges returned as whole references (`Sheet1!A1:B2`) rather than separate tokens for each part: (`Sheet1`,`!`,`A1`,`:`,`B2`).
|
|
382
371
|
|
|
383
|
-
|
|
372
|
+
##### Parameters
|
|
384
373
|
|
|
385
|
-
| Name
|
|
386
|
-
|
|
|
387
|
-
| tokenlist | `Array
|
|
374
|
+
| Name | Type | Description |
|
|
375
|
+
| --------- | --------------- | -------------------------------------- |
|
|
376
|
+
| tokenlist | `Array<object>` | An array of tokens (from `tokenize()`) |
|
|
388
377
|
|
|
389
|
-
|
|
378
|
+
##### Returns
|
|
390
379
|
|
|
391
|
-
`Array
|
|
380
|
+
`Array<any>` – A new list of tokens with range parts merged.
|
|
392
381
|
|
|
393
382
|
---
|
|
394
383
|
|
|
395
|
-
### <a
|
|
384
|
+
### <a id="parse" href="#parse">#</a> parse( formula, _[options = `{}`]_ ) ⇒ `object`
|
|
396
385
|
|
|
397
386
|
Parses a string formula or list of tokens into an AST.
|
|
398
387
|
|
|
@@ -402,28 +391,28 @@ The AST Abstract Syntax Tree's format is documented in [AST_format.md](./AST_for
|
|
|
402
391
|
|
|
403
392
|
**See also:** [nodeTypes](#nodeTypes).
|
|
404
393
|
|
|
405
|
-
|
|
394
|
+
##### Parameters
|
|
406
395
|
|
|
407
|
-
| Name
|
|
408
|
-
|
|
|
409
|
-
| formula
|
|
410
|
-
|
|
|
411
|
-
|
|
|
412
|
-
|
|
|
413
|
-
|
|
|
414
|
-
|
|
|
415
|
-
|
|
|
416
|
-
|
|
|
417
|
-
|
|
|
418
|
-
|
|
|
396
|
+
| Name | Type | Default | Description |
|
|
397
|
+
| --------------------------- | --------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
398
|
+
| formula | `string` \| `Array<object>` | | An Excel formula string (an Excel expression) or an array of tokens. |
|
|
399
|
+
| [options] | `object` | `{}` | Options |
|
|
400
|
+
| [options].allowNamed | `boolean` | `true` | Enable parsing names as well as ranges. |
|
|
401
|
+
| [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. |
|
|
402
|
+
| [options].negativeNumbers | `boolean` | `true` | Merges unary minuses with their immediately following number tokens (`-`,`1`) => `-1` (alternatively these will be unary operations in the tree). |
|
|
403
|
+
| [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. |
|
|
404
|
+
| [options].permitArrayRanges | `boolean` | `false` | Ranges are allowed as elements of arrays. This is a feature in Google Sheets while Excel does not allow it. |
|
|
405
|
+
| [options].r1c1 | `boolean` | `false` | Ranges are expected to be in the R1C1 style format rather than the more popular A1 style. |
|
|
406
|
+
| [options].withLocation | `boolean` | `false` | Nodes will include source position offsets to the tokens: `{ loc: [ start, end ] }` |
|
|
407
|
+
| [options].xlsx | `boolean` | `false` | Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) |
|
|
419
408
|
|
|
420
|
-
|
|
409
|
+
##### Returns
|
|
421
410
|
|
|
422
|
-
`
|
|
411
|
+
`object` – An AST of nodes
|
|
423
412
|
|
|
424
413
|
---
|
|
425
414
|
|
|
426
|
-
### <a
|
|
415
|
+
### <a id="parseA1Ref" href="#parseA1Ref">#</a> parseA1Ref( refString, _[options = `{}`]_ ) ⇒ `object` | `null`
|
|
427
416
|
|
|
428
417
|
Parse a string reference into an object representing it.
|
|
429
418
|
|
|
@@ -446,23 +435,23 @@ parseA1Ref('Sheet1!A$1:$B2');
|
|
|
446
435
|
|
|
447
436
|
For A:A or A1:A style ranges, `null` will be used for any dimensions that the syntax does not specify:
|
|
448
437
|
|
|
449
|
-
|
|
438
|
+
##### Parameters
|
|
450
439
|
|
|
451
|
-
| Name
|
|
452
|
-
|
|
|
453
|
-
| refString
|
|
454
|
-
|
|
|
455
|
-
|
|
|
456
|
-
|
|
|
457
|
-
|
|
|
440
|
+
| Name | Type | Default | Description |
|
|
441
|
+
| ---------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
442
|
+
| refString | `string` | | An A1-style reference string |
|
|
443
|
+
| [options] | `object` | `{}` | Options |
|
|
444
|
+
| [options].allowNamed | `boolean` | `true` | Enable parsing names as well as ranges. |
|
|
445
|
+
| [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. |
|
|
446
|
+
| [options].xlsx | `boolean` | `false` | Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) |
|
|
458
447
|
|
|
459
|
-
|
|
448
|
+
##### Returns
|
|
460
449
|
|
|
461
|
-
`
|
|
450
|
+
`object` | `null` – An object representing a valid reference or null if it is invalid.
|
|
462
451
|
|
|
463
452
|
---
|
|
464
453
|
|
|
465
|
-
### <a
|
|
454
|
+
### <a id="parseR1C1Ref" href="#parseR1C1Ref">#</a> parseR1C1Ref( refString, _[options = `{}`]_ ) ⇒ `object` | `null`
|
|
466
455
|
|
|
467
456
|
Parse a string reference into an object representing it.
|
|
468
457
|
|
|
@@ -483,23 +472,23 @@ parseR1C1Ref('Sheet1!R[9]C9:R[9]C9');
|
|
|
483
472
|
// }
|
|
484
473
|
```
|
|
485
474
|
|
|
486
|
-
|
|
475
|
+
##### Parameters
|
|
487
476
|
|
|
488
|
-
| Name
|
|
489
|
-
|
|
|
490
|
-
| refString
|
|
491
|
-
|
|
|
492
|
-
|
|
|
493
|
-
|
|
|
494
|
-
|
|
|
477
|
+
| Name | Type | Default | Description |
|
|
478
|
+
| ---------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
479
|
+
| refString | `string` | | An R1C1-style reference string |
|
|
480
|
+
| [options] | `object` | `{}` | Options |
|
|
481
|
+
| [options].allowNamed | `boolean` | `true` | Enable parsing names as well as ranges. |
|
|
482
|
+
| [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. |
|
|
483
|
+
| [options].xlsx | `boolean` | `false` | Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) |
|
|
495
484
|
|
|
496
|
-
|
|
485
|
+
##### Returns
|
|
497
486
|
|
|
498
|
-
`
|
|
487
|
+
`object` | `null` – An object representing a valid reference or null if it is invalid.
|
|
499
488
|
|
|
500
489
|
---
|
|
501
490
|
|
|
502
|
-
### <a
|
|
491
|
+
### <a id="parseStructRef" href="#parseStructRef">#</a> parseStructRef( ref, _[options = `{}`]_ ) ⇒ `object` | `null`
|
|
503
492
|
|
|
504
493
|
Parse a structured reference string into an object representing it.
|
|
505
494
|
|
|
@@ -515,21 +504,21 @@ parseStructRef('workbook.xlsx!tableName[[#Data],[Column1]:[Column2]]');
|
|
|
515
504
|
|
|
516
505
|
For A:A or A1:A style ranges, `null` will be used for any dimensions that the syntax does not specify:
|
|
517
506
|
|
|
518
|
-
|
|
507
|
+
##### Parameters
|
|
519
508
|
|
|
520
|
-
| Name
|
|
521
|
-
|
|
|
522
|
-
| ref
|
|
523
|
-
|
|
|
524
|
-
|
|
|
509
|
+
| Name | Type | Default | Description |
|
|
510
|
+
| -------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
511
|
+
| ref | `string` | | A structured reference string |
|
|
512
|
+
| [options] | `object` | `{}` | Options |
|
|
513
|
+
| [options].xlsx | `boolean` | `false` | Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) |
|
|
525
514
|
|
|
526
|
-
|
|
515
|
+
##### Returns
|
|
527
516
|
|
|
528
|
-
`
|
|
517
|
+
`object` | `null` – An object representing a valid reference or null if it is invalid.
|
|
529
518
|
|
|
530
519
|
---
|
|
531
520
|
|
|
532
|
-
### <a
|
|
521
|
+
### <a id="stringifyA1Ref" href="#stringifyA1Ref">#</a> stringifyA1Ref( refObject, _[options = `{}`]_ ) ⇒ `object`
|
|
533
522
|
|
|
534
523
|
Get an A1-style string representation of a reference object.
|
|
535
524
|
|
|
@@ -550,21 +539,21 @@ stringifyA1Ref({
|
|
|
550
539
|
// => 'Sheet1!A$1:$B2'
|
|
551
540
|
```
|
|
552
541
|
|
|
553
|
-
|
|
542
|
+
##### Parameters
|
|
554
543
|
|
|
555
|
-
| Name
|
|
556
|
-
|
|
|
557
|
-
| refObject
|
|
558
|
-
|
|
|
559
|
-
|
|
|
544
|
+
| Name | Type | Default | Description |
|
|
545
|
+
| -------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
546
|
+
| refObject | `object` | | A reference object |
|
|
547
|
+
| [options] | `object` | `{}` | Options |
|
|
548
|
+
| [options].xlsx | `boolean` | `false` | Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) |
|
|
560
549
|
|
|
561
|
-
|
|
550
|
+
##### Returns
|
|
562
551
|
|
|
563
|
-
`
|
|
552
|
+
`object` – The reference in A1-style string format
|
|
564
553
|
|
|
565
554
|
---
|
|
566
555
|
|
|
567
|
-
### <a
|
|
556
|
+
### <a id="stringifyR1C1Ref" href="#stringifyR1C1Ref">#</a> stringifyR1C1Ref( refObject, _[options = `{}`]_ ) ⇒ `object`
|
|
568
557
|
|
|
569
558
|
Get an R1C1-style string representation of a reference object.
|
|
570
559
|
|
|
@@ -585,21 +574,21 @@ stringifyR1C1Ref({
|
|
|
585
574
|
// => 'Sheet1!R[9]C9:R[9]C9'
|
|
586
575
|
```
|
|
587
576
|
|
|
588
|
-
|
|
577
|
+
##### Parameters
|
|
589
578
|
|
|
590
|
-
| Name
|
|
591
|
-
|
|
|
592
|
-
| refObject
|
|
593
|
-
|
|
|
594
|
-
|
|
|
579
|
+
| Name | Type | Default | Description |
|
|
580
|
+
| -------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
581
|
+
| refObject | `object` | | A reference object |
|
|
582
|
+
| [options] | `object` | `{}` | Options |
|
|
583
|
+
| [options].xlsx | `boolean` | `false` | Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) |
|
|
595
584
|
|
|
596
|
-
|
|
585
|
+
##### Returns
|
|
597
586
|
|
|
598
|
-
`
|
|
587
|
+
`object` – The reference in R1C1-style string format
|
|
599
588
|
|
|
600
589
|
---
|
|
601
590
|
|
|
602
|
-
### <a
|
|
591
|
+
### <a id="stringifyStructRef" href="#stringifyStructRef">#</a> stringifyStructRef( refObject, _[options = `{}`]_ ) ⇒ `object`
|
|
603
592
|
|
|
604
593
|
Get a string representation of a structured reference object.
|
|
605
594
|
|
|
@@ -613,39 +602,75 @@ stringifyStructRef({
|
|
|
613
602
|
// => 'workbook.xlsx!tableName[[#Data],[Column1]:[Column2]]'
|
|
614
603
|
```
|
|
615
604
|
|
|
616
|
-
|
|
605
|
+
##### Parameters
|
|
617
606
|
|
|
618
|
-
| Name
|
|
619
|
-
|
|
|
620
|
-
| refObject
|
|
621
|
-
|
|
|
622
|
-
|
|
|
607
|
+
| Name | Type | Default | Description |
|
|
608
|
+
| -------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
609
|
+
| refObject | `object` | | A structured reference object |
|
|
610
|
+
| [options] | `object` | `{}` | Options |
|
|
611
|
+
| [options].xlsx | `boolean` | `false` | Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) |
|
|
623
612
|
|
|
624
|
-
|
|
613
|
+
##### Returns
|
|
625
614
|
|
|
626
|
-
`
|
|
615
|
+
`object` – The structured reference in string format
|
|
627
616
|
|
|
628
617
|
---
|
|
629
618
|
|
|
630
|
-
### <a
|
|
619
|
+
### <a id="toA1" href="#toA1">#</a> toA1( range ) ⇒ `string`
|
|
620
|
+
|
|
621
|
+
Stringify a range object into A1 syntax.
|
|
622
|
+
|
|
623
|
+
**See also:** [parseA1Ref](#parseA1Ref).
|
|
624
|
+
|
|
625
|
+
##### Parameters
|
|
626
|
+
|
|
627
|
+
| Name | Type | Description |
|
|
628
|
+
| ----- | -------- | -------------- |
|
|
629
|
+
| range | `object` | A range object |
|
|
630
|
+
|
|
631
|
+
##### Returns
|
|
632
|
+
|
|
633
|
+
`string` – An A1-style string represenation of a range
|
|
634
|
+
|
|
635
|
+
---
|
|
636
|
+
|
|
637
|
+
### <a id="toCol" href="#toCol">#</a> toCol( columnIndex ) ⇒ `string`
|
|
631
638
|
|
|
632
639
|
Convert a 0 based offset number to a column string representation (`2` = `"C"`).
|
|
633
640
|
|
|
634
641
|
The method expects a number between 0 and 16383. Other input will return garbage.
|
|
635
642
|
|
|
636
|
-
|
|
643
|
+
##### Parameters
|
|
637
644
|
|
|
638
|
-
| Name
|
|
639
|
-
|
|
|
645
|
+
| Name | Type | Description |
|
|
646
|
+
| ----------- | -------- | ------------------------------ |
|
|
640
647
|
| columnIndex | `number` | Zero based column index number |
|
|
641
648
|
|
|
642
|
-
|
|
649
|
+
##### Returns
|
|
643
650
|
|
|
644
651
|
`string` – The column string identifier
|
|
645
652
|
|
|
646
653
|
---
|
|
647
654
|
|
|
648
|
-
### <a
|
|
655
|
+
### <a id="toR1C1" href="#toR1C1">#</a> toR1C1( range ) ⇒ `string`
|
|
656
|
+
|
|
657
|
+
Stringify a range object into R1C1 syntax.
|
|
658
|
+
|
|
659
|
+
**See also:** [parseR1C1Ref](#parseR1C1Ref).
|
|
660
|
+
|
|
661
|
+
##### Parameters
|
|
662
|
+
|
|
663
|
+
| Name | Type | Description |
|
|
664
|
+
| ----- | -------- | -------------- |
|
|
665
|
+
| range | `object` | A range object |
|
|
666
|
+
|
|
667
|
+
##### Returns
|
|
668
|
+
|
|
669
|
+
`string` – An R1C1-style string represenation of a range
|
|
670
|
+
|
|
671
|
+
---
|
|
672
|
+
|
|
673
|
+
### <a id="tokenize" href="#tokenize">#</a> tokenize( formula, _[options = `{}`]_ ) ⇒ `Array<object>`
|
|
649
674
|
|
|
650
675
|
Breaks a string formula into a list of tokens.
|
|
651
676
|
|
|
@@ -674,26 +699,26 @@ To support syntax highlighting as you type, `STRING` tokens are allowed to be "u
|
|
|
674
699
|
|
|
675
700
|
**See also:** [tokenTypes](#tokenTypes).
|
|
676
701
|
|
|
677
|
-
|
|
702
|
+
##### Parameters
|
|
678
703
|
|
|
679
|
-
| Name
|
|
680
|
-
|
|
|
681
|
-
| formula
|
|
682
|
-
|
|
|
683
|
-
|
|
|
684
|
-
|
|
|
685
|
-
|
|
|
686
|
-
|
|
|
687
|
-
|
|
|
688
|
-
|
|
|
704
|
+
| Name | Type | Default | Description |
|
|
705
|
+
| ------------------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
706
|
+
| formula | `string` | | An Excel formula string (an Excel expression) or an array of tokens. |
|
|
707
|
+
| [options] | `object` | `{}` | Options |
|
|
708
|
+
| [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. |
|
|
709
|
+
| [options].mergeRefs | `boolean` | `true` | Should ranges be returned as whole references (`Sheet1!A1:B2`) or as separate tokens for each part: (`Sheet1`,`!`,`A1`,`:`,`B2`). This is the same as calling [`mergeRefTokens`](#mergeRefTokens) |
|
|
710
|
+
| [options].negativeNumbers | `boolean` | `true` | Merges unary minuses with their immediately following number tokens (`-`,`1`) => `-1` (alternatively these will be unary operations in the tree). |
|
|
711
|
+
| [options].r1c1 | `boolean` | `false` | Ranges are expected to be in the R1C1 style format rather than the more popular A1 style. |
|
|
712
|
+
| [options].withLocation | `boolean` | `true` | Nodes will include source position offsets to the tokens: `{ loc: [ start, end ] }` |
|
|
713
|
+
| [options].xlsx | `boolean` | `false` | Enables a `[1]Sheet1!A1` or `[1]!name` syntax form for external workbooks found only in XLSX files. |
|
|
689
714
|
|
|
690
|
-
|
|
715
|
+
##### Returns
|
|
691
716
|
|
|
692
|
-
`Array
|
|
717
|
+
`Array<object>` – An AST of nodes
|
|
693
718
|
|
|
694
719
|
---
|
|
695
720
|
|
|
696
|
-
### <a
|
|
721
|
+
### <a id="translateToA1" href="#translateToA1">#</a> translateToA1( formula, anchorCell, _[options = `{}`]_ ) ⇒ `string` | `Array<object>`
|
|
697
722
|
|
|
698
723
|
Translates ranges in a formula or list of tokens from relative R1C1 syntax to absolute A1 syntax.
|
|
699
724
|
|
|
@@ -716,24 +741,24 @@ translateToA1("=R[-1]C[-1]", "A1", { wrapEdges: false });
|
|
|
716
741
|
|
|
717
742
|
Note that if you are passing in a list of tokens that was not created using `mergeRefs` and you disable edge wrapping (or you simply set both options to false), you can end up with a formula such as `=#REF!:B2` or `=Sheet3!#REF!:F3`. These are valid formulas in the Excel formula language and Excel will accept them, but they are not supported in Google Sheets.
|
|
718
743
|
|
|
719
|
-
|
|
744
|
+
##### Parameters
|
|
720
745
|
|
|
721
|
-
| Name
|
|
722
|
-
|
|
|
723
|
-
| formula
|
|
724
|
-
| anchorCell
|
|
725
|
-
|
|
|
726
|
-
|
|
|
727
|
-
|
|
|
728
|
-
|
|
|
746
|
+
| Name | Type | Default | Description |
|
|
747
|
+
| ------------------- | --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
|
748
|
+
| formula | `string` \| `Array<object>` | | A string (an Excel formula) or a token list that should be adjusted. |
|
|
749
|
+
| anchorCell | `string` | | A simple string reference to an A1 cell ID (`AF123` or`$C$5`). |
|
|
750
|
+
| [options] | `object` | `{}` | The options |
|
|
751
|
+
| [options].mergeRefs | `boolean` | `true` | Should ranges be treated as whole references (`Sheet1!A1:B2`) or as separate tokens for each part: (`Sheet1`,`!`,`A1`,`:`,`B2`). |
|
|
752
|
+
| [options].wrapEdges | `boolean` | `true` | Wrap out-of-bounds ranges around sheet edges rather than turning them to #REF! errors |
|
|
753
|
+
| [options].xlsx | `boolean` | `false` | Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) |
|
|
729
754
|
|
|
730
|
-
|
|
755
|
+
##### Returns
|
|
731
756
|
|
|
732
|
-
`string` | `Array
|
|
757
|
+
`string` | `Array<object>` – A formula string or token list (depending on which was input)
|
|
733
758
|
|
|
734
759
|
---
|
|
735
760
|
|
|
736
|
-
### <a
|
|
761
|
+
### <a id="translateToR1C1" href="#translateToR1C1">#</a> translateToR1C1( formula, anchorCell, _[options = `{}`]_ ) ⇒ `string` | `Array<object>`
|
|
737
762
|
|
|
738
763
|
Translates ranges in a formula or list of tokens from absolute A1 syntax to relative R1C1 syntax.
|
|
739
764
|
|
|
@@ -744,16 +769,72 @@ translateToR1C1("=SUM(E10,$E$2,Sheet!$E$3)", "D10");
|
|
|
744
769
|
// => "=SUM(RC[1],R2C5,Sheet!R3C5)");
|
|
745
770
|
```
|
|
746
771
|
|
|
747
|
-
|
|
772
|
+
##### Parameters
|
|
773
|
+
|
|
774
|
+
| Name | Type | Default | Description |
|
|
775
|
+
| -------------- | --------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
776
|
+
| formula | `string` \| `Array<object>` | | A string (an Excel formula) or a token list that should be adjusted. |
|
|
777
|
+
| anchorCell | `string` | | A simple string reference to an A1 cell ID (`AF123` or`$C$5`). |
|
|
778
|
+
| [options] | `object` | `{}` | The options |
|
|
779
|
+
| [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
|
+
|
|
781
|
+
##### Returns
|
|
748
782
|
|
|
749
|
-
|
|
|
750
|
-
| ---- | ---- | ------- | ----------- |
|
|
751
|
-
| formula | `string` \| `Array.<Object>` | | A string (an Excel formula) or a token list that should be adjusted. |
|
|
752
|
-
| anchorCell | `string` | | A simple string reference to an A1 cell ID (`AF123` or`$C$5`). |
|
|
753
|
-
| _[options]_ | `Object` | `{}` | The options |
|
|
754
|
-
| _[options]_.xlsx | `boolean` | `false` | Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) |
|
|
783
|
+
`string` | `Array<object>` – A formula string or token list (depending on which was input)
|
|
755
784
|
|
|
756
|
-
|
|
785
|
+
---
|
|
786
|
+
|
|
787
|
+
## Constants
|
|
788
|
+
|
|
789
|
+
### <a id="nodeTypes" href="#nodeTypes">#</a> nodeTypes = `Readonly<Record<string, string>>`
|
|
790
|
+
|
|
791
|
+
A dictionary of the types used to identify AST node variants.
|
|
792
|
+
|
|
793
|
+
**See also:** [parse](#parse).
|
|
794
|
+
|
|
795
|
+
##### Properties
|
|
796
|
+
|
|
797
|
+
| Name | Type | Description |
|
|
798
|
+
| ---------- | -------- | ---------------------------------------------------------------- |
|
|
799
|
+
| ARRAY | `string` | An array expression (`{1,2;3,4}`) |
|
|
800
|
+
| BINARY | `string` | A binary operation (`10+10`) |
|
|
801
|
+
| CALL | `string` | A function call expression (`SUM(1,2)`) |
|
|
802
|
+
| ERROR | `string` | An error literal (`#VALUE!`) |
|
|
803
|
+
| IDENTIFIER | `string` | A function name identifier (`SUM`) |
|
|
804
|
+
| LITERAL | `string` | A literal (number, string, or boolean) (`123`, `"foo"`, `false`) |
|
|
805
|
+
| REFERENCE | `string` | A range identifier (`A1`) |
|
|
806
|
+
| UNARY | `string` | A unary operation (`10%`) |
|
|
807
|
+
|
|
808
|
+
---
|
|
809
|
+
|
|
810
|
+
### <a id="tokenTypes" href="#tokenTypes">#</a> tokenTypes = `Readonly<Record<string, string>>`
|
|
811
|
+
|
|
812
|
+
A dictionary of the types used to identify token variants.
|
|
813
|
+
|
|
814
|
+
**See also:** [tokenize](#tokenize).
|
|
815
|
+
|
|
816
|
+
##### Properties
|
|
817
|
+
|
|
818
|
+
| Name | Type | Description |
|
|
819
|
+
| ------------- | -------- | ---------------------------------------------------------------- |
|
|
820
|
+
| BOOLEAN | `string` | Boolean literal (`TRUE`) |
|
|
821
|
+
| CONTEXT | `string` | Reference context ([Workbook.xlsx]Sheet1) |
|
|
822
|
+
| CONTEXT_QUOTE | `string` | Quoted reference context (`'[My workbook.xlsx]Sheet1'`) |
|
|
823
|
+
| ERROR | `string` | Error literal (`#VALUE!`) |
|
|
824
|
+
| FUNCTION | `string` | Function name (`SUM`) |
|
|
825
|
+
| FX_PREFIX | `string` | A leading equals sign at the start of a formula (`=`) |
|
|
826
|
+
| NEWLINE | `string` | Newline character (`\n`) |
|
|
827
|
+
| NUMBER | `string` | Number literal (`123.4`, `-1.5e+2`) |
|
|
828
|
+
| OPERATOR | `string` | Newline (`\n`) |
|
|
829
|
+
| REF_BEAM | `string` | A range "beam" identifier (`A:A` or `1:1`) |
|
|
830
|
+
| REF_NAMED | `string` | A name / named range identifier (`income`) |
|
|
831
|
+
| REF_RANGE | `string` | A range identifier (`A1`) |
|
|
832
|
+
| REF_STRUCT | `string` | A structured reference identifier (`table[[Column1]:[Column2]]`) |
|
|
833
|
+
| REF_TERNARY | `string` | A ternary range identifier (`B2:B`) |
|
|
834
|
+
| STRING | `string` | String literal (`"Lorem ipsum"`) |
|
|
835
|
+
| UNKNOWN | `string` | Any unidentifiable range of characters. |
|
|
836
|
+
| WHITESPACE | `string` | Whitespace character sequence (` `) |
|
|
837
|
+
|
|
838
|
+
---
|
|
757
839
|
|
|
758
|
-
`string` | `Array.<Object>` – A formula string or token list (depending on which was input)
|
|
759
840
|
|