Friday, March 19, 2010

Plain Old Documentation( POD) in perl

If you know how to write the perl codes then you should also know "How to document your script for better user interface". When you run script then if any of the wrong input should be told by script and user should be able to know how to use your script.

So the solution is use of POD::Usage module from perl. If you want to know more on basics of POD refer to this link. This link has good explanation on pod2usage.


pod2usage will print a usage message for the invoking script (using its embedded pod documentation) and then exit the script with the desired exit status. The usage message printed may have any one of three levels of "verboseness": 

Verbose = 0; Only SYNOPSIS
Verbose = 1; SYNOPSIS along with OPTIONS(command line arguments)
Verbose = 2; Full manual Page

Default Exit status: 2, verbose: 0
If exit status < 2, default Verbose = 1, else default verbose = 0
If verbose = 0, default exit status = 2, else default exit =1

If exit status < 2, output printed on STDOUT, otherwise on STDERR.

Usage:
use POD::Usage;

my $message_text = "This text precedes the usage message.";
my $exit_status = 2;
my $verbose_level = 0;
my $filehandle = \*STDERR;

pod2usage($message_text); # Will print a message immediately before printing usage message

pod2usage($exit_status); # Prints usage message depending upon exit status

pod2usage( { -message => $message_text ,
                    -exitval => $exit_status ,
                    -verbose => $verbose_level,
                    -output => $filehandle } );

Hash Keys for pod2usage(Arguments): Refer to this page for more help

-message : To print message before usage


-exitval : value to be passed to exit().


-verbose : Describes Level of usage message to be printed


-output : File handle where to print usage e.g. STDOUT, STDERR or any file


-input : A reference to a filehandle from which the invoking script's pod documentation should be read. Default is $0 i.e. current file.

-sections : Can print sections described in this section list as string e.g. "NAME|SYNOPSIS|OPTIONS", but only when verbose is 99.


-pathlist :A list of directory paths. If input file not in current directory then used.

-noperldoc : It will call perldoc if verbose >2.


A good example for using pod2usage(), for more refer to this link 

=================================================================

use Getopt::Long; 
use Pod::Usage;

my $args = @ARGV; # After GetOptions @ARGV will be undefined
GetOptions(
       'opt=s'    => \$option,
       'help'     => \$help,
       'man'      => \$man,
     ) or pod2usage( -message => "Try \"perl $0 -help\" for more information", exitval => 2);



pod2usage( -verbose => 1 ) if( $help || !$args);

pod2usage(-verbose => 2) if($man);
;1
__END__
 
=head1 NAME
 
   sample - Using GetOpt::Long and Pod::Usage
 
=head1 SYNOPSIS
 
   sample [options] [file ...]
 
   Options:
   -help brief help message
   -man  full documentation
   -opt  Option value
 
=head1 OPTIONS
 
=over 8
 
=item B<-help>
 
   Print a brief help message and exits.
 
=item B<-man>
 
   Prints the manual page and exits.

=item B<-opt>
 
   Takes some integer value
 
=back
 
=head1 DESCRIPTION
 
   B<This program> will read the given input in opt and do something
   useful with the contents thereof.
 
=cut

#=================================================================
Some important Links:
POD TUTORIAL
POD USAGE IN PERLDOC
PERLPOD IN PERLDOC




No comments:

Post a Comment