=encoding utf8

=head1 NAME

std/data/kdl - KDL parsing and serialization for ZuzuScript.

=head1 SYNOPSIS

  from std/data/kdl import KDL;
  
  let kdl := new KDL();
  let doc := kdl.decode("""
    package name="zuzu" { version "0.1.0" }
  """);
  let text := kdl.encode(doc);

=head1 IMPLEMENTATION SUPPORT

This module is supported by zuzu.pl, zuzu-rust, and zuzu-js on Node and
Electron. It is partially supported by zuzu-js in the browser: in-memory
KDL parsing and serialization coverage passes, but fixture and load/dump
coverage is unsupported because browser filesystem capability is
unavailable.

=head1 DESCRIPTION

This module provides a pure-Zuzu implementation of the KDL document
model and parser, with a user-facing API modelled on C<std/data/json>.

=head1 EXPORTS

The parser returns explicit KDL model objects rather than generic Dict
and Array structures.

=head2 C<KDLDocument>

C<KDLDocument> represents a complete parsed KDL document.

Constructor fields:

=over

=item * C<nodes>

An Array of top-level C<KDLNode> objects. Defaults to an empty Array.

=back

Methods:

=over

=item C<nodes()>

Parameters: none. Returns: C<Array>. Returns the Array of top-level
C<KDLNode> objects.

=item C<to_Iterator()>

Parameters: none. Returns: C<Function>. Returns an iterator over the
document's top-level nodes.

=back

=head2 C<KDLNode>

C<KDLNode> represents one KDL node.

Constructor fields:

=over

=item * C<name>

The node name as a String.

=item * C<type_annotation>

The node type annotation as a String, or C<null> when unannotated.

=item * C<args>

An Array of unnamed argument C<KDLValue> objects. Defaults to an empty
Array.

=item * C<props>

A C<PairList> mapping property names to C<KDLValue> objects. Defaults
to an empty C<PairList>, and preserves duplicate property names.

=item * C<children>

An Array of child C<KDLNode> objects. Defaults to an empty Array.

=back

Methods:

=over

=item C<name()>

Parameters: none. Returns: C<String>. Returns the node name.

=item C<type_annotation()>

Parameters: none. Returns: C<String> or C<null>. Returns the node type
annotation.

=item C<args()>

Parameters: none. Returns: C<Array>. Returns the unnamed argument
C<KDLValue> objects.

=item C<props()>

Parameters: none. Returns: C<PairList>. Returns the named property
C<KDLValue> objects.

=item C<children()>

Parameters: none. Returns: C<Array>. Returns the child C<KDLNode>
objects.

=item C<to_Iterator()>

Parameters: none. Returns: C<Function>. Returns an iterator over the
node's arguments followed by its child nodes.

=back

=head2 C<KDLValue>

C<KDLValue> represents an unnamed argument or named property value.

Constructor fields:

=over

=item * C<type>

The KDL value type: C<null>, C<boolean>, C<number>, or C<string>.
Some conversion helpers may create opaque C<KDLValue> objects with
other type names; those are not KDL primitives.

=item * C<kind>

For numbers, one of C<integer>, C<float>, or C<string>. C<string> is
used for KDL number keywords such as C<#inf> that do not have a native
JSON-like numeric value.

=item * C<value>

The raw native value.

=item * C<type_annotation>

The value type annotation as a String, or C<null> when unannotated.

=item * C<canonical_number>

The canonical numeric spelling used by canonical serialization, or
C<null>.

=back

Methods:

=over

=item C<type()>

Parameters: none. Returns: C<String>. Returns the value type.

=item C<kind()>

Parameters: none. Returns: C<String> or C<null>. Returns the numeric
kind for number values.

=item C<value()>

Parameters: none. Returns: value. Returns the raw native value.

=item C<type_annotation()>

Parameters: none. Returns: C<String> or C<null>. Returns the value type
annotation.

=item C<canonical_number()>

Parameters: none. Returns: C<String> or C<null>. Returns the canonical
numeric spelling.

=item C<is_null()>, C<is_boolean()>, C<is_number()>, C<is_string()>

Parameters: none. Returns: C<Boolean>. Predicate methods for the four
KDL primitive value types.

=item C<is_true()>, C<is_false()>

Parameters: none. Returns: C<Boolean>. Predicate methods for boolean
C<#true> and C<#false> values.

=item C<to_Number()>

Parameters: none. Returns: C<Number>. Returns the native number, or
throws when the value is not a finite native number.

=item C<to_String()>

Parameters: none. Returns: C<String>. Coerces the value to a string.

=item C<to_Boolean()>

Parameters: none. Returns: C<Boolean>. Coerces the value to a boolean.

=item C<native_value()>

Parameters: none. Returns: value. Returns the raw native value, with KDL
C<#null> represented as C<null>.

=back

=head2 C<KDL>

C<KDL> is the codec class for KDL text.

=over

=item C<< codec.decode(String text) >>

Parameters: C<text> is KDL text. Returns: C<KDLDocument>. Parses KDL
text.

=item C<< codec.decode_binarystring(BinaryString bytes) >>

Parameters: C<bytes> is UTF-8 KDL bytes. Returns: C<KDLDocument>.
Parses KDL bytes.

=item C<< codec.encode(value) >>

Parameters: C<value> is a C<KDLDocument>, C<KDLNode>, or compatible
value. Returns: C<String>. Serializes KDL data to text.

=item C<< codec.encode_binarystring(value) >>

Parameters: C<value> is a C<KDLDocument>, C<KDLNode>, or compatible
value. Returns: C<BinaryString>. Serializes KDL data to UTF-8 bytes.

=item C<< codec.load(path) >>

