xnl-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 kongweixian
+
+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,67 @@
+# XNL Parser (TypeScript)
+
+Node + browser-friendly parser for the XNL (Extensible Notation Language) format described in `doc/ai-guide/XnlDataFormatIntroduce.md`.
+
+## Install
+
+```bash
+npm install xnl-core
+```
+
+## Usage
+
+```ts
+import { XNL, parseXnl, stringify } from "xnl-core";
+
+// Parse many
+const { nodes, warnings } = XNL.parseMany(`<item a=1 { b = 2 } [ 3 4 ]>`);
+
+// Parse one
+const { node } = XNL.parseSingle(`<text a=1 {b=2} #>hello</#>`);
+
+// Unique children (extend-like)
+const { node: unique } = XNL.parseUnique("root", `<a {x=1}> <a {x=2}> <b>`);
+
+// Stringify (compact by default)
+const compact = stringify({ nodes });
+
+// Pretty stringify
+const pretty = XNL.stringify({ nodes }, { pretty: true, indent: 2 });
+```
+
+## API
+
+- `parseXnl(input: string): XnlDocument` – parse a full XNL string into an AST of nodes plus optional `warnings`.
+- `parseXnlSingleNode(input: string): { node: XnlNode; warnings?: ParseWarning[] }` – parse exactly one node; errors if extra content remains.
+- `parseUniqueChildren(name: string, input: string, metadata?: AttributeMap, attributes?: AttributeMap): { node: XnlNode; warnings?: ParseWarning[] }` – parse multiple sibling elements into a node whose `extend` children overwrite duplicates with a warning.
+- `XNL` namespace: `XNL.parseMany`, `XNL.parseSingle`, `XNL.parseUnique` (wrappers around the above) and `XNL.stringify`.
+- `XNL.stringify(value: XnlDocument | XnlNode, options?)` – serialize a document or node to XNL. Defaults to compact single-line; pass `{ pretty: true, indent: 2 }` (or string indent) for pretty output.
+- AST nodes carry `tag`, `metadata` (inline `key=value`), optional `{}` `attributes`, optional `body` array (`[]` block), optional unique `extend` children (`()` block with warn+overwrite on duplicate tag names), and optional `text`/`textMarker` for `<tag ... #>...</#...>`.
+- `ValueLiteral` is primitive-only (`String`/`Boolean`/`Null`/`Number`). `ObjectValue.entries`, `ArrayValue.items`, `metadata`/`attributes`, and `body` all hold `XnlNode`, so object/array/attribute entries can themselves be elements, values, or comments.
+- Value literals keep numeric kind metadata (`Integer` vs `Float`) while using `number` values in JS/TS.
+- Multiline text blocks dedent like C# triple-quoted strings: drop a leading blank line, then strip the closing tag’s indentation prefix (spaces/tabs) from each line.
+
+### Errors
+
+Errors are thrown as `XnlParseError` with `code`, line/column, and tag/marker context in the message:
+
+- `UNEXPECTED_EOF` – input ended before a structure closed (message names the tag/delimiter).
+- `MISMATCHED_TAG` – closing text marker did not match opener (message shows expected vs found).
+- `DUPLICATE_CHILD` – extend `( ... )` block repeated a child name (later overwrote earlier).
+- `INVALID_CONTENT` – disallowed content for the current body type (e.g., text with `[]`/`()`), message cites parent tag.
+- `INVALID_LITERAL` – malformed or unsupported literal.
+- `UNEXPECTED_TOKEN` – unexpected character while parsing.
+- Warnings (returned, not logged): `DUPLICATE_CHILD` when extend children repeat names (later overwrites earlier).
+
+Example:
+
+```ts
+import { parseXnl, XnlParseError } from "xnl-core";
+
+try {
+  parseXnl("<wrap ( <a> <a> )>");
+} catch (err) {
+  const e = err as XnlParseError;
+  console.error(e.code, e.message); // DUPLICATE_CHILD ...
+}
+```