feat(pointfree-lang): add >word, update pkg & readme

thi-ng · Apr 12, 2020 · 4fe2f7f · 4fe2f7f
1 parent 94adf04
commit 4fe2f7f
Show file tree

Hide file tree

Showing 4 changed files with 58 additions and 13 deletions.
diff --git a/packages/pointfree-lang/README.md b/packages/pointfree-lang/README.md
@@ -23,6 +23,7 @@ This project is part of the
   - [Identifiers](#identifiers)
   - [Word definitions](#word-definitions)
     - [Hyperstatic words](#hyperstatic-words)
+    - [Dynamic word creation from quotations](#dynamic-word-creation-from-quotations)
     - [Local variables](#local-variables)
   - [Boolean](#boolean)
   - [Numbers](#numbers)
@@ -53,6 +54,7 @@ an ES6 embedded DSL for concatenative programming:
 - dynamically scoped variables (stored in environment object)
     - syntax sugar for declaring & autobinding local vars w/ stack values
 - nested quotations (code as data, vanilla JS arrays)
+- dynamic word construction from quotations
 - array & object literals (optionally w/ computed properties)
 - all other features of @thi.ng/pointfree (combinators, array/vector ops etc.)
 - CLI version w/ basic file I/O, library includes, JSON
@@ -67,11 +69,12 @@ an ES6 embedded DSL for concatenative programming:
 yarn add @thi.ng/pointfree-lang
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 5.02 KB / CJS: 5.01 KB / UMD: 4.93 KB
+Package sizes (gzipped, pre-treeshake): ESM: 5.05 KB / CJS: 5.05 KB / UMD: 4.97 KB
 
 ## Dependencies
 
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
+- [@thi.ng/bench](https://github.com/thi-ng/umbrella/tree/develop/packages/bench)
 - [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
 - [@thi.ng/pointfree](https://github.com/thi-ng/umbrella/tree/develop/packages/pointfree)
 - [commander](https://github.com/thi-ng/umbrella/tree/develop/packages/undefined)
@@ -93,13 +96,8 @@ A selection:
 
 The package includes a `pointfree` CLI command to evaluate strings or files:
 
-(It's recommended to install the package globally for CLI usage)
-
 ```text
-# install globally
-yarn global add @thi.ng/pointfree-lang
-
-pointfree --help
+npx @thi.ng/pointfree-lang
 
 Usage: pointfree [options] [file]
 
@@ -380,6 +378,7 @@ aren't valid names in the ES6 context):
 | `match?` | `ismatch`     |
 | `>json`  | `tojson`      |
 | `json>`  | `fromjson`    |
+| `>word`  | `word`        |
 | `pi`     | `Math.PI`     |
 | `tau`    | `2 * Math.PI` |
 | `.`      | `print`       |
@@ -441,6 +440,26 @@ foo bar
 // [ 'foo1foo2', 'foo1bar' ]
 ```
 
+#### Dynamic word creation from quotations
+
+Quotations are used to treat code as data, delay execution of words
+and/or dynamically compose words. The latter can be achieved via the
+`>word`, which takes a quotation and a word name as arguments.
+
+```forth
+( takes min/max values, produces range check quotation )
+( uses local variables `a` and `b`, see section below  )
+
+: range-check ( a b -- q ) ^{ a b } [dup @a >= [@b <=] [drop F] if] ;
+
+( build range check for "0".."9" ASCII interval and define as word `digit?` )
+0 9 range-check "digit?" >word
+
+( now use... )
+"5" digit? . ( true )
+"a" digit? . ( false )
+```
+
 #### Local variables
 
 A word definition can include an optional declaration of local

diff --git a/packages/pointfree-lang/package.json b/packages/pointfree-lang/package.json
@@ -43,6 +43,7 @@
     },
     "dependencies": {
         "@thi.ng/api": "^6.10.1",
+        "@thi.ng/bench": "^2.0.8",
         "@thi.ng/errors": "^1.2.10",
         "@thi.ng/pointfree": "^1.3.3",
         "commander": "^5.0.0",
@@ -63,6 +64,7 @@
         "Forth",
         "functional",
         "grammar",
+        "language",
         "PEG",
         "pointfree",
         "RPN",

diff --git a/packages/pointfree-lang/src/api.ts b/packages/pointfree-lang/src/api.ts
@@ -65,6 +65,13 @@ export const ALIASES: IObjectOf<pf.StackFn> = {
     "match?": pf.ismatch,
     ">json": pf.tojson,
     "json>": pf.fromjson,
+    ">word": (ctx) => {
+        const ds = ctx[0];
+        pf.ensureStack(ds, 2);
+        const name = ds.pop();
+        ctx[2].__words[name] = pf.word(ds.pop());
+        return ctx;
+    },
     pi: pf.push(Math.PI),
     tau: pf.push(2 * Math.PI),
     ".": pf.print,

diff --git a/packages/pointfree-lang/tpl.readme.md b/packages/pointfree-lang/tpl.readme.md
@@ -26,6 +26,7 @@ an ES6 embedded DSL for concatenative programming:
 - dynamically scoped variables (stored in environment object)
     - syntax sugar for declaring & autobinding local vars w/ stack values
 - nested quotations (code as data, vanilla JS arrays)
+- dynamic word construction from quotations
 - array & object literals (optionally w/ computed properties)
 - all other features of @thi.ng/pointfree (combinators, array/vector ops etc.)
 - CLI version w/ basic file I/O, library includes, JSON
@@ -56,13 +57,8 @@ ${examples}
 
 The package includes a `pointfree` CLI command to evaluate strings or files:
 
-(It's recommended to install the package globally for CLI usage)
-
 ```text
-# install globally
-yarn global add @thi.ng/pointfree-lang
-
-pointfree --help
+npx @thi.ng/pointfree-lang
 
 Usage: pointfree [options] [file]
 
@@ -344,6 +340,7 @@ aren't valid names in the ES6 context):
 | `match?` | `ismatch`     |
 | `>json`  | `tojson`      |
 | `json>`  | `fromjson`    |
+| `>word`  | `word`        |
 | `pi`     | `Math.PI`     |
 | `tau`    | `2 * Math.PI` |
 | `.`      | `print`       |
@@ -405,6 +402,26 @@ foo bar
 // [ 'foo1foo2', 'foo1bar' ]
 ```
 
+#### Dynamic word creation from quotations
+
+Quotations are used to treat code as data, delay execution of words
+and/or dynamically compose words. The latter can be achieved via the
+`>word`, which takes a quotation and a word name as arguments.
+
+```forth
+( takes min/max values, produces range check quotation )
+( uses local variables `a` and `b`, see section below  )
+
+: range-check ( a b -- q ) ^{ a b } [dup @a >= [@b <=] [drop F] if] ;
+
+( build range check for "0".."9" ASCII interval and define as word `digit?` )
+0 9 range-check "digit?" >word
+
+( now use... )
+"5" digit? . ( true )
+"a" digit? . ( false )
+```
+
 #### Local variables
 
 A word definition can include an optional declaration of local