Parameters: C<path> is a C<std/io> C<Path>. Returns: C<KDLDocument>.
Reads and parses a KDL file.

=item C<< codec.dump(path, value) >>

Parameters: C<path> is a C<std/io> C<Path> and C<value> is KDL data.
Returns: C<null>. Serializes and writes a KDL file.

=back

=head1 ZPATH

C<KDLDocument>, C<KDLNode>, and C<KDLValue> objects can be queried with
C<std/path/z>. A KDL document's top-level nodes are exposed as children.
A KDL node exposes its arguments first, then its child nodes, as ZPath
children. KDL properties are exposed as ZPath attributes.

  from std/data/kdl import KDL;
  from std/path/z import ZPath;

  let doc := ( new KDL() ).decode( """
  (pkg)package "zuzu" (email)"dev@example.test" version="0.1.0" {
    foo "first"
    bar "middle"
    foo "second"
    foo "third"
  }
  """ );

  // The package node's first child is its first argument.
  say( ( new ZPath( path: "/package/#0" ) ).first(doc) );       // zuzu

  // Properties are attributes.
  say( ( new ZPath( path: "/package/@version" ) ).first(doc) ); // 0.1.0

  // Child nodes can be selected by name and zero-based occurrence.
  say( ( new ZPath( path: "/package/foo#2/#0" ) ).first(doc) ); // third

  // tag() exposes type annotations on nodes and values.
  say( ( new ZPath( path: "tag(/package)" ) ).first(doc) );     // pkg
  say( ( new ZPath( path: "tag(/package/#1)" ) ).first(doc) );  // email

  // local-name() exposes the node name, like it does for XML elements.
  say( ( new ZPath( path: "local-name(/package)" ) ).first(doc) );
  say( ( new ZPath( path: "/package/foo#2/local-name()" ) ).first(doc) );

=head1 COMPATIBILITY

The parser is recursive descent and covers the usual KDL 2.0 document
model: nodes, arguments, properties, annotations, comments, slashdash,
strings, booleans, nulls, numbers, and children.

=head1 COPYRIGHT AND LICENCE

B<< std/data/kdl >> is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under
the terms of either the Artistic License 1.0 or the GNU General Public
License version 2.

=cut

from std/string import substr, index, chr, ord, sprint;


function _kdl_starts_with ( String text, Number pos, String prefix ) {
	return substr( text, pos, length prefix ) ≡ prefix;
}

function _kdl_is_newline ( String ch ) {
	return ch ≡ "\n" or ch ≡ "\r" or ch ≡ chr(11)
		or ch ≡ chr(133) or ch ≡ chr(8232) or ch ≡ chr(8233);
}

function _kdl_is_ws ( String ch ) {
	return false if ch ≡ "";
	let code := ord(ch);
	return ch ≡ " " or ch ≡ "\t" or ch ≡ chr(12)
		or code ≡ 160 or code ≡ 5760 or code ≡ 8239
		or code ≡ 8287 or code ≡ 12288
		or ( code >= 8192 and code <= 8202 );
}

function _kdl_is_line_space ( String ch ) {
	return _kdl_is_ws(ch) or _kdl_is_newline(ch);
}

function _kdl_is_digit ( String ch ) {
	return ch ~ /^[0-9]$/;
}

function _kdl_is_hex_digit ( String ch ) {
	return ch ~ /^[0-9a-fA-F]$/;
}

function _kdl_hex_value ( String ch ) {
	if ( _kdl_is_digit(ch) ) {
		return ch + 0;
	}
	if ( index( "abcdef", ch ) >= 0 ) {
		return 10 + index( "abcdef", ch );
	}
	if ( index( "ABCDEF", ch ) >= 0 ) {
		return 10 + index( "ABCDEF", ch );
	}
	die `Invalid hexadecimal digit '${ch}'`;
}

function _kdl_from_hex ( String raw ) {
	let n := 0;
	let i := 0;
	while ( i < length raw ) {
		n := n * 16 + _kdl_hex_value( substr( raw, i, 1 ) );
		i++;
	}
	return n;
}

function _kdl_clean_number ( String token ) {
	let out := "";
	let i := 0;
	while ( i < length token ) {
		let ch := substr( token, i, 1 );
		out _= ch if ch ≢ "_";
		i++;
	}
	return out;
}

function _kdl_parse_radix ( String token, Number radix ) {
	let sign := 1;
	let i := 0;
	if ( substr( token, 0, 1 ) ≡ "-" ) {
		sign := -1;
		i := 1;
	}
	else if ( substr( token, 0, 1 ) ≡ "+" ) {
		i := 1;
	}
	i += 2;

	let n := 0;
	while ( i < length token ) {
		let ch := substr( token, i, 1 );
		if ( ch ≢ "_" ) {
			let v := radix ≡ 16 ? _kdl_hex_value(ch) : ch + 0;
			die `Invalid digit '${ch}' for radix ${radix}` if v >= radix;
			n := n * radix + v;
		}
		i++;
	}
	return sign * n;
}

function _kdl_strip_decimal_zeroes ( String raw ) {
	let i := 0;
	while ( i < length raw - 1 and substr( raw, i, 1 ) ≡ "0" ) {
		i++;
	}
	return substr( raw, i, length raw - i );
}

function _kdl_decimal_mul_add ( String raw, Number factor, Number add ) {
	let out := "";
	let carry := add;
	let i := length raw - 1;
	while ( i >= 0 ) {
		let n := ( substr( raw, i, 1 ) + 0 ) * factor + carry;
		out := "" _ ( n mod 10 ) _ out;
		carry := floor( n / 10 );
		i--;
	}
	while ( carry > 0 ) {
		out := "" _ ( carry mod 10 ) _ out;
		carry := floor( carry / 10 );
	}
	return _kdl_strip_decimal_zeroes(out);
}

