Release 2.0.0

doc/output/JSDOCS.md

@@ -8,68 +8,88 @@ function that can be used to evaluate the expression on a json payload.
 **Kind**: global class  
 
 * [JsonFormula](#JsonFormula)
-    * [new JsonFormula([customFunctions], [stringToNumber], [language], [debug])](#new_JsonFormula_new)
-    * [.search(json, [globals])](#JsonFormula+search) ⇒ <code>\*</code>
-    * [.run(ast, json, globals)](#JsonFormula+run) ⇒ <code>\*</code>
-    * [.compile(expression, [allowedGlobalNames], [debug])](#JsonFormula+compile)
+    * [new JsonFormula([customFunctions], [stringToNumber], [debug])](#new_JsonFormula_new)
+    * [.search(expression, json, [globals], [language])](#JsonFormula+search) ⇒ <code>\*</code>
+    * [.run(ast, json, [language], globals)](#JsonFormula+run) ⇒ <code>\*</code>
+    * [.compile(expression, [allowedGlobalNames])](#JsonFormula+compile)
 
 <a name="new_JsonFormula_new"></a>
 
-### new JsonFormula([customFunctions], [stringToNumber], [language], [debug])
+### new JsonFormula([customFunctions], [stringToNumber], [debug])
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
 | [customFunctions] | <code>object</code> | <code>{}</code> | custom functions needed by a hosting application. |
 | [stringToNumber] | <code>function</code> | <code>&#x27;null&#x27;</code> | A function that converts string values to numbers. Can be used to convert currencies/dates to numbers |
-| [language] | <code>string</code> | <code>&quot;en-US&quot;</code> |  |
 | [debug] | <code>array</code> | <code>[]</code> | will be populated with any errors/warnings |
 
 <a name="JsonFormula+search"></a>
 
-### jsonFormula.search(json, [globals]) ⇒ <code>\*</code>
+### jsonFormula.search(expression, json, [globals], [language]) ⇒ <code>\*</code>
 Evaluates the JsonFormula on a particular json payload and return the result
 
 **Kind**: instance method of [<code>JsonFormula</code>](#JsonFormula)  
 **Returns**: <code>\*</code> - the result of the expression being evaluated  
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
+| expression | <code>string</code> |  | the json-formula expression to evaluate |
 | json | <code>object</code> \| <code>array</code> |  | the json data on which the expression needs to be evaluated |
 | [globals] | <code>object</code> | <code>{}</code> | global objects that can be accessed via custom functions. |
-
+| [language] | <code>string</code> | <code>&quot;en-US&quot;</code> | BCP-47 language tag |
+
+**Example**  
+```js
+const jf = new JsonFormula();
+const result = jf.search('toDate(d) | day(@) & "/" & month(@)', {d: "2025-11-12"});
+// returns "12/11"
+```
 <a name="JsonFormula+run"></a>
 
-### jsonFormula.run(ast, json, globals) ⇒ <code>\*</code>
-Execute a previously compiled expression against a json object and return the result
+### jsonFormula.run(ast, json, [language], globals) ⇒ <code>\*</code>
+Execute a previously compiled expression against a json object and return the result.
+Use this method for better performance when you will evaluate the same expression
+multiple times with different data.
 
 **Kind**: instance method of [<code>JsonFormula</code>](#JsonFormula)  
 **Returns**: <code>\*</code> - the result of the expression being evaluated  
 
-| Param | Type | Description |
-| --- | --- | --- |
-| ast | <code>object</code> | The abstract syntax tree returned from compile() |
-| json | <code>object</code> \| <code>array</code> | the json data on which the expression needs to be evaluated |
-| globals | <code>\*</code> | set of objects available in global scope |
-
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| ast | <code>object</code> |  | The abstract syntax tree returned from compile() |
+| json | <code>object</code> \| <code>array</code> |  | the json data on which the expression needs to be evaluated |
+| [language] | <code>string</code> | <code>&quot;en-US&quot;</code> | BCP-47 language tag |
+| globals | <code>\*</code> |  | set of objects available in global scope |
+
+**Example**  
+```js
+const globals = {
+  $days: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
+};
+const jf = new JsonFormula();
+const ast = jf.compile('value($days, num)', ['$days']); // compile the expression once
+const result1 = jf.run(ast, {num: 2}, 'en-US', globals); // returns "Wed"
+const result2 = jf.run(ast, {num: 3}, 'en-US', globals); // returns "Thu"
+```
 <a name="JsonFormula+compile"></a>
 
-### jsonFormula.compile(expression, [allowedGlobalNames], [debug])
+### jsonFormula.compile(expression, [allowedGlobalNames])
 Creates a compiled expression that can be executed later on with some data.
 
 **Kind**: instance method of [<code>JsonFormula</code>](#JsonFormula)  
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
 | expression | <code>string</code> |  | the expression to evaluate |
-| [allowedGlobalNames] | <code>Array.&lt;string&gt;</code> | <code>[]</code> | A list of names of the global variables being used in the expression. |
-| [debug] | <code>array</code> | <code>[]</code> | will be populated with any errors/warnings |
+| [allowedGlobalNames] | <code>Array.&lt;string&gt;</code> | <code>[]</code> | An array of names of the global variables being used in the expression. |
 
 <a name="jsonFormula"></a>
 
 ## jsonFormula(json, globals, expression, [customFunctions], [stringToNumber], [language], [debug]) ⇒ <code>\*</code>
 Compile and execute a json-formula expression.
 If executing the same expression multiple times, it is more efficient to create a
-class instance of {JsonFormula} and call the search method multiple times.
+class instance of JsonFormula and call the search() method or the compile()/run() methods
+multiple times.
 
 **Kind**: global function  
 **Returns**: <code>\*</code> - the result of the expression being evaluated  
@@ -84,3 +104,71 @@ class instance of {JsonFormula} and call the search method multiple times.
 | [language] | <code>string</code> | <code>&quot;en-US&quot;</code> |  |
 | [debug] | <code>array</code> | <code>[]</code> | will be populated with any errors/warnings |
 
+<a name="CustomFunctionDefinition"></a>
+
+## CustomFunctionDefinition : <code>object</code>
+**Kind**: global typedef  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| _func | <code>function</code> | The function implementation |
+| [_signature] | <code>array</code> | Function signature metadata |
+
+**Example**  
+```js
+// simple custom functions definition
+  const customFunctions = {
+    true_fn: {
+      _func: () => true,
+      _signature: [],
+    },
+    false_fn: {
+      _func: () => false,
+      _signature: [],
+    },
+  };
+
+```
+**Example**  
+```js
+// custom function with a signature for its parameters
+  const customFunctions = {
+    padEnd: {
+      _func: args => {
+        const src = args[0];
+        const length = args[1];
+        const padChar = args[2];
+        if (Array.isArray(src)) return src.map(s => s.padEnd(length, padChar));
+        return src.padEnd(length, padChar);
+      },
+      _signature: [
+        { types: [TYPE_STRING, TYPE_ARRAY_STRING] },
+        { types: [TYPE_NUMBER] },
+        { types: [TYPE_STRING] },
+      ],
+    }
+  }
+  // May also register functions is via the `register()` or `registerWithParams()` methods. e.g.
+
+   const regFormula = `${register("${fn_name}", &${code})`;
+   // Run the registration formula after which, the registered function may be called
+   this.search(regFormula, {});
+```
+<a name="globals"></a>
+
+## globals : <code>object</code>
+An object where each key **MUST** begin with a `$` character, representing global variables
+that can be accessed inside a json-formula expression.
+The value of each key can be of any data type supported by json.
+
+**Kind**: global typedef  
+**Example**  
+```js
+const globals = {
+  $num: 42,
+  $arr: [1, 2, 3],
+  $days: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
+};
+jsonFormula({}, globals, '$arr * $num') // returns [42, 84, 126]
+```

doc/output/json-formula-specification-2.0.0.html

@@ -443,7 +443,7 @@ <h1>json-formula Specification</h1>
 <div class="details">
 <span id="author" class="author">PDF Association Forms Technical Working Group</span><br>
 <span id="revnumber">version 2.0.0,</span>
-<span id="revdate">2025-11-10</span>
+<span id="revdate">2025-11-12</span>
 <br><span id="revremark"></span>
 </div>
 </div>
@@ -544,15 +544,15 @@ <h2 id="_scope">Scope</h2>
 </ul>
 </div>
 <div class="paragraph">
-<p>The intended audience are both end-users of json-formula as well as implementors; the contents are then both a user guide and a specification.</p>
+<p>The intended audience are both end-users of json-formula as well as implementers; the contents are then both a user guide and a specification.</p>
 </div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="_notation">1. Notation</h2>
 <div class="sectionbody">
 <div class="paragraph">
-<p>In the specification, examples are shown through the use of a <code>search</code> function.  The syntax for this function is:</p>
+<p>In the specification, examples are shown through the use of a <code>search</code> function called <code>eval</code>.  The syntax for this function is:</p>
 </div>
 <div class="listingblock">
 <div class="content">
@@ -601,8 +601,7 @@ <h2 id="_data_types">2. Data Types</h2>
 </ul>
 </div>
 <div class="paragraph">
-<p>There is an additional type that is not a JSON type that&#8217;s used in
-json-formula functions:</p>
+<p>There is an additional type that is not a JSON type that&#8217;s used in json-formula functions:</p>
 </div>
 <div class="ulist">
 <ul>
@@ -2516,8 +2515,7 @@ <h3 id="_function_evaluation">9.2. Function evaluation</h3>
 <div class="paragraph">
 <p>Functions are evaluated in applicative order:
 - Each argument must be an expression
-- Each argument expression must be evaluated before evaluating the
-function
+- Each argument expression must be evaluated before evaluating the function
 - Each argument expression result must be coerced to the expected type
 - If coercion is not possible, a <code>TypeError</code> error is raised
 - The function is then called with the evaluated function arguments.</p>
@@ -8271,7 +8269,7 @@ <h3 id="_tracking">10.6. Tracking</h3>
 <div id="footer">
 <div id="footer-text">
 Version 2.0.0<br>
-Last updated 2025-11-10 13:40:00 UTC
+Last updated 2025-11-12 22:23:59 UTC
 </div>
 </div>
 </body>

doc/spec.adoc

@@ -1,6 +1,6 @@
 = json-formula Specification
 PDF Association Forms Technical Working Group
-0.2.0, {docdate}:
+2.0.0, {docdate}:
 :toc: macro
 :outlinelevels: 3
 :appendix-caption: Appendix
@@ -26,13 +26,13 @@ The grammar borrows from
 * https://docs.oasis-open.org/office/v1.2/os/OpenDocument-v1.2-os-part2.html[OpenFormula] for spreadsheet operators and function
 * https://jmespath.org/[JMESPath] for JSON query semantics
 
-The intended audience are both end-users of json-formula as well as implementors; the contents are then both a user guide and a specification.
+The intended audience are both end-users of json-formula as well as implementers; the contents are then both a user guide and a specification.
 
 // start numbering the sections from here...
 :sectnums:
 
 == Notation
-In the specification, examples are shown through the use of a `search` function.  The syntax for this function is:
+In the specification, examples are shown through the use of a `search` function called `eval`.  The syntax for this function is:
 
 [source%unbreakable]
 ----
@@ -59,8 +59,7 @@ json-formula supports all the JSON types:
 * object: an unordered collection of key value pairs
 * `null`
 
-There is an additional type that is not a JSON type that's used in
-json-formula functions:
+There is an additional type that is not a JSON type that's used in json-formula functions:
 
 * expression: A string prefixed with an ampersand (`&`) character
 
@@ -1250,8 +1249,7 @@ With nested arrays:
 
 Functions are evaluated in applicative order:
 - Each argument must be an expression
-- Each argument expression must be evaluated before evaluating the
-function
+- Each argument expression must be evaluated before evaluating the function
 - Each argument expression result must be coerced to the expected type
 - If coercion is not possible, a `TypeError` error is raised
 - The function is then called with the evaluated function arguments.