@xeplr/expression-handler 2.1.0 → 2.3.0

package/README.md

@@ -29,7 +29,9 @@ f({ country: 'India', score: 600, referred: true });   // → 'India payroll'
 | `xf.toText(tree)` | the tree back as text, for an editor showing a stored formula |
 | `xf.check(text, context?)` | `{ ok, tree, error, position }` — never throws; for editors |
 | `xf.analyze(textOrTree)` | `{ fields, fieldsOutsideTotals, thisrow, functions, aggregates, levels }` |
-| `xf.functions()` | the function list, for pickers and help |
+| `xf.functions()` | the function list, for pickers and help; each entry carries `params` |
+| `xf.usage(name, { rows }?)` | how to call it: `{ signature, params: [{ name, about, example }], description, example, min, max }`; `rows: false` for a total that names its list first. For signature help, a reference, an error |
+| `xf.arityMessage(name, given, { rows }?)` | the words for a wrong argument count, built from `usage` |
 | `xf.implementations(context?)` | `{ name: fn }` ready to call, for a caller that wants the functions without the language |
 | `xf.registerFunction(entry)` | adds one to the list |
 | `xf.evaluate(condition, row)` | 1.x: a condition → `true` / `false` |
@@ -132,6 +134,23 @@ Each function is one entry: its code **and** what the UI shows.
 validation, and Workflow's condition picker are all built from it.
 `xf.registerFunction(entry)` adds one.
 
+**Every argument is documented** — its name, what it is, and an example
+(`PARAMS` in `lib/functions.js`; a test fails for a function without them).
+`xf.usage(name)` gives them to an editor's signature help, and a call with the
+wrong number of arguments says exactly what it needs:
+
+```
+sumif(condition, value) needs 2 arguments, not 1. condition: Which rows to add:
+a test that is true or false for each row (e.g. status = "Paid"). value: What to
+add up for those rows — a column or a calculation (e.g. amount).
+Example: sumif(status = "Refunded", amount)
+```
+
+The words follow the caller: over a report group's rows, a total is
+`sumif(condition, value)`; where it names its list (Workflow, a `compile`
+without `aggregate`), `sumif(list, condition, value)`. Why: "takes 2 to 3
+arguments" named neither the arguments nor which form applied.
+
 | Category | Functions |
 |---|---|
 | Math | `round` `abs` `ceil` `floor` `sqrt` `min` `max` `pow` `trunc` `exp` `ln` `log` `log10` `log2` `cbrt` |
