Perl 6 Pod — формат ведения документации
Александр Загацкий, Витебск, Беларусь
LVEE 2011
Pod is an evolution of Perl 5’s POD markup. Compared to POD, Perl 6’s Pod is much more uniform, somewhat more compact, and considerably more expressive. Established in 2005, specification has undergone several revisions and is currently stable. The specification is written in Perl 6 Pod and is a good means of testing the implementations. There are several implementations in Perl 5 and Perl 6. Presentation covers the differences from Perl 5 POD, key features and experience of Perl 6 Pod personal usage.
Формат разметки Perl 6 Pod перестал быть черновиком. В финальной версии спецификации Synopsis 26 \cite{zag1pod} добавился ряд особенностей. Никогда не еще не было настолько тесной интеграции программного кода и документации к нему.
Так, добавился специальный тип блоков документации – блоки-деклараторы. Данные блоки предваряются специальным комментарием #= , за которым следует текст документации. Оформленные блоки документации ассоциируются с делараторами подпрограмм, а так же переменных. Уникальной особенностью
является тот факт, что эти блоки документации становятся доступными
через специальный атрибут .WHY. Например:
sub fu ( #= This text stored in &fu.WHY
Any !http://www.codecogs.com/png.latex?\textstyle%20bar,%20%20%20%20%23=%20This%20text%20stored%20in!bar.WHY
Mode :!http://www.codecogs.com/png.latex?\textstyle%20baz%20%20%20%23=%20This%20text%20stored%20in!baz.WHY
) { ... }
#= This is a special chainsaw
my SwissArmy !http://www.codecogs.com/png.latex?\textstyle%20chainsaw%20%20%20%20%23=%20(It%20has%20a%20rocket%20launcher)%0D%0A%0D%0A%20say!chainsaw.WHY; # prints: This is a special chainsaw
# (It has a rocket launcher)
В приведенном примере текст документации к переменной !http://www.codecogs.com/png.latex?\textstyle%20chainsaw%20%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%B8%D1%82%D1%81%D1%8F%20%D0%B4%D0%BE%D1%81%D1%82%D1%83%D0%BF%D0%BD%D1%8B%D0%BC%20%D0%B8%D0%B7%20%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%BD%D0%BE%D0%B3%D0%BE%20%D0%BA%D0%BE%D0%B4%D0%B0.%20%D0%92%20%D1%83%D0%BA%D0%B0%D0%B7%D0%B0%D0%BD%D0%BD%D0%BE%D0%BC%20%D0%BF%D1%80%D0%B8%D0%BC%D0%B5%D1%80%D0%B5%20%D0%B1%D0%BB%D0%BE%D0%BA%20%D0%BA%D0%BE%D0%B4%D0%B0%20%D0%B1%D1%83%D0%B4%D0%B5%D1%82%20%D0%B2%D1%8B%D0%B2%D0%B5%D0%B4%D0%B5%D0%BD%20%D0%BD%D0%B0%20%D1%8D%D0%BA%D1%80%D0%B0%D0%BD:%0D%0A%0D%0A%3Cpre%3E%3Ccode%3E%0D%0A%20say!chainsaw.WHY; # prints: This is a special chainsaw
- (It has a rocket launcher)
Уникальна сама концепция, а именно доступ программного кода к документации по нему. То есть становится возможным менять логику программы в зависимости от описанной в документации!
Еще одним примером интеграции документации и кода являются
контекстуальные псевдонимы. Для их определения используется директива
=alias. Например:
# This is actual code...
sub hash_function (!http://www.codecogs.com/png.latex?\textstyle%20key)%0D%0A%20*=alias%20HASHCODE*%0D%0A%20%7B%0D%0A%20%20%20%20my!hash = 0;
for !http://www.codecogs.com/png.latex?\textstyle%20key.split(%22%22)%20-%3E!char {
!http://www.codecogs.com/png.latex?\textstyle%20hash%20=!hash*33 + !http://www.codecogs.com/png.latex?\textstyle%20char.ord;%0D%0A%20%20%20%20%7D%0D%0A%20%20%20%20return!hash;
}
В данном примере определяется псевдоним HASHCODE. Его значением
является следующий за ним программный блок. Теперь, чтобы привести в
документации пример кода достаточно указать имя псевдонима внутри кода
форматирования A<>:
=begin pod
An ancient (but fast) hashing algorithm is used:
=begin code :allow<A>
A<HASHCODE>
=end code
=end pod
В результате в документации будет вставлен блок кода из программы:
An ancient (but fast) hashing algorithm is used:
my 
key.split("") → 
hash *= 33;
char.ord;
}
return $hash;
Это позволяет избежать ручного копирования блоков кода и последующую
актуализацию документации.
Источники
1 Спецификация формата Pod (Synopsis 26). https://github.com/zag/specs/raw/master/S26-documentation.pod
