Alconna Construct&Usage

前提

确保您已阅读关于命令结果的部分

结构

一个Alconna实例的结构如下:

Alconna(
    headers=["command_head"],
    command="command_name",
    options=[
        Subcommand(
            "sub_name",
            Option(
                "sub_opt_name", 
                sub_opt_arg=sub_opt_arg
            ), 
            sub_main_arg=sub_main_arg
        ),
        Option(
            "opt_name", 
             opt_arg=opt_arg
        )
    ]
    main_args=main_args
)

Alconna支持四大类参数：

• headers : 呼叫该命令的命令头，一般是你的机器人的名字或者符号，与 command 至少有一个填写. 例如: /, !; 0.5.3中支持传入非文本消息
• command : 命令名称，你的命令的名字，与 headers 至少有一个填写
• options : 命令选项，你的命令可选择的所有 option,是一个包含 Subcommand 与 Option 的列表
• main_args : 主参数，填入后当且仅当命令中含有该参数时才会成功解析

其中

• command_head: 命令头
• command_name: 命令名称
• sub_name: 子命令名称
• sub_opt_name: 子命令选项名称
• sub_opt_arg: 子命令选项参数
• sub_main_arg: 子命令主参数
• opt_name: 命令选项名称
• opt_arg: 命令选项参数

解析时，先判断命令头(即 headers + command), 再判断options与main args, 这里options与main args在输入指令时是不分先后的

使用

现在，我们假设一命令如下:

/pip
Usage:
  /pip <command> [options]

Commands:
  install                     Install packages.
  list                        List installed packages.
  show                        Show information about installed packages.
  help                        Show help for commands.

General Options:
  --help                      Show help.
  --retries <retries>         Maximum number of retries each connection should attempt (default 5 times).
  --timeout <sec>             Set the socket timeout (default 15 seconds).
  --exists-action <action>    Default action when a path already exists: (s)witch, (i)gnore, (w)ipe, (b)ackup, (a)bort.
  --trusted-host <hostname>   Mark this host or host:port pair as trusted, even though it does not have valid or any HTTPS.

根据上述的Alconna结构与前文的命令结构分析，我们可以得到这样的 Alconna:

pip = Alconna(
    command="/pip",
    options=[
        Subcommand(
            "install",
            Option("--upgrade"),
            pak=AnyStr,
        ),
        Subcommand(
            "show",
            pak=AnyStr,
        ),
        Subcommand(
            "help",
            command=AnyStr,
        ),
        Option("list"),
        Option("--help"),
        Option("--retries", retries=AnyDigit),
        Option("--timeout", sec=AnyDigit, alias='-t'),
        Option("--exists-action", action=AnyStr, alias='-ea'),
        Option("--trusted-host", hostname=AnyUrl, alias='-th')
    ]
)

现在你可以尝试如下输入:

>>> pip.analyse_message("/pip install cesloi --upgrade --trusted-host http://pypi.douban.com/simple").option_args

正常情况下, 会输出：

{'upgrade': Ellipsis, 'pak': 'cesloi', 'hostname': 'http://pypi.douban.com/simple'}

特殊的构造形式

如果你不想写一大串的代码, Alconna 目前提供了3种特殊的构造方式:

• koishi-like
• formatter
• iterable

Koishi-like

Alconna 的koishi-like形式的构造方法, 如

Alconna.set_custom_types(digit=int)
alc = Alconna.from_string(
...     "[tt|test_type] <wild> <text:str> <num:digit> <boolean:bool:False>",
...     "--foo|-f [True]"
... )

它与如下是等效的:

alc = Alconna(
    headers=["tt", "test_type"],
    options=[Option("--foo", alias='-f', actions=store_bool(True))]
    main_args=Args["wild":AnyParam, "text":str, "num":int, "boolean":bool:False]
)

<xxx>代表参数, 如<value:int>等价于Args['value':int], <message>等价于Args['message':AnyParam]

针对option的[xxx]代表store_val(xxx)的action

Formatter

Alconna 的formatter形式的构造方法, 如

alc = Alconna.format("lp user {0} perm set {1} {2}",[AnyStr, AnyStr, Args["value":Bool:True]])

或

alc = Alconna.format("lp user {target} perm set {perm} {value}", {"target": AnyStr, "perm": AnyStr, "value": Args["value":Bool:True]})

它与如下是等效的:

alc = Alconna(
    command="lp",
    options=[
        Option("user", target=AnyStr),
        Subcommand(
            "perm", 
            Option("set", perm=AnyStr), 
            Args["value":Bool:True]
        )
    ]
)

帮助文档

Alconna 支持通过XXX.help("XXX")来写入帮助说明,

以上面的指令为例：

pip = Alconna(
    command="/pip",
    options=[
        Subcommand("install", Option("--upgrade").help("升级包"), pak=str).help("安装一个包"),
        Subcommand("show", pak=str).help("显示一个包的信息"),
        Subcommand("help", command=str).help("显示一个指令的帮助"),
        Option("list").help("列出所有安装的包"),
        Option("--retries", retries=int).help("设置尝试次数"),
        Option("-t| --timeout", sec=int).help("设置超时时间"),
        Option("--exists-action", action=str).help("添加行为"),
        Option("--trusted-host", hostname=AnyUrl).help("选择可信赖地址")
    ]
).help("pip指令")

然后

print(pip.get_help())

则有

/pip 
可用的子命令有:
# 安装一个包
  install <pak>
## 该子命令内可用的选项有:
 # 升级包
  --upgrade 
# 显示一个包的信息
  show <pak>
# 显示一个指令的帮助
  help <command>
可用的选项有:
# 列出所有安装的包
  list 
# 设置尝试次数
  --retries <retries>
# 设置超时时间
  --timeout <sec>
# 添加行为
  --exists-action <action>
# 选择可信赖地址
  --trusted-host <hostname>