Написание примеров

Пожалуйста, используйте блоки кода для выделения примера кода. Любые блоки с отступом считаются кодом, но вы можете использовать директиву =for code или комбинацию =begin code и =end code, чтобы лучше контролировать, какие блоки считаются таковыми.

Примеры тестирования

Файл xt/examples-compilation.t будет тестировать код из всех примеров. Этот файл запускается как часть команды make xtest.

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

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

Пропуск или уточнение тестов

Хотя наша цель — протестировать каждый пример Perl 6 в репозитории, некоторые блоки нелегко проверить. Вот несколько способов пропустить тест или уточнить его.

• Другие языки Мы тестируем только Perl 6 здесь: чтобы пропустить другой язык, используйте :lang:

    =begin code :lang<tcl>
        puts "this is not Perl"
    =end code

Для обычного текста используйте :lang<text>.

• Разрешить .WHAT

Одна из проверок заключается в том, чтобы отговорить от использования .WHAT в тестах; однако в редких случаях это явная цель теста, поэтому вы можете разрешить это с помощью ok-test:

=begin code :ok-test<WHAT>
    say 42.WHAT;
=end

• Разрешить dd

dd — это специфическая процедура rakudo, которая не является частью спецификации; примеры не должны использовать её, если они явно не пытаются показать, как работает dd. Вы можете разрешить это с помощью ok-test:

=begin code :ok-test<dd>
    dd 42;
=end

• Методы

Если фрагмент кода выглядит как объявление метода, он автоматически оборачивается дополнительным кодом, так что вам не нужно указывать тело в документации. Многострочные сигнатуры методов гораздо сложнее обнаружить, поэтому, если у вас есть тело метода, которое охватывает лайки, используйте тег :method:

=begin code :method
    method arg (
        Bool $one,
        Bool $two
    )
=end code

Это помогает сохранить логику обнаружения методов в тестовом коде простой.

И наоборот, иногда обнаружение метода слишком активно; вы можете полностью отключить его с помощью :method<False>.

• Преамбулы

При написании примеров часто бывает полезно ссылаться на вещи, которые не определены в этом фрагменте; вам не нужно иметь полный рабочий пример в коде.

=begin code :preamble<no strict;>
    $x = pi;
=end code

=begin code :preamble<my $x; sub frob {...};>
    $x = frob();
=end code

• Сбои

Некоторые примеры завершаются сбоями во время компиляции и прерывают тест для файла. Используйте опцию конфигурации pod skip-test, чтобы пропустить их. Когда это возможно, укажите причину, по которой вы должны использовать это; это следует рассматривать как крайнюю меру, и многие примеры могут быть применимы к использованию одной из предыдущих аннотаций.

=begin code :skip-test<compile time error>
    if 1 "missing a block";
=end code