@tabnas/expr 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Richard Rodger and other contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# @tabnas/expr
+
+An expression-syntax plugin for the [Tabnas](https://github.com/tabnas/jsonic)
+parser, available in both TypeScript and Go.
+
+Adds Pratt-parser expressions to Tabnas: infix, prefix, suffix, ternary,
+and paren operators with a configurable binding-power (precedence) scale, so
+values can include arithmetic/logical expressions. Expressions parse into
+LISP-style S-expressions (arrays whose first element is the operator `Op`),
+which a user-supplied evaluator can reduce to values.
+
+[![npm version](https://img.shields.io/npm/v/@tabnas/expr.svg)](https://npmjs.com/package/@tabnas/expr)
+[![build](https://github.com/tabnas/expr/actions/workflows/build.yml/badge.svg)](https://github.com/tabnas/expr/actions/workflows/build.yml)
+
+## Install
+
+```sh
+npm install @tabnas/expr @tabnas/parser @tabnas/jsonic
+```
+
+## Tiny example
+
+```js
+const { Tabnas } = require('@tabnas/parser')
+const { jsonic } = require('@tabnas/jsonic')
+const { Expr } = require('@tabnas/expr')
+
+// Show parse trees with each Op replaced by its source string.
+const S = (x) => Array.isArray(x) && x.length ? [x[0].src || x[0].osrc || S(x[0]), ...x.slice(1).map(S)] : x
+
+const j = new Tabnas().use(jsonic).use(Expr)
+const show = (s) => JSON.parse(JSON.stringify(S(j.parse(s))))
+
+show('1+2*3')   // => ['+', 1, ['*', 2, 3]]
+show('-1+2')    // => ['+', ['-', 1], 2]
+```
+
+Add an `evaluate` callback to compute values instead:
+
+```js
+const { Tabnas } = require('@tabnas/parser')
+const { jsonic } = require('@tabnas/jsonic')
+const { Expr } = require('@tabnas/expr')
+
+const math = (rule, ctx, op, terms) => {
+  switch (op.src) {
+    case '+': return op.prefix ? +terms[0] : terms[0] + terms[1]
+    case '*': return terms[0] * terms[1]
+    case '(': return terms[0]
+    default:  return NaN
+  }
+}
+
+const j = new Tabnas().use(jsonic).use(Expr, { evaluate: math })
+
+j.parse('1+2*3')     // => 7
+j.parse('(1+2)*3')   // => 9
+```
+
+## Documentation
+
+Docs follow the [Diátaxis](https://diataxis.fr) framework:
+
+- **[Tutorial](doc/tutorial.md)** — parse and evaluate your first
+  expression, step by step.
+- **[Guide](doc/guide.md)** — recipes: add a custom operator, build
+  function-call syntax with paren-preval, add a ternary, restrict to strict
+  math, walk the tree yourself.
+- **[Reference](doc/reference.md)** — exports, `OpDef` options, the `Op` /
+  `Evaluate` types, and the default operator table.
+- **[Concepts](doc/concepts.md)** — how Pratt parsing works, the
+  binding-power scale, and the design trade-offs.
+
+Go port docs: [tutorial](../go/doc/tutorial.md) ·
+[guide](../go/doc/guide.md) · [reference](../go/doc/reference.md) ·
+[concepts](../go/doc/concepts.md).
+
+## Grammar diagram
+
+The installed grammar as a railroad/syntax diagram, generated from the live
+grammar with [`@tabnas/railroad`](https://github.com/tabnas/railroad):
+
+![expr grammar railroad diagram](doc/grammar.svg)
+
+A vertical ASCII version is in [`doc/grammar.txt`](doc/grammar.txt).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/expr.d.ts

@@ -0,0 +1,64 @@
+import { Plugin, Rule, Context, Token } from '@tabnas/parser';
+type OpDef = {
+    src?: string | string[];
+    osrc?: string;
+    csrc?: string;
+    left?: number;
+    right?: number;
+    use?: any;
+    prefix?: boolean;
+    suffix?: boolean;
+    infix?: boolean;
+    ternary?: boolean;
+    paren?: boolean;
+    preval?: {
+        active?: boolean;
+        required?: boolean;
+        allow?: string[];
+    };
+};
+type ExprOptions = {
+    op?: {
+        [name: string]: OpDef;
+    };
+    evaluate?: typeof evaluation;
+};
+type Op = {
+    name: string;
+    src: string;
+    left: number;
+    right: number;
+    use: any;
+    prefix: boolean;
+    suffix: boolean;
+    infix: boolean;
+    ternary: boolean;
+    paren: boolean;
+    terms: number;
+    tkn: string;
+    tin: number;
+    osrc: string;
+    csrc: string;
+    otkn: string;
+    otin: number;
+    ctkn: string;
+    ctin: number;
+    preval: {
+        active: boolean;
+        required: boolean;
+        allow?: string[];
+    };
+    token: Token;
+    OP_MARK: typeof OP_MARK;
+};
+type Evaluate = (rule: Rule, ctx: Context, op: Op, ...terms: any) => any;
+declare const OP_MARK: {};
+declare let Expr: Plugin;
+declare function prattify(expr: any, op?: Op, whence?: string): any[];
+declare function evaluation(rule: Rule, ctx: Context, expr: any, evaluate: Evaluate): any;
+declare const testing: {
+    prattify: typeof prattify;
+    opify: (x: any) => any;
+};
+export { Expr, evaluation, testing };
+export type { ExprOptions, OpDef, Op, Evaluate };