=over

=item do BLOCK

Not really a function.  Returns the value of the last command in the
sequence of commands indicated by BLOCK.  When modified by a loop
modifier, executes the BLOCK once before testing the loop condition.
(On other statements the loop modifiers test the conditional first.)

C<do BLOCK> does I<not> count as a loop, so the loop control statements
C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
See L<perlsyn> for alternative strategies.

=item do SUBROUTINE(LIST)

A deprecated form of subroutine call.  See L<perlsub>.

=item do EXPR

Uses the value of EXPR as a filename and executes the contents of the
file as a Perl script.  Its primary use is to include subroutines
from a Perl subroutine library.

    do 'stat.pl';

is just like

    eval `cat stat.pl`;

except that it's more efficient and concise, keeps track of the current
filename for error messages, searches the @INC libraries, and updates
C<%INC> if the file is found.  See L<perlvar/Predefined Names> for these
variables.  It also differs in that code evaluated with C<do FILENAME>
cannot see lexicals in the enclosing scope; C<eval STRING> does.  It's the
same, however, in that it does reparse the file every time you call it,
so you probably don't want to do this inside a loop.

If C<do> cannot read the file, it returns undef and sets C<$!> to the
error.  If C<do> can read the file but cannot compile it, it
returns undef and sets an error message in C<$@>.   If the file is
successfully compiled, C<do> returns the value of the last expression
evaluated.

Note that inclusion of library modules is better done with the
C<use> and C<require> operators, which also do automatic error checking
and raise an exception if there's a problem.

You might like to use C<do> to read in a program configuration
file.  Manual error checking can be done this way:

    # read in config files: system first, then user
    for $file ("/share/prog/defaults.rc",
               "$ENV{HOME}/.someprogrc")
   {
	unless ($return = do $file) {
	    warn "couldn't parse $file: $@" if $@;
	    warn "couldn't do $file: $!"    unless defined $return;
	    warn "couldn't run $file"       unless $return;
	}
    }

=back