PerlDoc Lesson (CBMG688P, Best Practices laboratory, Stoltzfus)

background

exercise

1. before going any further, note that, to ensure consistent formatting, always put blank lines before and after each perldoc command. The commands are the words preceded by "=" at the beginning of a line.
2. first we will add this at the beginning (only the bold part)

   #!/usr/local/bin/perl -w 
   #
   # 
   
   =pod
   
   =head1 NAME
   
   esearch_wrapper.pl - Perl wrapper for NCBI's esearch web service interface
   
   =head1 SYNOPSIS
   
       esearch_wrapper.pl --email EMAIL --db NCBI_DB --query TERMS --file FILE
   
       --help, --?         print help message
   
   Where I<FILE> is a file name.
   
   Examples:
   
       esearch_wrapper.pl --email=nobody@uerewhon.edu --db=genome --query="Thermanaerovibrio+acidaminovorans[organism]" 
   
   =head1 DESCRIPTION
   
   This wraps NCBI's esearch utility, providing an interface to specify the user's email, the NCBI genome division, query terms, and an output file. If no output file is specified, results go into esearch_query_results.xml.  
   
   Note that this only retrieves IDs, at best.  To download the data requires the efetch utility.  
   
   =head1 BUGS
   
   This is a demonstration script for class.  It illustrates some programming practices, but has several known issues: 
   
   We haven't completed the processing of XML results.  
   
   This uses wget (better to use LWP or BioPerl). Currently the output is confusing, due to messages on STDERR from wget.  
   
   =head1 VERSION
   
   $Id$
   
   =head1 AUTHOR
   
   Arlin Stoltzfus (arlin@umd.edu)
   
   =cut
   
   

3. Now we'll document the interface for our only subroutine (add only the bold part):

   ...
   exit; 
   
   =head2 Usage
   
    Title   : Usage
    Usage   : Usage( "lots of problems here, gotta go" )
    Function: Prints a usage message to STDERR, then exits
    Returns : nothing
    Args    : Any messages you want to send to the user on exit. 
   
   =cut
   
   sub Usage
   {
   ...
   

4. Now we will see what Perl thinks of this:
   unix_prompt$ perldoc esearch_wrapper.pl
5. That's all we really need. But now notice that there is a kind of redundancy-- we have 2 usage messages, one in the POD, and one in our Usage subroutine. That's not good practice! Actually we can fix this easily, because there already exists a POD module (Pod::Usage) that will do this for us:
   • First, add this at the top
     use Pod::Usage;
   • Now, delete the old Usage subroutine
   • Finally, change the code to invoke pod2usage (works just like our old subroutine):

     GetOptions(
         "email=s" => \$email,   
         "query=s" => \$search_terms, 
         "db=s" => \$db, 
         "file=s" => \$outfile, 
         "help|?" => \$help
         ) or pod2usage( "Invalid command-line options." );
     
     pod2usage() if defined( $help );