function _kdl_decimal_from_radix ( String token, Number radix ) {
	let sign := "";
	let i := 0;
	if ( substr( token, 0, 1 ) ≡ "-" ) {
		sign := "-";
		i := 1;
	}
	else if ( substr( token, 0, 1 ) ≡ "+" ) {
		i := 1;
	}
	i += 2;

	let out := "0";
	while ( i < length token ) {
		out := _kdl_decimal_mul_add(
			out,
			radix,
			_kdl_hex_value( substr( token, i, 1 ) ),
		);
		i++;
	}
	return sign _ out if sign ≢ "" and out ≢ "0";
	return out;
}

function _kdl_canonical_decimal_int ( String token ) {
	let sign := "";
	let i := 0;
	if ( substr( token, 0, 1 ) ≡ "-" ) {
		sign := "-";
		i := 1;
	}
	else if ( substr( token, 0, 1 ) ≡ "+" ) {
		i := 1;
	}
	let body := _kdl_strip_decimal_zeroes(
		substr( token, i, length token - i )
	);
	return sign _ body if sign ≢ "" and body ≢ "0";
	return body;
}

function _kdl_canonical_float ( String token ) {
	let epos := index( token, "e" );
	epos := index( token, "E" ) if epos < 0;
	return token if epos < 0;

	let mantissa := substr( token, 0, epos );
	let exponent := substr( token, epos + 1, length token - epos - 1 );
	if ( substr( exponent, 0, 1 ) ≢ "+"
		and substr( exponent, 0, 1 ) ≢ "-"
	) {
		exponent := "+" _ exponent;
	}
	return mantissa _ "E" _ exponent;
}

function _kdl_find_multiline_close (
	String text,
	String close,
	Number start,
	Boolean raw,
) {
	let found := index( text, close, start );
	while ( found >= 0 ) {
		if ( raw or found = 0 or substr( text, found - 1, 1 ) ≢ "\\" ) {
			return found;
		}
		found := index( text, close, found + 1 );
	}
	return -1;
}

function _kdl_reserved_ident ( String text ) {
	return text ≡ "true" or text ≡ "false" or text ≡ "null"
		or text ≡ "inf" or text ≡ "-inf" or text ≡ "nan";
}

function _kdl_ident_break ( String ch ) {
	return ch ≡ "" or _kdl_is_line_space(ch)
		or ch ≡ "\\" or ch ≡ "/" or ch ≡ "(" or ch ≡ ")"
		or ch ≡ "{" or ch ≡ "}" or ch ≡ ";" or ch ≡ "["
		or ch ≡ "]" or ch ≡ "\"" or ch ≡ "#" or ch ≡ "=";
}

function _kdl_forbidden_codepoint ( Number code ) {
	return code < 32 or code ≡ 127 or code ≡ 65279
		or code ≡ 8206 or code ≡ 8207
		or ( code >= 8234 and code <= 8238 )
		or ( code >= 8294 and code <= 8297 );
}

function _kdl_is_plain_ident ( String text ) {
	if ( text ≡ "" or _kdl_reserved_ident(text) ) {
		return false;
	}
	let first := substr( text, 0, 1 );
	let second := substr( text, 1, 1 );
	if ( _kdl_is_digit(first) ) {
		return false;
	}
	if ( ( first ≡ "+" or first ≡ "-" ) and _kdl_is_digit(second) ) {
		return false;
	}
	if ( first ≡ "." and _kdl_is_digit(second) ) {
		return false;
	}
	let i := 0;
	while ( i < length text ) {
		return false if _kdl_ident_break( substr( text, i, 1 ) );
		i++;
	}
	return true;
}

function _kdl_escape_string ( String text ) {
	let out := "";
	let i := 0;
	while ( i < length text ) {
		let ch := substr( text, i, 1 );
		if ( ch ≡ "\\" ) { out _= "\\\\"; }
		else if ( ch ≡ "\"" ) { out _= "\\\""; }
		else if ( ch ≡ chr(8) ) { out _= "\\b"; }
		else if ( ch ≡ chr(12) ) { out _= "\\f"; }
		else if ( ch ≡ "\n" ) { out _= "\\n"; }
		else if ( ch ≡ "\r" ) { out _= "\\r"; }
		else if ( ch ≡ "\t" ) { out _= "\\t"; }
		else if ( ord(ch) < 32 ) {
			out _= "\\u{" _ sprint( "%x", ord(ch) ) _ "}";
		}
		else { out _= ch; }
		i++;
	}
	return out;
}

function _kdl_name ( String text ) {
	return _kdl_is_plain_ident(text) ? text : `"${_kdl_escape_string(text)}"`;
}

function _kdl_indent ( Number level, Boolean canonical := false ) {
	let out := "";
	let i := 0;
	let unit := canonical ? "    " : "\t";
	while ( i < level ) {
		out _= unit;
		i++;
	}
	return out;
}

function _kdl_canonical_props ( PairList props ) {
	let latest := {};
	for ( let pair in props.to_Array() ) {
		let kv := pair{pair};
		latest{(kv[0])} := kv[1];
	}

	let out := [];
	for ( let key in latest.sorted_keys() ) {
		out.push( [ key, latest{(key)} ] );
	}
	return out;
}

class KDLValue {
	let String type := "null";
	let kind := null;
	let value := null;
	let type_annotation := null;
	let canonical_number := null;

	method type () { return type; }
	method kind () { return kind; }
	method value () { return value; }
	method type_annotation () { return type_annotation; }
	method canonical_number () { return canonical_number; }

