Perl - Dokumentasi Tertanam

Anda dapat menyematkan dokumentasi Pod (Plain Old Text) di modul dan skrip Perl Anda. Berikut adalah aturan untuk menggunakan dokumentasi yang disematkan di Kode Perl Anda -

Mulailah dokumentasi Anda dengan baris kosong, a =head1 perintah di awal, dan akhiri dengan a =cut

Perl akan mengabaikan teks Pod yang Anda masukkan ke dalam kode. Berikut ini adalah contoh sederhana menggunakan dokumentasi tertanam di dalam kode Perl Anda -

#!/usr/bin/perl

print "Hello, World\n";

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

print "Hello, Universe\n";

Ketika kode di atas dijalankan, itu menghasilkan hasil sebagai berikut -

Hello, World
Hello, Universe

Jika Anda akan meletakkan Pod Anda di akhir file, dan Anda menggunakan tanda potong __END__ atau __DATA__, pastikan untuk meletakkan baris kosong sebelum perintah Pod pertama seperti berikut, jika tidak tanpa baris kosong sebelumnya yang =head1, banyak penerjemah tidak akan mengenali =head1 sebagai memulai blok 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";

Ketika kode di atas dijalankan, itu menghasilkan hasil sebagai berikut -

Hello, World

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

Mari kita ambil satu contoh lagi untuk kode yang sama tanpa membaca bagian 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";

Ketika kode di atas dijalankan, itu menghasilkan hasil sebagai berikut -

Hello, World

Apa itu POD?

Pod adalah bahasa markup yang mudah digunakan yang digunakan untuk menulis dokumentasi untuk Perl, program Perl, dan modul Perl. Ada berbagai penerjemah yang tersedia untuk mengonversi Pod ke berbagai format seperti teks biasa, HTML, halaman manual, dan banyak lagi. Markup Pod terdiri dari tiga jenis paragraf dasar -

Ordinary Paragraph - Anda dapat menggunakan kode pemformatan dalam paragraf biasa, untuk huruf tebal, miring, gaya kode, hyperlink, dan lainnya.
Verbatim Paragraph - Paragraf kata demi kata biasanya digunakan untuk menampilkan blok kode atau teks lain yang tidak memerlukan penguraian atau pemformatan khusus, dan yang tidak boleh digabungkan.
Command Paragraph- Paragraf perintah digunakan untuk perlakuan khusus pada seluruh bagian teks, biasanya sebagai judul atau bagian dari daftar. Semua paragraf perintah dimulai dengan =, diikuti dengan pengenal, diikuti oleh teks arbitrer yang dapat digunakan oleh perintah sesuka hati. Perintah yang saat ini dikenal adalah -

=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

Contoh POD

Pertimbangkan POD berikut -

=head1 SYNOPSIS
Copyright 2005 [TUTORIALSOPOINT].
=cut

Kamu dapat memakai pod2html utilitas yang tersedia di Linux untuk mengubah POD di atas menjadi HTML, sehingga akan menghasilkan hasil sebagai berikut -

Selanjutnya, perhatikan contoh berikut -

=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

Saat Anda mengonversi POD di atas menjadi HTML menggunakan pod2html, ini akan menghasilkan hasil sebagai berikut -

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.