Merge pull request #28 from dy/pivot

Pivot

Author: dy

.github/copilot-instructions.md

@@ -0,0 +1,8 @@
+Avoid writing to `lookup`, use token instead.
+Avoid ad-hocs - that signals inconsistency of design. High-level API is for a reason, we need to use it and if it doesn't fit, we need to improve it.
+`/features` represent generic language features, not only JS: avoid js-specific checks.
+For features you implement or any changes, if relevant please add tests, update spec.md, docs.md and README.md, as well as REPL and other relevant files. Make sure tests pass.
+Make sure API and feature code is intuitive and user-friendly: prefer `unary`/`binary`/`nary`/`group`/`token` calls in the right order ( eg. first `|`, then `||`, then `||=` ) rather than low-level parsing. Eg. feature should not use `cur`, `idx` and use `skip` instead.
+The project is planned to be built with jz - simple javascript subset compiling to wasm, so don't use complex structures like Proxy, classes etc.
+By introducing a change, think how would that scale to various dialects and compile targets. Also make sure it doesn't compromise performance and doesn't bloat the code. Justin must be faster than jsep.
+By writing parser feature, aim for raw tree shape parsed with minimal code rather than edge cases validation.

.gitignore

@@ -106,3 +106,4 @@ dist
 # TernJS port file
 .tern-port
 .DS_Store
+test-results/

README.md

@@ -1,98 +1,67 @@
-# sub<em>script</em> <a href="https://github.com/spectjs/subscript/actions/workflows/node.js.yml"><img src="https://github.com/spectjs/subscript/actions/workflows/node.js.yml/badge.svg"/></a> <a href="https://bundlejs.com/?q=subscript"><img alt="npm bundle size" src="https://img.shields.io/bundlejs/size/subscript"/></a> <a href="http://npmjs.org/subscript"><img src="https://img.shields.io/npm/v/subscript"/></a> <a href="http://microjs.com/#subscript"><img src="https://img.shields.io/badge/microjs-subscript-blue?color=darkslateblue"/></a>
+# sub<sub><sup> ✦ </sup></sub>script [![build](https://github.com/dy/subscript/actions/workflows/node.js.yml/badge.svg)](https://github.com/dy/subscript/actions/workflows/node.js.yml) [![npm](https://img.shields.io/npm/v/subscript)](http://npmjs.org/subscript) [![size](https://img.shields.io/bundlephobia/minzip/subscript?label=size)](https://bundlephobia.com/package/subscript) [![demo](https://img.shields.io/badge/play-%F0%9F%9A%80-white)](https://dy.github.io/subscript/) [![microjs](https://img.shields.io/badge/microjs-subscript-blue?color=darkslateblue)](http://microjs.com/#subscript)
 
-> _Subscript_ is fast, tiny & extensible parser / evaluator / microlanguage.
+> Tiny expression parser & evaluator.
 