	method is_null () { return type ≡ "null"; }
	method is_boolean () { return type ≡ "boolean"; }
	method is_number () { return type ≡ "number"; }
	method is_string () { return type ≡ "string"; }
	method is_true () { return type ≡ "boolean" and value; }
	method is_false () { return type ≡ "boolean" and not value; }

	method to_Number () {
		die "KDLValue is not a number" if type ≢ "number";
		die "KDL keyword number has no native numeric value" if kind ≡ "string";
		return value;
	}

	method to_String () {
		return "" if type ≡ "null";
		return "" _ value;
	}

	method to_Boolean () {
		if ( type ≡ "boolean" ) { return value; }
		if ( type ≡ "null" ) { return false; }
		if ( type ≡ "number" ) {
			return kind ≢ "string" and value ≢ 0;
		}
		return value ≢ "";
	}

	method native_value () {
		return null if type ≡ "null";
		return value;
	}
}

class KDLNode {
	let name := "";
	let type_annotation := null;
	let args := [];
	let props := null;
	let children := [];

	method __build__ () {
		props := new PairList() if props ≡ null;
		args := [] if args ≡ null;
		children := [] if children ≡ null;
	}

	method name () { return name; }
	method type_annotation () { return type_annotation; }
	method args () { return args; }
	method props () { return props; }
	method children () { return children; }

	method to_Iterator () {
		let values := [];
		for ( let arg in args ) {
			values.push(arg);
		}
		for ( let child in children ) {
			values.push(child);
		}
		return values.to_Iterator();
	}
}

class KDLDocument {
	let nodes := [];

	method __build__ () {
		nodes := [] if nodes ≡ null;
	}

	method nodes () { return nodes; }

	method to_Iterator () {
		return nodes.to_Iterator();
	}
}

class _KDLParser {
	let String text := "";
	let Number pos := 0;

	method _eof () {
		return pos >= length text;
	}

	method _peek () {
		return "" if self._eof();
		return substr( text, pos, 1 );
	}

	method _take () {
		let ch := self._peek();
		pos++;
		return ch;
	}

	method _error ( String message ) {
		die `KDL parse error at offset ${pos}: ${message}`;
	}

	method _skip_newline () {
		if ( _kdl_starts_with( text, pos, "\r\n" ) ) {
			pos += 2;
			return true;
		}
		if ( _kdl_is_newline( self._peek() ) ) {
			pos++;
			return true;
		}
		return false;
	}

	method _skip_line_comment () {
		return false if not _kdl_starts_with( text, pos, "//" );
		pos += 2;
		while ( not self._eof() and not _kdl_is_newline( self._peek() ) ) {
			pos++;
		}
		self._skip_newline();
		return true;
	}

	method _skip_block_comment () {
		return false if not _kdl_starts_with( text, pos, "/*" );
		pos += 2;
		let depth := 1;
		while ( depth > 0 ) {
			self._error("Unterminated block comment") if self._eof();
			if ( _kdl_starts_with( text, pos, "/*" ) ) {
				depth++;
				pos += 2;
			}
			else if ( _kdl_starts_with( text, pos, "*/" ) ) {
				depth--;
				pos += 2;
			}
			else {
				pos++;
			}
		}
		return true;
	}

	method _skip_line_space () {
		let moved := false;
		let keep := true;
		while ( keep and not self._eof() ) {
			keep := false;
			if ( _kdl_is_ws( self._peek() ) ) {
				pos++;
				moved := true;
				keep := true;
			}
			else if ( self._skip_newline() ) {
				moved := true;
				keep := true;
			}
			else if ( self._skip_line_comment() ) {
				moved := true;
				keep := true;
			}
			else if ( self._skip_block_comment() ) {
				moved := true;
				keep := true;
			}
			else if ( self._skip_escline() ) {
				moved := true;
				keep := true;
			}
		}
		return moved;
	}

	method _skip_node_space () {
		let moved := false;
		let keep := true;
		while ( keep and not self._eof() ) {
			keep := false;
			if ( _kdl_is_ws( self._peek() ) ) {
				pos++;
				moved := true;
				keep := true;
			}
			else if ( self._skip_block_comment() ) {
				moved := true;
				keep := true;
			}
			else if ( self._skip_escline() ) {
				moved := true;
				keep := true;
			}
		}
		return moved;
	}

	method _skip_escline () {
		return false if self._peek() ≢ "\\";
		let save := pos;
		pos++;
		let keep := true;
		while ( keep and not self._eof() ) {
			keep := false;
			while ( _kdl_is_ws( self._peek() ) ) {
				pos++;
				keep := true;
			}
			if ( self._skip_block_comment() ) {
				keep := true;
			}
		}
		if ( self._skip_line_comment() or self._skip_newline() or self._eof() ) {
			return true;
		}
		pos := save;
		return false;
	}

	method _parse_document () {
		if ( _kdl_starts_with( text, pos, chr(65279) ) ) {
			pos++;
		}
		let nodes := self._parse_nodes(false);
		self._skip_line_space();
		self._error("Unexpected trailing input") if not self._eof();
		return new KDLDocument( nodes: nodes );
	}

	method _parse_nodes ( Boolean in_children ) {
		let nodes := [];
		while (true) {
			self._skip_line_space();
			if ( self._eof() ) {
				return nodes;
			}
			if ( in_children and self._peek() ≡ "}" ) {
				return nodes;
			}
			if ( _kdl_starts_with( text, pos, "/-" ) ) {
				self._consume_slashdash();
				self._parse_node(true);
			}
			else {
				let node := self._parse_node(false);
				nodes.push(node) if node ≢ null;
			}
		}
		return nodes;
	}

	method _consume_slashdash () {
		self._error("Expected slashdash") if not _kdl_starts_with( text, pos, "/-" );
		pos += 2;
		self._skip_line_space();
	}

