Alconna Construct&Usage - RF-Tar-Railt/Cesloi Wiki

前提

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

结构

一个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), 再判断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

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

alc = Alconna.from_string("[lp|test_lp] <id:digit> <perm> <value:bool:True>", {"digit": int})

它与如下是等效的:

alc = Alconna(
    headers=["lp", "test_lp"],
    main_args=Args["id":int, "perm":AnyParam, "value":bool:True]
)

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>