@tabnas/directive 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 jsonicjs
+
+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,60 @@
+# @tabnas/directive — directive syntax for the tabnas parser
+
+Adds directive syntax to the [tabnas](https://github.com/tabnas/parser)
+parser. A directive is a token sequence (e.g. `@name`, `add<1,2>`) that
+triggers custom parsing behaviour. It is a plugin for the tabnas engine —
+its only dependency — and layers onto whatever host grammar provides the
+standard `val` / `list` / `map` / `pair` rules. TypeScript (canonical)
+and Go ports share the same API shape and test specs.
+
+[![npm version](https://img.shields.io/npm/v/@tabnas/directive.svg)](https://npmjs.com/package/@tabnas/directive)
+[![build](https://github.com/tabnas/directive/actions/workflows/build.yml/badge.svg)](https://github.com/tabnas/directive/actions/workflows/build.yml)
+
+
+## Documentation
+
+The four-quadrant TypeScript docs live in [`doc/`](doc):
+[tutorial](doc/tutorial.md) · [how-to guide](doc/guide.md) ·
+[reference](doc/reference.md) · [concepts](doc/concepts.md). The Go-port
+docs are in [`../go/doc/`](../go/doc).
+
+
+## Quickstart
+
+The directive modifies host-grammar rules, so apply it to a `Tabnas`
+instance that already has a grammar that provides `val` / `list` / `map`
+/ `pair`. Here the host is [`@tabnas/json`](https://github.com/tabnas/json),
+which is why the input uses JSON syntax (quoted strings):
+
+```js
+const { Tabnas } = require('@tabnas/parser')
+const { json } = require('@tabnas/json')
+const { Directive } = require('@tabnas/directive')
+
+const j = new Tabnas({ plugins: [json] }).use(Directive, {
+  name: 'upper',
+  open: '@',
+  action: (rule) => (rule.node = String(rule.child.node).toUpperCase()),
+})
+
+j.parse('@"x"')              // => 'X'
+j.parse('[@"a", @"b", 1]')   // => ['A', 'B', 1]
+```
+
+A minimal host grammar (used by the tests) lives in
+[`test/mini-grammar.ts`](test/mini-grammar.ts); see the
+[tutorial](doc/tutorial.md) for a step-by-step walkthrough.
+
+
+## Build and test
+
+The `tabnas` engine is the only dependency and is consumed from source.
+From the repository root, `make build` / `make test` fetch it into
+`vendor/` and build/test both implementations. The tests bring their own
+small grammar. See the [root README](../README.md) and
+[`../AGENTS.md`](../AGENTS.md).
+
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/directive.d.ts

@@ -0,0 +1,23 @@
+import { Tabnas, StateAction, Plugin, Tin } from '@tabnas/parser';
+type DirectiveOptions = {
+    name: string;
+    open: string;
+    action: StateAction | string;
+    close?: string;
+    rules?: {
+        open?: string | string[] | Record<string, {
+            c?: Function;
+        }>;
+        close?: string | string[] | Record<string, {
+            c?: Function;
+        }>;
+    };
+    custom?: (tabnas: Tabnas, config: {
+        OPEN: Tin;
+        CLOSE: Tin | null | undefined;
+        name: string;
+    }) => void;
+};
+declare const Directive: Plugin;
+export { Directive };
+export type { DirectiveOptions };

package/dist/directive.js

@@ -0,0 +1,163 @@
+"use strict";
+/* Copyright (c) 2021-2022 Richard Rodger, MIT License */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Directive = void 0;
+const resolveRules = (rules) => {
+    const rulemap = {};
+    if ('string' == typeof rules) {
+        rules = rules.split(/\s*,\s*/);
+    }
+    if (Array.isArray(rules)) {
+        for (const n of rules) {
+            if (null != n && '' !== n)
+                rulemap[n] = {};
+        }
+    }
+    else if (null != rules) {
+        for (const k of Object.keys(rules)) {
+            if (null != rules[k])
+                rulemap[k] = rules[k];
+        }
+    }
+    return rulemap;
+};
+const Directive = (tabnas, options) => {
+    let rules = {
+        open: resolveRules(options?.rules?.open),
+        close: resolveRules(options?.rules?.close),
+    };
+    let name = options.name;
+    let open = options.open;
+    let close = options.close;
+    let action;
+    let custom = options.custom;
+    if ('string' === typeof options.action) {
+        let path = options.action;
+        action = (rule) => (rule.node = tabnas.util.prop(tabnas.options, path));
+    }
+    else {
+        action = options.action;
+    }
+    let token = {};
+    let openTN = '#OD_' + name;
+    let closeTN = '#CD_' + name;
+    let OPEN = tabnas.fixed(open);
+    let CLOSE = null == close ? null : tabnas.fixed(close);
+    // OPEN must be unique
+    if (null != OPEN) {
+        throw new Error('Directive open token already in use: ' + open);
+    }
+    else {
+        token[openTN] = open;
+    }
+    // Only create CLOSE if not already defined as a fixed token
+    if (null == CLOSE && null != close) {
+        token[closeTN] = close;
+    }
+    tabnas.options({
+        fixed: {
+            token,
+        },
+    });
+    let CA = tabnas.token.CA;
+    OPEN = tabnas.fixed(open);
+    CLOSE = null == close ? null : tabnas.fixed(close);
+    // NOTE: RuleSpec.open|close refers to Rule state, whereas
+    // OPEN|CLOSE refers to opening and closing tokens for the directive.
+    // Pre-seed the directive rule's hooks (clear existing alts, set bo/bc).
+    // `grammar()` below will then install the open/close alts with the
+    // `directive` group tag appended via the setting arg.
+    tabnas.rule(name, (rs) => rs
+        .clear()
+        .bo((rule) => ((rule.node = {}), undefined))
+        .bc(function (rule, ctx, next, tkn) {
+        let out = action.call(this, rule, ctx, next, tkn);
+        if (out?.isToken) {
+            return out;
+        }
+    }));
+    // Build a declarative grammar spec covering every rule modification
+    // plus the directive rule's own alts.
+    const grammarSpec = { rule: {} };
+    const ruleFor = (rn) => (grammarSpec.rule[rn] = grammarSpec.rule[rn] || {});
+    Object.entries(rules.open).forEach((entry) => {
+        const [rulename, rulespec] = entry;
+        const openAlts = [];
+        const closeAlts = [];
+        if (null != close) {
+            // More-specific OPEN+CLOSE alt first so it's tried before OPEN alone.
+            openAlts.push({
+                s: [OPEN, CLOSE],
+                b: 1,
+                p: name,
+                n: { ['dr_' + name]: 1 },
+                g: 'start,end',
+            });
+            closeAlts.push({
+                s: [CLOSE],
+                b: 1,
+                g: 'end',
+            });
+        }
+        openAlts.push({
+            s: [OPEN],
+            p: name,
+            n: { ['dr_' + name]: 1 },
+            g: 'start',
+            c: rulespec.c,
+        });
+        const r = ruleFor(rulename);
+        r.open = openAlts;
+        if (closeAlts.length)
+            r.close = closeAlts;
+    });
+    if (null != close) {
+        Object.entries(rules.close).forEach((entry) => {
+            const [rulename, rulespec] = entry;
+            const r = ruleFor(rulename);
+            r.close = [
+                {
+                    s: [CLOSE],
+                    c: (r, ctx) => 1 === r.n['dr_' + name] &&
+                        (rulespec.c ? rulespec.c(r, ctx) : true),
+                    b: 1,
+                    g: 'end',
+                },
+                {
+                    s: [CA, CLOSE],
+                    c: (r) => 1 === r.n['dr_' + name],
+                    b: 1,
+                    g: 'end,comma',
+                },
+            ];
+        });
+    }
+    const directiveOpenAlts = [];
+    if (null != close) {
+        directiveOpenAlts.push({ s: [CLOSE], b: 1 });
+    }
+    directiveOpenAlts.push({
+        p: 'val',
+        // Only accept implicits when there is a CLOSE token,
+        // otherwise we'll eat all following siblings.
+        n: null == close ? { dlist: 1, dmap: 1 } : { dlist: 0, dmap: 0 },
+    });
+    const dr = ruleFor(name);
+    dr.open = directiveOpenAlts;
+    if (null != close) {
+        dr.close = [{ s: [CLOSE] }, { s: [CA, CLOSE] }];
+    }
+    tabnas.grammar(grammarSpec, { rule: { alt: { g: 'directive' } } });
+    if (custom) {
+        custom(tabnas, { OPEN, CLOSE, name });
+    }
+};
+exports.Directive = Directive;
+Directive.defaults = {
+    rules: {
+        // By default, directives only operate where vals occur.
+        open: 'val',
+        close: 'list,elem,map,pair',
+    },
+};
+//# sourceMappingURL=directive.js.map

package/dist/directive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directive.js","sourceRoot":"","sources":["../src/directive.ts"],"names":[],"mappings":"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"}

package/dist/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/directive.ts"],"version":"6.0.3"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@tabnas/directive",
+  "version": "0.2.0",
+  "description": "Directive syntax plugin for the tabnas JSON parser.",
+  "main": "dist/directive.js",
+  "type": "commonjs",
+  "types": "dist/directive.d.ts",
+  "homepage": "https://github.com/tabnas/directive",
+  "keywords": [
+    "tabnas",
+    "parser",
+    "directive",
+    "plugin"
+  ],
+  "author": "Richard Rodger (http://richardrodger.com)",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/tabnas/directive.git",
+    "directory": "ts"
+  },
+  "scripts": {
+    "test": "node --enable-source-maps --test \"dist-test/*.test.js\"",
+    "test-some": "node --enable-source-maps --test-name-pattern=\"$npm_config_pattern\" --test \"dist-test/*.test.js\"",
+    "watch": "tsc --build src test -w",
+    "build": "tsc --build src test",
+    "clean": "rm -rf dist dist-test node_modules yarn.lock package-lock.json",
+    "reset": "npm run clean && npm i && npm run build && npm test",
+    "repo-tag": "REPO_VERSION=`node -e \"console.log(require('./package').version)\"` && echo TAG: v$REPO_VERSION && git commit -a -m v$REPO_VERSION && git push && git tag v$REPO_VERSION && git push --tags;",
+    "repo-publish": "npm run clean && npm i && npm run repo-publish-quick",
+    "repo-publish-quick": "npm run build && npm run test && npm run repo-tag && npm publish --access public --registry https://registry.npmjs.org "
+  },
+  "license": "MIT",
+  "files": [
+    "src",
+    "dist",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@tabnas/debug": "file:../../debug/ts",
+    "@tabnas/parser": "file:../../parser/ts",
+    "@tabnas/railroad": "file:../../railroad/ts",
+    "@types/node": "25.6.0",
+    "typescript": "6.0.3"
+  },
+  "peerDependencies": {
+    "@tabnas/parser": "^0.2.0"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

package/src/directive.ts

@@ -0,0 +1,222 @@
+/* Copyright (c) 2021-2022 Richard Rodger, MIT License */
+
+import {
+  Tabnas,
+  Rule,
+  RuleSpec,
+  StateAction,
+  Plugin,
+  Context,
+  Token,
+  Tin,
+} from '@tabnas/parser'
+
+
+type DirectiveOptions = {
+  name: string
+  open: string
+  action: StateAction | string
+  close?: string
+  rules?: {
+    open?: string | string[] | Record<string, { c?: Function }>
+    close?: string | string[] | Record<string, { c?: Function }>
+  }
+  custom?: (
+    tabnas: Tabnas,
+    config: { OPEN: Tin; CLOSE: Tin | null | undefined; name: string },
+  ) => void
+}
+
+
+const resolveRules = (
+  rules: undefined | string | string[] | Record<string, { c?: Function }>
+) => {
+  const rulemap: Record<string, any> = {}
+
+  if ('string' == typeof rules) {
+    rules = rules.split(/\s*,\s*/)
+  }
+
+  if (Array.isArray(rules)) {
+    for (const n of rules) {
+      if (null != n && '' !== n) rulemap[n] = {}
+    }
+  }
+  else if (null != rules) {
+    for (const k of Object.keys(rules)) {
+      if (null != rules[k]) rulemap[k] = rules[k]
+    }
+  }
+
+  return rulemap
+}
+
+
+const Directive: Plugin = (tabnas: Tabnas, options: DirectiveOptions) => {
+  let rules = {
+    open: resolveRules(options?.rules?.open),
+    close: resolveRules(options?.rules?.close),
+  }
+
+  let name = options.name
+  let open = options.open
+  let close = options.close
+  let action: StateAction
+  let custom = options.custom
+
+  if ('string' === typeof options.action) {
+    let path = options.action
+    action = (rule: Rule) =>
+      (rule.node = tabnas.util.prop(tabnas.options, path))
+  } else {
+    action = options.action
+  }
+
+  let token: Record<string, string> = {}
+
+  let openTN = '#OD_' + name
+  let closeTN = '#CD_' + name
+
+  let OPEN: Tin = tabnas.fixed(open) as Tin
+  let CLOSE = null == close ? null : tabnas.fixed(close)
+
+  // OPEN must be unique
+  if (null != OPEN) {
+    throw new Error('Directive open token already in use: ' + open)
+  } else {
+    token[openTN] = open
+  }
+
+  // Only create CLOSE if not already defined as a fixed token
+  if (null == CLOSE && null != close) {
+    token[closeTN] = close
+  }
+
+  tabnas.options({
+    fixed: {
+      token,
+    },
+  })
+
+  let CA = tabnas.token.CA
+  OPEN = tabnas.fixed(open) as Tin
+  CLOSE = null == close ? null : tabnas.fixed(close)
+
+  // NOTE: RuleSpec.open|close refers to Rule state, whereas
+  // OPEN|CLOSE refers to opening and closing tokens for the directive.
+
+  // Pre-seed the directive rule's hooks (clear existing alts, set bo/bc).
+  // `grammar()` below will then install the open/close alts with the
+  // `directive` group tag appended via the setting arg.
+  tabnas.rule(name, (rs) =>
+    rs
+      .clear()
+      .bo((rule: Rule) => ((rule.node = {}), undefined))
+      .bc(function(
+        this: RuleSpec,
+        rule: Rule,
+        ctx: Context,
+        next: Rule,
+        tkn?: Token | void,
+      ) {
+        let out = action.call(this, rule, ctx, next, tkn)
+        if (out?.isToken) {
+          return out
+        }
+      }),
+  )
+
+  // Build a declarative grammar spec covering every rule modification
+  // plus the directive rule's own alts.
+  const grammarSpec: any = { rule: {} }
+  const ruleFor = (rn: string) =>
+    (grammarSpec.rule[rn] = grammarSpec.rule[rn] || {})
+
+  Object.entries(rules.open).forEach((entry: any[]) => {
+    const [rulename, rulespec] = entry
+    const openAlts: any[] = []
+    const closeAlts: any[] = []
+    if (null != close) {
+      // More-specific OPEN+CLOSE alt first so it's tried before OPEN alone.
+      openAlts.push({
+        s: [OPEN, CLOSE],
+        b: 1,
+        p: name,
+        n: { ['dr_' + name]: 1 },
+        g: 'start,end',
+      })
+      closeAlts.push({
+        s: [CLOSE],
+        b: 1,
+        g: 'end',
+      })
+    }
+    openAlts.push({
+      s: [OPEN],
+      p: name,
+      n: { ['dr_' + name]: 1 },
+      g: 'start',
+      c: rulespec.c,
+    })
+    const r = ruleFor(rulename)
+    r.open = openAlts
+    if (closeAlts.length) r.close = closeAlts
+  })
+
+  if (null != close) {
+    Object.entries(rules.close).forEach((entry: any[]) => {
+      const [rulename, rulespec] = entry
+      const r = ruleFor(rulename)
+      r.close = [
+        {
+          s: [CLOSE],
+          c: (r: Rule, ctx: Context) =>
+            1 === r.n['dr_' + name] &&
+            (rulespec.c ? rulespec.c(r, ctx) : true),
+          b: 1,
+          g: 'end',
+        },
+        {
+          s: [CA, CLOSE],
+          c: (r: Rule) => 1 === r.n['dr_' + name],
+          b: 1,
+          g: 'end,comma',
+        },
+      ]
+    })
+  }
+
+  const directiveOpenAlts: any[] = []
+  if (null != close) {
+    directiveOpenAlts.push({ s: [CLOSE], b: 1 })
+  }
+  directiveOpenAlts.push({
+    p: 'val',
+    // Only accept implicits when there is a CLOSE token,
+    // otherwise we'll eat all following siblings.
+    n: null == close ? { dlist: 1, dmap: 1 } : { dlist: 0, dmap: 0 },
+  })
+  const dr = ruleFor(name)
+  dr.open = directiveOpenAlts
+  if (null != close) {
+    dr.close = [{ s: [CLOSE] }, { s: [CA, CLOSE] }]
+  }
+
+  tabnas.grammar(grammarSpec, { rule: { alt: { g: 'directive' } } })
+
+  if (custom) {
+    custom(tabnas, { OPEN, CLOSE, name })
+  }
+}
+
+Directive.defaults = {
+  rules: {
+    // By default, directives only operate where vals occur.
+    open: 'val',
+    close: 'list,elem,map,pair',
+  },
+} as DirectiveOptions
+
+export { Directive }
+
+export type { DirectiveOptions }

package/src/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "module": "nodenext",
+    "noEmitOnError": true,
+    "outDir":"../dist",
+    "rootDir":".",
+    "resolveJsonModule": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "es2021",
+    "declaration": true,
+    "declarationDir": "../dist"
+  }
+}