Perl - osadzona dokumentacja

Możesz osadzić dokumentację Pod (zwykły stary tekst) w swoich modułach i skryptach Perla. Poniżej znajduje się zasada korzystania z dokumentacji osadzonej w kodzie Perla -

Rozpocznij dokumentację od pustej linii, a =head1 polecenie na początku i zakończ je znakiem =cut

Perl zignoruje tekst Poda wprowadzony w kodzie. Poniżej znajduje się prosty przykład użycia dokumentacji osadzonej w kodzie Perla -

#!/usr/bin/perl

print "Hello, World\n";

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

print "Hello, Universe\n";

Wykonanie powyższego kodu daje następujący wynik -

Hello, World
Hello, Universe

Jeśli zamierzasz umieścić swój Pod na końcu pliku i używasz znaku cięcia __END__ lub __DATA__, pamiętaj, aby umieścić tam pusty wiersz przed pierwszym poleceniem Poda w następujący sposób, w przeciwnym razie bez pustej linii przed =head1, wielu tłumaczy nie rozpoznałoby znaku =head1 jako rozpoczęcie bloku Pod.

#!/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";

Wykonanie powyższego kodu daje następujący wynik -

Hello, World

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

Weźmy jeszcze jeden przykład dla tego samego kodu bez czytania części DANE -

#!/usr/bin/perl

print "Hello, World\n";

__END__

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

Wykonanie powyższego kodu daje następujący wynik -

Hello, World

Co to jest POD?

Pod to prosty w użyciu język znaczników używany do pisania dokumentacji dla Perla, programów Perla i modułów Perla. Dostępnych jest wielu tłumaczy umożliwiających konwersję Poda do różnych formatów, takich jak zwykły tekst, HTML, strony podręcznika i inne. Znaczniki pod składają się z trzech podstawowych rodzajów akapitów -

Ordinary Paragraph - Możesz używać kodów formatowania w zwykłych akapitach, pogrubienia, kursywy, stylu kodu, hiperłączy i nie tylko.
Verbatim Paragraph - Dosłowne akapity są zwykle używane do prezentowania bloku kodu lub innego tekstu, który nie wymaga specjalnego przetwarzania ani formatowania i który nie powinien być zawijany.
Command Paragraph- Akapit polecenia jest używany do specjalnego traktowania całych fragmentów tekstu, zwykle jako nagłówków lub części list. Wszystkie akapity poleceń zaczynają się od znaku =, po którym następuje identyfikator, po którym następuje dowolny tekst, którego polecenie może użyć w dowolny sposób. Obecnie rozpoznawane polecenia to -

=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

Przykłady POD

Rozważ następujący POD -

=head1 SYNOPSIS
Copyright 2005 [TUTORIALSOPOINT].
=cut

Możesz użyć pod2html narzędzie dostępne w systemie Linux do konwersji powyższego POD na HTML, dzięki czemu da następujący wynik -

Następnie rozważ następujący przykład -

=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

Kiedy przekonwertujesz powyższy POD na HTML za pomocą pod2html, da to następujący wynik -

An Example List
   This is a bulleted list.
   Here's another item.
Here's some embedded HTML. In this block I can include images, apply 
styles, or do anything else I can do with HTML. pod parsers that aren't 
outputting HTML will completely ignore it.