В одном файле miu можно набрать статью, в нём же — код и тесты к нему, а потом протестировать код и создать документацию, набрав всего лишь одну команду miu.
Быстрый старт
Miu считает любой текст, примыкающий к началу строки, текстом статьи, а с отступом — кодом.
my $abs = 16; # 16
теперь я запущу команду
`miu 0x` # 0x-miu.miu.pl ...\n
Файл этой статьи называется у меня miu/0x-miu.miu. Он будет выполнен как тест. Точки — это успешно пройденные тесты. E — не пройденные. F — которые умерли через die. Точки соответствуют строкам кода с #. Выполняются все файлы начинающиеся на 0x.
То что стоит после # считается строкой для сравнения без начальных и концевых пробелов. Если нам нужно сравнить с выражением perl, то ставим ##. Сравните:
1+5 # 6
1+5 ## 1+5
" 26\n" # \s26\n
bless {a=>2}, "Class" ## bless {a=>2}, "Class"
Львиная доля тестов приходится как раз на умное сравнение (обратите внимание на последний тест). Однако иногда мне бы хотелось сказать «больше» или «меньше».
2**3 #< 10
8 #!= 3
"8" #== 8
"meat" #ne eat
"abc" ##lt "eat"
"test" #~ es.$
{} #!~ (?i)^array
123456 #startswith 123
123456 #endswith 456
Если тест бросает исключение, то его можно протестировать так:
die "myexception" #@ startswith myexception
die "myexception" ##@ !~ qr/чего\?/
die "myexception" #@ !~ чего\?
Тестируем поток вывода:
print "123\n" #>> 123\n
А поток ошибок:
print STDERR " +26\t\r\e\v" #&> \s+26\t\r\e\v
#! тестирует переменную ошибок ввода-вывода $!
open $f, "/"; ##! ""
Программный код
Код программы так же может быть записан в файл miu. Он так же должен иметь отступ.
Чтобы переключатся между кодом и тестом нужно использовать [ code] и [test] с начала строки.
[ code]
package A::A;
sub A { print "A" }
1;
[test]
use A::A;
&A::A::A; #>> A
[ code]
package main;
use A::A;
&A::A::A;
[test]
`.miu/00-miu` # A
Каждая строка package будет генерировать файл .miu/lib/A/A.pm, и он будет подключён к тесту.
Изменить путь к каталогу lib можно ключом -u path/to/mylib.
А к каталогу с кодом программы: -b path/to/myexecutefile
Как выполнить тесты из раздела статьи
Часто пишешь-пишешь, написал огромную статью, тесты все в ней запускать не хочется. Нужно запустить какой-то, над которым работаешь.
`miu 0x "метки"` # 0x-miu.miu.pl .\n
Выполнятся все тесты в разделе, название которого начинается на метки или Метки — сравнение регистронезависимое.
== Метки 1
В статье 0x-miu.miu.pl это раздел Метки 1. Если таких разделов два, то выполнятся оба. Несколько — несколько.
Какие файлы создаёт miu
miu ищет файлы в текущей директории. Хотя в маске можно указать путь к файлам.
`cd ..; miu miu/0x -o miu/.miu` # miu/0x-miu.miu.pl ...\n
После запуска miu создат выходной каталог .miu в текущей директории.
Вы можете использовать ключ -o, чтобы изменить его.
- .miu/название_файла.markdown
- .miu/название_файла.t
- .miu/название_файла.log
- .miu/название_файла.stat
- .miu\miu-tmp-fh
- *.markdown - это документация на языке markdown. То есть, это копия файла miu\название_файла.miu, без тегов
[test]и[ code] - *.t - это тест
- *.log - это вывод теста
- *.stat - то же что и *.log, только с названиями токенов
- miu-tmp-fh - вспомогательный файл для тестирования ввода-вывода (#>> и #&>)
Эти файлы перезаписываются после каждого теста.
-e ".miu/0x-miu.log" # 1
Можно сразу вывести ошибки на консоль:
`miu -l 0x` #~ \.*
После первой же ошибки остальные файлы не выполнятся.
Установка
miu выложена на github и bitbucket:
Установить через git:
- git clone git@github.com:darviarush/miu.git
- git clone git@bitbucket.org:darij/miu.git
Далее выполните make link, эта команда создаст символьную ссылку на исполняемый файл miu в директории /bin/.
Как конвертировать markdown в html
Просто установите модуль perl Text::Markdown. miu его сразу «подхватит» и будет генерировать файл *.html в каталоге .miu.
cpan install Text::Markdown
Как конвертировать markdown в bbcode
Нужен Text::Markdown:
cpan install Text::Markdown
Необязательно:
cpan install Text::Typography
cpan install HTML::Entities
Откуда название miu?
miu названа в честь Рррумиу — героини романа Павла Шумила «Этот мир придуман не нами» из цикла «Окно контакта — 3».
TODO или куда miu будет развиваться
Что ещё предстоит сделать:
- Поддержка других языков программирования — сейчас поддерживается только perl.
- Конвертеры из markdown в другие языки разметки. На данный момент miu создаёт html и bbcode, но есть же ещё различные вариации: wiki, trac, lorcode и т. д.
- Автоматическая публикация получившихся статей на различных сайтах. Например, на habrahabr.ru, linux.org.ru, livejournal.com, wikipedia.org и т. д.
Перемещено splinter из doc
