kdl-org / kdljs Goto Github PK

Would be nice if you could leave out the tags field when formatting if you don't need to format type tags. Currently it just errors if it's missing.

Include a query example.
It's challenging to figure out from just reading the code.

It appears the examples in the readme don't work anymore, as it expects an extra field tags in every node. Please include some examples for how to use this, and what the values mean

Hi! Since this was originally written, KDL has stabilized to 1.0.0. No further changes should be made to spec so it should be safe to update + finalize kdljs to the 1.0 spec!

Please let me know if you have any questions or if there's anything I can do to help!

Apparently I did not implement this part yet...

If I'm reading the grammar right, an invalid unicode escape should cause the parser to fail. The below examples fail parsing in the rust implementation.

Grammar from spec:

character := '\' escape | [^\"]
escape := ["\\/bfnrt] | 'u{' hex-digit{1, 6} '}'

Existing behavior

// Not in 1..6 digits
kdl.parse("node \"\\u{}\"").output[0]
// { name: 'node', properties: {}, values: [ 'u{}' ], children: [] }

// Invalid hex digit(s)
kdl.parse("node \"\\u{xyz}\"").output[0]
// { name: 'node', properties: {}, values: [ 'u{xyz}' ], children: [] }

// Outside range 0..0x10FFFF
kdl.parse("node \"\\u{11FFFF}\"").output[0]
// { name: 'node', properties: {}, values: [ '�' ], children: [] }

// Unterminated unicode escape
kdl.parse("node \"\\u{\"").output[0]
// { name: 'node', properties: {}, values: [ 'u{' ], children: [] }

// Not in 1..6 digits
kdl.parse("node \"\\u{1234567}\"").output[0]
// { name: 'node', properties: {}, values: [ 'u{1234567}' ], children: [] }

Expected behavior

I would expect each of the above examples to fail to parse.

null, true and false are (for now, kdl-org/kdl#49) valid identifiers. However, this is not supported in the parser implementation.

The type for NodeTypeAnnotation is :

export interface NodeTypeAnnotations {    
  /** The type annotation of the Node */    
  name: string;    
  /** The type annotations of the {@link https://github.com/kdl-org/kdl/blob/main/SPEC.md#argument|Arguments} */    
  values: string[];    
  /** The type annotations of the {@link https://github.com/kdl-org/kdl/blob/main/SPEC.md#property|Properties} */    
  properties: Record<string, string>;    
}

However, name can be undefined.

See kdl-org/kdl#50

I'm writing a function in my app to map from generic KDL Node types to my app's specific type:

function nodeToItem(node: kdljs.Node, _index?: number, _array?: kdljs.Node[]): Item {
  return {
    label: node.name,
    run: node.values.map((v)=>String(v)),
    key: node.properties && String(node.properties.key) ,
    items: node.children.map(nodeToItem),
  };
}

But typescript is complaining that the Node type is not exported.

Namespace '"...../node_modules/kdljs/index"' has no exported member 'Node'.

I'm new to typescript so apologies if this is my misunderstanding, but I'm told if kdjls exported the Node type, I could directly use it. For now my workaround is to get access to the type via introspection into the kdljs.format function parameters.

type Node = Parameters<typeof kdljs.format>[0][number]

Similar to #10, I think the parser is supposed to fail if there is an unsupported escape. The rust implementation fails on the example below.

Grammar from spec:

character := '\' escape | [^\"]
escape := ["\\/bfnrt] | 'u{' hex-digit{1, 6} '}'

Existing behavior

kdl.parse("node \"hello \\k world\"").output[0]
// { name: 'node', properties: {}, values: [ 'hello k world' ], children: [] }

Expected behavior

I would expect the above example to fail to parse.

The API is not documented as of yet, I was thinking of just adding JSDoc?

KDL 2.0.0-draft.3 is now generally available (kdl-org/kdl#286), and with it, we've decided to encourage existing implementations to start working towards 2.0 support and send feedback and suggestions for anything you might run into, so I'm making this tracking issue. :)

Legal bare identifiers with a prefix that matches a keyword cause the parser to return errors. I submitted a PR with test cases to the main repo to help test the desired behavior.

Existing behavior

The following examples all return errors

kdl.parse("null_id");
kdl.parse("node null_id=1");

kdl.parse("true_id");
kdl.parse("node true_id=1");

kdl.parse("false_id");
kdl.parse("node false_id=1");

Expected behavior

The above examples should return a valid document with valid nodes.

When making use of KDL as the basis for a config or markup DSL, it'd be nice to be able to include line numbers in validation error output.

Only Commonjs support now~

See kdl-org/kdl#255: non-ASCII whitespace (and U+00A0) should also be excluded from bare identifiers.