The =begin / =end Pod block

Pod blocks start with the = sign, which should be the first non-space character in the line (thus, you cannot start a Pod block as you do a one-line comment—next to the code on the same line).

The block is marked with the pair of =begin and =end directives, each of which must be followed by a Perl 6 identifier describing the type of the data contained in the Pod block. There are a few predefined identifiers, they are either fully lowercased or fully uppercased. Consider a few examples of the most useful Pod blocks.

=begin pod
This program is the first program in Perl 6.
=end pod

say 'Hello, World!'

Here, the Pod block begins with =begin pod and stops with =end pod. Everything outside of the block is a regular Perl 6 program.

If you simply run the program, then the Pod is ignored. Save the program in a file and run it from a command-line as follows:

$ perl6 pod.pl
Hello, World!

In Chapter 1, What is Perl 6?, we looked at different command-line options that the Rakudo Star compiler supports. It is time to use one of them --doc to see how the compiler extracts the Pod documentation from the program and prints it without executing the program itself:

$ perl6 --doc pod.pl
This program is the first program in Perl 6.

In the preceding example, the type of block was pod. There are other types of Pod blocks.

The table type creates a Pod with a table:

=begin table
    Language   Year of appearance
    C          1973
    C++        1983
    Perl       1987
    Perl 6     2000
=end table

You can do some minimal formatting of the table in the source code yourself, but the Pod parser and formatter (parts of Rakudo in our case) do some extra jobs to display the table nicely. This is how the table will look if you run the program with the --pod command-line option:

$ perl6 --doc pod.pl
Language  Year of appearence 
C         1973               
C++       1983               
Perl      1987                
Perl 6    2000 

Notice that the indentation is lost and the table rows are printed from the beginning of the line. Another change is that there are two spaces between the columns while we had a bit more in the source code.

The table can optionally contain a caption, which you place in the =begin line using the so-called adverbial syntax, as shown in the following example:

=begin table :caption<History of Programming Languages>
    Language    Year of appearance
    C           1973
    C++         1983
    Perl        1987
    Perl 6      2000
=end table

The caption will be printed above the table:

$ perl6 --doc pod.pl
History of Programming Languages
Language  Year of appearance
C         1973               
C++       1983               
Perl      1987               
Perl 6    2000  

Before we go further into the other types of Pod blocks in Perl 6, let's learn alternative syntaxes to declare a Pod block:

• Abbreviated blocks
• Paragraph blocks

In the abbreviated block, the opening = sign is immediately followed by the name of the Pod block type. No closing =end directive is needed anymore, and the end of the Pod block will be the indicated by either an empty line or by the start of another Pod block.

Here is another example of the table block with the abbreviated syntax:

=table
    Language    Year of appearance
    C           1973
    C++         1983
    Perl        1987
    Perl 6      2000

say 'Ok';

The Pod block with a table ends before the empty line. After that, the compiler is switching back to parsing the Perl 6 code.

In the paragraph block, you start the Pod section with the =for directive, followed by the identifier. Thus, the last example may start with either =table or =for table.

This syntax is more natural for other types of Pod blocks whose content is usually short. For example, headers or items of a list. In those cases, the content of the block is supplied on the same line, immediately after the opening directive, as shown in the following example, which reflects part of the contents of the current chapter:

=head1 Writing Code
=head2 Comments in Perl 6
=item One-line comments
=item Multi-line comments
=item Embedded comments

Extracting the documentation with the --doc command-line option generates the following output:

Writing Code
  Comments in Perl 6
  * One-line comments
  * Multi-line comments
  * Embedded comments

It contains headers on two levels and a simple bullet list.