@@ -171,7 +190,7 @@ const f = xf.compile('sumif(fytd(order_date), revenue)', {
 | `fiscalYearStart` | `4` (April) | `fytd` and any financial-year function |
 | `today` | now | `ytd`, `fytd` — pin it for tests and scheduled runs |
 | `missing` | `'null'` | `'error'` makes a name the row lacks an error |
-| `ignoreCase` | `false` | `true` makes `=`, `!=`, `in` and the text operators (`contains`, `startsWith`, `endsWith`, `notIn`, …) ignore case. Numbers and null compare exactly as before. BI's report formulas set it, so a formula and the SQL it is translated into agree whatever the database's collation; Workflow's conditions leave it off |
+| `ignoreCase` | `false` | `true` makes `=`, `!=`, `in`, the text operators (`contains`, `startsWith`, `endsWith`, `notIn`, …) and the functions `contains()`, `startsWith()`, `endsWith()` ignore case. Numbers and null compare exactly as before. BI's report formulas set it, so a formula and the SQL it is translated into agree whatever the database's collation; Workflow's conditions leave it off |
 | `maxListItems` · `maxDistinct` · `maxSteps` · `maxLevels` | see [Limits](#limits) | |
 | `aggregate(name, args, { compile, level })` | none | supplies the rows for the group form of a total (BI) |
 

package/index.js

@@ -53,6 +53,12 @@ function contextKey(options) {
 // key to build: this is the path a caller passing text per row takes.
 var plainCache = new Map();
 
+// A total's words in an error follow the caller: over a report's rows when it
+// supplies them (options.aggregate), else naming a list first.
+function parseOptions(options) {
+  return { rows: Boolean(options && typeof options.aggregate === 'function') };
+}
+
 function compile(formula, options) {
   if (typeof formula === 'string' && options === undefined) {
     var plain = plainCache.get(formula);
@@ -64,11 +70,11 @@ function compile(formula, options) {
   }
   var key = contextKey(options);
   if (typeof formula === 'string') {
-    if (key === null) return compileTree(parse(formula), options);
+    if (key === null) return compileTree(parse(formula, parseOptions(options)), options);
     var k = key + '\u0000' + formula;
     var hit = textCache.get(k);
     if (hit) return hit;
-    var f = compileTree(parse(formula), options);
+    var f = compileTree(parse(formula, parseOptions(options)), options);
     if (textCache.size >= CACHE_MAX) textCache.clear();
     textCache.set(k, f);
     return f;
@@ -149,6 +155,10 @@ module.exports = {
   },
 
   functions: fns.listFunctions,
+  // How to call one: its signature and every argument named, explained and
+  // exemplified — for signature help, a reference list, an error.
+  usage: fns.usage,
+  arityMessage: fns.arityMessage,
   implementations: implementations,
   CATEGORIES: fns.CATEGORIES,
   registerFunction: registerFunction,

package/lib/compile.js

@@ -50,7 +50,7 @@ function compileTree(tree, options) {
   var fy = Number(opts.fiscalYearStart);
   if (!(fy >= 1 && fy <= 12 && Math.floor(fy) === fy)) fail('fiscalYearStart must be a month, 1–12');
 
-  var ctx = { now: dates.todayFor(opts), fiscalYearStart: fy };
+  var ctx = { now: dates.todayFor(opts), fiscalYearStart: fy, ignoreCase: Boolean(opts.ignoreCase) };
   // Equality for `=`, `in` and the word operators: exact, or folded when the
   // caller asked (opts.ignoreCase) — see operators.IGNORE_CASE.
   var eq = opts.ignoreCase ? operators.looseEqIgnoreCase : operators.looseEq;
@@ -133,7 +133,7 @@ function compileTree(tree, options) {
     var entry = functions.lookup(name);
     if (!entry || entry.special) fail('Unknown function "' + name + '"');
     if (entry.aggregate) fail(entry.name + '() must be written as a call, not a { fn } operand');
-    if (args.length < entry.min || args.length > entry.max) fail(entry.name + '() takes ' + entry.min + (entry.max === entry.min ? '' : '–' + entry.max) + ' arguments, not ' + args.length);
+    if (args.length < entry.min || args.length > entry.max) fail(functions.arityMessage(entry.name, args.length));
     var fn = entry.fn;
     if (entry.context) {
       var inner = fn;
@@ -253,7 +253,8 @@ function compileTree(tree, options) {
       }
       return opts.aggregate(entry.name, args, { level: inner, compile: function (n) { return c(n, inner); } });
     }
-    if (args.length !== implicit + 1) fail(entry.name + '() takes ' + implicit + ' or ' + (implicit + 1) + ' arguments, not ' + args.length);
+    // The words for the form this caller writes: a report's rows, or a list.
+    if (args.length !== implicit + 1) fail(functions.arityMessage(entry.name, args.length, { rows: typeof opts.aggregate === 'function' }));
 
     var list = c(args[0], level);
     var cond = entry.shape.cond ? c(args[1], inner) : null;

package/lib/functions.js

@@ -28,6 +28,9 @@ var asDate = dates.asDate;
 
 var CATEGORIES = ['Math', 'Text', 'Date', 'Logic', 'Aggregate'];
 
+// Text for a comparison: lower-cased when the formula ignores case.
+function fold(c, v) { var s = str(v); return c && c.ignoreCase ? s.toLowerCase() : s; }
+
 function str(v) { return v === null || v === undefined ? '' : String(v); }
 function num(v) { var n = Number(v); return isNaN(n) ? null : n; }
 function isEmpty(v) { return v === null || v === undefined || v === ''; }
@@ -121,15 +124,17 @@ var LIST = [
   { name: 'replace', category: 'Text', args: 'text, find, replace with', min: 3, max: 3,
     description: 'Swap one piece of text for another', example: 'replace(phone, "-", "")',
     fn: function (v, find, into) { return str(v).split(str(find)).join(str(into)); } },
-  { name: 'contains', category: 'Text', args: 'text, find', min: 2, max: 2,
+  // context: the compile option ignoreCase folds both sides, as it does for
+  // = and in — one rule for every text comparison in a formula.
+  { name: 'contains', category: 'Text', args: 'text, find', min: 2, max: 2, context: true,
     description: 'True when the text contains it', example: 'contains(notes, "urgent")',
-    fn: function (v, sub) { return str(v).indexOf(str(sub)) !== -1; } },
-  { name: 'startsWith', category: 'Text', args: 'text, find', min: 2, max: 2,
+    fn: function (c, v, sub) { return fold(c, v).indexOf(fold(c, sub)) !== -1; } },
+  { name: 'startsWith', category: 'Text', args: 'text, find', min: 2, max: 2, context: true,
     description: 'True when the text begins with it', example: 'startsWith(sku, "IN")',
-    fn: function (v, sub) { return str(v).startsWith(str(sub)); } },
-  { name: 'endsWith', category: 'Text', args: 'text, find', min: 2, max: 2,
+    fn: function (c, v, sub) { return fold(c, v).startsWith(fold(c, sub)); } },
+  { name: 'endsWith', category: 'Text', args: 'text, find', min: 2, max: 2, context: true,
     description: 'True when the text ends with it', example: 'endsWith(file, ".pdf")',
-    fn: function (v, sub) { return str(v).endsWith(str(sub)); } },
+    fn: function (c, v, sub) { return fold(c, v).endsWith(fold(c, sub)); } },
   { name: 'length', category: 'Text', args: 'text', min: 1, max: 1,
     description: 'How many characters', example: 'length(name)',
     fn: function (v) { return Array.isArray(v) ? v.length : str(v).length; } },
@@ -239,16 +244,118 @@ var LIST = [
   { name: 'sum', category: 'Aggregate', args: 'value', min: 1, max: 2, aggregate: true, shape: { cond: false, value: true },
     description: 'Total across the rows in this group', example: 'sum(amount)' },
   { name: 'sumif', category: 'Aggregate', args: 'condition, value', min: 2, max: 3, aggregate: true, shape: { cond: true, value: true },
-    description: 'Total across the rows that match', example: 'sumif(status == "refunded", amount)' },
+    description: 'Total across the rows that match', example: 'sumif(status = "Refunded", amount)' },
   { name: 'countif', category: 'Aggregate', args: 'condition', min: 1, max: 2, aggregate: true, shape: { cond: true, value: false },
     description: 'How many rows match', example: 'countif(qty > 10)' },
   { name: 'countifunique', category: 'Aggregate', args: 'condition, value', min: 2, max: 3, aggregate: true, shape: { cond: true, value: true },
-    description: 'How many different values among the rows that match', example: 'countifunique(status == "paid", customer_id)' },
+    description: 'How many different values among the rows that match', example: 'countifunique(status = "Paid", customer_id)' },
   // Not a function — a reference, usable inside any aggregate's condition.
   { name: '$thisrow.column', category: 'Aggregate', args: '', special: true,
-    description: 'This row\'s own value, so a total can cover every row sharing it', example: 'sumif(month == $thisrow.month, revenue)' }
+    description: 'This row\'s own value, so a total can cover every row sharing it', example: 'sumif(month = $thisrow.month, revenue)' }
 ];
 
+// ── What each argument IS ───────────────────────────────────────────────
+// [name, what it is, an example]. Read by usage() — the signature help in an
+// editor, the reference list and every "wrong number of arguments" message
+// come from here, so they cannot disagree. Optional ones say so; `…` repeats.
+var PARAMS = {
+  round: [['value', 'The number to round', 'amount'], ['places', 'Optional. Decimal places to keep; 0 when left out', '2']],
+  abs: [['value', 'A number', 'variance']],
+  ceil: [['value', 'A number', 'days']],
+  floor: [['value', 'A number', 'days']],
+  sqrt: [['value', 'A number, 0 or more', 'area']],
+  min: [['value …', 'Two or more values to compare, on the same row', 'price, cap']],
+  max: [['value …', 'Two or more values to compare, on the same row', 'price, floor_price']],
+  trunc: [['value', 'A number', 'hours']],
+  exp: [['value', 'The power to raise e to', 'rate']],
+  ln: [['value', 'A number above 0', 'growth']],
+  log: [['value', 'A number above 0', 'growth']],
+  log10: [['value', 'A number above 0', 'size']],
+  log2: [['value', 'A number above 0', 'size']],
+  cbrt: [['value', 'A number', 'volume']],
+  pow: [['value', 'The number to raise', 'rate'], ['exponent', 'The power to raise it to', 'years']],
+  upper: [['text', 'The text to change', 'city']],
+  lower: [['text', 'The text to change', 'email']],
+  trim: [['text', 'The text to clean', 'name']],
+  concat: [['value …', 'The pieces to join, in order — columns or "text in quotes"', 'first, " ", last']],
+  substring: [['text', 'The text to take from', 'code'], ['start', 'Where to start; the first character is 1', '1'], ['count', 'Optional. How many characters; to the end when left out', '3']],
+  left: [['text', 'The text to take from', 'deptCode'], ['count', 'How many characters from the start', '3']],
+  right: [['text', 'The text to take from', 'invoice'], ['count', 'How many characters from the end', '4']],
+  replace: [['text', 'The text to change', 'phone'], ['find', 'What to look for, in quotes', '"-"'], ['replace with', 'What to put instead, in quotes ("" removes it)', '""']],
+  contains: [['text', 'The text to look in', 'notes'], ['find', 'What to look for, in quotes; capitals ignored', '"urgent"']],
+  startsWith: [['text', 'The text to look at', 'sku'], ['find', 'What it should begin with, in quotes; capitals ignored', '"IN"']],
+  endsWith: [['text', 'The text to look at', 'file'], ['find', 'What it should end with, in quotes; capitals ignored', '".pdf"']],
+  length: [['text', 'The text to count', 'name']],
+  year: [['date', 'A date column', 'order_date']],
+  month: [['date', 'A date column', 'order_date']],
+  day: [['date', 'A date column', 'order_date']],
+  quarter: [['date', 'A date column', 'order_date']],
+  weekday: [['date', 'A date column', 'order_date']],
+  datediff: [['from', 'The earlier date', 'ordered'], ['to', 'The later date; days from "from" to this', 'shipped']],
+  dateadd: [['date', 'The date to move', 'order_date'], ['days', 'How many days to add; negative goes back', '30']],
+  monthname: [['date', 'A date column, or a month number 1–12', 'order_date']],
+  monthkey: [['date', 'A date column', 'order_date']],
+  quarterkey: [['date', 'A date column', 'order_date']],
+  daykey: [['date', 'A date column', 'order_date']],
+  ytd: [['date', 'The date column that decides the year', 'order_date']],
+  fytd: [['date', 'The date column that decides the financial year', 'order_date']],
+  if: [['condition', 'A test that is true or false', 'qty > 10'], ['then', 'The result when it is true', '"bulk"'], ['otherwise', 'The result when it is false', '"single"']],
+  coalesce: [['value …', 'Values to try in order; the first that is not empty wins', 'nickname, name']],
+  ifnull: [['value', 'The value to use', 'discount'], ['fallback', 'What to use when it is empty', '0']],
+  isnull: [['value', 'The value to test', 'closed_date']],
+  between: [['value', 'The value to test', 'score'], ['low', 'The lowest allowed, included', '600'], ['high', 'The highest allowed, included', '750']],
+  sum: [['value', 'What to add up for each row of the group — a column or a calculation', 'amount']],
+  sumif: [['condition', 'Which rows to add: a test that is true or false for each row', 'status = "Paid"'], ['value', 'What to add up for those rows — a column or a calculation', 'amount']],
+  countif: [['condition', 'Which rows to count: a test that is true or false for each row', 'qty > 10']],
+  countifunique: [['condition', 'Which rows to look at: a test that is true or false for each row', 'status = "Paid"'], ['value', 'What to count the different values of', 'customer_id']]
+};
+// Written first when a total names its own list (outside a report).
+var LIST_PARAM = ['list', 'The list to go through — outside a report a total names it first', 'orders'];
+
+function paramsOf(entry) {
+  return (PARAMS[entry.name] || []).map(function (p) { return { name: p[0], about: p[1], example: p[2] }; });
+}
+
+/**
+ * How to call a function, with every argument named and explained.
+ *
+ * @param name     the function's name
+ * @param options  { rows: true } — a total over the rows of a report group (the
+ *                 default for a total); { rows: false } — a total that names
+ *                 its list first, sumif(orders, condition, value)
+ * @returns {{ name, signature, params: [{ name, about, example }], description,
+ *             example, min, max }} or null for a name that is no function
+ */
+function usage(name, options) {
+  var entry = lookup(name);
+  if (!entry) return null;
+  var params = paramsOf(entry);
+  var listed = entry.aggregate && options && options.rows === false;
+  if (listed) params = [{ name: LIST_PARAM[0], about: LIST_PARAM[1], example: LIST_PARAM[2] }].concat(params);
+  var count = entry.aggregate ? params.length : null;
+  return {
+    name: entry.name,
+    signature: entry.name + '(' + params.map(function (p) { return p.name; }).join(', ') + ')',
+    params: params,
+    description: entry.description || '',
+    example: listed ? entry.name + '(' + params.map(function (p) { return p.example; }).join(', ') + ')' : (entry.example || ''),
+    min: count === null ? entry.min : count,
+    max: count === null ? entry.max : count
+  };
+}
+
+/**
+ * The words for a call with the wrong number of arguments: the signature,
+ * how many it needs, how many it got, and each argument with an example.
+ */
+function arityMessage(name, given, options) {
+  var u = usage(name, options);
+  var need = u.min === u.max ? String(u.min) : u.max === Infinity ? u.min + ' or more' : u.max === u.min + 1 ? u.min + ' or ' + u.max : u.min + ' to ' + u.max;
+  return u.signature + ' needs ' + need + ' argument' + (need === '1' ? '' : 's') + ', not ' + given + '. ' +
+    u.params.map(function (p) { return p.name + ': ' + p.about + ' (e.g. ' + p.example + ')'; }).join('. ') +
+    (u.example ? '. Example: ' + u.example : '');
+}
+
 // Lookup by lower-cased name. A null-prototype map, so no formula can reach
 // Object.prototype through a function name.
 var FUNCTIONS = Object.create(null);
@@ -279,7 +386,9 @@ function registerFunction(entryOrName, fn) {
 
 /** The list the UI renders: every visible entry, in reference order. */
 function listFunctions() {
-  return LIST.filter(function (f) { return !f.hidden; });
+  return LIST.filter(function (f) { return !f.hidden; }).map(function (f) {
+    return f.special && f.name !== 'if' ? f : Object.assign({}, f, { params: f.params || paramsOf(f) });
+  });
 }
 
-module.exports = { FUNCTIONS: FUNCTIONS, CATEGORIES: CATEGORIES, lookup: lookup, registerFunction: registerFunction, listFunctions: listFunctions, str: str, num: num, isEmpty: isEmpty };
+module.exports = { FUNCTIONS: FUNCTIONS, CATEGORIES: CATEGORIES, lookup: lookup, usage: usage, arityMessage: arityMessage, registerFunction: registerFunction, listFunctions: listFunctions, str: str, num: num, isEmpty: isEmpty };

package/lib/parse.js

@@ -110,8 +110,12 @@ function tokenize(src) {
 }
 
 // ── grammar ───────────────────────────────────────────────────────────────
-function parse(src) {
+// options.rows: false when a total names its list first (Workflow);
+// otherwise a total is over a report group's rows — sumif(condition, value).
+// Only the WORDS of an error depend on it.
+function parse(src, options) {
   if (typeof src !== 'string') throw new Error('parse: formula must be text');
+  var rows = !(options && options.rows === false);
   if (!src.trim()) fail('The formula is empty');
   var toks = tokenize(src);
   var pos = 0;
@@ -285,10 +289,7 @@ function parse(src) {
       while (isPunct(',')) { next(); args.push(conditional()); }
     }
     expect(')');
-    if (args.length < entry.min || args.length > entry.max) {
-      var want = entry.min === entry.max ? String(entry.min) : entry.max === Infinity ? 'at least ' + entry.min : entry.min + ' to ' + entry.max;
-      fail(entry.name + '() takes ' + want + ' argument' + (want === '1' ? '' : 's') + ', not ' + args.length, nameTok.at);
-    }
+    if (args.length < entry.min || args.length > entry.max) fail(functions.arityMessage(entry.name, args.length, { rows: rows }), nameTok.at);
     if (entry.name === 'if') return { if: args[0], then: args[1], else: args[2] };
     return { call: entry.name, args: args };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/expression-handler",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "The one formula engine for xeplr: its own parser (no eval, no dependencies), one function list, compiled-once formulas, totals over lists, AND/OR conditions. Runs in Node and the browser.",
   "main": "index.js",
   "files": [