-####  Used for:
+* **Safe** — sandboxed, blocks `__proto__`, `constructor`, no global access
+* **Fast** — Pratt parser engine, see [benchmarks](#performance)
+* **Portable** — universal expression format, any compile target
+* **Metacircular** — can parse and compile itself
+* **Extensible** — pluggable syntax for building custom DSL
 
-* expressions evaluators, calculators
-* subsets of languages
-* sandboxes, playgrounds, safe eval
-* custom DSL
-* preprocessors
-* templates
+## Usage
 
-_Subscript_ has [3.5kb](https://npmfs.com/package/subscript/7.4.3/subscript.min.js) footprint <!-- (compare to [11.4kb](https://npmfs.com/package/jsep/1.2.0/dist/jsep.min.js) _jsep_ + [4.5kb](https://npmfs.com/package/expression-eval/5.0.0/dist/expression-eval.module.js) _expression-eval_) -->, good [performance](#performance) and extensive test coverage.
+```js
+import subscript from 'subscript'
 
+let fn = subscript('a + b * 2')
+fn({ a: 1, b: 3 })  // 7
+```
 
-## Usage
+## Presets
 
-```js
-import subscript from './subscript.js'
+### subscript
 
-// parse expression
-const fn = subscript('a.b + Math.sqrt(c - 1)')
+Common expressions:
 
-// evaluate with context
-fn({ a: { b:1 }, c: 5, Math })
-// 3
+`a.b a[b] a(b) + - * / % < > <= >= == != ! && || ~ & | ^ << >> ++ -- = += -= *= /=`
+```js
+import subscript from 'subscript'
+
+subscript('a.b + c * 2')({ a: { b: 1 }, c: 3 })  // 7
 ```
 
-## Operators
-
-_Subscript_ supports [common syntax](https://en.wikipedia.org/wiki/Comparison_of_programming_languages_(syntax)) (_JavaScript_, _C_, _C++_, _Java_, _C#_, _PHP_, _Swift_, _Objective-C_, _Kotlin_, _Perl_ etc.):
-
-* `a.b`, `a[b]`, `a(b)`
-* `a++`, `a--`, `++a`, `--a`
-* `a * b`, `a / b`, `a % b`
-* `+a`, `-a`, `a + b`, `a - b`
-* `a < b`, `a <= b`, `a > b`, `a >= b`, `a == b`, `a != b`
-* `~a`, `a & b`, `a ^ b`, `a | b`, `a << b`, `a >> b`
-* `!a`, `a && b`, `a || b`
-* `a = b`, `a += b`, `a -= b`, `a *= b`, `a /= b`, `a %= b`, `a <<= b`, `a >>= b`
-* `(a, (b))`, `a; b;`
-* `"abc"`, `'abc'`
-* `0.1`, `1.2e+3`
-
-### Justin
-
-_Just-in_ is no-keywords JS subset, _JSON_ + _expressions_ (see [thread](https://github.com/endojs/Jessie/issues/66)).<br/>
-It extends _subscript_ with:
-
-+ `a === b`, `a !== b`
-+ `a ** b`, `a **= b`
-+ `a ?? b`, `a ??= b`
-+ `a ||= b`, `a &&= b`
-+ `a >>> b`, `a >>>= b`
-+ `a ? b : c`, `a?.b`
-+ `...a`
-+ `[a, b]`
-+ `{a: b}`
-+ `(a, b) => c`
-+ `// foo`, `/* bar */`
-+ `true`, `false`, `null`, `NaN`, `undefined`
-+ `a in b`
+### justin
+
+JSON + expressions + templates + arrows:
 
+`` 'str' 0x 0b === !== ** ?? >>> ?. ? : => ... [] {} ` // /**/ true false null ``
 ```js
-import justin from 'subscript/justin'
+import justin from 'subscript/justin.js'
 
-let fn = justin('{ x: 1, "y": 2+2 }["x"]')
-fn()  // 1
+justin('{ x: a?.b ?? 0, y: [1, ...rest] }')({ a: null, rest: [2, 3] })
+// { x: 0, y: [1, 2, 3] }
 ```
 
-### Extra
+### jessie
 
-+ `if (c) a`, `if (c) a else b`
-+ `while (c) body`
-+ `for (init; cond; step) body`
-+ `{ a; b }` — block scope
-+ `let x`, `const x = 1`
-+ `break`, `continue`, `return x`
-+ `` `a ${x} b` `` — template literals
-+ `/pattern/flags` — regex literals
-+ `5px`, `10rem` — unit suffixes
+JSON + expressions + statements, functions:
 
+`if else for while do let const var function class return throw try catch switch import export /regex/`
 ```js
-import subscript from 'subscript/justin'
-import 'subscript/feature/loop.js'
-
-let sum = subscript(`
-  let sum = 0;
-  for (i = 0; i < 10; i += 1) sum += i;
-  sum
+import jessie from 'subscript/jessie.js'
+
+let fn = jessie(`
+  function factorial(n) {
+    if (n <= 1) return 1
+    return n * factorial(n - 1)
+  }
+  factorial(5)
 `)
-sum() // 45
+fn({})  // 120
 ```
 
+Jessie can parse and compile its own source.
+
 
 ## Parse / Compile
 
@@ -110,157 +79,113 @@ fn = compile(tree)
 fn({ a: {b: 1}, c: 2 }) // 2
 ```
 
-### Syntax Tree
-
-AST has simplified lispy tree structure (inspired by [frisk](https://ghub.io/frisk) / [nisp](https://github.com/ysmood/nisp)), opposed to [ESTree](https://github.com/estree/estree):
+## Extension
 
-* not limited to particular language (JS), can be compiled to different targets;
-* reflects execution sequence, rather than code layout;
-* has minimal overhead, directly maps to operators;
-* simplifies manual evaluation and debugging;
-* has conventional form and one-liner docs:
+```js
+import { binary, operator, compile } from 'subscript/justin.js'
+
+// add intersection operator
+binary('∩', 80)  // register parser
+operator('∩', (a, b) => (  // register compiler
+  a = compile(a), b = compile(b),
+  ctx => a(ctx).filter(x => b(ctx).includes(x))
+))
+```
 
 ```js
-import { compile } from 'subscript.js'
-
-const fn = compile(['+', ['*', 'min', [,60]], [,'sec']])
-fn({min: 5}) // min*60 + "sec" == "300sec"
-
-// node kinds
-'a'                // identifier — variable from scope
-[, value]          // literal — [0] empty distinguishes from operator
-[op, a]            // unary — prefix operator
-[op, a, null]      // unary — postfix operator (null marks postfix)
-[op, a, b]         // binary
-[op, a, b, c]      // n-ary / ternary
-
-// operators
-['+', a, b]        // a + b
-['.', a, 'b']      // a.b — property access
-['[]', a, b]       // a[b] — bracket access
-['()', a]          // (a) — grouping
-['()', a, b]       // a(b) — function call
-['()', a, null]    // a() — call with no args
-
-// literals & structures
-[, 1]              // 1
-[, 'hello']        // "hello"
-['[]', [',', ...]] // [a, b] — array literal
-['{}', [':', ...]] // {a: b} — object literal
-
-// justin extensions
-['?', a, b, c]     // a ? b : c — ternary
-['=>', params, x]  // (a) => x — arrow function
-['...', a]         // ...a — spread
-
-// control flow (extra)
-['if', cond, then, else]
-['while', cond, body]
-['for', init, cond, step, body]
-
-// postfix example
-['++', 'a']        // ++a
-['++', 'a', null]  // a++
-['px', [,5]]       // 5px (unit suffix)
+import justin from 'subscript/justin.js'
+justin('[1,2,3] ∩ [2,3,4]')({})  // [2, 3]
 ```
 
-### Stringify
+See [docs.md](./docs.md) for full API.
+
+
+## Syntax Tree
 
-To convert tree back to code, there's codegenerator function:
+Expressions parse to a minimal JSON-compatible AST:
 
 ```js
-import { stringify } from 'subscript.js'
+import { parse } from 'subscript'
 
-stringify(['+', ['*', 'min', [,60]], [,'sec']])
-// 'min * 60 + "sec"'
+parse('a + b * 2')
+// ['+', 'a', ['*', 'b', [, 2]]]
 ```
 
-## Extending
-
-_Subscript_ provides premade language [features](./feature) and API to customize syntax:
+AST has simplified lispy tree structure (inspired by [frisk](https://ghub.io/frisk) / [nisp](https://github.com/ysmood/nisp)), opposed to [ESTree](https://github.com/estree/estree):
 
-* `unary(str, precedence, postfix=false)` − register unary operator, either prefix `⚬a` or postfix `a⚬`.
-* `binary(str, precedence, rassoc=false)` − register binary operator `a ⚬ b`, optionally right-associative.
-* `nary(str, precedence)` − register n-ary (sequence) operator like `a; b;` or `a, b`, allows missing args.
-* `group(str, precedence)` - register group, like `[a]`, `{a}`, `(a)` etc.
-* `access(str, precedence)` - register access operator, like `a[b]`, `a(b)` etc.
-* `token(str, precedence, lnode => node)` − register custom token or literal. Callback takes left-side node and returns complete expression node.
-* `operator(str, (a, b) => ctx => value)` − register evaluator for an operator. Callback takes node arguments and returns evaluator function.
+* not limited to particular language (JS), can be compiled to different targets;
+* reflects execution sequence, rather than code layout;
+* has minimal overhead, directly maps to operators;
+* simplifies manual evaluation and debugging;
+* has conventional form and one-liner docs:
 
-Longer operators should be registered after shorter ones, eg. first `|`, then `||`, then `||=`.
+Three forms:
 
 ```js
-import script, { compile, operator, unary, binary, token } from './subscript.js'
+'x'             // identifier — resolve from context
+[, value]       // literal — return as-is (empty slot = data)
+[op, ...args]   // operation — apply operator
+```
 
-// enable objects/arrays syntax
-import 'subscript/feature/array.js';
-import 'subscript/feature/object.js';
+See [spec.md](./spec.md).
 
-// add identity operators (precedence of comparison)
-binary('===', 9), binary('!==', 9)
-operator('===', (a, b) => (a = compile(a), b = compile(b), ctx => a(ctx)===b(ctx)))
-operator('!==', (a, b) => (a = compile(a), b = compile(b), ctx => a(ctx)!==b(ctx)))
 
-// add nullish coalescing (precedence of logical or)
-binary('??', 3)
-operator('??', (a, b) => b && (a = compile(a), b = compile(b), ctx => a(ctx) ?? b(ctx)))
+## Safety
 
-// add JS literals
-token('undefined', 20, a => a ? err() : [, undefined])
-token('NaN', 20, a => a ? err() : [, NaN])
+Blocked by default:
+- `__proto__`, `__defineGetter__`, `__defineSetter__`
+- `constructor`, `prototype`
+- Global access (only context is visible)
+
+```js
+subscript('constructor.constructor("alert(1)")()')({})
+// undefined (blocked)
 ```
 
-See [`./feature/*`](./feature) or [`./justin.js`](./justin.js) for examples.
+## Performance
 
+```
+Parse 30k:  subscript 150ms · justin 183ms · jsep 270ms · expr-eval 480ms · jexl 1056ms
+Eval 30k:   new Function 7ms · subscript 15ms · jsep+eval 30ms · expr-eval 72ms
+```
 
+## Utils
 
-## Performance
+### Codegen
 
-Subscript shows good performance within other evaluators. Example expression:
+Convert tree back to code:
 
-```
-1 + (a * b / c % d) - 2.0 + -3e-3 * +4.4e4 / f.g[0] - i.j(+k == 1)(0)
+```js
+import { codegen } from 'subscript/util/stringify.js'
+
+codegen(['+', ['*', 'min', [,60]], [,'sec']])
+// 'min * 60 + "sec"'
 ```
 
-Parse 30k times:
+### Bundle
 
-```
-subscript: ~150 ms 🥇
-justin: ~183 ms
-jsep: ~270 ms 🥈
-jexpr: ~297 ms 🥉
-mr-parser: ~420 ms
-expr-eval: ~480 ms
-math-parser: ~570 ms
-math-expression-evaluator: ~900ms
-jexl: ~1056 ms
-mathjs: ~1200 ms
-new Function: ~1154 ms
-```
+Create custom dialect as single file:
 
-Eval 30k times:
-```
-new Function: ~7 ms 🥇
-subscript: ~15 ms 🥈
-justin: ~17 ms
-jexpr: ~23 ms 🥉
-jsep (expression-eval): ~30 ms
-math-expression-evaluator: ~50ms
-expr-eval: ~72 ms
-jexl: ~110 ms
-mathjs: ~119 ms
-mr-parser: -
-math-parser: -
+```js
+import { bundle } from 'subscript/util/bundle.js'
+
+const code = await bundle('subscript/jessie.js')
+// → self-contained ES module
 ```
 
-<!--
+
 ## Used by
 
-[prepr](https://github.com/dy/prepr), [justin](#justin), [jz](https://github.com/dy/jz), [glsl-transpiler](https://github.com/stackgl/glsl-transpiler), [piezo](https://github.com/dy/piezo)
--->
+* [jz](https://github.com/dy/jz) — JS subset → WASM compiler
+<!-- * [prepr](https://github.com/dy/prepr) -->
+<!-- * [glsl-transpiler](https://github.com/stackgl/glsl-transpiler) -->
+<!-- * [piezo](https://github.com/dy/piezo) -->
+
+
+## Refs
 
-## Alternatives
+[jsep](https://github.com/EricSmekens/jsep), [jexl](https://github.com/TomFrost/Jexl), [expr-eval](https://github.com/silentmatt/expr-eval), [math.js](https://mathjs.org/).
 
-[jexpr](https://github.com/justinfagnani/jexpr), [jsep](https://github.com/EricSmekens/jsep), [jexl](https://github.com/TomFrost/Jexl), [mozjexl](https://github.com/mozilla/mozjexl), [expr-eval](https://github.com/silentmatt/expr-eval), [expression-eval](https://github.com/donmccurdy/expression-eval), [string-math](https://github.com/devrafalko/string-math), [nerdamer](https://github.com/jiggzson/nerdamer), [math-codegen](https://github.com/mauriciopoppe/math-codegen), [math-parser](https://www.npmjs.com/package/math-parser), [math.js](https://mathjs.org/docs/expressions/parsing.html), [nx-compile](https://github.com/nx-js/compiler-util), [built-in-math-eval](https://github.com/mauriciopoppe/built-in-math-eval)
+<!-- [mozjexl](https://github.com/mozilla/mozjexl), [jexpr](https://github.com/justinfagnani/jexpr), [expression-eval](https://github.com/donmccurdy/expression-eval), [string-math](https://github.com/devrafalko/string-math), [nerdamer](https://github.com/jiggzson/nerdamer), [math-codegen](https://github.com/mauriciopoppe/math-codegen), [math-parser](https://www.npmjs.com/package/math-parser), [nx-compile](https://github.com/nx-js/compiler-util), [built-in-math-eval](https://github.com/mauriciopoppe/built-in-math-eval) -->
 
-<p align=center><a href="https://github.com/krsnzd/license/">🕉</a></p>
+<p align=center><a href="https://github.com/krsnzd/license/">ॐ</a></p>