Модуль не найден при извлечении документации - PullRequest
Новая
       14

Модуль не найден при извлечении документации

6 голосов
/ 10 марта 2019

Допустим, у меня есть следующие два .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>

1 Ответ

6 голосов
/ 10 марта 2019

TL; DR Я думаю, что это предназначено для обеспечения безопасности.Сообщение об ошибке: LTA .Комментарии к вашему вопросу объясняют, что вам нужно сделать.Этот ответ дает, как мне кажется, обоснование.

Я думаю, что этот вопрос, возможно, следует обсудить дополнительно с целью улучшения одного или нескольких сообщений об ошибках, документации P6, p6doc и / или P6компилятор.

Я буду изучать исходный код компилятора, чтобы лучше понять, что происходит, и планирую обновить этот ответ позднее.

Аббревиатура / слово "pod" былопридумал для оригинальной серии Perl и расшифровывался как «простая старая документация».В P6 это стало Pod (обратите внимание на скорректированное соглашение правописания, чтобы отличить его от оригинального p5 pod / POD).Pod выглядит как pod / POD, но это другой формат.

В частности, он больше не является простым или старым - это код.Предположим, что это означает «Производит оптимальную документацию» или что-то подобное.

За документация P6 для Pod это:

Простая в использовании разметкаязык для документирования модулей и программ Perl

Imo довольно просто читать в исходном виде и довольно просто писать .(Хотя, как и большинство из нас, я привык к уценке, которую я использую, чтобы написать это ...)

Но наиболее существенная характеристика imo Pod, по крайней мере, в контексте с использованием это то, что это код.Так что его так же легко использовать, как и код.Иными словами, это не обязательно просто, учитывая проблему вредоносного кода и функции безопасности, которые обеспечивают безопасность.

SO, начинающийся с "Документация в программах на Perl 6 с использованием Pod6 DSL, фактически анализируется как часть кода " - это шаг к пониманию этого.Но важно понимать, что он не просто анализируется, но компилируется и что компиляция включает в себя запуск компилятора, а в P6 может даже включать запуск кода в компилируемой программе.

Это связано ск природе синтаксиса и семантики P6.

За страницу Википедии о языках разметки они представляют собой систему для:

аннотирования документа таким образом, чтосинтаксически отличается от текста

Но синтаксис (и семантика) P6 может быть динамически изменен модулями.Это имеет убедительные преимущества 1 , но это также означает, что код P6 должен быть скомпилирован для компилятора, чтобы точно определить, как его анализировать.

И это включает в себя выяснение того, что такое Pod и какразобрать этот Pod.Кроме того, Pod может вызвать P6 код во время компиляции.Таким образом, Pod (и любой код, который он вызывает) также должен быть скомпилирован, и для его определения может потребоваться run , чтобы выяснить окончательные данные Pod.

Вы, конечно, можете прочитатьстручок на месте с помощью инструментов просмотра текста.Он специально разработан для того, чтобы его было довольно легко прочитать в необработанном виде.

Но если вы используете p6doc, вы компилируете код P6.(На самом деле p6doc - это очень простая оболочка для компилятора .)

И поскольку в компиляцию P6 может входить работающий код , те же политики безопасности, которыеодин из них относится к запуску кода в целом; должен применяться к использованию p6doc для извлечения P6 Pod.

С точки зрения безопасности, никогда не следует запускать код, который ищет каталоги в вашей системе и выполняет код, который он находит там безвы так говорите.

Когда вы пишете p6doc foo/bar, вы, как считается, говорите p6doc, что все в порядке, чтобы скомпилировать foo/bar и запустить любой код, который является частью компиляции этого кода.

Но прагма use lib сознательно игнорируется, когда компилятору предоставляется опция --doc.Отсюда и ответ на ваш ТА в комментариях к нему.

Сноски

1 Это делает P6 способным к неограниченным мутациям, как в рамках одной программы, так и в качестве языка, развивающегося со временем.Как с любым полным языком тьюринга, что означает, что почти все из них, если это возможно, P6 может сделать это. В отличие от почти на всех языках, если вы делаете это и чувствуете, что он принадлежит языку, а не модулю, вы можете настроить язык P6, чтобы он впитался в вашу копию P6.И если люди P6 хотят, чтобы ваш языковой трюк впитался в каждый P6, ваш твик может стать частью будущего языка.Таким образом, P6 облегчает модификацию самого P6 и максимально открыт для будущего улучшения языка и, по существу, устраняет одну из вещей, которая может тратить много времени и энергии, а именно борьбу за то, что принадлежит языку.

...