From 342d879addb063a02849d16482b18a2161991360 Mon Sep 17 00:00:00 2001
From: yanyongyu <yanyongyu_1@126.com>
Date: Tue, 22 Sep 2020 00:18:57 +0800
Subject: [PATCH] :memo: add matcher tutorial

---
 docs/guide/writing-a-plugin.md | 71 +++++++++++++++++++++++++++++++++-
 nonebot/matcher.py             |  6 +--
 2 files changed, 73 insertions(+), 4 deletions(-)

diff --git a/docs/guide/writing-a-plugin.md b/docs/guide/writing-a-plugin.md
index fbf15695..2a6635d8 100644
--- a/docs/guide/writing-a-plugin.md
+++ b/docs/guide/writing-a-plugin.md
@@ -111,6 +111,75 @@ async def handle_city(bot: Bot, event: Event, state: dict):
     city = state["city"]
     if city not in ["上海", "北京"]:
         await weather.reject("你想查询的城市暂不支持，请重新输入！")
-    city_weather = await get_weather_from_xxx(city)
+    city_weather = await get_weather(city)
     await weather.finish(city_weather)
+
+
+async def get_weather(city: str):
+    return f"{city}的天气是..."
 ```
+
+为了简单起见，我们在这里的例子中没有接入真实的天气数据，但要接入也非常简单，你可以使用中国天气网、和风天气等网站提供的 API。
+
+下面我们来说明这段代码是如何工作的。
+
+:::tip 提示
+从这里开始，你需要对 Python 的 asyncio 编程有所了解，因为 NoneBot 是完全基于 asyncio 的，具体可以参考 [廖雪峰的 Python 教程](https://www.liaoxuefeng.com/wiki/1016959663602400/1017959540289152)
+:::
+
+### 注册一个 [事件响应器](../api/matcher.md)
+
+```python{4}
+from nonebot import on_command
+from nonebot.rule import to_me
+
+weather = on_command("天气", rule=to_me(), priority=5)
+```
+
+在上方代码中，我们注册了一个事件响应器 `Matcher`，它由几个部分组成：
+
+1. `on_command` 注册一个消息类型的命令处理器
+2. `"天气"` 指定 command 参数 - 命令名
+3. `rule` 补充事件响应器的匹配规则
+4. `priority` 事件响应器优先级
+5. `permission` 事件响应器的“使用权限”
+
+其他详细配置可以参考 API 文档，下面我们详细说明各个部分：
+
+#### 事件响应器类型
+
+事件响应器类型其实就是对应 `Event.type` ，NoneBot 提供了一个基础类型事件响应器 `on()` 以及一些内置的事件响应器。
+
+- `on("事件类型")`: 基础事件响应器，第一个参数为事件类型，空字符串表示不限
+- `on_metaevent()` ~ `on("meta_event")`: 元事件响应器
+- `on_message()` ~ `on("message")`: 消息事件响应器
+- `on_request()` ~ `on("request")`: 请求事件响应器
+- `on_notice()` ~ `on("notice")`: 通知事件响应器
+- `on_startswith(str)` ~ `on("message", startswith(str))`: 消息开头匹配处理器
+- `on_endswith(str)` ~ `on("message", endswith(str))`: 消息结尾匹配处理器
+- `on_command(str|tuple)` ~ `on("message", command(str|tuple))`: 命令处理器
+- `on_regax(pattern_str)` ~ `on("message", regax(pattern_str))`: 正则匹配处理器
+
+#### 匹配规则
+
+事件响应器的匹配规则即 `Rule`，由非负个 `RuleChecker` 组成，当所有 `RuleChecker` 返回 `True` 时匹配成功。这些 `RuleChecker` 的形式如下：
+
+```python
+async def check(bot: Bot, event: Event, state: dict) -> bool:
+    return True
+
+def check(bot: Bot, event: Event, state: dict) -> bool:
+    return True
+```
+
+`Rule` 和 `RuleChecker` 之间可以使用 `与 &` 互相组合：
+
+```python
+from nonebot.rule import Rule
+
+Rule(async_checker1) & sync_checker & async_checker2
+```
+
+:::danger 警告
+`Rule(*checkers)` 只接受 async function，或使用 `nonebot.utils.run_sync` 自行包裹 sync function。在使用 `与 &` 时，NoneBot 会自动包裹 sync function
+:::
diff --git a/nonebot/matcher.py b/nonebot/matcher.py
index 351661b9..87321876 100644
--- a/nonebot/matcher.py
+++ b/nonebot/matcher.py
@@ -101,8 +101,7 @@ class Matcher(metaclass=MatcherMeta):
 
     @classmethod
     async def check_perm(cls, bot: Bot, event: Event) -> bool:
-        return (event.type == (cls.type or event.type) and
-                await cls.permission(bot, event))
+        return await cls.permission(bot, event)
 
     @classmethod
     async def check_rule(cls, bot: Bot, event: Event, state: dict) -> bool:
@@ -114,7 +113,8 @@ class Matcher(metaclass=MatcherMeta):
         Returns:
             bool: 条件成立与否
         """
-        return await cls.rule(bot, event, state)
+        return (event.type == (cls.type or event.type) and
+                await cls.rule(bot, event, state))
 
     @classmethod
     def args_parser(cls, func: ArgsParser) -> ArgsParser: