如何在 REPL 中获得“帮助”功能

Question

当我使用 REPL 时，我有时需要查找函数的功能，例如splice. 我通常会访问文档网站。但我并不总是有互联网，如果我可以直接在 REPL 中编写help("splice")或某些内容（例如splice?）并查看结果，那就太好了。

\n

然后我认为p6docRakudo Star 附带的可以使用，因为p6doc Array.splice在命令行上提供了文档。然后我在 REPL 中这样做：

\n

> run <p6doc Array.splice>\n\nProc.new(in => IO::Pipe, out => IO::Pipe, err => IO::Pipe, exitcode => 1,\n         signal => 0, pid => Nil, command => ("p6doc", "Array.splice"))\n

\n

:out但它有 exitcode 1。当我使用和捕获输出时:err，两者都是空字符串，但我不知道为什么。

\n

有没有办法让 REPL 中的这种帮助功能与“run p6doc”或其他东西一起工作？

\n

我使用 Windows10

\n

Welcome to \xe2\x84\xa2 v2021.07.\nImplementing the \xe2\x84\xa2 programming language v6.d.\nBuilt on MoarVM version 2021.07.\n

\n

Answer 1

\n

您的具体问题

\n

当您输入 REPL 时遇到的错误run <p6doc Array.splice>看起来就像您因找不到命令而遇到的错误。您可以通过输入 \xe2\x80\x93 来确认，qx <p6doc Array.splice>我怀疑您会收到一个错误，更清楚地表明p6doc无法找到该命令。

\n

假设这就是问题所在，听起来$PATH环境变量没有在 REPL 中正确设置。我不确定为什么会这样，而且我没有方便测试的 Windows 盒子。但是，无论如何，您应该能够通过指定p6doc可执行文件的绝对路径来解决这个问题。（对我来说，这就像qx </home/dsock/.raku/bin/p6doc Array.splice>，但显然你会有不同的路径）。

\n

（哦，对于这种用途，您可能会更好地使用qxorshell而不是run，尽管两者都应该有效。请参阅shell 引用文档。）

\n

更广泛的问题 \xe2\x80\x93 CLI 文档生态系统的状态

\n

正如 JJ 在评论中提到的，Raku 生态系统正在从源p6doc迁移到源，而且还没有 100% 提供出色的 CLI/REPL 文档。这绝对是一项正在进行的工作，也是我们需要改进的领域。安装（使用）可能会提供更好的体验，但正如我所说，这是社区仍在努力的事情。欢迎 PR！rakudoc rakudoczef install \'rakudoc:auth<github:Raku>\'

\n

与此同时，离线访问文档的另一个选项是在本地构建文档（raku/doc README中的说明）并运行本地服务器。这需要 docker 或 perl、graphviz 和 nodejs（我们也在努力减少这些要求）。这样，虽然您仍然需要切换到浏览器来检查文档，但至少缓慢/无互联网访问不会成为问题。

\n

REPL 中的其他信息选项

\n

您提到了函数的想法help(\'splice\')。目前不存在任何与 \xe2\x80\x93 完全相同的东西，尽管这对于模块来说是一个好主意。但 Raku 确实提供了丰富的内省工具，这些工具可以提供许多相同的功能。

\n

例如，如果您想检查提供参数的顺序，您可以列出以下所有 30 个 (!) 签名Array.splice：

\n

for Array.^lookup(\'splice\').candidates\xc2\xbb.signature { .say }\n# if "splice" weren\'t a multi method, you don\'t need `.candidates\xc2\xbb`\n

\n

其他一些好的内省方法需要了解：

\n

\n
• &say.candidates\xc2\xbb.signtaure # same as above, but for independent sub/multi
\n
• Array.^methods\xc2\xbb.name
\n
• $x.VAR.WHAT# 如果 $x 是赋值而不是绑定，则返回 \xc2\xab(Scalar)\xc2\xbb
\n
• Rat.^attributes\xc2\xbb.name# 所有属性（公共和私有）
\n
• Rat.^attributes.grep({Rat.^has_public_attribute(.name)})\xc2\xbb.name
\n
• Array.^mro # All classes Array inherits from
\n
• Array.^roles
\n
• Foo.WHY # returns any declarator block for the type/method/sub/attribute
\n

\n

最后一个值得详细说明：.WHY打印项目 \xe2\x80\x93 的任何声明器 pod 块，即源代码中使用#|或#=（针对前一项）所做的任何注释。最好将这些文档注释包含在模块导出的公共项目中，Raku 生态系统中的许多模块也是如此。由于多种原因，Rakudo 源代码不包含#|注释，因此.WHY对于内置类型没有用处。

\n

（在我的梦想世界中，我们会看到一个 REPL 命令，例如您建议的，它将内置类型help的输出的一些过滤版本与自定义类型的输出结合起来，但我们还没有类似的东西.)rakudocs.WHY

\n

Answer 2

虽然当前的内置 REPL 没有帮助功能，但Comma IDE确实包含其自己的 Raku REPL（可在“工具”菜单上找到，并包含在免费版本中）。站在例程名称或类型名称上时按 Ctrl+Q 将尝试解析其文档。这包括内置函数：

而且还添加了 Pod 声明器文档的模块：

虽然安装整个 IDE 可能只是为了在帮助下获得 REPL，但我认为值得一提 - 特别是因为我遇到过使用 Comma 的人，但没有意识到它也包含 REPL！