kdl-test

An implementation-agnostic test suite for KDL implementations.

The official test cases are underspecified and requires implementations have a rendering implementation (ref). kdl-test only requires that implementations can parse a KDL document, and validates values via a JSON protocol.

Installation

Download binaries on the releases page.

Alternatively, use dotslash using the config in the GitHub release notes.

Usage

kdl-test --decoder my-kdl-decoder

You should implement a my-kdl-decoder executable for your implementation with the following interface:

• Accept KDL input on stdin
• If the KDL data is invalid, return a non-zero exit code
  • You may output error information to stderr, for debugging
• If the KDL data is valid, output the JSON encoding of that data on stdout and return with a zero exit code

JSON encoding

Node lists (and therefore documents) are represented as a JSON array.

Nodes are represented as a JSON object with the following schema. All keys are required.

{
  "type": "type_of_node", // `null` if no annotation
  "name": "name_of_node",
  "args": [
    {
      "type": "type_of_value", // `null` if no annotation
      "value": { /* See Value encoding */ }
    }
  ],
  "props": {
    "name_of_prop": {
      "type": "type_of_value", // `null` if no annotation
      "value": { /* See Value encoding */ }
    }
  },
  "children": [ /* nodes */ ]
}

Values are represented as a JSON object with the following schema.

// String
//   Multi-line + raw strings are converted to single-line strings
{
  "type": "string",
  "value": "hello world"
}

// Number
//   Ints should always include ".0"
//   Hex/octal/binary should be decoded
//   Keywords should be "inf", "-inf", "nan"
{
  "type": "number",
  "value": "123.0"
}

// Boolean
{
  "type": "boolean",
  "value": "true"
}

// Null
{
  "type": "null"
}

Example:

• KDL input
• Expected JSON