@thi.ng/sax 2.2.62 → 2.3.1

package/README.md

@@ -35,7 +35,7 @@
 [@thi.ng/transducers](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers)-based,
 [SAX](https://en.wikipedia.org/wiki/Simple_API_for_XML)-like,
 non-validating, [configurable](#parser-options), speedy & tiny XML
-parser (~1.8KB gzipped).
+parser (~1.4KB brotli).
 
 Unlike the classic event-driven approach of SAX, this parser is
 implemented as a transducer function, transforming an XML input into a
@@ -88,7 +88,7 @@ For Node.js REPL:
 const sax = await import("@thi.ng/sax");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.41 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.65 KB
 
 ## Dependencies
 
@@ -132,12 +132,12 @@ src=`<?xml version="1.0" encoding="utf-8"?>
     <b2 foo="bar" />
 </a>`
 
-// sax.parse() returns a transducer
-doc = [...tx.iterator(sax.parse(), src)]
-
-// ...or returns iterator if input is given
+// sax.parse() returns iterator if input is given
 doc = [...sax.parse(src)]
 
+// ...or returns a transducer to be used with thi.ng/transducers
+doc = [...tx.iterator(sax.parse(), src)]
+
 // (see description of `type` values and parse options further below)
 
 // [ { type: 0,
@@ -188,11 +188,8 @@ first `<g>` element is complete. This is because the `matchFirst()`
 transducer will cause early termination once that element has been
 processed.
 
-```ts
-import { parse, Type } from "@thi.ng/sax";
-import * as tx from "@thi.ng/transducers";
-
-svg=`
+```ts id:svgdoc
+const svg = `
 <?xml version="1.0"?>
 <svg version="1.1" height="300" width="300" xmlns="http://www.w3.org/2000/svg">
     <g fill="yellow">
@@ -206,27 +203,37 @@ svg=`
         <circle cx="150.00" cy="150.00" r="25.00" />
     </g>
 </svg>`;
+```
 
-[...tx.iterator(
-    tx.comp(
-        // transform into parse events (see parser options below)
-        parse({ children: true }),
-        // match 1st group end
-        tx.matchFirst((e) => e.type == Type.ELEM_END && e.tag == "g"),
-        // extract group's children
-        tx.mapcat((e) => e.children),
-        // select circles only
-        tx.filter((e) => e.tag == "circle"),
-        // transform attributes
-        tx.map((e)=> [e.tag, {
-            ...e.attribs,
-            cx: parseFloat(e.attribs.cx),
-            cy: parseFloat(e.attribs.cy),
-            r:  parseFloat(e.attribs.r),
-        }])
-    ),
-    svg
-)]
+```ts tangle:export/readme-parse-svg.ts
+import { parse, Type } from "@thi.ng/sax";
+import * as tx from "@thi.ng/transducers";
+
+// using the SVG example doc defined above
+<<svgdoc>>
+
+console.log(
+    [...tx.iterator(
+        tx.comp(
+            // transform into parse events (see parser options below)
+            parse({ children: true }),
+            // match 1st group end
+            tx.matchFirst((e) => e.type == Type.ELEM_END && e.tag == "g"),
+            // extract group's children
+            tx.mapcat((e) => e.children),
+            // select circles only
+            tx.filter((e) => e.tag == "circle"),
+            // transform attributes
+            tx.map((e)=> [e.tag, {
+                ...e.attribs,
+                cx: parseFloat(e.attribs.cx),
+                cy: parseFloat(e.attribs.cy),
+                r:  parseFloat(e.attribs.r),
+            }])
+        ),
+        svg
+    )]
+);
 // [ [ 'circle', { cx: 50, cy: 150, r: 50 } ],
 //   [ 'circle', { cx: 250, cy: 150, r: 50 } ],
 //   [ 'circle', { cx: 150, cy: 150, fill: 'rgba(0,255,255,0.25)', r: 100, stroke: '#ff0000' } ] ]
@@ -238,22 +245,25 @@ This example shows how SVG can be parsed into
 [@thi.ng/hiccup](https://github.com/thi-ng/umbrella/tree/develop/packages/hiccup)
 format.
 
-```ts
+```ts tangle:export/readme-parse-elements.ts
 import { defmulti, DEFAULT } from "@thi.ng/defmulti";
-import { parse } from "@thi.ng/sax";
+import { parse, type ParseElement } from "@thi.ng/sax";
 import * as tx from "@thi.ng/transducers";
 
+// using the SVG example doc defined above
+<<svgdoc>>
+
 // coerces given attribute IDs into numeric values and
 // keeps all other attribs
-const numericAttribs = (e, ...ids: string[]) =>
+const numericAttribs = (e: ParseElement, ...ids: string[]) =>
     ids.reduce(
         (acc, id) => (acc[id] = parseFloat(e.attribs[id]), acc),
-        { ...e.attribs }
+        <Record<string,any>>{ ...e.attribs }
     );
 
 // returns iterator of parsed & filtered children of given element
 // (iterator is used to avoid extraneous copying at call sites)
-const parsedChildren = (e) =>
+const parsedChildren = (e: ParseElement) =>
     tx.iterator(
         tx.comp(
             tx.map(parseElement),
@@ -281,11 +291,13 @@ parseElement.add("svg", (e) =>
 // implementation for unhandled elements
 parseElement.add(DEFAULT, () => null);
 
-// using the same SVG source as in previous example:
+// finally parse & transform results:
 // the `last()` reducer just returns the ultimate value
 // which in this case is the SVG root element's ELEM_END parse event
 // this also contains all children (by default)
-parseElement(tx.transduce(parse(), tx.last(), svg));
+console.log(
+    parseElement(tx.transduce(parse(), tx.last(), svg))
+);
 
 // ["svg",
 //     {
@@ -327,14 +339,14 @@ If the parser encounters a syntax error, an error event value incl. a
 description and input position will be produced (but no JS error will be
 thrown) and the entire transducer pipeline stopped.
 
-```ts
+```ts tangle:export/readme-error-handling.ts
 import { parse } from "@thi.ng/sax";
 import { iterator } from "@thi.ng/transducers";
 
-[...iterator(parse(), `a`)]
+console.log([...iterator(parse(), `a`)]);
 // [ { type: 7, body: 'unexpected char: \'a\' @ pos 1' } ]
 
-[...iterator(parse(), `<a><b></c></a>`)]
+console.log([...iterator(parse(), `<a><b></c></a>`)]);
 // [ { type: 4, tag: 'a', attribs: {} },
 //   { type: 4, tag: 'b', attribs: {} },
 //   { type: 7, body: 'unmatched tag: c @ pos 7' } ]

package/index.d.ts

@@ -84,4 +84,40 @@ export declare enum Type {
 export declare function parse(opts?: Partial<ParseOpts>): Transducer<string, ParseEvent>;
 export declare function parse(src: string): IterableIterator<ParseEvent>;
 export declare function parse(opts: Partial<ParseOpts>, src: string): IterableIterator<ParseEvent>;
+/**
+ * Convenience helper for certain applications of {@link parse} to produce a
+ * tree of the parsed document.
+ *
+ * @remarks
+ * This functions always enables the {@link ParseOpts.children} option, only
+ * keeps {@link Type.ELEM_END} events and only returns the last one, i.e that of
+ * the root element (including all children).
+ *
+ * Also see {@link parseAsHiccup}.
+ *
+ * @param src
+ * @param opts
+ */
+export declare const parseAsTree: (src: string, opts?: Partial<ParseOpts>) => ParseEvent;
+/**
+ * Convenience helper for certain applications of {@link parse} to produce a
+ * tree of the parsed document in thi.ng/hiccup format.
+ *
+ * @remarks
+ * Uses {@link parseAsTree} and then transforms result.
+ *
+ * @example
+ * ```ts tangle:../export/parse-as-hiccup.ts
+ * import { parseAsHiccup } from "@thi.ng/sax";
+ *
+ * const doc = `<svg><g id="foo"><circle x="0" y="0" r="100"/></g></svg>`;
+ *
+ * console.log(parseAsHiccup(doc));
+ * // ["svg", {}, ["g", { id: "foo" }, ["circle", { x: "0", y: "0", r: "100" }]]]
+ * ```
+ *
+ * @param src
+ * @param opts
+ */
+export declare const parseAsHiccup: (src: string, opts?: Partial<ParseOpts>) => [string, IObjectOf<string>, ...any[]];
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,6 +1,10 @@
 import { NO_OP } from "@thi.ng/api/api";
 import { unescapeEntities } from "@thi.ng/strings/entities";
 import { ESCAPES } from "@thi.ng/strings/escape";
+import { transduce } from "@thi.ng/transducers/transduce";
+import { comp } from "@thi.ng/transducers/comp";
+import { filter } from "@thi.ng/transducers/filter";
+import { last } from "@thi.ng/transducers/last";
 import { fsm } from "@thi.ng/transducers-fsm";
 import { __iter, iterator } from "@thi.ng/transducers/iterator";
 const VOID_TAGS = new Set(
@@ -61,6 +65,20 @@ function parse(...args) {
     terminate: 1 /* ERROR */
   });
 }
+const parseAsTree = (src, opts) => transduce(
+  comp(
+    parse({ ...opts, children: true }),
+    filter((x) => x.type === 5 /* ELEM_END */)
+  ),
+  last(),
+  src
+);
+const parseAsHiccup = (src, opts) => __toHiccup(parseAsTree(src, opts));
+const __toHiccup = (root) => [
+  root.tag,
+  root.attribs ?? {},
+  ...root.children?.length ? root.children.map(__toHiccup) : root.body ? [root.body] : []
+];
 const __isWS = (x) => {
   const c = x.charCodeAt(0);
   return c === 32 || // space
@@ -70,12 +88,14 @@ const __isWS = (x) => {
 };
 const __isTagChar = (x) => {
   const c = x.charCodeAt(0);
-  return c >= 65 && c <= 90 || // A-Z
-  c >= 97 && c <= 122 || // a-z
+  return c >= 97 && c <= 122 || // a-z
   c >= 48 && c <= 57 || // 0-9
-  c == 45 || // -
-  c == 95 || // _
-  c == 58;
+  c >= 65 && c <= 90 || // A-Z
+  c === 58 || // :
+  c === 45 || // -
+  c === 95 || // _
+  c === 46 || // .
+  c === 183 || c >= 192 && c <= 214 || c >= 248 && c <= 767 || c >= 768 && c <= 879 || c >= 880 && c <= 893 || c >= 895 && c <= 8191 || c >= 895 && c <= 8191 || c === 8204 || c === 8205 || c === 8255 || c === 8256 || c >= 8304 && c <= 8591 || c >= 11264 && c <= 12271 || c >= 12289 && c <= 55295 || c >= 63744 && c <= 64975 || c >= 65008 && c <= 65533;
 };
 const __error = (s, body) => {
   s.state = 1 /* ERROR */;
@@ -411,5 +431,7 @@ const __beginElementBody = (state) => {
 export {
   Type,
   VOID_TAGS,
-  parse
+  parse,
+  parseAsHiccup,
+  parseAsTree
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@thi.ng/sax",
-	"version": "2.2.62",
+	"version": "2.3.1",
 	"description": "Transducer-based, SAX-like, non-validating, speedy & tiny XML parser",
 	"type": "module",
 	"module": "./index.js",
@@ -39,13 +39,13 @@
 		"tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
 	},
 	"dependencies": {
-		"@thi.ng/api": "^8.12.7",
-		"@thi.ng/strings": "^3.9.27",
-		"@thi.ng/transducers": "^9.6.15",
-		"@thi.ng/transducers-fsm": "^2.2.148"
+		"@thi.ng/api": "^8.12.8",
+		"@thi.ng/strings": "^3.9.29",
+		"@thi.ng/transducers": "^9.6.17",
+		"@thi.ng/transducers-fsm": "^2.2.150"
 	},
 	"devDependencies": {
-		"esbuild": "^0.25.11",
+		"esbuild": "^0.27.0",
 		"typedoc": "^0.28.14",
 		"typescript": "^5.9.3"
 	},
@@ -82,5 +82,5 @@
 		],
 		"year": 2018
 	},
-	"gitHead": "d977f819bcafdcb2b24c45f8d01a167fe29fc85a\n"
+	"gitHead": "be6e7657b1e5c54d7d648d1b52888a7297e95a17\n"
 }