一个纯 Lua 5.4 实现的 TOML 1.0.0 规范,具有完整的解析和编码支持。
语言: English | 中文
- ✅ 完整的 TOML 1.0.0 支持 - 解析和编码所有数据类型
- ✅ 零依赖 - 纯 Lua,无需 C 扩展
- ✅ Lua 5.4 原生 - 为 Lua 5.4 优化
- ✅ 全面的测试 - 165 个通过的测试
- ✅ 清晰的错误信息 - 带行/列号的上下文错误
- ✅ 双向转换 - 解析 TOML 到 Lua,编码 Lua 到 TOML
- ✅ 往返安全 - 编码 → 解析 → 编码保留数据
- ✅ 简单的 API - 易于使用的
parse()、encode()、parse_file()、encode_file() - ✅ 快速 - 15K+ 解析操作/秒,160K+ 编码操作/秒
# 复制单文件到您的项目
cp toml.lua /path/to/your/project/lib/单文件版本包含所有功能,只需一个文件即可使用,方便集成到您的项目中。
# 复制模块化源码到您的项目
cp -r src/toml.lua /path/to/your/project/src/
cp -r src/toml /path/to/your/project/src/luarocks install toml-lua
单文件版本:
local toml = require("toml") -- 直接使用单文件
模块化版本:
local toml = require("toml") -- 需要确保 src/toml 和 src/toml.lua 在模块路径中
local toml = require("toml") -- 解析 TOML 字符串 local data = toml.parse([[ name = "Tom" age = 42 active = true fruits = ["apple", "banana"] ]]) print(data.name) --> "Tom" print(data.age) --> 42 print(data.fruits[1]) --> "apple" -- 解析 TOML 文件 local config = toml.parse_file("config.toml")
local toml = require("toml") -- 将 Lua 表编码为 TOML 字符串 -- 默认使用易读格式([[array]] 语法) local data = { name = "Tom", age = 42, items = {"a", "b", "c"} } local toml_string = toml.encode(data) print(toml_string) -- 输出(易读格式): -- age = 42 -- name = "Tom" -- items = ["a", "b", "c"] -- 对于复杂配置,默认生成更易读的格式 local config = { server = "example.com", services = { {name = "web", port = 80}, {name = "db", port = 5432} } } local config_toml = toml.encode(config) -- 输出(默认使用 [[services]] 数组表格式): -- server = "example.com" -- -- [[services]] -- name = "web" -- port = 80 -- [[services]] -- name = "db" -- port = 5432 -- 如需紧凑格式,需要明确指定 local compact_toml = toml.encode(config, { use_array_table_format = false }) -- 输出(内联数组格式): -- server = "example.com" -- services = [{name = "web", port = 80}, {name = "db", port = 5432}] -- 编码并写入文件 local ok, err = toml.encode_file(data, "config.toml")
local original = { name = "Tom", age = 42, config = { debug = true, port = 8080 } } -- 编码为 TOML local toml_string = toml.encode(original) -- 解析回来 local parsed = toml.parse(toml_string) -- 数据被保留! print(parsed.name) --> "Tom" print(parsed.config.port) --> 8080
| 类型 | 状态 | 示例 |
|---|---|---|
| 基本字符串 | ✅ | name = "Tom" |
| 多行字符串 | ✅ | text = """Line 1\nLine 2""" |
| 字面字符串 | ✅ | path = 'C:\Users\path' |
| 整数(十进制/十六进制/八进制/二进制) | ✅ | count = 42,hex = 0xDEADBEEF |
| 浮点数 | ✅ | pi = 3.14,sci = 5e22 |
| 布尔值 | ✅ | active = true |
| 数组 | ✅ | items = ["a", "b", "c"] |
| 表 | ✅ | [section]\nkey = "value" |
| 内联表 | ✅ | user = {name = "Tom", age = 42} |
| 表数组 | ✅ | [[items]]\nname = "item1" |
- 点号键:
server.port = 8080 - 表头:
[database] - 嵌套表:
[parent.child] - 内联表:
{key = "value"} - 数组:
["a", "b", "c"] - 表数组:
[[items]]
将 TOML 字符串解析为 Lua 表。
参数:
input(string): TOML 文档
返回:
table|nil: 解析后的 Lua 表数据,错误时返回nilstring|nil: 解析失败时的错误信息
示例:
local data, err = toml.parse('name = "Tom"') if data then print(data.name) --> "Tom" end
将 TOML 文件解析为 Lua 表。
参数:
path(string): TOML 文件路径
返回:
table|nil: 解析后的 Lua 表数据,错误时返回nilstring|nil: 解析失败时的错误信息
示例:
local config, err = toml.parse_file("config.toml")
验证解析后的数据结构。
参数:
data(table): 解析后的 TOML 数据
返回:
boolean: 有效时返回truestring|nil: 无效时的错误信息
将 Lua 表编码为 TOML 字符串。
参数:
data(table): 要编码的 Lua 表options(table, 可选): 编码选项indent(number): 缩进空格数(默认:2)sort_keys(boolean): 按字母顺序排序键(默认:false)use_table_headers(boolean): 对嵌套表使用表头(默认:false)inline_max_keys(number): 内联表格式的最大键数(默认:3)
返回:
string: TOML 字符串表示
示例:
local data = { name = "Tom", age = 42, items = {"a", "b", "c"} } -- 基本编码 local toml_string = toml.encode(data) -- 带选项 local toml_sorted = toml.encode(data, {sort_keys = true})
将 Lua 表编码并写入 TOML 文件。
参数:
data(table): 要编码的 Lua 表path(string): 输出文件路径options(table, 可选): 编码选项(参见toml.encode)
返回:
boolean: 成功时返回truestring|nil: 失败时的错误信息
示例:
local data = {name = "Tom", age = 42} local ok, err = toml.encode_file(data, "config.toml") if not ok then print("Error:", err) end
# config.toml title = "My App" debug = true port = 8080 [database] host = "localhost" port = 5432 name = "mydb"
local config = toml.parse_file("config.toml") print(config.title) --> "My App" print(config.database.host) --> "localhost"
fruits = ["apple", "banana", "orange"] [server] host = "localhost" port = 8080 [server.ssl] enabled = true cert = "/path/to/cert.pem"
local data = toml.parse_file("config.toml") print(data.fruits[1]) --> "apple" print(data.server.port) --> 8080 print(data.server.ssl.enabled) --> true
user = {name = "Tom", age = 42, active = true} config = {debug = true, port = 8080}
local data = toml.parse(toml_string) print(data.user.name) --> "Tom"
-- 无效的 TOML local data, err = toml.parse('name =') -- 错误输出: -- Parse error: Parse error at line 1, column 6: Expected value -- 文件不存在 local data, err = toml.parse_file("nonexistent.toml") -- 错误输出: -- Cannot open file: nonexistent.toml: No such file or directory
运行测试套件:
# 安装 busted luarocks install busted # 运行测试 busted spec/
测试覆盖率:
- 总测试数: 165 个通过
- 文件: 7 个测试文件
- 覆盖范围: 错误处理、词法分析器、解析器、AST、序列化器、主 API
版本: 1.0.0
进度: 100% 完成
- 带有丰富错误信息的错误处理
- 词法分析器(标记生成器),支持完整的标记支持
- AST 节点定义
- 递归下降解析器
- TOML 序列化器,带格式化选项
- 主模块 API(解析和编码)
- 全面的测试套件(165 个测试)
- 使用示例
- 文档
- 性能优化
- 文档完善
- 阶段 1: 基础(错误处理、词法分析器、测试)
- 阶段 2: 核心解析(解析器、AST)
- 阶段 3: 高级解析(数组、表、内联表)
- 阶段 4: TOML 序列化器(编码、encode_file)
- 阶段 5: 优化和完善(性能、文档)
- 阶段 6: v1.0.0 发布(LuaRocks、合规性)
欢迎贡献!请:
- Fork 仓库
- 创建功能分支
- 为您的更改编写测试
- 确保所有测试通过
- 提交 pull request
# 克隆仓库 git clone https://github.com/yourusername/toml.lua.git cd toml.lua # 运行测试 busted spec/ # 运行解析示例 lua5.4 examples/basic.lua # 运行序列化示例 lua5.4 examples/serializer.lua
MIT 许可证 - 详见 LICENSE 文件
- TOML 1.0.0 规范
- toml-test - 语言无关的测试套件
- Busted - Lua 测试框架
使用 ❤️ 和 Claude Code 创建
注意: 这是一个 1.0.0 版本,API 已稳定。