KDL-JS

A JavaScript library for the KDL Document Language.

Install

npm install kdljs

Usage

Parsing

const { parse } = require('kdljs')
parse(`
// Nodes can be separated into multiple lines
title \
  "Some title"
`)

// [
//   {
//     name: 'title',
//     properties: {},
//     values: [ 'Some title' ],
//     children: [],
//     tags: {
//       name: undefined,
//       properties: {},
//       values: [ undefined ]
//     }
//   }
// ]

parse(`
// Files must be utf8 encoded!
smile "😁"
`)

// [
//   {
//     name: 'smile',
//     properties: {},
//     values: [ '😁' ],
//     children: [],
//     tags: {
//       name: undefined,
//       properties: {},
//       values: [ undefined ]
//     }
//   }
// ]

parse(`
// Instead of anonymous nodes, nodes and properties can be wrapped
// in "" for arbitrary node names.
"!@#$@$%Q#$%~@!40" "1.2.3" "!!!!!"=true
`)

// [
//   {
//     name: '!@#$@$%Q#$%~@!40',
//     properties: { '!!!!!': true },
//     values: [ '1.2.3' ],
//     children: [],
//     tags: {
//       name: undefined,
//       properties: { '!!!!!': undefined },
//       values: [ undefined ]
//     }
//   }
// ]

parse(`
// The following is a legal bare identifier:
foo123~!@#$%^&*.:'|/?+ "weeee"

// And you can also use unicode!
ノード お名前＝"☜(ﾟヮﾟ☜)"
`)

// [
//   {
//     name: "foo123~!@#$%^&*.:'|/?+",
//     properties: {},
//     values: [ 'weeee' ],
//     children: [],
//     tags: {
//       name: undefined,
//       properties: {},
//       values: [ undefined ]
//     }
//   },
//   {
//     name: 'ノード',
//     properties: { 'お名前': '☜(ﾟヮﾟ☜)' },
//     values: [],
//     children: [],
//     tags: {
//       name: undefined,
//       properties: {},
//       values: []
//     }
//   }
// ]

parse(`
// kdl specifically allows properties and values to be
// interspersed with each other, much like CLI commands.
foo bar=true "baz" quux=false 1 2 3
`)

// [
//   {
//     name: 'foo',
//     properties: { bar: true, quux: false },
//     values: [ 'baz', 1, 2, 3 ],
//     children: [],
//     tags: {
//       name: undefined,
//       properties: { bar: undefined, quux: undefined },
//       values: [ undefined, undefined, undefined, undefined ]
//     }
//   }
// ]

parse(`
// kdl also allows for annotationg values with types, and
// for denoting relations between nodes.
package {
  (author)person contact=(email)"[email protected]"
  (contributor)person homepage=(url)"https://example.org/example"
}

// [
//   {
//     name: 'package',
//     properties: {},
//     values: [],
//     children: [
//       {
//         name: 'person',
//         properties: { contact: '[email protected]' },
//         values: [],
//         children: [],
//         tags: {
//           name: 'author',
//           properties: { contact: 'email' },
//           values: []
//         }
//       },
//       {
//         name: 'person',
//         properties: { homepage: 'https://example.org/example' },
//         values: [],
//         children: [],
//         tags: {
//           name: 'contributor',
//           properties: { homepage: 'url' },
//           values: []
//         }
//       }
//     ]
//   }
// ]
`)

Querying

const { parse, query } = require('kdljs')

const { output: document } = parse(`package {
    name "foo"
    version "1.0.0"
    dependencies platform="windows" {
        winapi "1.0.0" path="./crates/my-winapi-fork"
    }
    dependencies {
        miette "2.0.0" dev=true
    }
}`)

query(document, 'package name') // or
query(document, 'top() > package name')

// [
//   {
//     name: 'name',
//     values: ['foo'],
//     ...
//   }
// ]

query(document, 'dependencies')

// [
//   {
//     name: 'dependencies',
//     properties: { platform: 'windows' },
//     ...
//   },
//   {
//     name: 'dependencies',
//     ...
//   }
// ]

query(document, 'dependencies[platform]') // or
query(document, 'dependencies[prop(platform)]')

// [
//   {
//     name: 'dependencies',
//     properties: { platform: 'windows' },
//     ...
//   }
// ]

query(document, 'dependencies > []')

// [
//   {
//     name: 'winapi',
//     properties: { path: './crates/my-winapi-fork' },
//     values: [ '1.0.0' ],
//     ...
//   },
//   {
//     name: 'miette',
//     properties: { dev: 'true' },
//     values: [ '2.0.0' ],
//     ...
//   }
// ]

// MAP OPERATOR
// ============

query(document, 'package name => val()')
// ['foo'].

query(document, 'dependencies[platform] => platform')
// ['windows']

query(document, 'dependencies > [] => (name(), val(), path)')
// [('winapi', '1.0.0', './crates/my-winapi-fork'), ('miette', '2.0.0', None)]

query(document, 'dependencies > [] => (name(), values(), props())')
// [('winapi', ['1.0.0'], {'platform': 'windows'}), ('miette', ['2.0.0'], {'dev': true})]

Formatting

const { format } = require('kdljs')

format([
  {
    name: 'title',
    properties: {},
    values: [ 'Some title' ],
    children: [],
    tags: { properties: {}, values: [] }
  },
  {
    name: 'smile',
    properties: {},
    values: [ '😁' ],
    children: [],
    tags: { properties: {}, values: [] }
  },
  {
    name: '!@#$@$%Q#$%~@!40',
    properties: { '!!!!!': true },
    values: [ '1.2.3' ],
    children: [],
    tags: { properties: {}, values: [] }
  },
  {
    name: "foo123~!@#$%^&*.:'|/?+",
    properties: {},
    values: [ 'weeee' ],
    children: [],
    tags: { properties: {}, values: [] }
  },
  {
    name: 'ノード',
    properties: { 'お名前': '☜(ﾟヮﾟ☜)' },
    values: [],
    children: [],
    tags: { properties: {}, values: [] }
  },
  {
    name: 'foo',
    properties: { bar: true, quux: false },
    values: [ 'baz', 1, 2, 3 ],
    children: [],
    tags: { properties: {}, values: [] }
  }
])

`title "Some title"
smile "😁"
"!@#$@$%Q#$%~@!40" "1.2.3" !!!!!=true
foo123~!@#$%^&*.:'|/?+ "weeee"
ノード お名前="☜(ﾟヮﾟ☜)"
foo "baz" 1 2 3 bar=true quux=false
`

License

The code is available under the MIT license. The example above is made available from https://github.com/kdl-org/kdl under Creative Commons Attribution-ShareAlike 4.0 International. The submodule in test/kdl4j is licensed according to its LICENSE.md file.