查看“︁LNNBot/指令”︁的源代码

'''指令'''是 LNNBot 功能的一类，基于 Koishi.js 框架的指令系统，可通过发送以斜杠（<code>/</code>）开头的消息来调用，有共通的语法。

== 语法 ==

在 Koishi.js 框架中，指令由'''名称'''、若干'''参数'''和若干'''选项'''组成，其间使用空格、换行等空白字符分隔。一般情况下，指令选项和参数可以任意排列顺序。

=== 参数 ===

参数可以是不含空白字符的内容或用引号（<code>""</code>、<code><nowiki>''</nowiki></code>、-{<code>“”</code>、<code>‘’</code>}-）包围的任意内容，如果参数值本身就以引号开头和结尾则需要再加一层引号（可以是相同的引号，如 <code>""content""</code>）。

参数分为'''必填参数'''和'''可选参数'''，在指令用法中分别使用角括号和方括号包围参数名表示，如指令 <code>[[LNNBot/指令/5k|5k]]</code> 有一个必填参数 <code>text1</code> 和一个可选参数 <code>text2</code>，写作 <code>5k <text1> [text2]</code>。

有些指令有'''可变参数'''，即接受任意数量的额外参数，在指令用法中表示为最后一个参数的名称''前''加三点（如<code><...words></code>；区别于下文的''贪婪值''）。

=== 选项 ===

选项的通用语法是''两个''横杠（<code>--</code>）后紧跟'''选项名'''。很多选项是'''具值选项'''，它们后面需要再跟一个'''选项值'''，选项值的语法类似于参数。选项名和选项值之间由空白字符或一个等号（<code>=</code>）相隔，等号之后也可以有空白。等号后不能紧跟使用引号语法的选项值，可以在等号后添加空白或直接用空白代替等号。

大多数选项有单个字符的'''短名'''，可以用''一个''横杠后跟短名的'''短语法'''表示（如 <code>-a</code>）。短语法可以'''串联'''，写成一个横杠后连续跟上多个选项的短名（如 <code>-abc</code>）。串联短语法中除最后一个选项外，其他具值选项（若有）的值为空，最后一个选项可以正常指定值（如 <code>-abc "选项c的值"</code>）。

有些选项有'''符号名'''，可以用一个或几个特殊符号（如 <code>/</code>、<code>--</code>）的'''符号语法'''表示。具值选项使用符号语法时不能使用等号分隔名和值，只能用空白字符分隔。

有些指令使用'''严格选项解析'''，这些指令在解析时若遇到不存在的长、短选项，会将其视为参数，而非报错或忽略。

=== 贪婪值 ===

有些选项/参数是'''贪婪选项'''/'''贪婪参数'''（贪婪选项的值和贪婪参数合称'''贪婪值'''），它们会使指令其余的部分不再解析选项和参数语法，直接视为一个值（首尾若有引号也会视为值的一部分）。因此，贪婪值必须写在指令的末尾（即使用贪婪参数时其他参数和所有选项必须写在贪婪参数之前，使用贪婪选项时其他选项和所有参数必须写在贪婪选项之前），且贪婪选项和贪婪参数不能同时使用。贪婪值在指令用法中表示为值名称''后''加三点（如 <code><input...></code>；区别于上文的''可变参数''）。

=== 插值 ===

'''插值'''是将一条指令的结果直接作为另一条指令输入的一部分的功能，可以用于指令的参数和选项（包括贪婪值）内，但在直单引号（<code><nowiki>''</nowiki></code>）包围的值中无效。基本的插值语法是 <code>$(指令)</code>（被插值的指令不可包含半角右圆括号），同时也存在一些其他插值语法，会直接使用对应的指令进行插值：

{|class="wikitable"
! 语法 !! 等价指令 !! 备注
|-
| <code>${代码...}</code> || <code>[[LNNBot/指令/evaluate|eval]] 代码...</code> ||
|-
| <code>$¿{代码...}</code> || <code>[[LNNBot/指令/whatlang|whatlang]] 代码...</code> ||
|-
| <code>$¿(名称 参数...)</code> || <code>[[LNNBot/指令/whatcmd|whatcmd]] 名称 参数...</code> || WhatCommands指令不可包含半角右圆括号
|}

在一些情况下（如输入 JavaScript 代码时），我们可能不希望指令系统解析插值语法。在 QQ 平台，对于一些会自动过滤掉 QQ 表情的指令（如 <code>[[LNNBot/指令/evaluate|eval]]</code>），可以通过在美元符与括号之间添加一个 QQ 表情来“转义”插值语法。也可以通过先发送代码，再引用这条消息调用指令的方法来绕过插值解析。

== 机制 ==

=== 查询帮助 ===

指令 <code>[[LNNBot/指令/help|help]]</code> 可显示指令菜单或查询特定指令的帮助。有些指令是'''隐藏指令'''，不会出现在菜单里，但仍能通过 <code>help</code> 查询到其帮助信息。

=== 特殊调用方式 ===

在 QQ 私聊和部分群聊调用指令时可以省略斜杠，直接发送指令内容；在 Discord 平台，因为斜杠有时是一种特殊语法，所以也允许以两个斜杠开头。

部分指令也能用其他独特的语法来调用，称为'''快捷方式'''，如 <code>[[LNNBot/指令/evaluate|eval]]</code> 指令可以通过发送大于号和空格开头的消息来调用。

=== 捕获引用 ===

当调用指令的消息引用（回复）了另一条消息，大多数指令都会将被引用的消息内容自动添加到指令末尾作为参数或选项值。若指令使用了贪婪参数或选项，则会将被引用内容直接添加到贪婪值的末尾。

=== 请求输入参数 ===

有些指令在缺少必填参数时，会显示“请发送''(参数描述)''…”（区别于报错“缺少''某参数''…”），调用指令的用户若在 1 分钟内在同一聊天内发送了消息，bot 会将该消息的内容作为缺少的参数使用。目前无法在 bot 请求输入参数时手动取消调用，需要等待 1 分钟或通过发送一条任意内容来完成调用，否则直接重新进行指令调用不会被 bot 正常识别。

=== 子指令 ===

有些指令是另一个指令的'''子指令'''。子指令不会在顶层帮助菜单中显示，只会在其父指令的帮助信息内显示。子指令分为'''层级式'''和'''派生式'''两种，派生式子指令的名称总是以其父指令的名称加句点（<code>.</code>）开头。

有些指令本身并没有功能，仅用于收纳其他指令作为子指令，称为'''分组指令'''。调用分组指令的派生式子指令时可以用空格代替指令名中的句点；而如果直接调用分组指令本身，或将空格替换为句点后并不是一个存在的派生式子指令名称，则会直接显示分组指令的帮助信息。

== 指令列表 ==

指令文档索引尚未建成，您可以浏览下列已编写的指令条目：

{{Special:PrefixIndex/LNNBot/指令/}}