@ effected/toml (帮助)

零依赖性 TOML 1.1.0 解析,编辑和格式化,以Effect schemas和纯函数表示. 将 TOML 分析为纯值或字节精确线性 CST, 计算注释保留编辑, 格式, 通过路径修改, 将文档行走为 Stream,并直接解码为已验证域名计划.

预1.0.0。 。 。 . 此软件包是 @effected/* 在稳定基础上建造的工具包 效应v4(effect ~4.1.0) 并仍在 0.x 发展。 稳定效果 制作一个工具箱 1.0.0 可能,不是自动的。 为了保持你的 effect 财务报告和审定财务报表 @effect/* 该工具包在线上构建和测试、安装 @effected/pnpm-plugin-effected。 。 。 .

稳定:不稳定. 此软件包的 API 表面尚未考虑 完成并可能改变 0.x 释放 定一个确切的版本——甚至 标记软件包 稳定 在此之前 1.0.0 可以引入突破性更改 和精确的针 变成一个类型检查错误 而不是一个 跑步时间惊喜。 完全政策: 释放策略。 。 。 .

为什么

TOML 是后面的配置格式 Cargo.toml, (中文(简体) ), pyproject.toml 和一大部分的Rust和Python工具链——人们手持并大量评论的文件. 大多数JavaScript TOML 库通过平面对象模型来回行走,在将文件写回时会丢失每个注释和空白行.

这里的引擎是从头到尾地写在TOML 1.1.0 spec上,这是这个repo中唯一一个销售商完全没有上游代码的格式包. 解析接受所有 1.1 所添加的内容——新行,注释和后置逗号在内线表格中,可选秒数,以及 \e 财务报告和审定财务报表 \xHH 字符串逃出——同时 Toml.stringify 故意出出1.0的拼写,这些拼写是有效的1.1,因此这个包的文档可以保留由1.0-只限消费者读取. 它描述成一个没有损失的线性科技委员会, 其表达方式跨越了源字节的平地,所以 TomlDocument.parse(text).stringify() 复制任何有效文件的正本。 没有单独的可以从源头漂移的再序列化路径. 编辑是对照CST的字节-最小切片,所以格式化和基于路径的修改保存了每一个注释和每一个你没有碰过的字节.

值模型对TOML的类型是诚实的,而不是将其平整为JavaScript的. 整数 ±( 2^53 - 1) 解码为 bigint tOML 的四个日期类型解码为四个日历验证值类别,而不是一个 Date 这不能代表一个当地时间。 TOML 没有无效, 所以 Toml.stringify 含有 null 无法使用结构化 UnsupportedValue 诊断性地点出违法路径,而不是放下钥匙。 每个倒入点都带有一个从 TomlDiagnostic和筑巢 深度的卫士 在剖面和弦侧 意味着敌对输入失败 通过该通道,而不是堆叠溢出.

安装

npm install @effected/toml effect

pnpm add @effected/toml effect

需要节点.js~~24.11.0. effect v4 是一个对等依赖; 软件包本身没有添加其它运行时间依赖 .

全体 @effected/* 软件包仅为无害环境管理:只公布出口地图 import 条件,所以 require() 包括解析 CJS 模式的工具 —— 与节点失败 ERR_PACKAGE_PATH_NOT_EXPORTED 而不是装入不存在的 CJS 建筑。 从ES模块导入.

快开始

准备你的计划 Toml.schema 将 TOML 直接解码为已验证的域值, 或为预先输入的到达 Toml.TomlFromString 仅仅想要纯值时的代码 :

import { Toml } from "@effected/toml";
import { Effect, Schema } from "effect";

const Config = Schema.Struct({ name: Schema.String, port: Schema.Number });
const ConfigFromToml = Toml.schema(Config);

const program = Effect.gen(function* () {
  return yield* Schema.decodeUnknownEffect(ConfigFromToml)(`
    name = "api"
    port = 3000
  `);
});

Effect.runPromise(program).then(console.log);
// { name: "api", port: 3000 }

Toml.stringify 反之,释放出犬科TOML:

import { Toml } from "@effected/toml";
import { Effect } from "effect";

Effect.runPromise(Toml.stringify({ title: "app", server: { port: 8080 } })).then(console.log);
// title = "app"
//
// [server]
// port = 8080

在不丢失注释的情况下编辑

TomlFormat.modify 计算 a TomlEdit 与已解析的科技委的阵列; modifyToString 应用它一步。 编辑不覆盖的评论、空白行和布局通过同字节:

import { TomlFormat } from "@effected/toml";
import { Effect } from "effect";

const source = `# server config
name = "api"
port = 3000 # dev default
`;

Effect.runPromise(TomlFormat.modifyToString(source, ["port"], 8080)).then(console.log);
// # server config
// name = "api"
// port = 8080 # dev default

价值模型

TOML 类型并不都具有JavaScript的等同性,所以没有获得真实的等同性:

四个约会时间班是 Schema.Class 具有真实 Gregorian- calendar 验证和结构等同的值对象,而不是 Date 子类: JavaScript 的 Date 没有办法代表一个没有时间的日期,也没有时间抵消.

TOML 无法代表 null 一点也不 而不是放下密钥或写出一个空字符串, Toml.stringify 失败 :

import { Toml } from "@effected/toml";
import { Effect } from "effect";

Effect.runPromise(Effect.result(Toml.stringify({ a: null }))).then(console.log);
// Failure with TomlStringifyError, whose `diagnostic` carries:
// { code: "UnsupportedValue", message: "unsupported null value at a", ... }

特征

• Toml.parse 编号 : Toml.stringify ——值级解析和犬形字符串,两者均被打入 TomlParseError 编号 : TomlStringifyError 包括筑巢的严密守卫 对抗性输入.
• Toml.fromString 编号 : Toml.TomlFromString 编号 : Toml.schema 直接将 TOML 解码成有效效果的域计划工厂 Schema 数值.
• TomlDocument 无损失文件: parse, (中文(简体) ), schema, (中文(简体) ), toValue 财务报告和审定财务报表 stringify,以线性CST为后盾,其表达方式跨度重建出源字节精确.
• TomlEdit 编号 : TomlRange (与 applyAll() —— 格式和修改器共用的、形状相同的非修改文本编辑词汇 @effected/jsonc还有.. @effected/yaml对.
• TomlFormat —— 说 format 财务报告和审定财务报表 formatToString 计算保守、保留评论格式的编辑; modify 财务报告和审定财务报表 modifyToString 计算编辑以替换、删除或插入路径上的值.
• TomlVisitor ——将解析后的文件作为 Stream 游客活动.
• TomlDiagnostic 结构化诊断code, (中文(简体) ), message, (中文(简体) ), offset, (中文(简体) ), length, (中文(简体) ), line, (中文(简体) ), character每个打出的错误都包含着,跨越了五个阶段的错误编码结合.
• TomlLocalDate 编号 : TomlLocalTime 编号 : TomlLocalDateTime 编号 : TomlOffsetDateTime - TOML 的日期类型为日历验证 Schema.Class 值对象.

遵约

引擎运行 toml 测试 a. 遵约机制——其 files-toml-1.1.0 子集, 214个有效案例和 467个无效案例—— 百分之百的通过率, 没有跳过列表, 不同的属性套件对照独立的 TOML 解析器进行交叉检查 。 两个甲骨文都只具有依赖性;也没有达到你的运行时间.

许可证

麻省理工学院