Учебники

Perl — встроенная документация

Ноябрь 12, 2018

Вы можете встроить документацию Pod (Plain Old Text) в свои модули и скрипты Perl. Ниже приведено правило для использования встроенной документации в вашем коде Perl.

Начните документацию с пустой строки, команды a = head1 в начале, и завершите ее с помощью = cut

Perl будет игнорировать текст Pod, который вы ввели в коде. Ниже приведен простой пример использования встроенной документации внутри вашего кода Perl:

Live Demo

#!/usr/bin/perl

print "Hello, World\n";

=head1 Hello, World Example
This example demonstrate very basic syntax of Perl.
=cut

print "Hello, Universe\n";

Когда приведенный выше код выполняется, он дает следующий результат — 

Hello, World
Hello, Universe

Если вы собираетесь поместить свой Pod в конец файла и используете метку вырезания __END__ или __DATA__, обязательно поставьте пустую строку перед первой командой Pod следующим образом, в противном случае перед пустой строкой = head1 , многие переводчики не распознали бы = head1 как начало блока Pod.

Live Demo 

#!/usr/bin/perl

print "Hello, World\n";

while(<DATA>) {
  print $_;
}

__END__

=head1 Hello, World Example
This example demonstrate very basic syntax of Perl.
print "Hello, Universe\n";

Когда приведенный выше код выполняется, он дает следующий результат — 

Hello, World

=head1 Hello, World Example
This example demonstrate very basic syntax of Perl.
print "Hello, Universe\n";

Давайте возьмем еще один пример для того же кода без чтения части DATA —

Live Demo 

 #! / USR / бен / Perl

 print "Hello, World \ n";

 __КОНЕЦ__

 = head1 Привет, пример мира
 Этот пример демонстрирует очень простой синтаксис Perl.
 print "Привет, Вселенная \ n";

Когда приведенный выше код выполняется, он дает следующий результат — 

Hello, World

Что такое POD?

Pod — это простой в использовании язык разметки, используемый для написания документации для Perl, программ Perl и модулей Perl. Существуют различные переводчики для преобразования Pod в различные форматы, такие как простой текст, HTML, справочные страницы и многое другое. Стручковая разметка состоит из трех основных видов абзацев —

  • Обычный абзац — Вы можете использовать коды форматирования в обычных абзацах, для полужирного, курсива, стиля кода, гиперссылок и многого другого.

  • Дословный абзац. Дословные абзацы обычно используются для представления кодового блока или другого текста, который не требует какого-либо специального анализа или форматирования и который не следует переносить.

  • Командный абзац — командный абзац используется для специальной обработки целых кусков текста, обычно как заголовков или частей списков. Все абзацы команды начинаются с =, за которым следует идентификатор, за которым следует произвольный текст, который команда может использовать по своему усмотрению. В настоящее время признаны команды —

Обычный абзац — Вы можете использовать коды форматирования в обычных абзацах, для полужирного, курсива, стиля кода, гиперссылок и многого другого.

Дословный абзац. Дословные абзацы обычно используются для представления кодового блока или другого текста, который не требует какого-либо специального анализа или форматирования и который не следует переносить.

Командный абзац — командный абзац используется для специальной обработки целых кусков текста, обычно как заголовков или частей списков. Все абзацы команды начинаются с =, за которым следует идентификатор, за которым следует произвольный текст, который команда может использовать по своему усмотрению. В настоящее время признаны команды — 

=pod
=head1 Heading Text
=head2 Heading Text
=head3 Heading Text
=head4 Heading Text
=over indentlevel
=item stuff
=back
=begin format
=end format
=for format text...
=encoding type
=cut

Примеры POD

Рассмотрим следующий POD — 

=head1 SYNOPSIS
Copyright 2005 [TUTORIALSOPOINT].
=cut

Вы можете использовать утилиту pod2html, доступную в Linux, для преобразования вышеупомянутого POD в HTML, поэтому она даст следующий результат:

Copyright 2005 [TUTORIALSOPOINT].

Далее рассмотрим следующий пример — 

=head2 An Example List

=over 4
=item * This is a bulleted list.
=item * Here's another item.
=back
=begin html
<p>
Here's some embedded HTML.  In this block I can
include images, apply <span style="color: green">
styles</span>, or do anything else I can do with
HTML.  pod parsers that aren't outputting HTML will
completely ignore it.
</p>

=end html

Когда вы преобразуете POD в HTML с помощью pod2html, он даст следующий результат —

52
Share: