toml

TOML 是 Tom 的明显、最小化语言的缩写。这个 Go 包提供了一个类似于 Go 标准库中 json 和 xml 包的反射接口。

兼容 TOML 版本 v1.0.0。

文档：https://godocs.io/github.com/BurntSushi/toml

查看发布页面获取更新日志；这些信息也可以在 git 标签注释中找到（例如 git show v0.4.0）。

此库需要 Go 1.18 或更新版本；通过以下命令将其添加到你的 go.mod 中：

% go get github.com/BurntSushi/toml@latest

它还附带了一个 TOML 验证器 CLI 工具：

% go install github.com/BurntSushi/toml/cmd/tomlv@latest
% tomlv some-toml-file.toml

示例

对于最简单的示例，将 TOML 文件视为键值对列表：

Age = 25
Cats = [ "Cauchy", "Plato" ]
Pi = 3.14
Perfection = [ 6, 28, 496, 8128 ]
DOB = 1987-07-05T05:45:00Z

可以通过以下方式解码：

type Config struct {
	Age        int
	Cats       []string
	Pi         float64
	Perfection []int
	DOB        time.Time
}

var conf Config
_, err := toml.Decode(tomlData, &conf)

如果你的结构体字段名称与 TOML 键值不直接对应，你也可以使用结构体标签：

some_key_NAME = "wat"

type TOML struct {
    ObscureKey string `toml:"some_key_NAME"`
}

请注意，与其他解码器一样，只有导出的字段在编码和解码时才会被考虑；私有字段会被静默忽略。

使用 Marshaler 和 encoding.TextUnmarshaler 接口

这里有一个自动解析 mail.Address 值的示例：

contacts = [
    "Donald Duck <donald@duckburg.com>",
    "Scrooge McDuck <scrooge@duckburg.com>",
]

可以通过以下方式解码：

// 创建满足 encoding.TextUnmarshaler 接口的地址类型
type address struct {
	*mail.Address
}

func (a *address) UnmarshalText(text []byte) error {
	var err error
	a.Address, err = mail.ParseAddress(string(text))
	return err
}

// 解码
func decode() {
	blob := `
		contacts = [
			"Donald Duck <donald@duckburg.com>",
			"Scrooge McDuck <scrooge@duckburg.com>",
		]
	`

	var contacts struct {
		Contacts []address
	}

	_, err := toml.Decode(blob, &contacts)
	if err != nil {
		log.Fatal(err)
	}

	for _, c := range contacts.Contacts {
		fmt.Printf("%#v\n", c.Address)
	}

	// 输出：
	// &mail.Address{Name:"Donald Duck", Address:"donald@duckburg.com"}
	// &mail.Address{Name:"Scrooge McDuck", Address:"scrooge@duckburg.com"}
}

要专门针对 TOML，你可以用类似的方式实现 UnmarshalTOML TOML 接口。

更复杂的用法

查看 _example/ 目录获取更复杂的示例。