命令行接口
命令行接口 - 概述
Raku 脚本的默认命令行界面由三部分组成：
将命令行参数解析为捕获
这将查看 @*ARGS 中的值，根据某些策略解释这些值，并创建一个 Capture 对象。解析器的替代方式可以由开发者提供或使用模块安装。
使用该捕获调用提供的MAIN子例程
标准多分重分派用于使用生成的 Capture 对象调用 MAIN 子例程。这意味着您的 MAIN子 例程可能是一个 multi sub，其中每个候选程序负责处理给定命令行参数的某些部分。
如果调用 MAIN 失败，则创建/显示使用信息
如果多重分派失败，则应尽可能通知脚本的用户失败的原因。默认情况下，这是通过检查每个 MAIN 候选 sub 的签名以及任何关联的 pod 信息来完成的。然后在 STDERR 上向用户显示结果（如果指定了 --help，则在 STDOUT 上显示）。生成使用信息的替代方式可以由开发者提供或使用模块安装。
sub MAIN
在运行所有相关的输入phasers（BEGIN，CHECK，INIT，PRE，ENTER）并执行脚本的主线之后，将执行具有特殊名称 MAIN 的子程序。如果没有 MAIN sub，则不会发生错误：您的脚本只需要在脚本的主线中执行工作，例如参数解析。
从 MAIN sub 的任何正常退出将导致退出代码为 0，表示成功。 MAIN 子的任何返回值都将被忽略。如果抛出未在 MAIN 子内部处理的异常，则退出代码将为 1。如果调度到 MAIN 失败，则在 STDERR 上将显示一条用法消息，退出代码将为 2。
命令行参数存在于 @*ARGS 动态变量中，并且可以在调用 MAIN 单元之前在脚本的主线中进行更改。
（多个子 MAIN 的候选者）的签名确定使用标准多重分派语义实际调用哪个候选者。
一个简单的例子：
# inside file 'hello.p6'
sub MAIN($name) {
say "Hello $name, how are you?"
}
如果您调用该脚本没有任何参数：
$ raku hello.p6
Usage:
hello.p6 <name>
但是，如果为参数指定默认值，则无论是否指定名称，运行脚本始终有效：
# inside file 'hello.p6'
sub MAIN($name = 'bashful') {
say "Hello $name, how are you?"
}
$ raku hello.p6
Hello bashful, how are you?
$ raku hello.p6 Liz
Hello Liz, how are you?
另一种方法是使 sub MAIN 成为一个 multi sub：
# inside file 'hello.p6'
multi sub MAIN() { say "Hello bashful, how are you?" }
multi sub MAIN($name) { say "Hello $name, how are you?" }
这将提供与上述示例相同的输出。您是否应该使用任何一种方法来实现预期目标完全取决于您。
使用单个位置和多个命名参数的更复杂的示例：
# inside "frobnicate.p6"
sub MAIN(
Str $file where *.IO.f = 'file.dat',
Int :$length = 24,
Bool :$verbose
) {
say $length if $length.defined;
say $file if $file.defined;
say 'Verbosity ', ($verbose ?? 'on' !! 'off');
}
有了 file.dat，这将以这种方式工作：
$ raku frobnicate.p6
24
file.dat
Verbosity off
或者这样 --verbose：
$ raku frobnicate.p6 --verbose
24
file.dat
Verbosity on
如果文件 file.dat 不存在，或者您指定了另一个不存在的文件名，您将获得从 MAIN 子的内省创建的标准用法消息：
$ raku frobnicate.p6 doesntexist.dat
Usage:
frobnicate.p6 [--length=<Int>] [--verbose] [<file>]
虽然您不必在代码中执行任何操作，但它仍然可能被视为有点简洁。但是通过使用 pod 功能提供提示，有一种简单的方法可以更好地使用该消息：
# inside "frobnicate.p6"
sub MAIN(
Str $file where *.IO.f = 'file.dat', #= an existing file to frobnicate
Int :$length = 24, #= length needed for frobnication
Bool :$verbose, #= required verbosity
) {
say $length if $length.defined;
say $file if $file.defined;
say 'Verbosity ', ($verbose ?? 'on' !! 'off');
}
哪个会改善这样的用法消息：
$ raku frobnicate.p6 doesntexist.dat
Usage:
frobnicate.p6 [--length=<Int>] [--verbose] [<file>]
[<file>] an existing file to frobnicate
--length=<Int> length needed for frobnication
--verbose required verbosity
%*SUB-MAIN-OPTS
通过设置 %*SUB-MAIN-OPTS 哈希中的选项，可以在将参数传递给 sub MAIN {} 之前更改参数的处理方式。由于动态变量的性质，需要设置 %*SUB-MAIN-OPTS 哈希并使用适当的设置填充它。例如：
my %*SUB-MAIN-OPTS =
:named-anywhere, # allow named variables at any location
# other possible future options / custom options
;
sub MAIN ($a, $b, :$c, :$d) {
say "Accepted!"
}
可用选项包括：
named-anywhere
默认情况下，传递给程序的命名参数（即 MAIN）在任何位置参数后都不会出现。但是，如果将 %*SUB-MAIN-OPTS<named-anywhere> 设置为 true 值，则可以在任何位置指定命名参数，即使在位置参数之后也是如此。例如，可以使用以下命令调用上述程序：
$ raku example.p6 1 --c=2 3 --d=4
is hidden-from-USAGE
有时您希望排除MAIN候选者显示在任何自动生成的使用消息中。这可以通过向您不想显示的 MAIN 候选者的规范添加 hidden-from-USAGE 特征来实现。扩展前面的例子：
# inside file 'hello.p6'
multi sub MAIN() is hidden-from-USAGE {
say "Hello bashful, how are you?"
}
multi sub MAIN($name) { #= the name by which you would like to be called
say "Hello $name, how are you?"
}
因此，如果您只使用命名变量调用此脚本，您将获得以下用法：
$ raku hello.p6 --verbose
Usage:
hello.p6 <name> -- the name by which you would like to be called
没有第一个候选者 hidden-from-USAGE 特征，它看起来像这样：
$ raku hello.p6 --verbose
Usage:
hello.p6
hello.p6 <name> -- the name by which you would like to be called
虽然技术上是正确的，但也不能读。
MAIN 的单位作用域定义
如果整个程序体驻留在 MAIN 中，则可以使用单位声明符，如下所示（调整前面的示例）：
unit sub MAIN(
Str $file where *.IO.f = 'file.dat',
Int :$length = 24,
Bool :$verbose,
); # <- note semicolon here
say $length if $length.defined;
say $file if $file.defined;
say 'Verbosity ', ($verbose ?? 'on' !! 'off');
# rest of script is part of MAIN
请注意，这只适用于只有一个（仅）sub MAIN 的情况。
sub USAGE
如果找不到给定命令行参数的 MAIN 的多候选者，则调用 sub USAGE。如果未找到此类方法，编译器将输出默认用法消息。
#|(is it the answer)
multi MAIN(Int $i) { say $i == 42 ?? 'answer' !! 'dunno' }
#|(divide two numbers)
multi MAIN($a, $b){ say $a/$b }
sub USAGE() {
print Q:c:to/EOH/;
Usage: {$*PROGRAM-NAME} [number]
Prints the answer or 'dunno'.
EOH
}
通过只读 $*USAGE 变量，sub USAGE 内的默认用法消息可用。它将基于可用的 sub MAIN 候选者及其参数生成。如前所示，您可以使用 #|(...) Pod 块为每个候选项指定其他扩展描述以设置 WHY。
拦截 CLI 参数解析(2018.10, v6.d and later)
您可以通过自己提供 ARGS-TO-CAPTURE 子例程，或者从生态系统中可用的任何 Getopt 模块中导入一个子例程来替换或扩充参数解析的默认方式。
sub ARGS-TO-CAPTURE
ARGS-TO-CAPTURE 子程序应该接受两个参数：一个 Callable 表示要执行的 MAIN 单元（因此可以在必要时进行内省）和一个带有来自命令行的参数的数组。它应该返回一个将用于调度 MAIN 单元的 Capture 对象。一个非常人为的例子，它将根据输入的某个关键字创建一个 Capture（在测试脚本的命令行界面时可以很方便）：
sub ARGS-TO-CAPTURE(&main, @args --> Capture) {
# if we only specified "frobnicate" as an argument
@args == 1 && @args[0] eq 'frobnicate'
# then dispatch as MAIN("foo","bar",verbose => 2)
?? Capture.new( list => <foo bar>, hash => { verbose => 2 } )
# otherwise, use default processing of args
!! &*ARGS-TO-CAPTURE(&main, @args)
}
请注意，动态变量 &*ARGS-TO-CAPTURE 可用于执行捕获处理的默认命令行参数，因此如果您不想，则不必重新发明整个轮子。
拦截使用消息生成（2018.10，v6.d及更高版本）
您可以通过自己提供 GENERATE-USAGE 子例程，或者从生态系统中可用的任何 Getopt 模块导入一个子例程来替换或扩充默认的使用方式消息生成方式（在向 MAIN 发送失败之后）。
sub RUN-MAIN
定义为：
sub RUN-MAIN(&main, $mainline, :$in-as-argsfiles)
该程序允许完全控制 MAIN 的处理。它得到一个 Callable，它是应该执行的 MAIN，主线执行的返回值和其他命名变量:: in-as-argsfiles 如果 STDIN 应该被视为 $*ARGFILES，它将为 True。
如果未提供 RUN-MAIN，将运行默认的 RUN-MAIN 以查找旧接口的子例程，例如 MAIN_HELPER 和 USAGE。如果找到，将执行“旧”语义。
class Hero {
has @!inventory;
has Str $.name;
submethod BUILD( :$name, :@inventory ) {
$!name = $name;
@!inventory = @inventory
}
}
sub new-main($name, *@stuff ) {
Hero.new(:name($name), :inventory(@stuff) ).perl.say
}
RUN-MAIN( &new-main, Nil );
这将打印生成的对象的名称（第一个参数）。
sub GENERATE-USAGE
GENERATE-USAGE 子例程应该接受一个 Callable，表示由于调度失败而未执行的 MAIN 子例程。这可以用于内省。所有其他参数都是设置为发送到MAIN的参数。它应该返回您想要显示给用户的使用信息的字符串。这个例子只是重新创建从处理参数创建的 Capture：
sub GENERATE-USAGE(&main, |capture) {
capture<foo>:exists
?? "You're not allowed to specify a --foo"
!! &*GENERATE-USAGE(&main, |capture)
}
您还可以使用 multi 子例程来创建相同的效果：
multi sub GENERATE-USAGE(&main, :$foo!) {
"You're not allowed to specify a --foo"
}
multi sub GENERATE-USAGE(&main, |capture) {
&*GENERATE-USAGE(&main, |capture)
}
请注意，动态变量 &*GENERATE-USAGE 可用于执行默认使用消息生成，因此您不必重新发明整个轮子。
拦截 MAIN 调用（2018.10之前，v6.e）
较旧的接口使得一个接口完全拦截对 MAIN 的调用。这取决于是否存在 MAIN_HELPER 子程序，如果在程序的主线中找到 MAIN 子程序，则该子程序将被调用。
此接口从未记录过。但是，使用此未记录的界面的任何程序将继续运行，直到 v6.e。从 v6.d 开始，使用未记录的 API 将导致 DEPRECATED 消息。
生态系统模块可以提供新旧接口，以便与旧版本的 Raku 兼容：如果较新的 Raku 识别出新的（记录的）接口，它将使用它。如果没有可用的新接口子例程，但旧的 MAIN_HELPER 接口是，那么它将使用旧接口。
如果模块开发人员决定仅为 v6.d 或更高版本提供模块，则可以从模块中删除对旧接口的支持。