脚语

Question

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

Vehicle.pm6-车辆的界面。

=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类：

#!/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。您对问题的评论解释了您需要做什么。这个答案提供了我认为的理由。

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

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

首字母缩写词/“ pod”是原始Perl系列的缩写，代表“普通的旧文档”。在P6中，它已成为Pod（请注意，经过调整的拼写约定使其与原始P5 Pod / POD有所区别）。 Pod与Pod / POD相似，但格式不同。

尤其是它不再是简单或旧的-它是代码。假设它代表“产生最佳文档”或诸如此类。

每the P6 documentation of Pod是：

一种易于使用的标记语言，用于记录Perl模块和程序

Imo可以很容易地以其源代码形式阅读，也很容易编写。（尽管像我们大多数人一样，我已经习惯了我用来编写本书的减价...）

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

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

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

对于每个wikipedia's page on markup languages，它们是用于以下目的的系统：

以与文本在语法上可区分的方式注释文档

但是P6语法（和语义）可以由模块动态修改。 ¹具有令人信服的优势，但这也意味着必须编译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编译指示。因此，在评论中对您的SO的回答。

脚语

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

提取文档时找不到模块

1 个答案:

脚语