TOML API

TOML 解析与编辑辅助能力位于 ptool.toml 和 p.toml 下。

ptool.toml.parse

v0.1.0 - 引入。

ptool.toml.parse(input) 将 TOML 字符串解析为 Lua 表。

• input（string，必填）：TOML 文本。
• 返回：Lua 表（根节点始终是 table）。

类型映射：

• TOML table / inline table -> Lua table
• TOML array -> Lua 序列表（从 1 开始）
• TOML string -> Lua string
• TOML integer -> Lua integer
• TOML float -> Lua number
• TOML boolean -> Lua boolean
• TOML datetime/date/time -> Lua string

错误行为：

• 如果 input 不是字符串，会抛出错误。
• 如果 TOML 语法有误，会抛出错误，错误信息中包含行号和列号。

示例：

local text = ptool.fs.read("ptool.toml")
local conf = ptool.toml.parse(text)

print(conf.project.name)
print(conf.build.jobs)
print(conf.release_date) -- datetime/date/time values are strings

ptool.toml.get

v0.1.0 - 引入。

v0.4.0 - 新增数组索引用的数字路径段。

ptool.toml.get(input, path) 从 TOML 文本中读取指定路径上的值。

• input（string，必填）：TOML 文本。
• path（(string|integer)[]，必填）：非空路径数组，例如 {"package", "version"} 或 {"bin", 1, "name"}。
• 返回：对应的 Lua 值；如果路径不存在，则返回 nil。

行为说明：

• 字符串路径段用于选择 table 键。
• 整数路径段用于选择数组元素，采用 Lua 的 1-based 索引。

示例：

local text = ptool.fs.read("Cargo.toml")
local version = ptool.toml.get(text, {"package", "version"})
print(version)

local first_bin_name = ptool.toml.get(text, {"bin", 1, "name"})
print(first_bin_name)

ptool.toml.set

v0.1.0 - 引入。

v0.4.0 - 新增复合值写入和数字路径段。

ptool.toml.set(input, path, value) 设置指定路径上的值，并返回更新后的 TOML 文本。

• input（string，必填）：TOML 文本。
• path（(string|integer)[]，必填）：非空路径数组，例如 {"package", "version"} 或 {"bin", 1, "name"}。
• value（string|integer|number|boolean|table，必填）：要写入的值。
• 返回：更新后的 TOML 字符串。

行为说明：

• 缺失的中间路径会自动创建为 table。
• 如果某个中间路径已存在但不是 table，会抛出错误。
• 仅包含字符串键的 Lua table 会写成 TOML table。
• Lua 序列表会写成 TOML array。
• 由“仅包含字符串键的 Lua table”组成的序列表会写成 TOML array of tables。
• 空 Lua table 目前会按 TOML table 写入。
• 解析和回写基于 toml_edit，会尽可能保留原始注释和格式。

示例：

local text = ptool.fs.read("Cargo.toml")
local updated = ptool.toml.set(text, {"package", "version"}, "0.2.0")
ptool.fs.write("Cargo.toml", updated)

local text2 = ptool.toml.set(text, {"package", "keywords"}, {"lua", "toml"})
local text3 = ptool.toml.set(text2, {"package", "metadata"}, {
  channel = "stable",
  maintainers = {"peterlits"},
})

ptool.toml.remove

v0.1.0 - 引入。

v0.4.0 - 新增数组索引用的数字路径段。

ptool.toml.remove(input, path) 删除指定路径，并返回更新后的 TOML 文本。

• input（string，必填）：TOML 文本。
• path（(string|integer)[]，必填）：非空路径数组，例如 {"package", "name"} 或 {"bin", 1}。
• 返回：更新后的 TOML 字符串。

行为说明：

• 如果路径不存在，不会报错，而是返回原始文本或其等价形式。
• 如果某个中间路径已存在但不是 table，会抛出错误。

示例：

local text = ptool.fs.read("Cargo.toml")
local updated = ptool.toml.remove(text, {"package", "description"})
ptool.fs.write("Cargo.toml", updated)

ptool.toml.stringify

v0.4.0 - 引入。

ptool.toml.stringify(value) 将 Lua 值编码为 TOML 文本。

• value（table，必填）：要编码的根 TOML table。
• 返回：编码后的 TOML 字符串。

行为说明：

• 根值必须是表示 TOML table 的 Lua table。
• 嵌套 Lua table 与 ptool.toml.set 使用相同的 table/array 判定规则。
• 空 Lua table 目前会编码为 TOML table。

示例：

local text = ptool.toml.stringify({
  package = {
    name = "ptool",
    version = "0.4.0",
    keywords = {"lua", "toml"},
  },
})

print(text)

说明：

• ptool.toml.get/set/remove 的 path 参数必须是由字符串和/或正整数构成的非空数组。
• 整数路径段是 1-based 的，与 Lua 数组索引保持一致。
• TOML datetime/date/time 值目前仍会读取为 Lua string。