Finish readme

Author: dy

README.md

@@ -1,35 +1,33 @@
-# 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/)
+# 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)
 
-> Tiny expression compiler.
+> Tiny expression parser & evaluator.
 
-```js
-import subscript from 'subscript'
-
-let fn = subscript('a + b * 2')
-fn({ a: 1, b: 3 })  // 7
-```
-
-
-* **Minimal** – common expressions < JSON + expressions < JS subset
 * **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
 
+## Usage
 
+```js
+import subscript from 'subscript'
+
+let fn = subscript('a + b * 2')
+fn({ a: 1, b: 3 })  // 7
+```
 
 ## Presets
 
-**subscript** — common expressions (~4kb gzip):
+**subscript** — common expressions:<br>
 `a.b a[b] a(b) + - * / % < > <= >= == != ! && || ~ & | ^ << >> ++ -- = += -= *= /=`
 ```js
 import subscript from 'subscript'
 
 subscript('a.b + c * 2')({ a: { b: 1 }, c: 3 })  // 7
 ```
 
-**justin** — + JSON, arrows, templates (~6kb gzip):
+**justin** — + JSON, arrows, templates:<br>
 `` 'str' 0x 0b === !== ** ?? >>> ?. ? : => ... [] {} ` // /**/ true false null ``
 ```js
 import justin from 'subscript/justin.js'
@@ -38,7 +36,7 @@ justin('{ x: a?.b ?? 0, y: [1, ...rest] }')({ a: null, rest: [2, 3] })
 // { x: 0, y: [1, 2, 3] }
 ```
 
-**jessie** — + statements, functions (~8kb gzip):
+**jessie** — + statements, functions:<br>
 `if else for while do let const var function class return throw try catch switch import export /regex/`
 ```js
 import jessie from 'subscript/jessie.js'
@@ -55,6 +53,23 @@ fn({})  // 120
 
 Jessie can parse and compile its own source.
 
+
+## Parse / Compile
+
+Subscript exposes `parse` to build AST and `compile` to create evaluators.
+
+```js
+import { parse, compile } from 'subscript'
+
+// parse expression
+let tree = parse('a.b + c - 1')
+tree // ['-', ['+', ['.', 'a', 'b'], 'c'], [,1]]
+
+// compile tree to evaluable function
+fn = compile(tree)
+fn({ a: {b: 1}, c: 2 }) // 2
+```
+
 ## Extension
 
 ```js
@@ -73,7 +88,7 @@ import justin from 'subscript/justin.js'
 justin('[1,2,3] ∩ [2,3,4]')({})  // [2, 3]
 ```
 
-See [docs.md](./docs.md) for full API: `binary`, `unary`, `nary`, `group`, `access`, `literal`, `token`.
+See [docs.md](./docs.md) for full API.
 
 
 ## Syntax Tree
@@ -87,6 +102,14 @@ parse('a + b * 2')
 // ['+', 'a', ['*', 'b', [, 2]]]
 ```
 
+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):
+
+* 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:
+
 Three forms:
 
 ```js
@@ -95,7 +118,7 @@ Three forms:
 [op, ...args]   // operation — apply operator
 ```
 
-Portable to any language. See [spec.md](./spec.md).
+See [spec.md](./spec.md).
 
 
 ## Safety
@@ -117,6 +140,30 @@ Parse 30k:  subscript 150ms · justin 183ms · jsep 270ms · expr-eval 480ms ·
 Eval 30k:   new Function 7ms · subscript 15ms · jsep+eval 30ms · expr-eval 72ms
 ```
 
+## Utils
+
+### Stringify
+
+To convert tree back to code, there's codegenerator function:
+
+```js
+import { stringify } from 'subscript.js'
+
+stringify(['+', ['*', 'min', [,60]], [,'sec']])
+// 'min * 60 + "sec"'
+```
+
+## Bundle
+
+Create custom dialect as single file:
+
+```js
+import { bundle } from 'subscript/util/bundle.js'
+
+const code = await bundle('subscript/jessie.js')
+// → self-contained ES module
+```
+
 
 ## Used by
 

docs.md

@@ -14,7 +14,6 @@ subscript('a * b')({ a: 3, b: 4 })  // 12
 ```
 
 
-
 ## Evaluate Code
 
 ### Function Call
@@ -309,41 +308,6 @@ import {
 ```
 
 
-
-## 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):
-
-* portable to any language, not limited to JS;
-* 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
-'x'              // identifier
-[, 1]            // literal
-['+', 'a', 'b']  // binary
-['-', 'a']       // unary prefix
-['++', 'a', null]  // unary postfix
-['?', a, b, c]   // ternary
-['if', cond, then, else] // control flow
-```
-
-See full [spec](./spec.md)
-
-
-## Bundle
-
-Create custom dialect as single file:
-
-```js
-import { bundle } from 'subscript/util/bundle.js'
-
-const code = await bundle('subscript/jessie.js')
-// → self-contained ES module
-```
-
 [**Playground →**](https://dy.github.io/subscript/) — interactive DSL builder
 
 <p align="center">🕉</p>