diff --git a/docs/api/exception.md b/docs/api/exception.md index ac2d28b2..817c02a9 100644 --- a/docs/api/exception.md +++ b/docs/api/exception.md @@ -40,6 +40,27 @@ sidebarDepth: 0 +## _exception_ `ParserExit` + +基类:`nonebot.exception.NoneBotException` + + +* **说明** + + `shell command` 处理消息失败时返回的异常 + + + +* **参数** + + + * `status` + + + * `message` + + + ## _exception_ `PausedException` 基类:`nonebot.exception.NoneBotException` diff --git a/docs/api/plugin.md b/docs/api/plugin.md index 24bfb5ab..960521da 100644 --- a/docs/api/plugin.md +++ b/docs/api/plugin.md @@ -507,16 +507,16 @@ def something_else(): -## `on_shell_like_command(cmd, rule=None, aliases=None, shell_like_argsparser=None, **kwargs)` +## `on_shell_command(cmd, rule=None, aliases=None, parser=None, **kwargs)` * **说明** 注册一个支持 `shell_like` 解析参数的命令消息事件响应器。 - 与普通的 `on_command` 不同的是,在添加 `shell_like_argsparser` 参数时, 响应器会自动处理消息, + 与普通的 `on_command` 不同的是,在添加 `parser` 参数时, 响应器会自动处理消息。 - 并将 `shell_like_argsparser` 处理的参数保存在 `state["args"]` 中 + 并将用户输入的原始参数列表保存在 `state["argv"]`, `parser` 处理的参数保存在 `state["args"]` 中 @@ -532,7 +532,7 @@ def something_else(): * `aliases: Optional[Set[Union[str, Tuple[str, ...]]]]`: 命令别名 - * `shell_like_argsparser:Optional[ArgumentParser]`: `argparse.ArgumentParser` 对象,是一个类 `shell` 的 `argsparser` + * `parser: Optional[ArgumentParser]`: `nonebot.rule.ArgumentParser` 对象 * `permission: Optional[Permission]`: 事件响应权限 @@ -680,6 +680,32 @@ def something_else(): +### `shell_command(cmd, **kwargs)` + + +* **说明** + + 注册一个新的命令。 + + + +* **参数** + + + * `cmd: Union[str, Tuple[str, ...]]`: 命令前缀 + + + * `**kwargs`: 其他传递给 `on_command` 的参数,将会覆盖命令组默认值 + + + +* **返回** + + + * `Type[Matcher]` + + + ## _class_ `MatcherGroup` 基类:`object` @@ -1127,6 +1153,63 @@ def something_else(): +### `on_shell_command(cmd, rule=None, aliases=None, parser=None, **kwargs)` + + +* **说明** + + +注册一个支持 `shell_like` 解析参数的命令消息事件响应器。 + +与普通的 `on_command` 不同的是,在添加 `parser` 参数时, 响应器会自动处理消息。 + +并将用户输入的原始参数列表保存在 `state["argv"]`, `parser` 处理的参数保存在 `state["args"]` 中 + + +* **参数** + + + +* `cmd: Union[str, Tuple[str, ...]]`: 指定命令内容 + + +* `rule: Optional[Union[Rule, T_RuleChecker]]`: 事件响应规则 + + +* `aliases: Optional[Set[Union[str, Tuple[str, ...]]]]`: 命令别名 + + +* `parser: Optional[ArgumentParser]`: `nonebot.rule.ArgumentParser` 对象 + + +* `permission: Optional[Permission]`: 事件响应权限 + + +* `handlers: Optional[List[T_Handler]]`: 事件处理函数列表 + + +* `temp: bool`: 是否为临时事件响应器(仅执行一次) + + +* `priority: int`: 事件响应器优先级 + + +* `block: bool`: 是否阻止事件向更低优先级传递 + + +* `state: Optional[T_State]`: 默认 state + + +* `state_factory: Optional[T_StateFactory]`: 默认 state 的工厂函数 + + +* **返回** + + + +* `Type[Matcher]` + + ### `on_regex(pattern, flags=0, rule=None, **kwargs)` diff --git a/docs/api/rule.md b/docs/api/rule.md index e9a8ce4d..b569a400 100644 --- a/docs/api/rule.md +++ b/docs/api/rule.md @@ -170,7 +170,7 @@ Rule(async_function, run_sync(sync_function)) ::: -## `shell_like_command(shell_like_argsparser=None, *cmds)` +## `shell_command(*cmds, parser=None)` * **说明** @@ -179,29 +179,35 @@ Rule(async_function, run_sync(sync_function)) 可以通过 `state["_prefix"]["command"]` 获取匹配成功的命令(例:`("test",)`),通过 `state["_prefix"]["raw_command"]` 获取匹配成功的原始命令文本(例:`"/test"`)。 - 添加 `shell_like_argpsarser` 参数后, 可以自动处理消息并将结果保存在 `state["args"]` 中。 + 可以通过 `state["argv"]` 获取用户输入的原始参数列表 + + 添加 `parser` 参数后, 可以自动处理消息并将结果保存在 `state["args"]` 中。 * **参数** - * `shell_like_argsparser: Optional[ArgumentParser]`: `argparse.ArgumentParser` 对象, 是一个类 `shell` 的 `argsparser` - - * `*cmds: Union[str, Tuple[str, ...]]`: 命令内容 + * `parser: Optional[ArgumentParser]`: `nonebot.rule.ArgumentParser` 对象 + + * **示例** - 使用默认 `command_start`, `command_sep` 配置 + 使用默认 `command_start`, `command_sep` 配置,更多示例参考 `argparse` 标准库文档。 - 命令 `("test",)` 可以匹配:`/test` 开头的消息 - 命令 `("test", "sub")` 可以匹配”`/test.sub` 开头的消息 - 当 `shell_like_argsparser` 的 `argument` 为 `-a` 时且 `action` 为 `store_true` , `state["args"]["a"]` 将会记录 `True` +```python +from nonebot.rule import ArgumentParser +parser = ArgumentParser() +parser.add_argument("-a", type=bool) + +rule = shell_command("ls", parser=parser) +``` :::tip 提示 命令内容与后续消息间无需空格!