tjawn 0.0.0-stage → 2.0.0

package/README.md

@@ -1,3 +1,231 @@
-# Temporary Holding Version
+# tjawn <img src="https://github.com/tjkopena/tjawn/raw/main/docs/shark.png" height="50" title="tjawn" alt='Drawing of a shark stabbing out of the water and growling "Rwaa rwaa, rwaa rwaa!" as it tries to eat you.' style="vertical-align: middle" />
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This is an implementation of *jawns*, a human friendly lightweight
+object notation.  A jawn is a Python dict literal or a slight superset
+of JSON but with more flexible formatting. An example:
+
+```
+protocol: 1.0,
+token: 854c37ee-517c-4ba6-b56b-06475ad24041
+conn: {
+    offer= { 'TLS1.2', TLS1.3  "TLS 1.17" }
+    "dns:resolver" = 10.0.0.1
+    cert: """
+        -----BEGIN CERTIFICATE-----
+        MIICUTCCAfugAwIBAgIBADANBgkqhkiG9w0BAQQFADBXMQswCQYDVQQGEwJDTjEL
+        MAkGA1UECBMCUE4xCzAJBgNVBAcTAkNOMQswCQYDVQQKEwJPTjELMAkGA1UECxMC
+        VU4xFDASBgNVBAMTC0hlcm9uZyBZYW5nMB4XDTA1MDcxNTIxMTk0N1oXDTA1MDgx
+            ...
+    """
+}
+```
+
+Which parses to the equivalent of this Python literal:
+```python
+{
+    "protocol": 1.0,
+    "token": "854c37ee-517c-4ba6-b56b-06475ad24041",
+    "conn": {
+        "offer": {"TLS1.2", "TLS1.3",  "TLS 1.17"},
+        "dns:resolver": "10.0.0.1",
+        "cert": """-----BEGIN CERTIFICATE-----
+MIICUTCCAfugAwIBAgIBADANBgkqhkiG9w0BAQQFADBXMQswCQYDVQQGEwJDTjEL
+MAkGA1UECBMCUE4xCzAJBgNVBAcTAkNOMQswCQYDVQQKEwJPTjELMAkGA1UECxMC
+VU4xFDASBgNVBAMTC0hlcm9uZyBZYW5nMB4XDTA1MDcxNTIxMTk0N1oXDTA1MDgx
+    ..."""
+    }
+}
+```
+
+Some features:
+* Strings without whitespace generally do not need to be quoted.
+* Single or double quotes used interchangeably (in matched pairs).
+* Multiline whitespace trimming with relative indentation preservation.
+* Key/value pairs interchangeably denoted by either ':' or '='.
+* Commas largely optional but permitted (e.g., on closing elements).
+* Objects, sets, and lists are delimited by brackets, not whitespace.
+* Sets are supported.
+
+> _"jawn?"_
+
+JSON Alternative Written Notation?\
+Joe's Awesome Wacky ... Notation?\
+[Don't think about it too hard.](https://en.wikipedia.org/wiki/Jawn)
+
+
+> _"But why?"_
+
+I (tjkopena) find it _almost_ convenient to write simple config files
+or parameter sets and so on in JSON.  I don't implement such often
+enough to bother to remember how to format TOML or YAML or whateverML,
+and in any event I dislike their whitespace-based formatting, nesting,
+and other aspects.  I know JSON, use it all the time, I just want to
+write a little object file in it.  But it's _not actually_ convenient
+to do so because JSON is a picky, pedantic pain in the ass---double
+quotes on everything, no trailing commas, blah blah blah GTFO. Hence
+jawns, a similarly simple, straightforward object model and syntax
+that's not too fussed about the details.
+
+
+## jawns
+
+jawns and their closely associated human-friendly text syntax are
+specified in [](docs/jawn.md).  The core description is pretty readable.
+A grammar is in [](src/jawn.g).
+
+In sum: A jawn is a map; its values are recursive collections maps,
+lists, or sets, or primitives strings, numbers, booleans, or null; you
+can write them down without lots of double quotes and without having to
+precisely maintain whitespace.
+
+
+## Implementations
+
+This repository includes several implementations, outlined here.
+
+### Python
+
+#### Setup
+
+tjawn's Python module has no dependencies.  It is [listed in
+PyPi](https://pypi.org/project/tjawn/) and should be includable in
+all the usual ways.
+
+#### Usage
+
+The `loads` and `dumps` functions respectively provide for reading and
+writing jawns from a string.
+
+```
+import tjawn
+
+o = tjawn.loads('a: "Four score and seven..."')
+print(tjawn.dumps(o))
+```
+
+A jawn is a map.  As a convenience, a list of jawns, e.g. a file of
+several records, can be read and written with separate functions:
+
+```
+l = tjawn.loads_list('[ {name: alice} {name: bob} ]')
+print(tjawn.dumps_list(l))
+```
+
+The `loadf`, `dumpf`, `loadf_list`, and `dumpf_list` functions do the
+same for UTF-8 files named by a filename parameter:
+
+```
+tjawn.dumpf(o, 'config.jawn')
+o = tjawn.loadf('config.jawn')
+```
+
+#### Development Notes
+
+Internally, tjawn's Python module is implemented using Lark to
+generate the lexer and parser, which are then vendored in the project
+rather than incurring a dependency.  From the `src/py` directory:
+
+```bash
+poetry install --no-root   # install pytest and lark for development
+make parser                # regenerate tjawn/lark_parser.py from src/jawn.g
+make test                  # run the tests
+make build                 # build the package, including this README
+```
+
+The tests check that the vendored parser matches `src/jawn.g`.
+
+### TypeScript
+
+#### Setup
+
+tjawn's TypeScript package, in `src/ts`, has no runtime dependencies.
+It is an ES module with type declarations.  Parsing and serializing
+work in any ES2022 environment, including browsers; the file functions
+require Node.js 20.16 or later.
+
+#### Usage
+
+The `parse` and `stringify` functions respectively provide for reading
+and writing jawns from a string, as `JSON.parse` and `JSON.stringify`
+do for JSON.
+
+```
+import * as tjawn from 'tjawn';
+
+const o = tjawn.parse('a: "Four score and seven..."');
+console.log(tjawn.stringify(o));
+```
+
+Maps are parsed to plain objects and lists to arrays.  Sets are parsed
+to `JawnSet`s, which compare their elements by value, e.g. `{ {a: 1} }`
+holds one map that `has({ a: 1 })`, and keep `true` distinct from `1`.
+Numbers are JavaScript numbers, so `1.0` is read as `1` and written that
+way.  `jawnEquals` compares two values as jawns.
+
+`stringify` writes objects, `Map`s, arrays, `JawnSet`s, and `Set`s.
+Class instances are written as maps of their own enumerable properties
+not starting with `_`, and properties whose value is `undefined` are
+skipped.  Options `indent` and `eoln` set the indentation and
+linebreak; with an empty `eoln` all is written on one line.
+
+A jawn is a map.  As a convenience, a list of jawns, e.g. a file of
+several records, can be read and written with separate functions:
+
+```
+const l = tjawn.parseList('[ {name: alice} {name: bob} ]');
+console.log(tjawn.stringifyList(l));
+```
+
+The `loadFile`, `dumpFile`, `loadFileList`, and `dumpFileList`
+functions do the same for UTF-8 files named by a path or file URL:
+
+```
+tjawn.dumpFile(o, 'config.jawn');
+const o = tjawn.loadFile('config.jawn');
+```
+
+Errors are thrown as `JawnError`, or its subclass `JawnTypeError` for
+values that can't be written as jawns.
+
+#### Development Notes
+
+The parser is written by hand, with a contextual lexer whose terminals
+are transcribed from `src/jawn.g` and that mirrors Lark's, so that it
+accepts exactly what the Python module does and reports errors the
+same way.  From the `src/ts` directory:
+
+```bash
+npm install         # install TypeScript and Vitest for development
+npm test            # run the tests
+npm run typecheck   # check types, including the tests'
+npm run build       # build the package into dist
+npm pack            # package it, including this README
+```
+
+The tests check that the lexer's terminals match `src/jawn.g`.
+
+
+## License
+
+tjawn is released under MIT-0:
+
+> Copyright 2023, 2026 tjkopena
+>
+> 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.
+>
+> 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.
+
+[Shark icon](https://thenounproject.com/icon/shark-1257563/) by Luis
+Prado for The Noun Project, CCBY3.0.

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+/** Thrown for text that isn't a valid jawn, or data that can't be one. */
+export declare class JawnError extends Error {
+    constructor(message: string);
+}
+/** Thrown for data of a type that can't be a jawn value. */
+export declare class JawnTypeError extends JawnError {
+}

package/dist/errors.js

@@ -0,0 +1,10 @@
+/** Thrown for text that isn't a valid jawn, or data that can't be one. */
+export class JawnError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** Thrown for data of a type that can't be a jawn value. */
+export class JawnTypeError extends JawnError {
+}

package/dist/files.d.ts

@@ -0,0 +1,10 @@
+import { StringifyOptions } from './serializer.js';
+import type { Jawn } from './types.js';
+/** Parse a jawn from a UTF-8 file. */
+export declare function loadFile(path: string | URL): Jawn;
+/** Parse a list of jawns from a UTF-8 file. */
+export declare function loadFileList(path: string | URL): Jawn[];
+/** Serialize a jawn to a UTF-8 file, ending with a linebreak. */
+export declare function dumpFile(o: unknown, path: string | URL, options?: StringifyOptions): void;
+/** Serialize a list of jawns to a UTF-8 file, ending with a linebreak. */
+export declare function dumpFileList(o: unknown, path: string | URL, options?: StringifyOptions): void;

package/dist/files.js

@@ -0,0 +1,52 @@
+import { JawnError } from './errors.js';
+import { parse, parseList } from './parser.js';
+import { stringify, stringifyList } from './serializer.js';
+// Node's modules are obtained when called rather than imported, so that
+// the rest of the package works where they're absent, e.g. browsers.
+function node() {
+    const getBuiltinModule = globalThis.process?.getBuiltinModule;
+    if (!getBuiltinModule) {
+        throw new Error('Reading and writing jawn files requires Node.js 20.16 or later');
+    }
+    return {
+        fs: getBuiltinModule('node:fs'),
+        url: getBuiltinModule('node:url'),
+    };
+}
+/** Parse a jawn from a UTF-8 file. */
+export function loadFile(path) {
+    return load(parse, path);
+}
+/** Parse a list of jawns from a UTF-8 file. */
+export function loadFileList(path) {
+    return load(parseList, path);
+}
+function load(f, path) {
+    // Linebreaks are read untranslated, as the parser handles them, and
+    // errors name the file.
+    const { fs, url } = node();
+    const text = fs.readFileSync(path, 'utf8');
+    try {
+        return f(text);
+    }
+    catch (e) {
+        if (e instanceof JawnError) {
+            const name = path instanceof URL ? url.fileURLToPath(path) : path;
+            throw new JawnError(`${name}: ${e.message}`);
+        }
+        throw e;
+    }
+}
+/** Serialize a jawn to a UTF-8 file, ending with a linebreak. */
+export function dumpFile(o, path, options = {}) {
+    dump(stringify(o, options), path, options);
+}
+/** Serialize a list of jawns to a UTF-8 file, ending with a linebreak. */
+export function dumpFileList(o, path, options = {}) {
+    dump(stringifyList(o, options), path, options);
+}
+function dump(s, path, options) {
+    // The text is serialized before the file is opened so that an error
+    // leaves any existing file untouched.
+    node().fs.writeFileSync(path, s + (options.eoln || '\n'), 'utf8');
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { JawnError, JawnTypeError } from './errors.js';
+export { JawnSet, jawnEquals } from './jawnset.js';
+export { parse, parseList } from './parser.js';
+export { stringify, stringifyList } from './serializer.js';
+export type { StringifyOptions } from './serializer.js';
+export { loadFile, loadFileList, dumpFile, dumpFileList } from './files.js';
+export type { Jawn, JawnMap, JawnPrimitive, JawnValue } from './types.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { JawnError, JawnTypeError } from './errors.js';
+export { JawnSet, jawnEquals } from './jawnset.js';
+export { parse, parseList } from './parser.js';
+export { stringify, stringifyList } from './serializer.js';
+export { loadFile, loadFileList, dumpFile, dumpFileList } from './files.js';

package/dist/jawnset.d.ts

@@ -0,0 +1,55 @@
+import type { JawnValue } from './types.js';
+/**
+ * The canonical form of a jawn value, a string that's equal for two
+ * values exactly when they're equal as jawns: maps and sets compare
+ * regardless of order, numbers by value (so -0 is 0), and booleans are
+ * distinct from numbers.  Throws a JawnError for a value that can't be a
+ * jawn value.
+ */
+export declare function jawnKey(v: unknown): string;
+/** Whether two values are equal as jawn values; false if either isn't one. */
+export declare function jawnEquals(a: unknown, b: unknown): boolean;
+/**
+ * A set of jawn values compared by value and type.
+ *
+ * Unlike the builtin Set, elements are compared by their content rather
+ * than identity, so maps and lists may be elements, and booleans are
+ * distinct from numbers.  Elements are compared by their content when
+ * added, so mutating one afterwards leaves the set inconsistent.  Methods
+ * taking another collection compare by jawn value too, e.g.
+ * `new JawnSet([true]).isSubsetOf(new Set([1]))` is false.
+ */
+export declare class JawnSet<T = JawnValue> implements Iterable<T> {
+    private items;
+    constructor(items?: Iterable<T> | null);
+    get size(): number;
+    get [Symbol.toStringTag](): string;
+    /** Adds an element, which must be a jawn value. */
+    add(x: T): this;
+    /** Like an absent element, a non-jawn value is simply not present. */
+    has(x: unknown): boolean;
+    delete(x: unknown): boolean;
+    clear(): void;
+    values(): IterableIterator<T>;
+    keys(): IterableIterator<T>;
+    entries(): IterableIterator<[T, T]>;
+    [Symbol.iterator](): IterableIterator<T>;
+    forEach(f: (value: T, value2: T, set: this) => void, thisArg?: unknown): void;
+    copy(): JawnSet<T>;
+    /** Whether other is a set with the same elements, compared as jawns. */
+    equals(other: unknown): boolean;
+    union<U>(...others: Iterable<U>[]): JawnSet<T | U>;
+    intersection(...others: Iterable<unknown>[]): JawnSet<T>;
+    difference(...others: Iterable<unknown>[]): JawnSet<T>;
+    symmetricDifference<U>(other: Iterable<U>): JawnSet<T | U>;
+    isSubsetOf(other: Iterable<unknown>): boolean;
+    isSupersetOf(other: Iterable<unknown>): boolean;
+    isDisjointFrom(other: Iterable<unknown>): boolean;
+    update(...others: Iterable<T>[]): this;
+    intersectionUpdate(...others: Iterable<unknown>[]): this;
+    differenceUpdate(...others: Iterable<unknown>[]): this;
+    symmetricDifferenceUpdate(other: Iterable<T>): this;
+    private within;
+    /** The elements as an array, so that JSON.stringify writes sets as lists. */
+    toJSON(): T[];
+}

package/dist/jawnset.js

@@ -0,0 +1,250 @@
+import { JawnError, JawnTypeError } from './errors.js';
+import { classify, mapEntries, nested, toNumber, typeName } from './values.js';
+/**
+ * The canonical form of a jawn value, a string that's equal for two
+ * values exactly when they're equal as jawns: maps and sets compare
+ * regardless of order, numbers by value (so -0 is 0), and booleans are
+ * distinct from numbers.  Throws a JawnError for a value that can't be a
+ * jawn value.
+ */
+export function jawnKey(v) {
+    return key(v, new Set());
+}
+function key(v, stack) {
+    switch (classify(v)) {
+        case 'null':
+            return 'z';
+        case 'boolean':
+            return v ? 't' : 'f';
+        case 'number': {
+            const n = toNumber(v);
+            return 'n' + (n === 0 ? '0' : String(n));
+        }
+        case 'string':
+            return 's' + JSON.stringify(v);
+        case 'list':
+            return nested(v, stack, () => '[' + Array.from(v, (x) => key(x, stack)).join(',') + ']');
+        case 'set':
+            if (v instanceof JawnSet) {
+                return '<' + [...v.keys_()].sort().join(',') + '>';
+            }
+            return nested(v, stack, () => '<' + [...new Set(Array.from(v, (x) => key(x, stack)))].sort().join(',') + '>');
+        case 'map':
+            return nested(v, stack, () => '{' + mapEntries(v).map(([k, x]) => JSON.stringify(k) + ':' + key(x, stack))
+                .sort().join(',') + '}');
+    }
+    throw new JawnTypeError(`Not a jawn value: ${typeName(v)}`);
+}
+/** Whether two values are equal as jawn values; false if either isn't one. */
+export function jawnEquals(a, b) {
+    try {
+        return jawnKey(a) === jawnKey(b);
+    }
+    catch (e) {
+        if (e instanceof JawnError) {
+            return false;
+        }
+        throw e;
+    }
+}
+// Canonical forms of another collection's elements, for comparing by jawn
+// rather than JavaScript equality.  A non-jawn element gets a form of its
+// own that equals no other; canonical forms never begin with \0.
+let unique = 0;
+function keysOf(o) {
+    if (o instanceof JawnSet) {
+        return new Set(o.keys_());
+    }
+    const ks = new Set();
+    for (const x of o) {
+        try {
+            ks.add(jawnKey(x));
+        }
+        catch (e) {
+            if (!(e instanceof JawnError)) {
+                throw e;
+            }
+            ks.add(`\0${unique++}`);
+        }
+    }
+    return ks;
+}
+/**
+ * A set of jawn values compared by value and type.
+ *
+ * Unlike the builtin Set, elements are compared by their content rather
+ * than identity, so maps and lists may be elements, and booleans are
+ * distinct from numbers.  Elements are compared by their content when
+ * added, so mutating one afterwards leaves the set inconsistent.  Methods
+ * taking another collection compare by jawn value too, e.g.
+ * `new JawnSet([true]).isSubsetOf(new Set([1]))` is false.
+ */
+export class JawnSet {
+    items = new Map();
+    constructor(items) {
+        if (items) {
+            for (const x of items) {
+                this.add(x);
+            }
+        }
+    }
+    /** @internal The canonical forms of the elements. */
+    keys_() {
+        return this.items.keys();
+    }
+    get size() {
+        return this.items.size;
+    }
+    get [Symbol.toStringTag]() {
+        return 'JawnSet';
+    }
+    /** Adds an element, which must be a jawn value. */
+    add(x) {
+        const k = jawnKey(x);
+        if (!this.items.has(k)) {
+            this.items.set(k, x);
+        }
+        return this;
+    }
+    /** Like an absent element, a non-jawn value is simply not present. */
+    has(x) {
+        const k = tryKey(x);
+        return k !== undefined && this.items.has(k);
+    }
+    delete(x) {
+        const k = tryKey(x);
+        return k !== undefined && this.items.delete(k);
+    }
+    clear() {
+        this.items.clear();
+    }
+    values() {
+        return this.items.values();
+    }
+    keys() {
+        return this.items.values();
+    }
+    *entries() {
+        for (const x of this.items.values()) {
+            yield [x, x];
+        }
+    }
+    [Symbol.iterator]() {
+        return this.items.values();
+    }
+    forEach(f, thisArg) {
+        for (const x of this.items.values()) {
+            f.call(thisArg, x, x, this);
+        }
+    }
+    copy() {
+        return new JawnSet(this);
+    }
+    /** Whether other is a set with the same elements, compared as jawns. */
+    equals(other) {
+        if (!(other instanceof JawnSet || other instanceof Set)) {
+            return false;
+        }
+        const ks = keysOf(other);
+        return ks.size === this.items.size && this.within(ks);
+    }
+    // Set operations, named as the builtin Set's, which accept any
+    // iterables and return new sets.
+    union(...others) {
+        const r = new JawnSet(this);
+        return r.update(...others);
+    }
+    intersection(...others) {
+        return this.copy().intersectionUpdate(...others);
+    }
+    difference(...others) {
+        return this.copy().differenceUpdate(...others);
+    }
+    symmetricDifference(other) {
+        return new JawnSet(this).symmetricDifferenceUpdate(other);
+    }
+    isSubsetOf(other) {
+        return this.within(keysOf(other));
+    }
+    isSupersetOf(other) {
+        for (const k of keysOf(other)) {
+            if (!this.items.has(k)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    isDisjointFrom(other) {
+        for (const k of keysOf(other)) {
+            if (this.items.has(k)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    // In-place counterparts, which return this set.
+    update(...others) {
+        for (const o of others) {
+            for (const x of o) {
+                this.add(x);
+            }
+        }
+        return this;
+    }
+    intersectionUpdate(...others) {
+        for (const o of others) {
+            const keep = keysOf(o);
+            for (const k of [...this.items.keys()]) {
+                if (!keep.has(k)) {
+                    this.items.delete(k);
+                }
+            }
+        }
+        return this;
+    }
+    differenceUpdate(...others) {
+        for (const o of others) {
+            for (const x of o) {
+                this.delete(x);
+            }
+        }
+        return this;
+    }
+    symmetricDifferenceUpdate(other) {
+        for (const x of new JawnSet(other)) {
+            if (this.has(x)) {
+                this.delete(x);
+            }
+            else {
+                this.add(x);
+            }
+        }
+        return this;
+    }
+    within(ks) {
+        for (const k of this.items.keys()) {
+            if (!ks.has(k)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /** The elements as an array, so that JSON.stringify writes sets as lists. */
+    toJSON() {
+        return [...this.items.values()];
+    }
+    [Symbol.for('nodejs.util.inspect.custom')](_depth, options, inspect) {
+        return `JawnSet(${inspect([...this.items.values()], options)})`;
+    }
+}
+function tryKey(x) {
+    try {
+        return jawnKey(x);
+    }
+    catch (e) {
+        if (e instanceof JawnError) {
+            return undefined;
+        }
+        throw e;
+    }
+}