### Install @bgotink/kdl

Source: https://github.com/bgotink/kdl/blob/main/README.md

Install the package using your preferred package manager.

```sh
yarn add @bgotink/kdl
# or
npm install @bgotink/kdl
# or
pnpm add @bgotink/kdl
# or ...
```

--------------------------------

### Enable Experimental Suffixed Numbers

Source: https://github.com/bgotink/kdl/blob/main/documentation/src/api/parse.md

Demonstrates enabling the `experimentalSuffixedNumbers` flag to allow numbers with suffix tags. This example shows how to use the `flags` option in the `parse` function. It also shows how an invalid suffixed number would throw an error without the flag.

```javascript
import {parse} from "@bgotink/kdl";

assert.throws(() => parse("node 10px"));

assert.doesNotThrow(() =>
	parse("node 10px", {
		flags: {
			experimentalSuffixedNumbers: true,
		},
	}),
);
```

--------------------------------

### Parse KDL and Get Node Argument

Source: https://github.com/bgotink/kdl/blob/main/documentation/src/README.md

Use the `kdl` export to parse a KDL string and retrieve a specific node's argument. Ensure the `kdl` object is available in the browser's console.

```javascript
console.log(kdl.parse("node arg").findNodeByName("node").getArgument(0));
```

--------------------------------

### Parse and Format KDL Document

Source: https://github.com/bgotink/kdl/blob/main/README.md

Parses a KDL document and demonstrates format-preserving modifications by adding a child node. Assumes a Node.js environment for 'assert'.

```js
import {parse, format} from "@bgotink/kdl";
import assert from "node:assert/strict";

const doc = parse(String.raw`
	node "value" #"other value"# 2.0 4 #false \
			#null -0 {
		child; "child too"
	}
`);

doc.nodes[0].children.nodes[0].entries.push(
	parse(
		String.raw`/-lorem="ipsum" \
			dolor=#true`,
		{as: "entry"},
	),
);

assert.equal(
	format(doc),
	String.raw`
	node "value" #"other value"# 2.0 4 #false \
			#null -0 {
		child /-lorem="ipsum" \
			dolor=#true; "child too"
	}
`,
);

```

--------------------------------

### Deserialize KDL Document with Custom Context

Source: https://github.com/bgotink/kdl/blob/main/README.md

Parses a KDL document using the '@bgotink/kdl/dessert' module and a custom context function to structure the data into package information. Assumes a Node.js environment for 'assert'.

```js
import {parse} from "@bgotink/kdl/dessert";
import assert from "node:assert/strict";

assert.deepEqual(
	parse(
		String.raw`
			name "my-package"
			
			dependency "@bgotink/kdl" range="^0.2.0"
			dependency "prettier" range="^3" dev=#true
		`,
		(ctx) => {
			const dependencies = {};
			const devDependencies = {};

			const name = ctx.child.single.required("name", (ctx) =>
				ctx.argument.required("string")
			);

			for (const dependency of ctx.children("dependency", (ctx) => ({
				name: ctx.argument.required("string"),
				range: ctx.property("range", "string") ?? "*",
				dev: ctx.property("dev", "boolean") ?? false,
			})))
			{
				(dependency.dev ? devDependencies : dependencies)[dependency.name] = 
					dependency.range;
			}

			return {name, dependencies, devDependencies};
		},
	),
	{
		name: "my-package",
		dependencies: {
			"@bgotink/kdl": "^0.2.0",
		},
		devDependencies: {
			prettier: "^3",
		},
	},
);

```

--------------------------------

### Manipulating Representation for Formatting

Source: https://github.com/bgotink/kdl/blob/main/documentation/src/api/format.md

Demonstrates how to manually set the `representation` property on KDL DOM elements like `Node`, `Entry`, `Value`, and `Identifier`. Note that this approach is discouraged for actual use.

```javascript
// Do not do this!
import {Entry, Identifier, Node, Value, format} from "@bgotink/kdl";

const node = new Node(new Identifier("real_name"));
node.name.representation = "fake_name";

const entry = new Entry(new Value(42), new Identifier("property"));
entry.name.representation = "something_else";
entry.value.representation = "false";

assert.equal(format(node), "fake_name something_else=false");

```

--------------------------------

### Parse JSON-in-KDL (JiK)

Source: https://github.com/bgotink/kdl/blob/main/README.md

Parses a KDL document formatted as JSON-in-KDL (JiK) into a JavaScript object. Assumes a Node.js environment for 'assert'.

```js
import {parse} from "@bgotink/kdl/json";
import assert from "node:assert/strict";

assert.deepEqual(
	parse(
		String.raw`
			- {
				prop #false
				otherProp {
					- 0
					- 2
					- 4
				}
			}
		`,
	),
	{
		prop: false,
		otherProp: [0, 2, 4],
	},
);

```

--------------------------------

### Parse KDL Document or Node

Source: https://github.com/bgotink/kdl/blob/main/documentation/src/api/parse.md

Use the `parse` function to parse a KDL document or a specific KDL node. The `as` option can be set to 'node' to parse the input as a single node.

```javascript
import {parse, Document, Node} from "@bgotink/kdl";

assert(
	parse(
		String.raw`
			node Lorem Ipsum
		`,
	)
	instanceof Document,
);

