月度归档:2018年01月

围棋文本通讯协议

Weiqi Text Protocol

第1版

目录

1 前言

1.1 概述

1.2 文本编码

1.3 通讯模式

1.4 辅助符号

2 文本格式

2.1 命令

2.1.1 命令格式

2.1.2 命令说明

2.2 响应

2.2.1 响应格式

2.2.1.1 命令有效或成功

2.2.1.2 命令无效或失败

2.2.2 响应说明

2.3 注释

2.3.1 注释格式

2.3.2 注释说明

3 文本类型

3.1 空

3.2 真假

3.3 整数

3.4 小数

3.5 颜色

3.6 着点

3.7 着手

3.8 局面

3.9 时限

3.10 普通文本

4 内部状态

4.1 内部状态系列

4.2 内部状态缺省值

5 命令列表

5.1 基本命令

5.1.1 管理命令

5.1.1.1 协议版本

5.1.1.2 程序名称

5.1.1.3 程序版本

5.1.1.4 命令列表

5.1.1.5 退出

5.1.2 设置命令

5.1.2.1 棋盘路数

5.1.2.2 添加黑子

5.1.2.3 添加白子

5.1.2.4 设置贴还

5.1.2.5 设置时限

5.1.3 状态命令

5.1.3.1 新局

5.1.3.2 终局

5.1.4 对弈命令

5.1.4.1 下子

5.1.4.2 生成着手

5.1.4.3 悔子

5.2 扩展命令

6 版权

7 致谢

1 前言

1.1 概述

本协议中文名称为”围棋文本协议”,英文名称为”Weiqi Text Protocol”,简称”WTP”。

程序启动后如果在对自己的首次输入中获取字符串”WTP”或”wtp”,应理解为外部对象请求使用本协议与自己通讯。

1.2 文本编码

文本使用gb18030编码。

1.3 通讯模式

程序与外部的交互通讯由“命令-响应”模式驱动。程序始终监测对自己的输入,获取文本后进行分析、处理,然后输出响应。

在通讯过程中,程序是被动的,外部对象反复向程序发送命令,推动对弈的进行,直至终局、中止通讯。外部对象可能来自操作系统的控制台终端,或者是一个图形用户界面,或者是某种语言的脚本,或者是某种协议的计算机网络连接,但本协议并不关心它是谁。

1.4 辅助符号

在本协议中,下面的这些符号用来辅助说明文本的类型或使用方法,实际使用该文本时,并不包含这些符号。部分符号含义如下:

( ) 圆括号。表示圆括号中的文本仅仅是对这个文本实际值的描述。使用时用实际的值代替这个文本。

[ ] 方括号。表示方括号中的文本是可选的。

… 省略号。表示重复前一字符,或者重复前一行文本。

” ” 双引号。表示多字节文本。

‘ ‘ 单引号。表示单字节字符。

2 文本格式

2.1 命令

2.1.1 命令格式

格式如下:

[id ]name[ argument]\n

实际运用的形式可能是下列之一:

name\n

name argument\n

id name\n

id name argument\n

2.1.2 命令说明

命令一般由命令名称和参数两部分组成,之间用一个空格符’ ‘相隔。也可以没有参数。命令名称前可以加命令编号,与命令名称之间也用一个空格符’ ‘分隔。

用一个换行符’\n’表示一条命令结束。

命令与参数只能在一行中。一行命令只能有一个命令名称。

一次只能发送一行命令。

命令编号只能是不小于0的整数。

命令名称只能由下列字符组成:

小写拉丁字母;

下划线’_’;

连字符’-‘。

命令名称只能小写拉丁字母开头。

命令参数中不能有下列字符,如果有将忽略:

小于十进制32的控制符;

删除符(十进制127)。

2.2 响应

2.2.1 响应格式

2.2.1.1 命令有效或成功

如果命令有效或成功,程序输出的文本为返回值。

格式如下:

=[id][ value]\n\n

方括号中的部分是可选项。实际运用的形式可能是下列之一:

=\n\n

= value\n\n

=id\n\n

=id value\n\n

如果返回值是多行,格式如下:

=[id] value\n

…\n

value\n\n

方括号中的部分是可选项。实际运用的形式可能是下列之一:

= value\n

…\n

value\n\n

=id value\n

…\n

value\n\n

2.2.1.2 命令无效或失败

如果命令无效或失败,程序输出的文本为错误消息。

格式如下:

?[id][ message]\n\n

方括号中的部分是可选项。实际运用的形式可能是下列之一:

?\n\n

