Изучаем Perl 6: как написать свой модуль

31 октября 2012

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

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

.
├── lib
│   └── Sitemap
│       └── XML
│           └── Parser.pm6
├── META.info
├── README
└── t
    └── main.t

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

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

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

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

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

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

use v6;
use lib 'lib';
use Test;

ok(1);

done;

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

prove -e perl6 ./t

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

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

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

{
"name"        : "Sitemap::XML::Parser",
"version"     : "*",
"description" : "A Perl 6 module for parsing sitemap.xml files",
"depends"     : [
                  "LWP::Simple",
                  "XML::Parser::Tiny",
                  "DateTime::Format::W3CDTF"
                ],
"source-type" : "git",
"source-url"  : "git://github.com/afiskon/p6-sitemap-xml-parser.git"
}

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

perl6 --doc ./lib/Sitemap/XML/Parser.pm6 > ./README

Используя этот подход, вам не придется беспокоится о том, как поддерживать файл 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. Пробуем установить модуль:

panda update
panda install Sitemap::XML::Parser

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

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

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

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

Метки: , , .

Подпишись через RSS, E-Mail, Google+, Facebook, Vk или Twitter!

Понравился пост? Поделись с другими: