raku - 提取文档时找不到模块

Question

假设我有以下两个.pm6目录中的文件Foo :

Vehicle.pm6 - 车辆接口(interface)。

=TITLE C<Vehicle> interface

unit role Foo::Vehicle;

#| Get the vehicle to move
method run(--> Nil) { ... }

#| Get fuel into the vehicle
method get-fuel(--> Nil) { ... }

Car.pm6 - 一个实现 Vehicle 的类界面。

=TITLE C<Car> class

use Foo::Vehicle;
unit class Foo::Car does Foo::Vehicle;

has $!speed = 2;

#| Get the car to move
method run(--> Str) { 
    "{::?CLASS.perl} is moving at {$!speed}km/h."
}

#| Get fuel into the car
method get-fuel(--> Str) { 
    "Getting some fuel..."
}

与 Foo同级, 我有一个 main.p6实例化 Car 的文件类(class):

#!/usr/bin/env perl6

use lib '.';
use Foo::Car;

my Foo::Car $car .= new;

say $car.run;       #=> Foo::Car is moving at 2km/h.
say $car.get-fuel;  #=> Getting some fuel...

到目前为止，一切正常。但是，当我尝试从 Car.pm6 获取文档时(使用 p6doc Foo/Car.pm6 )，我收到以下错误:

===SORRY!===
Could not find Foo::Vehicle at line 1 in:
    /home/cosmos/.perl6
    /opt/rakudo/install/share/perl6/site
    /opt/rakudo/install/share/perl6/vendor
    /opt/rakudo/install/share/perl6
    CompUnit::Repository::AbsolutePath<94376788126208>
    CompUnit::Repository::NQP<94376768814296>
    CompUnit::Repository::Perl5<94376768814336>

Answer 1

TL;DR 我认为这是一个安全功能。错误消息是 LTA .对您的问题的评论解释了您需要做什么:

Since you are using use lib '.' in your script, I think you need to add the current directory to the perl6 search path in order for p6doc to find your module – Håkon Hægland

to set perl6 search path to current directory do: PERL6LIB=. p6doc Foo/Car.pm6 – Valle Lukas

这个答案提供了我认为的理由。

我认为也许应该进一步讨论这个问题，以改进一个或多个错误消息，P6 文档， p6doc。和/或 P6 编译器。

我将探索编译器的源代码，以更好地了解正在发生的事情，并计划在以后更新这个答案。

首字母缩略词/单词“pod”是为最初的 Perl 系列创造的，代表“plain old documentation”。在 P6 中，它变成了 Pod(请注意调整后的拼写约定以将其与原始 P5 pod/POD 区分开来)。 Pod 看起来与 pod/POD 相似，但格式不同。

特别是，它不再是普通的或旧的——它是代码。假设它代表“产生最佳文档”或类似的东西。

根据 the P6 documentation of Pod它是:

An easy-to-use markup language for documenting Perl modules and programs

Imo 它的源代码形式相当容易阅读，并且相当容易编写。 (虽然像我们大多数人一样，我已经习惯了我用来写这个的 Markdown ......)

但是 imo Pod 最显着的特点，至少在使用它的上下文中，是它的代码。所以它就像代码一样容易使用。也就是说，考虑到恶意代码的问题和确保事情安全的安全功能，这并不一定容易。

以 "The documentation in Perl 6 programs, using the Pod 6 DSL, is actually parsed as part of the code" 开头的 SO是朝着明确这一点迈出的一步。但重要的是要认识到它不仅是解析的，而且是编译的，编译涉及运行编译器，在 P6 中，甚至可能涉及在正在编译的程序中运行代码。

这是由于 P6 语法和语义的性质造成的。

根据 wikipedia's page on markup languages它们是一个系统:

annotating a document in a way that is syntactically distinguishable from the text

但是 P6 语法(和语义)可以由模块动态修改。这有令人信服的好处1，但这也意味着必须为编译器编译 P6 代码才能确定如何解析它。

这包括弄清楚 Pod 是什么以及如何解析该 Pod。此外，Pod 可以在编译时调用 P6 代码。因此 Pod(以及它调用的任何代码)也必须被编译，并且可能必须运行其中的一些来确定最终的 Pod 数据是什么。

您当然可以使用文本查看工具原位阅读 Pod。它经过精心设计，以原始形式相当容易阅读。

但是如果你使用 p6doc您正在编译 P6 代码。 (事实上​​， p6doc is a very simple wrapper around the compiler 。)

并且因为在 P6 编译中可以包含运行代码，所以通常适用于运行代码的相同安全策略必须适用于使用 p6doc。提取 P6 Pod。

从安全的角度来看，不应该运行在系统上搜索目录并运行它在没有您说的情况下找到的代码的代码。

当你写 p6doc foo/bar , 你被认为是在告诉 p6doc可以编译 foo/bar并运行作为编译该代码一部分的任何代码。

但是 use lib当 --doc 时，pragma 被故意忽略。选项提供给编译器。因此，在对它的评论中回答了你的 SO。

脚注

1 这使得 P6 能够在单个程序中以及作为一种随时间演变的语言进行无限变异。与任何图灵完备的语言一样，这意味着几乎所有的语言，如果可以做到，P6 可以做到。与几乎所有语言不同，如果您这样做并且觉得它属于该语言而不是作为一个模块，您可以调整 P6 语言以将其吸收到您的 P6 副本中。如果 P6 的人们希望您的语言调整被吸收到每个人的 P6 中，那么您的调整可以成为该语言 future 的一部分。因此，P6 使得修改 P6 本身变得容易，并且最大限度地为 future 的语言改进开放，并且从本质上消除了可能浪费大量时间和精力的事情之一，即为语言中的哪些特性而争吵。