	method _parse_type_annotation () {
		return null if self._peek() ≢ "(";
		pos++;
		self._skip_node_space();
		let name := self._parse_string();
		self._skip_node_space();
		self._error("Expected ')' after type annotation") if self._peek() ≢ ")";
		pos++;
		self._skip_node_space();
		return name;
	}

	method _parse_node ( Boolean discard ) {
		let annotation := self._parse_type_annotation();
		self._skip_node_space();
		let name := self._parse_string();
		let args := [];
		let props := new PairList();
		let children := [];
		let slashdash_child_before_entry := false;

		while (true) {
			let had_space := self._skip_node_space();
			if ( self._eof() ) {
				return discard ? null : new KDLNode(
					name: name,
					type_annotation: annotation,
					args: args,
					props: props,
					children: children,
				);
			}

			let ch := self._peek();
			if ( ch ≡ ";" ) {
				pos++;
				return discard ? null : new KDLNode(
					name: name,
					type_annotation: annotation,
					args: args,
					props: props,
					children: children,
				);
			}
			if ( ch ≡ "}" ) {
				return discard ? null : new KDLNode(
					name: name,
					type_annotation: annotation,
					args: args,
					props: props,
					children: children,
				);
			}
			if ( _kdl_is_newline(ch) ) {
				self._skip_newline();
				return discard ? null : new KDLNode(
					name: name,
					type_annotation: annotation,
					args: args,
					props: props,
					children: children,
				);
			}
			if ( _kdl_starts_with( text, pos, "//" ) ) {
				self._skip_line_comment();
				return discard ? null : new KDLNode(
					name: name,
					type_annotation: annotation,
					args: args,
					props: props,
					children: children,
				);
			}
			if ( _kdl_starts_with( text, pos, "/-" ) ) {
				self._consume_slashdash();
				if ( self._peek() ≡ "{" ) {
					self._parse_children();
					slashdash_child_before_entry := true;
				}
				else {
					self._parse_entry(true, args, props);
				}
				next;
			}
			if ( ch ≡ "{" ) {
				self._error("Child block must be the final node field")
					if children.length() > 0;
				children := self._parse_children();
				next;
			}
			self._error("Expected whitespace before node field")
				if not had_space;
			self._error("Child block must be the final node field")
				if children.length() > 0;
			self._error("Discarded child block must not precede node fields")
				if slashdash_child_before_entry;
			self._parse_entry(discard, args, props);
		}
	}

	method _parse_children () {
		self._error("Expected '{'") if self._peek() ≢ "{";
		pos++;
		let kids := self._parse_nodes(true);
		self._skip_line_space();
		self._error("Expected '}' after child block") if self._peek() ≢ "}";
		pos++;
		return kids;
	}

	method _parse_entry ( Boolean discard, Array args, PairList props ) {
		if ( self._peek() ≡ "(" ) {
			let value := self._parse_value();
			args.push(value) if not discard;
			return;
		}

		if ( self._peek() ≡ "#" or self._starts_number() ) {
			let value := self._parse_value();
			args.push(value) if not discard;
			return;
		}

		let key := self._parse_string();
		let after_key := pos;
		self._skip_node_space();
		if ( self._peek() ≡ "=" ) {
			pos++;
			self._skip_node_space();
			let value := self._parse_value();
			props.add( key, value ) if not discard;
			return;
		}
		pos := after_key;

		let value := new KDLValue( type: "string", value: key );
		args.push(value) if not discard;
		return;
	}

	method _parse_value () {
		let annotation := self._parse_type_annotation();
		self._skip_node_space();

		if ( self._peek() ≡ "#" ) {
			return self._parse_hash_value(annotation);
		}
		if ( self._starts_number() ) {
			return self._parse_number(annotation);
		}
		return new KDLValue(
			type: "string",
			value: self._parse_string(),
			type_annotation: annotation,
		);
	}

	method _starts_number () {
		let ch := self._peek();
		let nxt := substr( text, pos + 1, 1 );
		return _kdl_is_digit(ch)
			or ( ( ch ≡ "+" or ch ≡ "-" ) and _kdl_is_digit(nxt) );
	}

	method _read_token () {
		let start := pos;
		while ( not self._eof() ) {
			let ch := self._peek();
			last if _kdl_ident_break(ch);
			pos++;
		}
		return substr( text, start, pos - start );
	}

	method _parse_hash_value ( annotation ) {
		if ( _kdl_starts_with( text, pos, "#true" ) ) {
			pos += 5;
			return new KDLValue(
				type: "boolean",
				value: true,
				type_annotation: annotation,
			);
		}
		if ( _kdl_starts_with( text, pos, "#false" ) ) {
			pos += 6;
			return new KDLValue(
				type: "boolean",
				value: false,
				type_annotation: annotation,
			);
		}
		if ( _kdl_starts_with( text, pos, "#null" ) ) {
			pos += 5;
			return new KDLValue(
				type: "null",
				value: null,
				type_annotation: annotation,
			);
		}
		if ( _kdl_starts_with( text, pos, "#inf" ) ) {
			pos += 4;
			return new KDLValue(
				type: "number",
				kind: "string",
				value: "#inf",
				type_annotation: annotation,
			);
		}
		if ( _kdl_starts_with( text, pos, "#-inf" ) ) {
			pos += 5;
			return new KDLValue(
				type: "number",
				kind: "string",
				value: "#-inf",
				type_annotation: annotation,
			);
		}
		if ( _kdl_starts_with( text, pos, "#nan" ) ) {
			pos += 4;
			return new KDLValue(
				type: "number",
				kind: "string",
				value: "#nan",
				type_annotation: annotation,
			);
		}
		return new KDLValue(
			type: "string",
			value: self._parse_raw_string(),
			type_annotation: annotation,
		);
	}

