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

【问题标题】：How to get a "help" functionality in REPL如何在 REPL 中获得“帮助”功能
【发布时间】：2021-11-10 11:19:45
【问题描述】：

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

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

> run <p6doc Array.splice>

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

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

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

我使用 Windows10 与

Welcome to ????????????????????????™ v2021.07.
Implementing the ????????????????™ programming language v6.d.
Built on MoarVM version 2021.07.

【问题讨论】：

恐怕不行。现在甚至 p6doc 都没有真正工作......但它肯定会很方便。
@jjmerelo 感谢您的回复。那么你认为run p6doc 失败与p6doc 本身有关吗
完全有可能。您可能想使用 rakudoc，但我也不太确定。
@raiph 我确实尝试过 Comma IDE，但它滞后且缓慢（在 Windows 上）......也许是因为我的系统，但有人也在不和谐#raku 中制作了类似的 cmets，所以......（但我还没有尝试过我猜的当前最新版本，所以我可能会再试一次，谢谢。）
@Hanselmann 太糟糕了。我看到在 VScode GH 上发布 slow/laggy 问题后，海报在 4 天内得到了解决方案（尽管我看到其他 VSCode 问题，如 Slow reponse to scroll and typing 仍然存在）。 Edument 不是 Microsoft，但也许您愿意通过电子邮件发送 info@commaide.com 让他们知道它的滞后/缓慢（并包括您的 Windows 版本和其他基本系统信息）？（如果你这样做，请建议他们打开一个带有问题 Q for Comma 的 GH 回购。）也许他们会回应......

标签： raku read-eval-print-loop introspection code-documentation rakudo

【解决方案1】：

您的具体问题

当您在 REPL 中输入 run <p6doc Array.splice> 时遇到的错误看起来像您在找不到命令时遇到的错误。您可以通过输入qx <p6doc Array.splice> 来确认这一点——我怀疑您会收到一个更清楚地表明找不到p6doc 命令的错误。

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

（哦，您可能可能使用qx 或shell 而不是run，虽然两者都应该工作。请参阅shell quoting 文档。）

更广泛的问题 - CLI 文档生态系统的状态

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

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

REPL 中的其他信息选项

您在help('splice') 中提到了函数的概念。目前不存在与此完全一样的东西——尽管这对于一个模块来说是个好主意。但 Raku 确实提供了丰富的自省工具，可以提供许多相同的功能。

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

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

其他一些很好的自省方法：

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

最后一个值得详细说明：.WHY 为该项目打印任何 declarator pod blocks - 即源代码中使用 #| 或 #= 制作的任何 cmets（用于前一个项目）。将这些 doc cmets 包含在您的模块导出的公共项目中是一种很好的做法，Raku 生态系统中的许多模块都这样做。对于variety of reasons，Rakudo 源代码不包含#| cmets，因此.WHY 对于内置类型没有用处。

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

【讨论】：

感谢您的回复。 qx & shell 和 <p6doc ...> 有效。对于run，我指定了p6doc.bat 的完整路径，正如你所说，它也有效。至于自省：谢谢！但是恕我直言，有些是冗长的，多重签名有点吓人，我不确定^methods 给出方法的顺序（如果首先给出特定类型的方法，然后是继承的方法，然后是大写等，那会很酷。）。无论如何，我希望 REPL 有朝一日会附带help 命令或? 后缀。现在我将尝试对 qx p6doc 进行包装，并尝试在每次 REPL 打开时使其可用。

【解决方案2】：

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

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

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

【讨论】：