? message\n\n

?id\n\n

?id message\n\n

如果错误消息是多行,格式如下:

?[id] message\n

…\n

message\n\n

方括号中的部分是可选项。实际运用的形式可能是下列之一:

? message\n

…\n

message\n\n

?id message\n

…\n

message\n\n

2.2.2 响应说明

响应一般由结果、返回值或错误消息两部分组成,之间用一个空格符’ ‘分隔。也可以没有返回值或错误消息。

如果认为命令有效或成功,结果以字符’=’表示,该字符后面如有文本,是返回值;否则,以字符’?’表示,该字符后面如有文本,是错误消息。

如果接收的命令中含有命令编号,则在响应输出的字符’=’或’?’后紧接着输出该命令编号。

用两个连续的换行符”\n\n”表示对一行命令的响应结束。

响应如果有多行,除最后一行外,每行结束用一个换行符’\n’表示。

返回值、错误消息可以是除下列字符外的其他任何字符:

小于十进制32的控制符,除换行符(十进制10)外;

删除符(十进制127)。

如果返回值、错误消息中含有上述字符,忽略掉,而不是视为无效。

2.3 注释

2.3.1 注释格式

格式如下:

#text\n

如果注释是多行,格式如下:

#text\n

#text\n

2.3.2 注释说明

一行中字符’#’后面的文本为注释,可以忽略。

用一个换行符’\n’表示一行中的注释结束。

注释可以出现在一行命令字符串的后半部分,或者一行响应字符串的后半部分。或者整行都是注释。

虽未接受命令的请求,程序也可以自行输出注释。

注释文本可以是任意可打印字符。

3 文本类型

命令的参数和响应的返回值是有类型的,程序和外部对象根据文本类型对参数和响应值进行分析、处理。

3.1 空

格式如下:

(null)

“(null)”在这里说明不是任何值,实际使用时没有任何字符来表示。

3.2 真假

格式如下:

true|false

真为表示”true”,假表示为”false”。

3.3 整数

格式如下:

int

以阿拉伯数字表示的十进制整数。

3.4 小数

格式如下:

float

以阿拉伯数字表示的十进制小数。

3.5 颜色

格式如下:

b|w|e

对局双方或棋盘点的颜色,用小写拉丁字母表示,黑方’b’,白方’w’,空点’e’。

3.6 着点

格式如下:

XY|PASS|RESIGN

棋盘为正方形,有效范围5至25路。缺省为标准的19路。着点以先纵后横的棋盘坐标描述。以左下角为原点。从左到右为纵线X,用大写拉丁字母表示。从下到上为横线Y,以阿拉伯数字表示。纵线坐标有效范围’A’-‘Z’,其中跳过字母’I’。横线坐标有效范围1-25。

如果是虚着,则以”PASS”表示。如果不下子而认输,以”RESIGN”表示。

如果是着点系列,两个着点间以空格符’ ‘分隔。

3.7 着手

格式如下:

(b|w) (XY|PASS|RESIGN)

由颜色和着点两部分组成。

如果是着手系列,从第二手开始省略颜色部分,该手颜色总是前一手的对方;两个着点间以空格符’ ‘分隔。

3.8 局面

格式如下:

b|w|e…

由棋盘各行下子点的颜色组成,到边路则换行。

3.9 时限

格式如下:

maintime overtime overcount

由基本时间(maintime)和读秒(时间overtime,次数overcount)组成,以整数表示。基本时间单位为分种,读秒时间单位为秒。

如果进入读秒,在读秒到最后一秒前作出响应,则重新开始本次读秒。共四种模式:

0 0 0 不使用基本时间和读秒;

maintime 0 0 仅使用基本时间。倒数基本时间,至0则停止计时器;

0 overtime overcount 仅使用读秒。倒数读秒时间,至0时,减少读秒次数,再倒数读秒时间。如果倒数读秒为0时,读秒次数也为0,则停止计时器;

maintime overtime overcount 使用基本时间和读秒。倒数基本时间,至0则开始读秒。

3.10 普通文本

格式如下:

string

除小于十进制32的控制符、删除符(十进制127)以外的字符组成的字符串。推荐单行长度为不要超过1024字节。

4 内部状态

4.1 内部状态系列

棋盘路数

贴还

时限和用时

下子前的局面

着手历史

程序始终维护上述内部状态。这些状态是生成着手的基础,可能被外部改变。

4.2 内部状态缺省值

棋盘路数:19

贴还:0

时限和用时:无

下子前的局面:空

着手历史:无

