# 双拼方案文本格式

本文档说明自定义双拼方案配置文件（例如 `sp.dat`）的文本格式。

仓库内的示例可参考 `test/testshuangpinprofile.cpp`。

## 概览

双拼方案文件是一个 UTF-8 文本文件。通常会按下面的结构编写：

1. `[方案]`
2. `[零声母标识]`
3. `[声母]`
4. `[韵母]`
5. `[音节]`

示例：

```text
[方案]
方案名称=自定义

[零声母标识]
=O*

[声母]
ch=I
sh=U
zh=V

[韵母]
ai=L
an=J
ang=H
ao=K
ei=Z
en=F
eng=G
er=R
ia=W
ian=M
iang=D
iao=C
ie=X
in=N
ing=Y
iong=S
iu=Q
ong=S
ou=B
ua=W
uai=Y
uan=R
uang=D
ue=T
ui=V
un=P
ve=T
uo=O

[音节]
ju=jv
shi=ui
e=ee
```

## 行规则

- 文件按行解析。
- 空行会被忽略。
- 去掉前导空白后，以 `#` 开头的行会被当作注释。
- 每行前后的空白会被忽略。
- 等号右侧的按键大小写不敏感，内部会统一转换为小写。

`[方案]`、`[韵母]` 这样的分节标题主要用于增强可读性，真正有意义的是
其中的映射行。

## 1. 方案名称

写法：

```text
方案名称=<name>
```

例如：

```text
方案名称=自定义
```

对于自定义方案，请使用 `自定义` 或其他非内建方案名。

下面这些内建名称具有特殊含义：

- `自然码`
- `微软`
- `紫光`
- `拼音加加`
- `中文之星`
- `智能ABC`
- `小鹤`

如果 `方案名称=` 被设置为上述内建名称之一，那么文件里后面的自定义映射
内容会被忽略。因此自定义方案不要使用这些名称。

## 2. 零声母标识

写法：

```text
=<chars>
```

例如：

```text
=O*
=a
=o
```

含义：

- `<chars>` 中每个不是 `*` 的字符，都可以作为零声母音节的首键
- 该值大小写不敏感

例如：

- `=o` 表示允许 `o` 作为零声母标识
- `=a` 表示允许 `a` 作为零声母标识
- `=O*` 表示 `o` 是零声母标识，同时 `*` 会启用下面描述的自然码/小鹤式
  零声母规则

### `*` 的特殊行为

如果零声母标识中包含 `*`，则还会额外生成这种形式的零声母输入：

1. 单字母韵母使用重复按键，例如 `aa`、`ee`
2. 双字母韵母保持全拼形式，例如 `ou`、`en`
3. 更长的韵母使用“全拼首字母 + 该韵母映射键”

例如，如果 `ang=g`，那么零声母 `ang` 可以写成：

```text
ag
```

### 默认行为

如果没有提供有效的零声母标识行，默认标识为 `o`。

只有下面这一行：

```text
=
```

并不表示空零声母标识；它会保持默认行为不变。

## 3. 声母映射

写法：

```text
<initial>=<key>
```

例如：

```text
ch=u
sh=i
zh=v
```

等号右侧必须正好是一个字符。

允许一对多映射：

```text
ch=u
ch=;
zh=o
zh=v
```

如果某个声母的双拼键本来就和它自身的一字母声母相同，通常不需要显式列出。
例如 `b=b`、`m=m` 一般没有必要写。

## 4. 韵母映射

写法：

```text
<final>=<key>
```

例如：

```text
iu=q
ian=w
uang=z
ui=;
v=v
```

等号右侧必须正好是一个字符。

允许一对多映射：

```text
ua=a
ua=m
uo=p
uo=b
```

像 `a`、`e`、`i`、`o`、`u`、`v` 这样的单字母韵母并不总是需要显式列出。
除非你要覆盖默认行为或增加别名，否则它们通常可以直接输入。

## 5. 显式音节映射

写法：

```text
<full-pinyin>=<two-key-input>
```

例如：

```text
ju=jv
e=ee
e=e;
shi=is
zhong=os
yue=yb
```

这一部分用于定义完整音节的显式覆盖或别名，适合那些仅靠声母映射和韵母映射
还不足以表达的情况。

规则：

- 左侧必须是合法的完整拼音音节
- 右侧必须正好是两个字符
- 这两个按键大小写不敏感
- 同一个音节允许定义多个显式映射

这一部分尤其适用于：

- `e`、`ou`、`er` 这类零声母音节
- 一个音节有多个可接受双拼形式的情况
- 兼容性别名
- 自定义消歧选择

## 各部分如何共同生效

一个双拼方案由三类信息共同构成：

1. 声母映射
2. 韵母映射
3. 显式音节映射

此外：

- 单字母声母即使不写出来也会被直接接受
- 单字母韵母也会直接可用
- 显式音节映射会额外增加可接受的两键输入形式
- 同一个声母、韵母或音节都允许多个映射

## 等号右侧支持的字符

按键字符不局限于字母，也允许使用 `;` 这样的标点符号，这在
`test/testshuangpinprofile.cpp` 中就有示例。

例如：

```text
ch=;
ue=;
ui=;
```

每条映射都必须写在单独的一行中。