	method _parse_number ( annotation ) {
		let token := self._read_token();
		self._error( `Invalid number '${token}'` )
			if token ~ /^[+-]?0[xob]_/i or token ~ /\._/;
		let clean := _kdl_clean_number(token);
		if ( clean ~ /^[+-]?0x[0-9a-fA-F]+$/ ) {
			return new KDLValue(
				type: "number",
				kind: "integer",
				value: _kdl_parse_radix( clean, 16 ),
				canonical_number: _kdl_decimal_from_radix( clean, 16 ),
				type_annotation: annotation,
			);
		}
		if ( clean ~ /^[+-]?0o[0-7]+$/ ) {
			return new KDLValue(
				type: "number",
				kind: "integer",
				value: _kdl_parse_radix( clean, 8 ),
				canonical_number: _kdl_decimal_from_radix( clean, 8 ),
				type_annotation: annotation,
			);
		}
		if ( clean ~ /^[+-]?0b[01]+$/ ) {
			return new KDLValue(
				type: "number",
				kind: "integer",
				value: _kdl_parse_radix( clean, 2 ),
				canonical_number: _kdl_decimal_from_radix( clean, 2 ),
				type_annotation: annotation,
			);
		}
		if ( clean ~ /^[+-]?[0-9]+$/ ) {
			return new KDLValue(
				type: "number",
				kind: "integer",
				value: clean + 0,
				canonical_number: _kdl_canonical_decimal_int(clean),
				type_annotation: annotation,
			);
		}
		if ( clean ~ /^[+-]?[0-9]+(\.[0-9]+)?([eE][+-]?[0-9]+)?$/ ) {
			return new KDLValue(
				type: "number",
				kind: "float",
				value: clean + 0,
				canonical_number: _kdl_canonical_float(clean),
				type_annotation: annotation,
			);
		}
		self._error( `Invalid number '${token}'` );
	}

	method _parse_string () {
		if ( self._peek() ≡ "#" ) {
			return self._parse_raw_string();
		}
		if ( self._peek() ≡ "\"" ) {
			return self._parse_quoted_string();
		}
		return self._parse_identifier_string();
	}

	method _parse_identifier_string () {
		let ident := self._read_token();
		self._error("Expected string") if ident ≡ "";
		self._error( `Reserved KDL identifier '${ident}'` )
			if _kdl_reserved_ident(ident);
		self._error( `Invalid KDL identifier '${ident}'` )
			if substr( ident, 0, 1 ) ≡ "."
				and _kdl_is_digit( substr( ident, 1, 1 ) );
		let i := 0;
		while ( i < length ident ) {
			let code := ord( substr( ident, i, 1 ) );
			self._error( `Forbidden codepoint in KDL identifier '${ident}'` )
				if _kdl_forbidden_codepoint(code);
			i++;
		}
		return ident;
	}

	method _parse_quoted_string () {
		if ( _kdl_starts_with( text, pos, "\"\"\"" ) ) {
			return self._parse_multiline_string( "", false );
		}
		pos++;
		let out := "";
		while ( not self._eof() ) {
			let ch := self._take();
			if ( ch ≡ "\"" ) {
				return out;
			}
			if ( ch ≡ "\\" ) {
				out _= self._parse_escape();
			}
			else {
				self._error("Newline in quoted string") if _kdl_is_newline(ch);
				out _= ch;
			}
		}
		self._error("Unterminated quoted string");
	}

	method _parse_escape () {
		self._error("Unterminated string escape") if self._eof();
		let ch := self._take();
		if ( ch ≡ "\"" ) { return "\""; }
		if ( ch ≡ "\\" ) { return "\\"; }
		if ( ch ≡ "b" ) { return chr(8); }
		if ( ch ≡ "f" ) { return chr(12); }
		if ( ch ≡ "n" ) { return "\n"; }
		if ( ch ≡ "r" ) { return "\r"; }
		if ( ch ≡ "s" ) { return " "; }
		if ( ch ≡ "t" ) { return "\t"; }
		if ( _kdl_is_line_space(ch) ) {
			while ( _kdl_is_line_space(ch) ) {
				if ( _kdl_is_newline(ch) ) {
					self._skip_newline();
				}
				ch := self._peek();
				pos++ if _kdl_is_ws(ch);
			}
			return "";
		}
		if ( ch ≡ "u" ) {
			self._error("Expected '{' in Unicode escape") if self._peek() ≢ "{";
			pos++;
			let start := pos;
			while ( not self._eof() and self._peek() ≢ "}" ) {
				self._error("Invalid Unicode escape") if not _kdl_is_hex_digit( self._peek() );
				pos++;
			}
			self._error("Unterminated Unicode escape") if self._peek() ≢ "}";
			let raw := substr( text, start, pos - start );
			self._error("Unicode escape must contain 1 to 6 hex digits")
				if length raw < 1 or length raw > 6;
			pos++;
			let code := _kdl_from_hex(raw);
			return chr(code);
		}
		self._error( `Invalid string escape '\\${ch}'` );
	}

	method _parse_raw_string () {
		let hashes := "";
		while ( self._peek() ≡ "#" ) {
			hashes _= "#";
			pos++;
		}
		self._error("Expected raw string quotes") if self._peek() ≢ "\"";
		if ( _kdl_starts_with( text, pos, "\"\"\"" ) ) {
			return self._parse_multiline_string( hashes, true );
		}
		pos++;
		let close := "\"" _ hashes;
		let end := index( text, close, pos );
		self._error("Unterminated raw string") if end < 0;
		let out := substr( text, pos, end - pos );
		self._error("Newline in raw string") if out ~ /[\r\n\v]/;
		pos := end + length close;
		return out;
	}

