TOML配置文件格式全面解析

TOML配置文件格式全面解析

toml Tom's Obvious, Minimal Language 项目地址: https://gitcode.com/gh_mirrors/to/toml

TOML（Tom's Obvious, Minimal Language）是一种现代化的配置文件格式，旨在通过直观的语义实现易读性。本文将全面介绍TOML的核心语法特性，帮助开发者掌握这一简洁高效的配置语言。

TOML基础概念

TOML具有以下基本特性：

• 严格区分大小写
• 使用制表符（U+0009）或空格（U+0020）作为空白字符
• 换行符可以是LF（U+000A）或CRLF（U+000D U+000A）
• 文件必须采用UTF-8编码

注释规范

TOML使用#符号表示注释，从#开始到行尾的内容都会被解析器忽略：

# 这是整行注释
server = "example.com"  # 行尾注释

注意：注释中的控制字符（除制表符外）都是不允许的。

键值对结构

键值对是TOML的基本构建块，格式为key = value：

title = "TOML示例"
port = 8080
enabled = true

值支持多种数据类型，包括字符串、数字、布尔值、日期时间等。

键的命名规则

TOML支持三种键命名方式：

1. 裸键（Bare keys）：仅包含字母、数字、下划线和连字符

   server_name = "example"
   port_8080 = true
   

2. 引号键（Quoted keys）：使用双引号或单引号包裹

   "127.0.0.1" = "localhost"
   'special@key' = "value"
   

3. 点分隔键（Dotted keys）：用于创建嵌套结构

   database.connection.max = 100
   user.profile.name = "Alice"
   

数据类型详解

字符串类型

TOML提供四种字符串表示方式：

1. 基本字符串：双引号包裹，支持转义

   str1 = "I'm a string. \nNew line here."
   

2. 多行基本字符串：三个双引号包裹，保留换行

   str2 = """
   This is a
   multi-line
   string"""
   

3. 字面字符串：单引号包裹，不处理转义

   path = 'C:\Users\Documents'
   

4. 多行字面字符串：三个单引号包裹

   str3 = '''
   No escape
   processing'''
   

数值类型

整数支持十进制、十六进制、八进制和二进制表示：

int1 = 42
int2 = 0xFF  # 十六进制
int3 = 0o755 # 八进制
int4 = 0b1101 # 二进制

浮点数支持科学计数法：

float1 = 3.1415
float2 = 6.626e-34

布尔值

仅接受小写的true和false：

enabled = true
debug_mode = false

日期时间类型

TOML支持多种日期时间格式：

1. 带时区偏移的日期时间：

   dt1 = 2023-05-15T12:30:45Z
   dt2 = 2023-05-15T12:30:45+08:00
   

2. 本地日期时间（不含时区）：

   ldt = 2023-05-15T12:30:45
   

3. 本地日期：

   date = 2023-05-15
   

4. 本地时间：

   time = 12:30:45
   

复合数据结构

数组

使用方括号定义，元素类型可以混合：

ports = [ 80, 443, 8080 ]
mixed = [ "text", 42, true ]

表（Tables）

表用于创建嵌套结构，有两种定义方式：

1. 标准表：

   [database]
   server = "192.168.1.1"
   ports = [ 8001, 8002 ]
   

2. 内联表（紧凑格式）：

   database = { server = "192.168.1.1", ports = [8001, 8002] }
   

表数组

表示多个相同结构的配置项：

[[products]]
name = "Hammer"
sku = 738594937

[[products]]
name = "Nail"
sku = 284758393

最佳实践建议

1. 键命名：优先使用裸键，仅在必要时使用引号键
2. 组织结构：相关配置项使用点分隔键或表进行分组
3. 日期时间：需要明确时区时使用带偏移的格式
4. 大数字：使用下划线增强可读性（如1_000_000）
5. 字符串：短字符串用基本格式，长文本用多行格式

常见错误规避

1. 避免重复定义键
2. 不要混合使用裸键和引号键表示相同键名
3. 浮点数必须包含小数点前后的数字
4. 整数不能有前导零（八进制/十六进制除外）
5. 表定义后不能直接修改为简单值

TOML通过其简洁明了的语法和强大的表达能力，已经成为许多现代应用的首选配置格式。掌握这些核心概念后，开发者可以编写出既易于维护又便于机器解析的配置文件。

toml Tom's Obvious, Minimal Language 项目地址: https://gitcode.com/gh_mirrors/to/toml