未经通讯改变,上述程序内部状态总是为缺省值。

5 命令列表

5.1 基本命令

遵循本协议的程序进行对弈必须支持的命令集。

5.1.1 管理命令

5.1.1.1 协议版本

protocol

参数:无。

影响:无。

失败:从不。

输出:整数。

说明:本协议版本号。支持的协议版本应当向下兼容。

5.1.1.2 程序名称

name

参数:无。

影响:无。

失败:从不。

输出:普通文本。

说明:程序名称。不要包含版本号。

5.1.1.3 程序版本

version

参数:无。

影响:无。

失败:从不。

输出:普通文本。

说明:程序的版本号。如果程序没有设置版本号,输出空。

5.1.1.4 命令列表

help

参数:无。

影响:无。

失败:从不。

输出:普通文本。多行。

说明:程序支持的本协议命令列表。每行一个命令名称。不能将多个命令名称放在一行,这样将被识别为一个命令。

5.1.1.5 退出

quit

参数:无。

影响:程序与外部的会话中止,连接关闭。

失败:从不。

输出:无。

说明:退出交互通讯状态。在关闭与一个程序的连接前,必须调用此命令,在获得响应后再关闭连接,确保程序能作一些清理工作。

5.1.2 设置命令

5.1.2.1 棋盘路数

board_size

参数:整数。必需。

影响:棋盘路数。

失败:如果参数文本格式错误。

输出:无。如果失败,输出错误消息。

说明:设置棋盘路数。如果是标准19路棋盘,无需发送此命令。

5.1.2.2 添加黑子

add_black

参数:着点系列。必需。

影响:下子前的局面。

失败:如果参数文本格式错误、着点无效。

输出:无。如果失败,输出错误消息。

说明:在下子前的原始局面上添加黑子。添加的棋子不能使对方或己方棋子无气。如果着点无效,则中止添加棋子,返回错误消息。

5.1.2.3 添加白子

add_white

参数:着点系列。必需。

影响:下子前的局面。

失败:如果参数文本格式错误、着点无效。添加的棋子不能使对方或己方棋子无气。

输出:无。如果失败,输出错误消息。

说明:在下子前的原始局面上添加白子。添加的棋子不能使对方或己方棋子无气。如果着点无效,则中止添加棋子,返回错误消息。

5.1.2.4 设置贴还

recoup

参数:小数。必需。

影响:贴还。

失败:如果参数文本格式错误。

输出:无。如果失败,输出错误消息。

说明:设置贴还。

5.1.2.5 设置时限

time_control

参数:时限。必需。

影响:时限。

失败:如果参数文本格式错误。

输出:无。如果失败,输出错误消息。

说明:设置时限。

5.1.3 状态命令

5.1.3.1 新局

new

参数:无。

影响:内部状态设置为缺省值。

失败:从不。

输出:无。

说明:新局。

5.1.3.2 终局

end

参数:无。

影响:无。

失败:从不。

输出:无。

说明:终局。

5.1.4 对弈命令

5.1.4.1 下子

set

参数:着手。必需。

影响:着手历史。

失败:参数文本格式错误、着手无效。

输出:无。如果失败,输出错误消息。

说明:下子。如果是着手系列,从第二手开始省略颜色部分。

5.1.4.2 生成着手

get

参数:颜色。必需。

影响:着手历史。

失败:从不。

输出:着点。

说明:生成着手并在程序内部下子。

5.1.4.3 悔子

undo

参数:无或整数。

影响:着手历史。

失败:如果程序没有正式着手可取消。

输出:无。如果失败,输出错误消息。

说明:取消最后一手着手,或者指定数量的最后着手。

5.2 扩展命令

一个程序可以根据需要,添加自定义的扩展命令,但不能与本协议已定义的命令同名,不能修改或覆盖本协议已定义的命令。同时,命令及响应的文本格式应当遵守本协议的规范。

推荐在创建一个扩展命令时,按如下格式给出命令的说明:

名称

参数:(有无,类型)。

影响:(有无,被改变的内部状态)。

失败:(会否,原因)。

输出:(有无,类型)。

说明:(使用指导)。

6 版权

版权所有 2017 余俊峰。保留所有权利。

允许遵循GNU自由文档许可证1.2版或更新版的条款复制、发布并且/或修改本文;“目录”及以下的部分是不可变章节。许可证的副本可以从http://www.gnu.org/licenses/fdl.html获取。

7 致谢

本协议基于 Go Text Protocol ,感谢其起草者 Gunnar Farneback 。