	method _parse_multiline_string ( String hashes, Boolean raw ) {
		pos += 3;
		self._error("Expected newline after multiline string opener")
			if not self._skip_newline();
		let close := "\"\"\"" _ hashes;
		let end := _kdl_find_multiline_close( text, close, pos, raw );
		self._error("Unterminated multiline string") if end < 0;
		let body := substr( text, pos, end - pos );
		pos := end + length close;

		let last_nl := -1;
		let i := length body - 1;
		while ( i >= 0 and last_nl < 0 ) {
			if ( substr( body, i, 1 ) ≡ "\n" ) {
				last_nl := i;
			}
			i--;
		}
		return "" if last_nl < 0;
			let content := substr( body, 0, last_nl );
			let indent := substr( body, last_nl + 1, length body - last_nl - 1 );
			if ( not raw ) {
				let bs := 0;
				while ( bs < length indent
					and _kdl_is_ws( substr( indent, bs, 1 ) )
				) {
					bs++;
				}
				if ( bs < length indent and substr( indent, bs, 1 ) ≡ "\\" ) {
					let k := bs + 1;
					let only_ws := true;
					while ( k < length indent ) {
						only_ws := false
							if not _kdl_is_ws( substr( indent, k, 1 ) );
						k++;
					}
					indent := substr( indent, 0, bs ) if only_ws;
				}
			}
			if ( indent ≡ "" ) {
				let min_indent := null;
				let scan := 0;
				let scan_start := 0;
				while ( scan <= length content ) {
					if ( scan ≡ length content
						or substr( content, scan, 1 ) ≡ "\n"
					) {
						let raw_line := substr(
							content,
							scan_start,
							scan - scan_start,
						);
						if ( not( raw_line ~ /^\s*$/ ) ) {
							let width := 0;
							while ( width < length raw_line
								and _kdl_is_ws( substr( raw_line, width, 1 ) )
							) {
								width++;
							}
							min_indent := width
								if min_indent ≡ null or width < min_indent;
						}
						scan_start := scan + 1;
					}
					scan++;
				}
				if ( min_indent ≢ null and min_indent > 0 ) {
					indent := "";
					let si := 0;
					while ( si < min_indent ) {
						indent _= " ";
						si++;
					}
				}
			}
			let out := "";
		i := 0;
		let line_start := 0;
			let emitted := false;
			let continued := false;
			let last_line_continued_with_text := false;
			while ( i <= length content ) {
			if ( i ≡ length content or substr( content, i, 1 ) ≡ "\n" ) {
				let line := substr( content, line_start, i - line_start );
				if ( line ~ /^\s*$/ ) {
					line := "";
				}
					else if ( continued ) {
						if ( length indent > 0
							and substr( line, 0, length indent ) ≡ indent
						) {
							line := substr(
								line,
								length indent,
								length line - length indent,
							);
						}
					}
					else if ( length indent > 0 and substr( line, 0, length indent ) ≡ indent ) {
						line := substr( line, length indent, length line - length indent );
					}
					else if ( length indent > 0 ) {
						let k := 0;
						while ( k < length line
							and _kdl_is_ws( substr( line, k, 1 ) )
						) {
							k++;
						}
						let ok_escape_prefix := false;
						if ( not raw and substr( line, k, 1 ) ≡ "\\" ) {
							k++;
							ok_escape_prefix := true;
							while ( k < length line ) {
								ok_escape_prefix := false
									if not _kdl_is_ws( substr( line, k, 1 ) );
								k++;
							}
						}
						self._error("Multiline string indentation mismatch")
							if not ok_escape_prefix;
					}

				let line_continues := false;
				if ( not raw ) {
					let j := length line - 1;
					while ( j >= 0 and _kdl_is_ws( substr( line, j, 1 ) ) ) {
						j--;
					}
					if ( j >= 0 and substr( line, j, 1 ) ≡ "\\" ) {
						let slashes := 0;
						while ( j - slashes >= 0
							and substr( line, j - slashes, 1 ) ≡ "\\"
						) {
							slashes++;
						}
						if ( slashes mod 2 = 1 ) {
							line_continues := true;
							line := substr( line, 0, j );
						}
					}
				}
				self._error("Invalid final multiline whitespace escape")
					if line_continues and line ≡ "" and indent ≡ "";

				out _= "\n"
					if emitted and not continued
						and not ( line_continues and line ≡ "" );
				out _= raw ? line : self._unescape_multiline_line(line);
				emitted := true;
				continued := line_continues;
				last_line_continued_with_text := line_continues and line ≢ "";
				line_start := i + 1;
			}
			i++;
		}
		self._error("Invalid final multiline whitespace escape")
			if last_line_continued_with_text;
		return out;
	}

	method _unescape_multiline_line ( String line ) {
		let out := "";
		let i := 0;
		while ( i < length line ) {
			let ch := substr( line, i, 1 );
			if ( ch ≢ "\\" ) {
				out _= ch;
				i++;
				next;
			}

			i++;
			self._error("Unterminated string escape") if i >= length line;
			ch := substr( line, i, 1 );
			if ( ch ≡ "\"" ) { out _= "\""; }
			else if ( ch ≡ "\\" ) { out _= "\\"; }
			else if ( ch ≡ "b" ) { out _= chr(8); }
			else if ( ch ≡ "f" ) { out _= chr(12); }
			else if ( ch ≡ "n" ) { out _= "\n"; }
			else if ( ch ≡ "r" ) { out _= "\r"; }
			else if ( ch ≡ "s" ) { out _= " "; }
			else if ( ch ≡ "t" ) { out _= "\t"; }
			else if ( _kdl_is_ws(ch) ) {
				while ( i < length line and _kdl_is_ws( substr( line, i, 1 ) ) ) {
					i++;
				}
				i--;
			}
			else if ( ch ≡ "u" ) {
				self._error("Expected '{' in Unicode escape")
					if substr( line, i + 1, 1 ) ≢ "{";
				i += 2;
				let start := i;
				while ( i < length line and substr( line, i, 1 ) ≢ "}" ) {
					self._error("Invalid Unicode escape")
						if not _kdl_is_hex_digit( substr( line, i, 1 ) );
					i++;
				}
				self._error("Unterminated Unicode escape")
					if i >= length line;
				let raw := substr( line, start, i - start );
				self._error("Unicode escape must contain 1 to 6 hex digits")
					if length raw < 1 or length raw > 6;
				let code := _kdl_from_hex(raw);
				out _= chr(code);
			}
			else {
				self._error( `Invalid string escape '\\${ch}'` );
			}
			i++;
		}
		return out;
	}
}

