LINUX.ORG.RU

miu — система одновременного кодирования, документирования и тестирования

 , , , ,


0

1

В одном файле 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, чтобы изменить его.

  1. .miu/название_файла.markdown
  2. .miu/название_файла.t
  3. .miu/название_файла.log
  4. .miu/название_файла.stat
  5. .miu\miu-tmp-fh
  6. *.markdown - это документация на языке markdown. То есть, это копия файла miu\название_файла.miu, без тегов [test] и [ code]
  7. *.t - это тест
  8. *.log - это вывод теста
  9. *.stat - то же что и *.log, только с названиями токенов
  10. miu-tmp-fh - вспомогательный файл для тестирования ввода-вывода (#>> и #&>)

Эти файлы перезаписываются после каждого теста.

-e ".miu/0x-miu.log" # 1

Можно сразу вывести ошибки на консоль:

`miu -l 0x` #~ \.*

После первой же ошибки остальные файлы не выполнятся.

Установка

miu выложена на github и bitbucket:

  1. https://github.com/darviarush/miu
  2. https://bitbucket.org/darij/miu

Установить через git:

  1. git clone git@github.com:darviarush/miu.git
  2. 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 будет развиваться

Что ещё предстоит сделать:

  1. Поддержка других языков программирования — сейчас поддерживается только perl.
  2. Конвертеры из markdown в другие языки разметки. На данный момент miu создаёт html и bbcode, но есть же ещё различные вариации: wiki, trac, lorcode и т. д.
  3. Автоматическая публикация получившихся статей на различных сайтах. Например, на habrahabr.ru, linux.org.ru, livejournal.com, wikipedia.org и т. д.

Оригинал статьи

Перемещено splinter из doc

В одном файле miu можно набрать статью, в нём же — код и тесты к нему, а потом протестировать код и создать документацию

xxx: Таким надо на первую страницу трудовой ставить красную печать «Осторожно, АвтоКАДчик!!!».
А то они чертеж, спецификацию, и баланс предприятия в один файл запихнут: «а зачем мне на компьютере ДВА файла?»

Old_Hamster ★★★ ()
Последнее исправление: Old_Hamster (всего исправлений: 1)

Автоматическая публикация получившихся статей на различных сайтах. Например
linux.org.ru

Модераторы будут в восторге.

anonymous ()

автор, тебе надо все-таки переписать свой пост

сейчас у тебя что-то типа полной справки, а нужен все же *пример* использования

сделай пару файлов на 5...10 строк каждый, в одном определи класс/модуль, в другом запускалку класса/модуля (main грубо говоря), и затем их прокомментируй

дальше: то, что ты называешь тестами, наверно, все же, инварианты?

наконец, я не в курсе, позволяет ли движок лор-а писать «[cоde]» — я тупо заменил латинскую букву «о» на русскую, это все же лучше, чем пробел после скобки

насчет фич: мне было бы интересно

0. узнать, c какими системами literate programming ты знаком

1. поддержка с++ (сойдет парсинг регулярными выражниями)

2. поддержка сборки классов из методов

3. поддержка сборки методов из аспектов

... но честно говоря я даже код твой еще не посмотрел

www_linux_org_ru ★★★★★ ()
Последнее исправление: www_linux_org_ru (всего исправлений: 2)

Уже написали наверное, повторюсь, чем это лучше чем emacs + org mode + babel?

loz ★★★★★ ()

Зачем весь этот гемморой? Напишите модуль экспорта на линукс.орг.ру к knitr и у вас в распоряжении: Marcdown, HTML, LaTeX, экспорт в pdf, публикация на rpubs и вся мощь языка R.

BaBL ★★★★★ ()

Ну и зачем это ненужно, да ещё и на перле?

INFOMAN ★★★★★ ()
Вы не можете добавлять комментарии в эту тему. Тема перемещена в архив.