Записки программиста

Одна из интересных вещей относительно Perl 6 заключается в удивительной легкости, с которой происходит создание новых модулей/библиотек и добавление их в Perl 6 Ecosystem (аналог CPAN для Perl 6). Давайте разберемся, как же создаются новые модули для Perl 6.

Рассмотрим в качестве примера модуль Sitemap::XML::Parser. Содержимое соответствующего репозитория на GitHub следующее:

Что включает в себя модуль Perl 6:

• Собственно код модуля;
• Документацию в формате Perl 6 Pod;
• Набор автоматических тестов;
• Файл META.info;
• Файл README;
• Логотип модуля;

Само собой разумеется, можно обойтись без тестов и тем более без логотипа.

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

Документация пишется на английском языке и хранится в тех же pm- или pm6-файлах, что и код. Не думаю, что у вас возникнут сложности с форматом Perl 6 Pod, его очень просто освоить по примерам. При написании документации обычно достаточно указать краткое описание модуля, пример его использования и в одном-двух предложениях описать каждую функцию (или метод), доступную пользователю.

Тесты находятся в каталоге ./t в файлах с расширением t. На самом деле это обычные скрипты на Perl 6. Вот пример простейшего автоматического теста, который в действительности ничего не проверяет:

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

Основные модули, которые понадобятся вам при написании тестов — это Test и Test::Mock. Как несложно догадаться, первый предназначен собственно для написания тестов, а второй — для создания mock-объектов. Примеры использования обоих модулей можно посмотреть здесь. См также подборку ссылок в конце заметки.

Примечание: На всякий случай обращаю ваше внимание, что тесты не должны писаться в предположении, что у пользователя на localhost поднят Memcached или типа того. При необходимости используйте mock-объекты и помните, что вы пишите модульные (и иногда интеграционные) тесты, которые не должны зависеть от подобного рода вещей. Как показывает практика, для некоторых программистов это не очевидно.

В файле META.info содержится имя, версия и краткое описание модуля, а также список зависимостей, тип и адрес репозитория. Формат файла представляет собой обычный JSON:

Файл README, строго говоря, не очень-то и нужен. Однако те, кто заглянут в репозиторий с кодом вашего модуля, будут благодарны, если вы этот файл создадите. Проще всего создать его из Pod-документации к модулю:

Используя этот подход, вам не придется беспокоится о том, как поддерживать файл README в актуальном состоянии.

Что касается логотипа модуля, лично я считаю эту идею полнейшим бредом. Но если вам очень хочется, чтобы у вашего модуля был логотип, можете посмотреть, например, как это сделано в модуле JSON::Tiny.

Итак, вы создали некий полезный модуль, написали к нему документацию и как следует покрыли его тестами. Что требуется для того, чтобы другие программисты могли установить его с помощью panda? Для этого делаем форк репозитория https://github.com/perl6/ecosystem/, добавляем в конце файла META.list ссылку на файл META.info в своем репозитории и шлем pull request. GitHub позволяет сделать все это в пару кликов прямо через веб-интерфейс.

По моему опыту изменения принимают довольно быстро, обычно в течение часа или около того. Спустя еще какое-то время ваш модуль появится в файле http://feather.perl6.nl:3000/projects.json. Именно этот файл используется panda для получения полного списка всех существующих модулей для Perl 6. Пробуем установить модуль:

Проверяем, что тесты проходят, документация просматривается через p6doc и так далее. Спустя еще какое-то время ссылка на ваш модуль появится на modules.perl6.org. Если вы написали что-то полезное, новые тикеты в багтрекере, форки и pull request’ы не заставят себя долго ждать.

Поскольку все модули Perl 6, как и вообще все, связанное с Perl 6, хранятся в git-репозиториях на GitHub (хотя, насколько я понимаю, можно использовать не только GitHub и не только Git), вы можете без труда улучшить любой из них — исправить ошибку, дописать документацию и тп. Или, скажем, просто использовать их в качестве обучающих примеров.

Подборка ссылок по теме:

• Презентация по Perl 6 Pod;
• Примеры использования модуля Test;
• Примеры использования Test::Mock;
• Здесь можно следить за появлением новых модулей Perl 6;

Как обычно, я буду рад вашим вопросам, замечаниям, дополнениям и тп.

Метки: Perl, Разработка, Тестирование.