std/data/kdl

Standard Library documentation

KDL parsing and serialization for ZuzuScript.

Back to Stdlib View Source

Module

Name
std/data/kdl
Area
Standard Library
Source
modules/std/data/kdl.zzm

NAME

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

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);

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.

DESCRIPTION

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

EXPORTS

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

KDLDocument

KDLDocument represents a complete parsed KDL document.

Constructor fields:

  • nodes

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

Methods:

  • nodes()

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

  • to_Iterator()

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

KDLNode

KDLNode represents one KDL node.

Constructor fields:

  • name

    The node name as a String.

  • type_annotation

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

  • args

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

  • props

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

  • children

    An Array of child KDLNode objects. Defaults to an empty Array.

Methods:

  • name()

    Parameters: none. Returns: String. Returns the node name.

  • type_annotation()

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

  • args()

    Parameters: none. Returns: Array. Returns the unnamed argument KDLValue objects.

  • props()

    Parameters: none. Returns: PairList. Returns the named property KDLValue objects.

  • children()

    Parameters: none. Returns: Array. Returns the child KDLNode objects.

  • to_Iterator()

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

KDLValue

KDLValue represents an unnamed argument or named property value.

Constructor fields:

  • type

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

  • kind

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

  • value

    The raw native value.

  • type_annotation

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

  • canonical_number

    The canonical numeric spelling used by canonical serialization, or null.

Methods:

  • type()

    Parameters: none. Returns: String. Returns the value type.

  • kind()

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

  • value()

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

  • type_annotation()

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

  • canonical_number()

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

  • is_null(), is_boolean(), is_number(), is_string()

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

  • is_true(), is_false()

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

  • to_Number()

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

  • to_String()

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

  • to_Boolean()

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

  • native_value()

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

KDL

KDL is the codec class for KDL text.

  • codec.decode(String text)

    Parameters: text is KDL text. Returns: KDLDocument. Parses KDL text.

  • codec.decode_binarystring(BinaryString bytes)

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

  • codec.encode(value)

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

  • codec.encode_binarystring(value)

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

  • codec.load(path)

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

  • codec.dump(path, value)

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

ZPATH

KDLDocument, KDLNode, and KDLValue objects can be queried with 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) );

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.

COPYRIGHT AND LICENCE

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.