@borgar/fx 3.1.0 → 4.0.0-rc.1

package/.eslintrc

@@ -1,18 +1,31 @@
 {
-  parser: '@babel/eslint-parser',
-  extends: [ '@borgar/eslint-config' ],
-  env: {
-    es6: true,
-    node: true,
+  "parser": "@babel/eslint-parser",
+  "extends": [ "@borgar/eslint-config" ],
+  "env": {
+    "es6": true,
+    "node": true,
   },
-  parserOptions: {
-    ecmaVersion: 2021,
-    sourceType: 'module',
-    requireConfigFile: false,
+  "parserOptions": {
+    "ecmaVersion": 2021,
+    "sourceType": "module",
+    "requireConfigFile": false,
   },
-  rules: {
+  "rules": {
+    "max-len": [ "error", {
+      "code": 120,
+      "comments": 80,
+      "tabWidth": 2,
+      "ignoreUrls": true,
+      "ignoreStrings": true,
+      "ignoreTemplateLiterals": true,
+      "ignoreRegExpLiterals": true,
+      "ignorePattern": "^\\s*\\*\\s*@(param|return|property)\\s"
+    } ],
+    "no-trailing-spaces": [ "error", {
+      "ignoreComments": true
+    } ]
   },
-  globals: {
-    Promise,
+  "globals": {
+    "Promise"
   }
 }

package/.jsdoc/config.json

@@ -0,0 +1,17 @@
+{
+  "source": {
+    "includePattern": ".+\\.js(doc|x)?$",
+    "excludePattern": "((^|\\/|\\\\)_|spec\\.js$)"
+  },
+  "opts": {
+    "template": "./.jsdoc",
+    "encoding": "utf8",
+    "destination": "./docs/"
+  },
+  "templates": {
+    "default": {
+      "includeDate": false,
+      "outputSourceFiles": false
+    }
+  }
+}

package/.jsdoc/publish.js

@@ -0,0 +1,195 @@
+/* eslint-disable no-undefined, no-console */
+
+function formatType (d, inTable = false) {
+  return d.names?.map(n => `\`${n}\``).join(inTable ? ' \\| ' : ' | ') || '';
+}
+
+function formatArguments (args) {
+  let inOpt = false;
+  let r = args.reduce((a, d, i) => {
+    if (d.name.includes('.')) {
+      return a;
+    }
+    if (inOpt && !d.optional) {
+      a += ']_';
+      inOpt = false;
+    }
+    if (i) {
+      a += ', ';
+    }
+    if (!inOpt && d.optional) {
+      a += '_[';
+      inOpt = true;
+    }
+    a += d.name;
+    if (d.defaultvalue) {
+      a += ' = `' + d.defaultvalue + '`';
+    }
+    return a;
+  }, '');
+  if (inOpt) {
+    r += ']_';
+  }
+  return r;
+}
+
+function repValue (v) {
+  if (v === undefined) {
+    return '';
+  }
+  if (v === "''") {
+    // FIXME: should transform all '' strings to "" style
+    v = '""';
+  }
+  return '`' + v + '`';
+}
+
+function repArgName (name, optional = false) {
+  const names = name.split('.');
+  const nPath = names.length > 1 ? '.' + names.slice(1).join('.') : '';
+  return (optional ? '_[' : '') + names[0] + (optional ? ']_' : '') + nPath;
+}
+
+function listToTable (args) {
+  const useDefaults = args.some(d => !!d.defaultvalue);
+  const table = useDefaults
+    ? [
+      '| Name | Type | Default | Description |',
+      '| ---- | ---- | ------- | ----------- |' ]
+    : [
+      '| Name | Type | Description |',
+      '| ---- | ---- | ----------- |' ];
+  args.forEach(d => {
+    const row = [ repArgName(d.name, d.optional) ];
+    row.push(formatType(d.type, true));
+    useDefaults && row.push(repValue(d.defaultvalue));
+    row.push(transformLinks(d.description));
+    table.push('| ' + row.join(' | ') + ' |');
+  });
+
+  return table.join('\n');
+}
+
+function adjustLineBreaks (md) {
+  return md.trim().replace(
+    /(?:```([^\0]*?)```|(\S)\n(?!\n))/g,
+    (a, b, c) => {
+      return (c ? (c + ' ') : a);
+    }
+  );
+}
+
+function formatSee (see) {
+  if (see) {
+    if (/^[a-z][a-z0-9]*$/i.test(see)) {
+      see = `{@link ${see}}`;
+    }
+    return `\n**See also:** ${transformLinks(see)}.\n`;
+  }
+  return '';
+}
+
+const re_links = /(?:\[([^\]]+)\])?\{@link(?:code|plain)? ([^} ]+)([^}]+)?\}/g;
+function transformLinks (md) {
+  return md.replace(re_links, (a, preLabel, href, postLabel) => {
+    const hash = /^[a-z][a-z0-9]*$/i.test(href) ? '#' : '';
+    return `[${preLabel || postLabel || href}](${hash}${href})`;
+  });
+}
+
+function formatHeading (text, level = 2) {
+  return '#'.repeat(level || 1) + ' ' + text;
+}
+
+const format = {
+  function: d => {
+    return [
+      formatHeading(`<a name="${d.name}" href="#${d.name}">#</a> ${d.name}( ${formatArguments(d.params)} ) ⇒ ${formatType(d.returns[0].type)}`, 3),
+      adjustLineBreaks(transformLinks(d.description)),
+      formatSee(d.see),
+      formatHeading('Parameters', 4),
+      listToTable(d.params),
+      formatHeading('Returns', 4),
+      formatType(d.returns[0].type) + ' – ' + d.returns[0].description
+    ];
+  },
+  constant: d => {
+    return [
+      formatHeading(`<a name="${d.name}" href="#${d.name}">#</a> ${d.name} ⇒ ${formatType(d.type)}`, 3),
+      adjustLineBreaks(transformLinks(d.description)),
+      formatSee(d.see),
+      formatHeading('Properties', 4),
+      listToTable(d.properties)
+    ];
+  }
+};
+
+const categoryHeadings = {
+  package: null,
+  function: 'Functions',
+  constant: 'Constants'
+};
+
+exports.publish = (data, { destination }) => {
+  data({ undocumented: true }).remove();
+  const docs = data().get();
+
+  const test = '';
+  if (test) {
+    const s = docs.find(d => d.name === test);
+    const o = format[s.kind](s);
+    console.log(o.join('\n\n'));
+    return;
+  }
+
+  const categories = {};
+  docs.forEach(d => {
+    if (!categories[d.kind]) {
+      categories[d.kind] = [];
+    }
+    categories[d.kind].push(d);
+  });
+
+  let output = [];
+
+  Object.keys(categories)
+    .sort()
+    .forEach(kind => {
+      const heading = categoryHeadings[kind];
+      if (heading == null) { return; }
+      // emit category heading
+      output.push(formatHeading(heading, 2));
+      // emit all members belonging to that category
+      docs
+        .filter(d => d.kind === kind)
+        .filter(d => d.access !== 'private')
+        .sort((a, b) => {
+          if (a.name < b.name) { return -1; }
+          if (a.name > b.name) { return 1; }
+          return NaN;
+        })
+        .forEach((d, i) => {
+          if (i) {
+            output.push('---');
+          }
+          if (!format[d.kind]) {
+            console.error('Unsupported member type ' + d.kind);
+            process.exit(1);
+          }
+          output.push(...format[d.kind](d));
+        });
+    });
+
+  output = output
+    .map(d => d.trim())
+    .filter(Boolean);
+
+  // console.log(docs.map(d => d.name).sort());
+  if (destination === 'console') {
+    console.log(output.join('\n\n') + '\n');
+  }
+  else {
+    console.error('This template only supports output to the console. Use the option "-d console" when you run JSDoc.');
+    process.exit(1);
+  }
+};

package/README.md

@@ -1,8 +1,9 @@
 # _fx_
 
-This is a collection utilities to work with Excel formula code, specifically syntax highlighting.
+A tokenizer, parser, and other utilities to work with Excel formula code, specifically syntax highlighting.
+
+This utility is partially developed as tooling for [GRID – The new face of spreadsheets](https://grid.is/), to which it owes a debt of gratitude.
 
-This utility is developed as tooling for [GRID – The new face of spreadsheets](https://grid.is/), to which it owes a debt of gratitude.
 
 ## Installing
 
@@ -10,319 +11,15 @@ The library is also provided as an ES6 module in an NPM package:
 
     $ npm install @borgar/fx
 
-## API
-
-### <a name="tokenize" href="#tokenize">#</a> **tokenize**( _formula [, options]_ )
-
-* `formula` should be a string (an Excel formula).
-
-* `options` are set as an object of keys: `tokenize(formula, { option: true })`. Supported options are:
-
-  | name | default | effect |
-  |- |- |-
-  | `allowTernary` | `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.
-  | `emitRanges` | `false` | Adds offset ranges on the tokens: `{ range: [ start, end ] }`
-  | `mergeRanges` | `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 [`mergeRanges`](#mergeRanges)
-  | `negativeNumbers` | `true` | Merges unary minuses with their immediately following number tokens (`-`,`1`) => `-1`
-  | `r1c1` | `false` | Ranges are expected to be in the R1C1 style format rather than the more popular A1 style.
-
-The returned output will be an array of objects representing the tokens:
-
-```js
-[
-  { type: FX_PREFIX, value: '=' },
-  { type: FUNCTION, value: 'SUM' },
-  { type: OPERATOR, value: '(' },
-  { type: RANGE, value: 'A1:B2' },
-  { type: OPERATOR, value: ')' }
-]
-```
-
-Token types may be found as an Object as the `tokenTypes` export on the package (`import {tokenTypes} from '@borgar/fx';`):
-
-```js
-tokenTypes = {
-  OPERATOR: "operator",
-  BOOLEAN: "bool",
-  ERROR: "error",
-  NUMBER: "number",
-  FUNCTION: "func",
-  NEWLINE: "newline",
-  WHITESPACE: "whitespace",
-  STRING: "string",
-  CONTEXT_QUOTE: "context_quote",
-  CONTEXT: "context",
-  RANGE: "range",
-  RANGE_BEAM: "range_beam",
-  RANGE_NAMED: "range_named",
-  RANGE_TERNARY: "range_ternary",
-  FX_PREFIX: "fx_prefix",
-  UNKNOWN: "unknown"
-}
-```
-
-To support syntax highlighting as you type, `STRING` tokens are allowed to be "unterminated". For example, the incomplete formula `="Hello world` would be tokenized as:
-
-```js
-[
-  { type: FX_PREFIX, value: '=' },
-  { type: STRING, value: '"Hello world', unterminated: true },
-]
-```
-
-### <a name="translateToA1" href="#translateToA1">#</a> **translateToA1**( _formula, anchorCell_ )
-
-Translates ranges in a formula or list of tokens from relative R1C1 syntax to absolute A1 syntax.
-
-* `formula` should be a string (an Excel formula) or a token list.
-
-* `anchorCell` should be a simple string reference to an A1 cell (`AF123` or `$C$5`).
-
-Returns the same formula with the ranges translated. If an array of tokens was supplied, then the same array is returned (be careful that `mergeRanges` must be false).
-
-```js
-translateToA1("=SUM(RC[1],R2C5,Sheet!R3C5)", "D10");
-// => "=SUM(E10,$E$2,Sheet!$E$3)");
-```
-
-
-### <a name="translateToRC" href="#translateToRC">#</a> **translateToRC**( _formula, anchorCell_ )
-
-Translates ranges in a formula or list of tokens from absolute A1 syntax to relative R1C1 syntax.
-
-* `formula` should be a string (an Excel formula) or a token list.
-
-* `anchorCell` should be a simple string reference to an A1 cell (`AF123` or `$C$5`).
-
-Returns the same formula with the ranges translated. If an array of tokens was supplied, then the same array is returned (be careful that `mergeRanges` must be false).
-
-```js
-translateToRC("=SUM(E10,$E$2,Sheet!$E$3)", "D10");
-// => "=SUM(RC[1],R2C5,Sheet!R3C5)");
-```
-
-
-### <a name="addMeta" href="#addMeta">#</a> **addMeta**( _tokenlist [, context]_ )
-
-Runs through a list of tokens and adds extra attributes such as matching parens and ranges.
-
-* `tokenlist` should be a token list (from `tokenize()`).
-
-* `context` should be an object containing default reference attributes: `{ workbookName: 'report.xlsx', sheetName: 'Sheet1' }`. If supplied, these are used to match `A1` to `Sheet1!A1`)
-
-All tokens will be tagged with a `.depth` number value to indicating the level of nesting in parentheses as well as an `.index` number indicating their zero based position in the list.
-
-The returned output will be the same array of tokens but the following properties will added to tokens (as applicable):
-
-#### Parentheses ( )
-
-Matching parens will be tagged with `.groupId` string identifier as well as a `.depth` number value (indicating the level of nesting).
-
-Closing parens without a counterpart will be tagged with `.error` (boolean true).
-
-#### Curly brackets { }
-
-Matching curly brackets will be tagged with `.groupId` string identifier. These may not be nested in Excel.
-
-Closing curly brackets without a counterpart will be tagged with `.error` (boolean `true`).
-
-#### Ranges (`RANGE` or `RANGE_BEAM` type tokens)
-
-All ranges will be tagged with `.groupId` string identifier regardless of the number of times they occur.
-
-#### Tokens of type `UNKNOWN`
-
-All will be tagged with `.error` (boolean `true`).
-
-
-### <a name="mergeRanges" href="#mergeRanges">#</a> **mergeRanges**( _tokenlist_ )
-
-Given a tokenlist, returns a new list with ranges returned as whole references (`Sheet1!A1:B2`) rather than separate tokens for each part: (`Sheet1`,`!`,`A1`,`:`,`B2`).
-
-
-### <a name="fixRanges" href="#fixRanges">#</a> **fixRanges**( _formula[, { addBounds: true } ]_ )
-
-Normalizes A1 style ranges in a formula or list of tokens so that the top and left coordinates of the range are on the left-hand side of a colon operator:
-
-* `B2:A1` → `A1:B2`
-* `1:A1` → `A1:1`
-* `A:A1` → `A1:A`
-* `B:A` → `A:B`
-* `2:1` → `1:2`
-* `A1:A1` → `A1`
-
-When `{ addBounds: true }` is passed as an option, the missing bounds are also added. This can be done to ensure Excel compatible ranges. The fixes then additionally include:
-
-* `1:A1` → `A1:1` → `1:1`
-* `A:A1` → `A1:A` → `A:A`
-* `A1:A` → `A:A`
-* `A1:1` → `A:1`
-* `B2:B` → `B2:1048576`
-* `B2:2` → `B2:XFD2`
-
-Returns the same formula with the ranges updated. If an array of tokens was supplied, then a new array is returned.
-
-### <a name="isRange" href="#isRange">#</a> **isRange**( _token_ )
-
-Returns `true` if the input is a token that has a type of either RANGE (`A1` or `A1:B2`), RANGE_TERNARY (`A1:A`, `A1:1`, `1:A1`, or `A:A1`), or RANGE_BEAM (`A:A` or `1:1`). In all other cases `false` is returned.
-
-
-### <a name="isReference" href="#isReference">#</a> **isReference**( _token_ )
-
-Returns `true` if the input is a token of type RANGE (`A1` or `A1:B2`), RANGE_TERNARY (`A1:A`, `A1:1`, `1:A1`, or `A:A1`), RANGE_BEAM (`A:A` or `1:1`), or RANGE_NAMED (`myrange`). In all other cases `false` is returned.
-
-
-### .a1:
-
-An object of methods to interpret and manipulate A1 style references.
-
-#### <a name="a1.parse" href="#a1.parse">#</a> **.parse**( _refString[, { allowNamed: true, allowTernary: true } ]_ )
-
-Parse a string reference into an object representing it.
-
-```js
-import { a1 } from '@borgar/fx';
-a1.parse('Sheet1!A$1:$B2');
-// => {
-//   context: [ 'Sheet1' ],
-//   range: {
-//     top: 0,
-//     left: 0,
-//     bottom: 1,
-//     right: 1
-//     $top: true,
-//     $left: false,
-//     $bottom: false,
-//     $right: true
-//   }
-// }
-```
-
-For A:A or A1:A style ranges, null will be used for any dimensions that the syntax does not specify:
-
-#### <a name="a1.stringify" href="#a1.stringify">#</a> **.stringify**( _refObject_ )
-
-Get a string representation of a reference object.
-
-```js
-import { a1 } from '@borgar/fx';
-a1.stringify({
-  context: [ 'Sheet1' ],
-  range: {
-    top: 0,
-    left: 0,
-    bottom: 1,
-    right: 1,
-    $top: true,
-    $left: false,
-    $bottom: false,
-    $right: true
-  }
-});
-// => 'Sheet1!A$1:$B2'
-```
-
-#### <a name="a1.addBounds" href="#a1.addBounds">#</a> **.addBounds**( _refObject_ )
-
-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`.
-
-```js
-import { a1 } from '@borgar/fx';
-a1.addBounds({
-  context: [ 'Sheet1' ],
-  range: {
-    top: 0,
-    left: 0,
-    bottom: 1,
-    $top: true,
-    $left: false,
-    $bottom: false,
-  }
-});
-// => {
-//   context: [ 'Sheet1' ],
-//   range: {
-//     top: 0,
-//     left: 0,
-//     bottom: 1,
-//     right: 16383,
-//     $top: true,
-//     $left: false,
-//     $bottom: false,
-//     $right: false
-//   }
-// }
-```
-
-#### <a name="a1.to" href="#a1.to">#</a> **.to**( _rangeObject_ )
-
-Stringify a range object ([see above](#a1.parse)) into A1 syntax.
-
-#### <a name="a1.from" href="#a1.from">#</a> **.from**( _rangeString_ )
-
-Parse a simple string reference to an A1 range into a range object ([see above](#a1.parse)). Will accept `A1`, `A2`, `A:A`, or `1:1`.
-
-#### <a name="a1.fromCol" href="#a1.fromCol">#</a> **.fromCol**( _columnString_ )
-
-Convert a column string representation to a 0 based offset number (`"C"` = `2`). 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.
-
-#### <a name="a1.toCol" href="#a1.toCol">#</a> **.toCol**( _columnNumber_ )
-
-Convert a 0 based offset number to a column string representation (`2` = `"C"`). The method expects a number between 0 and 16383. Other input will return garbage.
-
-### .rc:
-
-An object of methods to interpret and manipulate R1C1 style references.
-
-#### <a name="rc.parse" href="#rc.parse">#</a> **.parse**( _refString[, { allowNamed: true, allowTernary: true } ]_ )
-
-Parse a string reference into an object representing it.
-
-```js
-import { rc } from '@borgar/fx';
-rc.parse('Sheet1!R[9]C9:R[9]C9');
-// => {
-//   context: [ 'Sheet1' ],
-//   range: {
-//     r0: 9,
-//     c0: 8,
-//     r1: 9,
-//     c1: 8,
-//     $c0: true,
-//     $c1: true
-//     $r0: false,
-//     $r1: false
-//   }
-// }
-```
-
-#### <a name="rc.stringify" href="#rc.stringify">#</a> **.stringify**( _refObject_ )
 
-Get a string representation of a reference object.
+## Documentation
 
-```js
-import { a1 } from '@borgar/fx';
-a1.stringify({
-  context: [ 'Sheet1' ],
-  range: {
-    r0: 9,
-    c0: 8,
-    r1: 9,
-    c1: 8,
-    $c0: true,
-    $c1: true
-    $r0: false,
-    $r1: false
-  }
-});
-// => 'Sheet1!R[9]C9:R[9]C9'
-```
+Documentation can be found under [docs/](./docs/):
 
+* The API is documented in [docs/API.md](./docs/API.md).
 
-#### <a name="rc.from" href="#rc.from">#</a> **.from**( _refString_ )
+* The AST format the parser emits is specified in [docs/AST format.md](./docs/AST format.md).
 
-Parse a simple string reference to an R1C1 range into a range object ([see above](#rc.parse)).
+* A primer/terminology definitions of Excel references and ranges can be found in [docs/References.md](./docs/References.md).
 
-#### <a name="rc.to" href="#rc.to">#</a> **.to**( _rangeObject_ )
 
-Stringify a range object ([see above](#rc.parse)) into R1C1 syntax.