@bgotink/kdl

此软件包包含一个解析器和字符串 KDL 文档语言,一种以节点为基础,方便人类的配置和串行格式.

此软件包中的解析器注重以允许格式保留修改的方式解析文档. 这在与人类维护的KDL文件合作时最为有用.

安装

yarn add @bgotink/kdl
# or
npm install @bgotink/kdl
# or
pnpm add @bgotink/kdl
# or ...

使用量

以下例子假设一个节点.js环境. 这个 @bgotink/kdl 软件包在任何javascript运行时间,包括浏览器中工作,只要它支持相对现代的浏览器标准. 如果您想在非节点运行时运行这些样本,请将输入替换为 assert 和你的运行时间相当的东西.

import {parse, format} from "@bgotink/kdl";
import assert from "node:assert/strict";

const doc = parse(String.raw`
    node "value" #"other value"# 2.0 4 #false \
            #null -0 {
        child; "child too"
    }
`);

doc.nodes[0].children.nodes[0].entries.push(
    parse(
        String.raw`/-lorem="ipsum" \
            dolor=#true`,
        {as: "entry"},
    ),
);

assert.equal(
    format(doc),
    String.raw`
    node "value" #"other value"# 2.0 4 #false \
            #null -0 {
        child /-lorem="ipsum" \
            dolor=#true; "child too"
    }
`,
);

JSON-in-KDL(吉克语)

此套件导出功能来自 @bgotink/kdl/json 以 JSON- in- KDL (JiK) 4. 0. 关于格式的资料,见 jiK 4.0.0 规格。 。 。 .

import {parse} from "@bgotink/kdl/json";
import assert from "node:assert/strict";

assert.deepEqual(
    parse(
        String.raw`
            - {
                prop #false
                otherProp {
                    - 0
                    - 2
                    - 4
                }
            }
        `,
    ),
    {
        prop: false,
        otherProp: [0, 2, 4],
    },
);

有四项职能:

• parse 财务报告和审定财务报表 stringify 将文本转换为编码的 JSON 值并返回。 这些功能对于编码/解码整个JiK文件很有用.
• toJson 财务报告和审定财务报表 fromJson 将 KDL 节点转换为编码后的 JSON 值并返回 。 这些函数对输出提供了更精细的控制,可用于例如嵌入到KDL文档的JiK节点的编码/解码.

(去)序号

该软件包包含用于(去)串行化的公用事业 @bgotink/kdl/dessert。 。 。 .

import {parse} from "@bgotink/kdl/dessert";
import assert from "node:assert/strict";

assert.deepEqual(
    parse(
        String.raw`
            name "my-package"
            
            dependency "@bgotink/kdl" range="^0.2.0"
            dependency "prettier" range="^3" dev=#true
        `,
        (ctx) => {
            const dependencies = {};
            const devDependencies = {};

            const name = ctx.child.single.required("name", (ctx) =>
                ctx.argument.required("string"),
            );

            for (const dependency of ctx.children("dependency", (ctx) => ({
                name: ctx.argument.required("string"),
                range: ctx.property("range", "string") ?? "*",
                dev: ctx.property("dev", "boolean") ?? false,
            }))) {
                (dependency.dev ? devDependencies : dependencies)[dependency.name] =
                    dependency.range;
            }

            return {name, dependencies, devDependencies};
        },
    ),
    {
        name: "my-package",
        dependencies: {
            "@bgotink/kdl": "^0.2.0",
        },
        devDependencies: {
            prettier: "^3",
        },
    },
);

KDL v1 数据

软件包导出两个函数 @bgotink/kdl/v1-compat 以支持 KDL v1 中写入的文档 :

• parse 剖析 KDL v1 文档,并将所有链接的格式信息转换为有效的 KDL v2 文档 . 如果产生的文件被传递到 format(),生成的字符串将是同一个文档,但在 KDL v2 语法中。 其中将包括原始文件作者采用的所有评论和格式.
• parseCompat 剖析 KDL v2 或 KDL v1 的文档, 并返回有效的 KDL v2 文档 . 这是一个结合正则 parse 与 v1 兼容的函数 parse 函数为支持两种格式的单一函数.

基尔克

这个软件包将 KDL 文档转换为 JavaScript 对象,反之亦然. 因此受到JavaScript语言的限制.

属性

允许多个同名属性. 将保留所有复制文件,这意味着这些文件将正确往返。 使用时 node.getProperty()编号 :node.getProperties()编号 :node.getPropertyEntry()中,最后一个有该名称值的属性将被返回,从而有效地阴影了任何先前的重复。 使用 node.getPropertyEntries()编号 :node.entries 确实暴露了阴影的复制品, 把它留给呼叫者来处理。 通过节点 clearFormat() 删除这些阴影复制件.

数字

JavaScript 将所有数字存储为 64 位 IEEE 754 (英语) 浮点数. 这限制了哪些整数可以安全使用. 这些限制比您可能预期的要低,如果您习惯于在一个单独的64位整数数据类型的环境中工作.

原表示的解析数字予以保留,除非 clearFormat 使用该值或含有该值的任何条目/节点/文档.

许可证

这个包裹根据麻省理工学院的许可获得许可,可以在 LICENSE.md。 。 。 .

测试套房在 test/upstream 属于 KDL 规格 依据创用CC授权使用.