view release on metacpan or  search on metacpan

pod/perlsyn.pod  view on Meta::CPAN

=head2 PODs: Embedded Documentation
X<POD> X<documentation>

Perl has a mechanism for intermixing documentation with source code.
While it's expecting the beginning of a new statement, if the compiler
encounters a line that begins with an equal sign and a word, like this

    =head1 Here There Be Pods!

Then that text and all remaining text up through and including a line
beginning with C<=cut> will be ignored.  The format of the intervening
text is described in L<perlpod>.

This allows you to intermix your source code
and your documentation text freely, as in

    =item snazzle($)

    The snazzle() function will behave in the most spectacular
    form that you can possibly imagine, not even excepting
    cybernetic pyrotechnics.

    =cut back to the compiler, nuff of this pod stuff!

    sub snazzle($) {
        my $thingie = shift;
        .........
    }

Note that pod translators should look at only paragraphs beginning
with a pod directive (it makes parsing easier), whereas the compiler
actually knows to look for pod escapes even in the middle of a
paragraph.  This means that the following secret stuff will be
ignored by both the compiler and the translators.

    $x=3;
    =secret stuff
     warn "Neither POD nor CODE!?"
    =cut back
    print "got $x\n";

You probably shouldn't rely upon the C<warn()> being podded out forever.
Not all pod translators are well-behaved in this regard, and perhaps
the compiler will become pickier.

One may also use pod directives to quickly comment out a section
of code.

=head2 Plain Old Comments (Not!)
X<comment> X<line> X<#> X<preprocessor> X<eval>

Perl can process line directives, much like the C preprocessor.  Using
this, one can control Perl's idea of filenames and line numbers in
error or warning messages (especially for strings that are processed
with C<eval()>).  The syntax for this mechanism is almost the same as for
most C preprocessors: it matches the regular expression

    # example: '# line 42 "new_filename.plx"'
    /^\#   \s*
      line \s+ (\d+)   \s*
      (?:\s("?)([^"]+)\g2)? \s*
     $/x

with C<$1> being the line number for the next line, and C<$3> being
the optional filename (specified with or without quotes).  Note that
no whitespace may precede the C<< # >>, unlike modern C preprocessors.

There is a fairly obvious gotcha included with the line directive:
Debuggers and profilers will only show the last source line to appear
at a particular line number in a given file.  Care should be taken not
to cause line number collisions in code you'd like to debug later.

Here are some examples that you should be able to type into your command
shell:

    % perl
    # line 200 "bzzzt"
    # the '#' on the previous line must be the first char on line
    die 'foo';
    __END__
    foo at bzzzt line 201.

    % perl
    # line 200 "bzzzt"
    eval qq[\n#line 2001 ""\ndie 'foo']; print $@;
    __END__
    foo at - line 2001.

    % perl
    eval qq[\n#line 200 "foo bar"\ndie 'foo']; print $@;
    __END__
    foo at foo bar line 200.

    % perl
    # line 345 "goop"
    eval "\n#line " . __LINE__ . ' "' . __FILE__ ."\"\ndie 'foo'";
    print $@;
    __END__
    foo at goop line 345.

=head2 Experimental Details on given and when

As previously mentioned, the "switch" feature is considered highly
experimental (it is also scheduled to be removed in perl 5.42.0);
it is subject to change with little notice.  In particular,
C<when> has tricky behaviours that are expected to change to become less
tricky in the future.  Do not rely upon its current (mis)implementation.
Before Perl 5.18, C<given> also had tricky behaviours that you should still
beware of if your code must run on older versions of Perl.

Here is a longer example of C<given>:

    use feature ":5.10";
    given ($foo) {
        when (undef) {
            say '$foo is undefined';
        }
        when ("foo") {
            say '$foo is the string "foo"';
        }
        when ([1,3,5,7,9]) {