illegalCreed

中文

English

中文

English

Appearance

键与字符串：裸键、引号键、点分键与四种字符串 ​

基于 TOML 1.0.0 · 核于 2026-07

速查 ​

  • 键三形态：裸键（A-Za-z0-9_-，如 bare-key、1234）／引号键（"127.0.0.1"、'key'，可含任意字符）／点分键（a.b.c，拆成多层表）。
  • 裸键字符集：只允许 ASCII 字母、数字、下划线 _、短横线 -；纯数字键（如 1234）合法。
  • 含点/空格/中文的键：必须用引号键——"127.0.0.1" = "x"；裸写 127.0.0.1 会被当点分键拆成多层。
  • 点分键 a.b.c = 1：为最后一段前的每层自动创建中间（超级）表，等价 { a = { b = { c = 1 } } }；点号两侧空白忽略。
  • 键不可重复定义：同名键（含裸键与引号键同名，如 spelling 与 "spelling"）定义两次 → 报错。
  • 四种字符串："基本" / """多行基本""" / '字面' / '''多行字面'''。
  • 基本字符串（双引号）：支持转义 \b \t \n \f \r \" \\ \uXXXX \UXXXXXXXX；不能裸含控制字符。
  • 多行基本（三双引号）：可跨行；紧跟开头定界符的首个换行被删除；行尾 \ 吃掉其后空白+换行（续行不留换行）。
  • 字面字符串（单引号）：不转义，所见即所得，最适合 Windows 路径 / 正则（'C:\Users\x'）。
  • 多行字面（三单引号）：不转义；首个换行被删除；内部可含 1~2 个连续单引号，不能连续 3 个。
  • ⚠️ 写含 \ 的正则/路径优先用单引号字面；双引号里 \d 等非法转义会报错。

一、键的三种形态 ​

裸键（bare key） ​

不加引号的键，字符集只限 ASCII 字母、数字、下划线 _、短横线 -：

toml
key = "value"
bare_key = "value"
bare-key = "value"
1234 = "value"        # 纯数字也是合法裸键

裸键不能含点/空格/中文

server name = 1（含空格）、site.com = 1（含点，会被当点分键）、名字 = 1（中文）都不能作为裸键——需要改用引号键。

引号键（quoted key） ​

用双引号或单引号包裹，从而突破裸键的字符限制，可包含任意字符：

toml
"127.0.0.1" = "value"
"character encoding" = "value"
"ʎǝʞ" = "value"
'quoted "value"' = "value"
'key2' = "value"

双引号引号键遵循基本字符串规则（可转义），单引号引号键遵循字面字符串规则（不转义）。空引号键 "" = 1 合法但强烈不建议。

点分键（dotted key） ​

用点号把键分成多个层级，是 [table] 表头的紧凑替代：

toml
physical.color = "orange"
physical.shape = "round"
site."google.com" = true    # 引号段可含点，不再拆层

上面等价于：

json
{
  "physical": { "color": "orange", "shape": "round" },
  "site": { "google.com": true }
}

点分键会为最后一段之前的每一层自动创建中间表（称「超级表 super-table」），无需手动先写表头。点号两侧的空白会被忽略，所以 a . b = 1 与 a.b = 1 完全等价（但为可读性建议紧凑写）。

二、键不可重复定义 ​

TOML 为保证「无歧义映射哈希表」，禁止同一个键被定义两次：

toml
# ❌ 非法：name 定义了两次
name = "Tom"
name = "Alice"

# ❌ 非法：裸键与引号键同名 = 同一个键
spelling = "favorite"
"spelling" = "favourite"

引号只是「允许键名包含更多字符」的书写手段，它不会因为加了引号就变成另一个键。修改值应直接改那一行，而不是再写一行覆盖——TOML 没有「后者覆盖」语义，重复即报错。

三、四种字符串 ​

TOML 有四种字符串，围绕两个维度组合：是否转义（基本 vs 字面）× 是否多行（单行 vs 三引号多行）。

基本字符串（双引号） ​

支持反斜杠转义，适合普通文本：

toml
str = "I'm a string. \"You can quote me\". Name\tJosé\nLocation\tSF."

合法转义序列仅限：\b（退格）、\t（制表）、\n（换行）、\f（换页）、\r（回车）、\"（双引号）、\\（反斜杠）、\uXXXX（16 位码点）、\UXXXXXXXX（32 位码点）。其它反斜杠组合（如 \d）是非法转义，多数解析器直接报错。基本字符串里不能裸含控制字符（制表符除外），想换行只能写 \n。

多行基本字符串（三双引号） ​

用 """ 包裹，可以真正跨行：

toml
str1 = """
Roses are red
Violets are blue"""

两条关键规则：

  1. 紧跟开头定界符的首个换行会被删除。所以上例里 str1 的值以 Roses 开头，不会多出一个空行——这让排版可以整齐地「另起一行写正文」。
  2. 行尾反斜杠 \ 是「行连接符」：它会删除其后的所有空白（包括换行和下一行的前导空白），直到遇到第一个非空白字符：
toml
# 下面三行拼成一整句，中间不含任何换行
str2 = """
The quick brown \
   fox jumps over \
   the lazy dog."""
# 结果 = "The quick brown fox jumps over the lazy dog."

字面字符串（单引号） ​

用 ' 包裹，不做任何转义，所见即所得：

toml
winpath  = 'C:\Users\nodejs\templates'
regex    = '<\i\c*\s*>'
quoted   = 'Tom "Dubs" Preston-Werner'

反斜杠、双引号在字面字符串里都是普通字符。这让它成为写 Windows 路径、正则表达式的理想选择——同样内容用双引号基本字符串写，\ 会被当转义符，反而容易报错。字面字符串不能跨行。

多行字面字符串（三单引号） ​

用 ''' 包裹，既不转义、又能跨行：

toml
regex2 = '''I [dw]on't need \d{2} apples'''
lines  = '''
第一行
第二行 \n 这里的 \n 是字面文本，不是换行
'''

同样，紧跟开头定界符的首个换行会被删除。内部可以直接出现 1 个或 2 个连续单引号，但不能连续 3 个（会被当成结束定界符）。

选串口诀

含大量 \ 的正则/路径 → 单引号字面；需要转义（如 \n、\u）→ 双引号基本；一段带换行的长文本 → 三引号多行版本；既有换行又不想被转义 → 三单引号。

字符串搞定后，下一步进入 标量与数组：整数的进制与下划线、浮点的 inf/nan 与非法写法、布尔、四种日期时间，以及数组的混合类型与多行写法。