function _kdl_value ( value ) {
	if ( value instanceof KDLValue ) {
		return value;
	}
	if ( value ≡ null ) {
		return new KDLValue( type: "null", value: null );
	}
	if ( value instanceof Boolean ) {
		return new KDLValue( type: "boolean", value: value );
	}
	if ( value instanceof Number ) {
		return new KDLValue( type: "number", kind: "float", value: value );
	}
	return new KDLValue( type: "string", value: "" _ value );
}

function _kdl_encode_value ( value, Boolean canonical := false ) {
	let v := _kdl_value(value);
	let prefix := "";
	if ( v.type_annotation() ≢ null ) {
		prefix := "(" _ _kdl_name( v.type_annotation() ) _ ")";
	}
	if ( v.is_null() ) { return prefix _ "#null"; }
	if ( v.is_boolean() ) {
		return prefix _ ( v.native_value() ? "#true" : "#false" );
	}
	if ( v.is_number() ) {
		if ( canonical and v.canonical_number() ≢ null ) {
			return prefix _ v.canonical_number();
		}
		return prefix _ ( v.kind() ≡ "string" ? v.value() : "" _ v.value() );
	}
	if ( v.is_string() ) {
		if ( canonical and _kdl_is_plain_ident( v.native_value() ) ) {
			return prefix _ v.native_value();
		}
		return prefix _ "\"" _ _kdl_escape_string( v.native_value() ) _ "\"";
	}

	let native := v.native_value();
	try {
		if ( native can "to_String" ) {
			let text := native.to_String();
			if ( canonical and _kdl_is_plain_ident(text) ) {
				return prefix _ text;
			}
			return prefix _ "\"" _ _kdl_escape_string(text) _ "\"";
		}
	}
	catch {
	}

	die `Cannot serialize KDLValue of type '${v.type()}'`;
}

function _kdl_encode_node (
	KDLNode node,
	Number level,
	Boolean canonical := false,
) {
	let out := _kdl_indent( level, canonical );
	if ( node.type_annotation() ≢ null ) {
		out _= "(" _ _kdl_name( node.type_annotation() ) _ ")";
	}
	out _= _kdl_name( node.name() );
	for ( let arg in node.args() ) {
		out _= " " _ _kdl_encode_value( arg, canonical );
	}
	if ( canonical ) {
		for ( let kv in _kdl_canonical_props( node.props() ) ) {
			out _= " " _ _kdl_name(kv[0]) _ "="
				_ _kdl_encode_value( kv[1], canonical );
		}
	}
	else {
		for ( let pair in node.props().to_Array() ) {
			let kv := pair{pair};
			out _= " " _ _kdl_name(kv[0]) _ "="
				_ _kdl_encode_value( kv[1], canonical );
		}
	}
	if ( node.children().length() > 0 ) {
		out _= " {\n";
		let i := 0;
		while ( i < node.children().length() ) {
			out _= _kdl_encode_node(
				node.children()[i],
				level + 1,
				canonical,
			);
			out _= "\n";
			i++;
		}
		out _= _kdl_indent( level, canonical ) _ "}";
	}
	return out;
}

function _kdl_encode_document ( KDLDocument doc, Boolean canonical := false ) {
	let out := "";
	let i := 0;
	while ( i < doc.nodes().length() ) {
		out _= "\n" if i > 0;
		out _= _kdl_encode_node( doc.nodes()[i], 0, canonical );
		i++;
	}
	out _= "\n" if canonical;
	return out;
}

class KDL {
	let Boolean canonical := false;

	method decode ( String text ) {
		return new _KDLParser( text: text, pos: 0 )._parse_document();
	}

	method decode_binarystring ( BinaryString raw ) {
		return self.decode( to_string(raw) );
	}

	method encode ( value ) {
		if ( value instanceof KDLDocument ) {
			return _kdl_encode_document( value, canonical );
		}
		if ( value instanceof KDLNode ) {
			return _kdl_encode_node( value, 0, canonical );
		}
		if ( value instanceof Array ) {
			return _kdl_encode_document(
				new KDLDocument( nodes: value ),
				canonical,
			);
		}
		die "KDL.encode expects a KDLDocument, KDLNode, or Array of KDLNode";
	}

	method encode_binarystring ( value ) {
		return to_binary( self.encode(value) );
	}

	method load ( path ) {
		from std/io import Path;
		die "KDL.load is denied by runtime policy" if __system__{deny_fs};
		die "KDL.load expects a std/io Path object" if not( path instanceof Path );
		return self.decode_binarystring( path.slurp() );
	}

	method dump ( path, value ) {
		from std/io import Path;
		die "KDL.dump is denied by runtime policy" if __system__{deny_fs};
		die "KDL.dump expects a std/io Path object" if not( path instanceof Path );
		path.spew( self.encode_binarystring(value) );
		return path;
	}
}
