botml
3.0.1
Botml 是一种声明性且功能强大的标记语言，用于设计现代聊天机器人（又名对话机器人）。
任何人（开发人员和非开发人员）都可以使用它来创建机器人并教机器人如何行为。使用正确的微小格式定义聊天机器人的行为并立即参与对话。亲眼看看：一个仅用两行编写的计算器机器人。
该项目使用node和npm。如果您本地没有安装它们，请检查它们。
$ npm i -g botml这将安装botml节点包和bot客户端。
或者，如果您使用 Atom 作为编辑器，您可能需要使用language-botml包安装语法突出显示。
运行 cli：
$ bot或在您的代码中使用它：
const Botml = require ( 'botml/lib/botml' )
const bot = new Botml ( 'alice.bot' )
bot . start ( )甚至在浏览器中静态加载它：
< script src =' https://unpkg.com/botml ' > </ script >
< script >
const bot = new Botml ( )
// either load an URI:
// bot.load('https://raw.githubusercontent.com/codename-co/botml/master/examples/hello.bot')
// or load the script directly:
bot . parse ( '> *n< yes?n' )
bot . start ( )
bot . send ( 'hey' )
</ script > 现有功能分为两类：满足基本机器人需求的基本功能，以及支持更丰富对话功能的高级功能。
基本特点：
高级功能：
该格式旨在用最少的资源实现最多的效果。通过正确且最少的约定，它可以非常强大。
一般语法遵循3 个重要约定：
最基本的.bot文件是：
! BOTML 1
> Hello
< Hello human!
需要规范行来告诉 Botml 它可以加载文件。
这必须是任何.bot文件的第一行。
! BOTML 1
1代表格式的当前版本。
注释可以帮助您的.bot文件更加清晰。
它们可以用作独立的块，也可以插入可操作的块中。
它们不能内联使用。
# COMMENT
对话是任何机器人的核心概念。它定义了人类和机器人如何交互。
对话必须以>行开头，它定义哪些句子可以激活机器人做出响应。
之后必须有一个或多个<行定义机器人响应。
通过在同一块内重复此序列可以进行多次来回。
> MESSAGE
< MESSAGE
例子：
> Hi
< Hello there. Who are you?
> *
< Nice to meet you.
对话中的随机回复会让机器人感觉不那么僵化。当回复人类时，机器人会随机选择回复候选者。机器人只能选择多个回复候选者之一。
> MESSAGE
< REPLY CANDIDATE #1
< REPLY CANDIDATE #2
例子：
> Hello
< Hi there
< Howdy?
列表有助于组合相似的概念或替代方案。
列表必须以=行开头，它定义列表名称。
它必须至少有一个列表项，但可以有更多。每个列表项都以-符号开头。
= LIST_NAME
- LIST_ITEM
- LIST_ITEM
一个列表项可以引用另一个列表。
= LIST_NAME
- LIST_ITEM
- [ANOTHER_LIST]
可以在>行中引用它来引用输入模式的多个变体。
可以在<行中引用它，以随机引用列表项之一作为响应。
它可以在?中引用。用于引用多个预定义选项的行（提示）。
引用列表是通过用方括号括起列表名称来完成的： [LIST_NAME] 。
例子：
= citrus
- oranges
- lemons
- grapefruits
= random_fruit
- apples
- apricots
- bananas
- [citrus]
> I like [random_fruit]
< Oh. I prefer [random_fruit].
# which is the equivalent to:
# > I like apples
# > I like apricots
# > I like bananas
# > I like oranges
# > I like lemons
# > I like grapefruits
# < Oh. I prefer apples
# < Oh. I prefer apricots
# < Oh. I prefer bananas
# < Oh. I prefer oranges
# < Oh. I prefer lemons
# < Oh. I prefer grapefruits
#
# > I like [random_fruit]
# < Oh. I prefer [random_fruit].
列表也可以用在提示中。
提示是针对特定情况的预定义快速回复。
它们必须放在对话末尾的<行之后。
他们必须引用一个列表才能访问所有快速回复。
快速回复的数量应保持最少。
= LIST_NAME
- LIST_ITEM
- LIST_ITEM
? [LIST_NAME]
例子：
= pizza_types
- Peperroni
- Margherita
- Hawaiian
> I need a pizza
< What kind of pizza?
? [pizza_types]
服务可以利用外部 API 端点。
服务必须在其自己的块中以@符号开头声明。它由名称和 JSON 格式的 API 端点（通过 http 或 https）组成。
它可以（并且大多数时候应该）通过在其端点内使用$符号来接受参数。
@ SERVICE_NAME ENDPOINT
它可以在对话中使用。
当 ENDPOINT 具有$符号时，它必须接受一个参数，该参数的值将替换$符号。
可以使用可选的输出来过滤服务调用的结果。它是一个选择器，其格式为/(.w)+/ 。
@ SERVICE_NAME( PARAMETER )[ OUTPUT ]
例子：
@ geo_domain http://freegeoip.net/json/$
> Where is *{domain}
@ geo_domain($domain).city
< It is running from $.
脚本可用于评估代码。
代码的语言取决于所使用的解析器所使用的语言。 botml解析器采用 Javascript，因此可以使用 Javascript 代码。
它必须内联在用 ``` 包裹的对话中。
它可以访问命名变量：
context.variables.get('price')$price例子：
> It will cost you #{price} USD
< `$price / 1000`k USD is a lot!
变量是检测、格式化、存储和重用有意义信息的方式。
可以在>行（对话）中捕获变量。
它必须是文本 ( $ )、数字 ( # ) 或字母数字 ( * )。
它可以用在<行中。
> My name is *{name}
< Nice to meet you, $name
> I am #{age} years old
< Seems that you are $age
变量格式为${VARIABLE_NAME} （及其数字和字母数字等效项）。但为了方便使用， $VARIABLE_NAME格式也可以用于文本和数字变量。
特殊的$变量总是指对话的最后一个匹配值或上一行的结果（例如服务消费的结果）。
可以在>行中使用正则表达式，以更好地控制要检测的内容。
正则表达式必须用/括起来，并且不能与基本表达式混合使用。
> /^I (?:.+s)?(w+) (?:.+s)?(it|this)/
< Cool bro.
事实上，XRegExp 库是在底层使用的，让您可以访问前导命名捕获、内联注释和模式修饰符。
对话工作流程是经典对话的超集。
工作流程可用于确定精确的对话流程。
它必须以~行开头，用于定义列表名称。
只有一个工作流程可以以<对话开始。当用户连接到机器人时，默认情况下将激活并使用这样的工作流程。
# grocery shopping
> I want to buy *{items}
< How many $items?
> #{count} $items
> #{count}
< There you go.
条件分支是根据测试条件将机器人引导至对话的另一部分的指令。
条件分支以---开头，侦听所有键入的信息，然后用所有情况对其进行测试。每个案例由---分隔：
---
> first input case
< first reply
---
> second input case
< second reply
---
> last input case
< last reply
条件分支与另一个标记为checkpoint 的功能配合得很好。
检查点是工作流程中的标记~ CHECKPOINT_NAME ，这使得在当前对话框的稍后阶段返回它变得轻而易举。可以用~ [CHECKPOINT_NAME]引用，它将流程重定向到检查点标记：
~ ask_howdy
< Hello stranger.
~ checkpoint_name
< How are you?
> meh
< So you feel bad huh
~ [checkpoint_name]
# Example of workflow working:
# < Hello stranger.
# < How are you?
# > meh
# < So you feel bad huh
# < How are you?
# > ...
检查点和列表都使得使用条件分支变得非常有趣：
= mood
- good
- meh
- great
- ok
= exceptions
- fantastic
- better than ever
~ ask_howdy
< hello stranger.
~ listen_howdy
< how are you?
? [mood]
---
> meh
< So you feel bad huh
~ [listen_howdy]
---
> good
< Oh, it is not bad ;)
~ [rechecker]
---
> [exceptions]
< Seems you really cool guy!
---
> ok
< Hmm, just ok? Okay then...
---
> great
< Nice! Let's continue then...
~ rechecker
< Maybe it is more than good?
> excellent
< Much better!
也可以使用“不等于”符号!在条件分支中：
= mood
- [bad_mood]
- [good_mood]
= bad_mood
- meh
- bad
= good_mood
- great
- ok
~ ask_howdy
< hello stranger.
~ listen_howdy
< how are you?
? [mood]
---
> ![mood]
< I asked you how you are ; please let's start over with another answer?
~ [listen_howdy]
---
> [good_mood]
< Oh, it is awesome ;)
---
> [bad_mood]
< Hmm... bye then...
只要返回值，条件分支也适用于脚本。如果脚本返回值true ，则相应的分支将被激活。如果所有测试均为false条件分支将跳过所有分支并继续当前工作流程：
~ ask_for_email
> start email workflow
~ listen_email
< Your email please?
> *{email}
---
` !/^.+@.+..+/.test('$email')
< This email $email seems not legit!
~ [listen_email]
---
< Cool. We'll reach you over at $email
触发器是机器人与其他程序集成的一种方式。
有两种类型的事件：标准事件和自定义事件。
标准事件如下：
'start''patterns:set' ：模式名称和值'match'带有两个字符串参数：标签、模式'current-dialogue-start' ：dialogLabel'reply' ：消息'smart-replies'带有一个数组参数：replies'current-dialogue-end'带有一个字符串参数：dialogLabel'variable:set' ：变量名称和值'quit''*'捕获所有标准和自定义事件可以在对话中触发自定义事件。
自定义事件必须有一个名称。
它可以有参数。参数可以依赖命名变量。
@ trigger( 'EVENT_NAME' [, PARAMETER] )
例子：
> hello
< hi
@ trigger('said_hi')
然后根据您的需要在代码中处理 'said_hi' 事件：
bot . on ( 'said_hi' , ( ) => console . log ( 'The bot said hi' ) ) ; TokensRegex 是一个用于定义基于先验自然语言处理（例如命名实体和词性标记）的高级模式的框架。
> ([ner: PERSON]+) /was|is/ /an?/ []{0,3} /painter|artist/
< An accomplished artist you say.
此功能是通过代码集成启用的。看一个例子。
NLP可以通过代码集成来启用。看一个例子。
请参阅examples/目录。
开始单元测试：
npm test
npm run autotest # this is for continuous testing使用 CLI 从控制台尝试 botml 脚本：
node lib/cli.js
node lib/cli.js examples/echo.bot # load script from a local file
debug=true node lib/cli.js # add logging verbosity在 CLI 模式下，一些特殊命令也可以帮助调试：
随意潜入吧！打开问题或提交 PR。
Botml 已获得 MIT 许可。