assert(
	parse(
		String.raw`
			node Lorem Ipsum
		`,
		{as: "node"},
	)
	instanceof Node,
);
```

--------------------------------

### Serialize KDL Tree using a Class Method

Source: https://github.com/bgotink/kdl/blob/main/documentation/src/api/dessert.md

This approach extends the `Tree` class with a `serialize` method to convert the tree object into KDL. It writes the value as an argument and handles optional left and right children.

```typescript
class Tree {
	// ... see the Tree class in the deserialize example

	serialize(ctx: SerializationContext) {
		ctx.argument(this.value);

		if (this.left) {
			ctx.child("left", this.left);
		}
		if (this.right) {
			ctx.child("right", this.right);
		}
	}
}

export function writeTree(tree: Tree): Node {
	return serialize("root", tree);
}
```

--------------------------------

### Preserving Comments in KDL Serialization

Source: https://github.com/bgotink/kdl/blob/main/documentation/src/api/dessert.md

Store the `DeserializationContext` and call `ctx.source()` before other serialization calls to preserve comments and formatting.

```typescript
class Tree {
	// ... see the Tree class in the deserialize and serialize examples

	// We store the DeserializationContext
	static deserialize(ctx: DeserializationContxt) {
		const tree = new Tree(
			ctx.argument.required("number"),
			ctx.child.single("left", Tree),
			ctx.child.single("right", Tree),
		);
		tree.#deserializationCtx = ctx;
		return tree;
	}

	#deserializationCtx?: DeserializationContxt;

	// ...

	serialize(ctx: SerializationContext) {
		ctx.source(this.#deserializationCtx);

		// keep the rest of the original serialize function here
	}
}
```

--------------------------------

### Serialize KDL Tree using Functions

Source: https://github.com/bgotink/kdl/blob/main/documentation/src/api/dessert.md

This function serializer converts a tree structure back into KDL. It writes the node's value as an argument and recursively serializes 'left' and 'right' children if they exist.

```typescript
function treeSerializer(ctx: SerializationContext, tree: Tree) {
	ctx.argument(tree.value);

	if (tree.left) {
		ctx.child("left", treeSerializer, tree.left);
	}
	if (tree.right) {
		ctx.child("right", treeSerializer, tree.right);
	}
}

export function writeTree(tree: Tree): Node {
	return serialize("root", treeDeserializer, tree);
}
```

--------------------------------

### Format KDL Document with Modifications

Source: https://github.com/bgotink/kdl/blob/main/documentation/src/api/format.md

Parses a KDL string, modifies a node's children by adding a new entry, and then formats the entire document back into a KDL string, preserving original formatting where possible.

```javascript
import {parse, format} from "@bgotink/kdl";

const doc = parse(
	String.raw`
		node "value" #"other value"# 2.0 4 #false \
				#null -0 {
			child; "child too"
		}
	`,
);

doc.nodes[0].children.nodes[0].entries.push(
	parse(
		String.raw`/-lorem="ipsum" \
				dolor=#true`,
		{as: "entry"},
	),
);

assert.equal(
	format(doc),
	String.raw`
		node "value" #"other value"# 2.0 4 #false \
				#null -0 {
			child /-lorem="ipsum" \
				dolor=#true; "child too"
		}
	`,
);

```

--------------------------------

### Deserialize KDL Tree using Functions

Source: https://github.com/bgotink/kdl/blob/main/documentation/src/api/dessert.md

Use this function deserializer when you need to convert a KDL node into a tree structure. It requires a 'number' argument and can recursively deserialize 'left' and 'right' child nodes.

```typescript
import type {DeserializationContext} from "@bgotink/kdl/dessert";

type Tree = {value: number; left?: Tree; right?: Tree};

function treeDeserializer(ctx: DeserializationContext): Tree {
	return {
		value: ctx.argument.required("number"),
		left: ctx.child.single("left", treeDeserializer),
		right: ctx.child.single("right", treeDeserializer),
	};
}

export function readTree(node: Node): Tree {
	return deserialize(node, treeDeserializer);
}
```

--------------------------------

### Deserialize KDL Tree using a Class

Source: https://github.com/bgotink/kdl/blob/main/documentation/src/api/dessert.md

This class-based deserializer provides an alternative way to convert KDL nodes to a tree structure. It leverages a static `deserialize` method and instance constructor for creating tree objects.

```typescript
import type {DeserializationContext} from "@bgotink/kdl/dessert";

class Tree {
	static deserialize(ctx: DeserializationContext): Tree {
		return new Tree(
			ctx.argument.required("number"),
			ctx.child.single("left", Tree),
			ctx.child.single("right", Tree),
		);
	}

	constructor(
		readonly value: number,
		readonly left?: Tree,
		readonly right?: Tree,
	) {}
}

export function readTree(node: Node): Tree {
	return deserialize(node, Tree);
}
```

--------------------------------

### Modifying KDL Node Values

Source: https://github.com/bgotink/kdl/blob/main/documentation/src/api/dessert.md

A function to read a KDL tree, modify specific node values, and write the tree back, preserving original formatting.

```typescript
function modify(node: Node): Node {
	const tree = readTree(node); // see deserialization example for this function

	tree.right.left.value++;
	tree.right.value++;
	tree.value++;

	return writeTree(tree);
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.