14. 命令行接口 - 概述 - 《Raku（Perl 6）官方文档(中文翻译)》

这将查看中的值，根据某些策略解释这些值，并创建一个对象。解析器的替代方式可以由开发者提供或使用模块安装。

使用该捕获调用提供的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 的候选者）的签名确定使用标准多重分派语义实际调用哪个候选者。

一个简单的例子：

如果您调用该脚本没有任何参数：

$ 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

如果文件 file.dat 不存在，或者您指定了另一个不存在的文件名，您将获得从 MAIN 子的内省创建的标准用法消息：

$ raku frobnicate.p6 doesntexist.dat
Usage:

虽然您不必在代码中执行任何操作，但它仍然可能被视为有点简洁。但是通过使用 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
  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 {} 之前更改参数的处理方式。由于动态变量的性质，需要设置 %*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 特征，它看起来像这样：

虽然技术上是正确的，但也不能读。

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 的情况。

如果找不到给定命令行参数的 MAIN 的多候选者，则调用 sub USAGE。如果未找到此类方法，编译器将输出默认用法消息。

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)

sub ARGS-TO-CAPTURE

ARGS-TO-CAPTURE 子程序应该接受两个参数：一个表示要执行的 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)
}

请注意，动态变量可用于执行捕获处理的默认命令行参数，因此如果您不想，则不必重新发明整个轮子。

拦截使用消息生成（2018.10，v6.d及更高版本）

您可以通过自己提供 GENERATE-USAGE 子例程，或者从生态系统中可用的任何模块导入一个子例程来替换或扩充默认的使用方式消息生成方式（在向 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 );

这将打印生成的对象的名称（第一个参数）。

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 接口是，那么它将使用旧接口。