Perl - Documentazione incorporata

Puoi incorporare la documentazione Pod (Plain Old Text) nei tuoi moduli e script Perl. Di seguito è riportata la regola per utilizzare la documentazione incorporata nel codice Perl:

Inizia la tua documentazione con una riga vuota, a =head1 comando all'inizio e terminarlo con un =cut

Perl ignorerà il testo del pod che hai inserito nel codice. Di seguito è riportato un semplice esempio di utilizzo della documentazione incorporata all'interno del codice Perl:

#!/usr/bin/perl

print "Hello, World\n";

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

print "Hello, Universe\n";

Quando viene eseguito il codice sopra, produce il seguente risultato:

Hello, World
Hello, Universe

Se hai intenzione di mettere il tuo Pod alla fine del file e stai usando un segno di taglio __END__ o __DATA__, assicurati di mettere una riga vuota lì prima del primo comando Pod come segue, altrimenti senza una riga vuota prima il =head1, molti traduttori non avrebbero riconosciuto il =head1 come avviare un blocco 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";

Quando viene eseguito il codice sopra, produce il seguente risultato:

Hello, World

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

Facciamo un altro esempio per lo stesso codice senza leggere la parte DATA -

#!/usr/bin/perl

print "Hello, World\n";

__END__

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

Quando viene eseguito il codice sopra, produce il seguente risultato:

Hello, World

Cos'è il POD?

Pod è un linguaggio di markup semplice da usare utilizzato per scrivere documentazione per Perl, programmi Perl e moduli Perl. Sono disponibili vari traduttori per convertire Pod in vari formati come testo normale, HTML, pagine man e altro. Il markup del pod è costituito da tre tipi fondamentali di paragrafi:

  • Ordinary Paragraph - È possibile utilizzare codici di formattazione in paragrafi ordinari, per grassetto, corsivo, stile codice, collegamenti ipertestuali e altro.

  • Verbatim Paragraph - I paragrafi Verbatim vengono solitamente utilizzati per presentare un blocco di codice o altro testo che non richiede alcuna analisi o formattazione speciale e che non deve essere inserito.

  • Command Paragraph- Un paragrafo di comando viene utilizzato per il trattamento speciale di intere porzioni di testo, solitamente come intestazioni o parti di elenchi. Tutti i paragrafi del comando iniziano con =, seguito da un identificatore, seguito da testo arbitrario che il comando può utilizzare come preferisce. I comandi attualmente riconosciuti sono:

=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

Esempi di POD

Considera il seguente POD:

=head1 SYNOPSIS
Copyright 2005 [TUTORIALSOPOINT].
=cut

Puoi usare pod2html utilità disponibile su Linux per convertire il POD sopra in HTML, quindi produrrà il seguente risultato:

Quindi, considera il seguente esempio:

=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

Quando converti il ​​POD sopra in HTML usando pod2html, produrrà il seguente risultato:

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.