Perl Best Practices

14.7. Interapplication Consistency

Factor out common command-line interface components into a shared module.

Tools such as Getopt::Long, Getopt::Clade, and Getopt::Euclid make it easy to follow the advice of the "Command-Line Structure" guideline to enforce a single consistent command-line structure across all of your applications.

If you're using Getopt::Long or Getopt::Clade, you can simply create a module that provides a suitable description of the standard interface. For example, if you're using Getopt::Clade, you might create a module (such as in Example 14-6) that provides the standard interface features that every application is expected to provide:

Example 14-6. Standard interface components for Getopt::Clade

package Corporate::Std::Cmdline; use strict; use warnings; use Getopt::Clade q{ -i[n] [=] <file:in> Specify input file [default: '-'] -o[ut] [=] <file:out> Specify output file [default: '-'] -v Print all warnings --verbose [ditto] }; 1;

# Magic true value required at the end of every module

You could then reuse it in each program you created. For example, you could refactor Example 14-4 to Example 14-7.

Example 14-7. Standardized command-line parsing via Getopt::Clade

# Specify and parse valid command-line arguments... use Corporate::Std::Cmdline plus => q{ -l[en] [=] <l:+int> Display length [default: 24 ] -w[id] [=] <w:+int> Display width [default: 78 ] };

# Report intended behaviour... if ($ARGV{-v}) { print "Loading first $ARGV{'-l'} chunks of file: $ARGV{'-i'}\n" }

# etc.

Getopt::Euclid allows you to construct interface specification modules in a similar way. The main difference is that those modules mainly contain POD (see Example 14-8).

Example 14-8. Standard interface components for Getopt::Euclid

package Corporate::Std::Cmdline; use Getopt::Euclid; 1;

# POD-only modules still need a magic true value at the end =head1 STANDARD OPTIONS =over =item -i[nfile] [=] <file> Specify input file =for Euclid: file.type: readable file.default: '-' =item -o[utfile] [=] <file> Specify output file =for Euclid: file.type: writable file.default: '-' =item -v[erbose] Print all warnings =item --version =item --usage =item --help =item --man Print the usual program information =back

Once that module was installed in the normal way, you could refactor Example 14-5 to the implementation shown in Example 14-9. Note that, once again, only the application-specific arguments need to be specified within the application itself.

Example 14-9. Standardized command-line parsing via Getopt::Euclid

# Handle command lines of the form:

#

# > orchestrate -in source.txt -o=dest.orc -verbose

# Create a command-line parser that implements the documentation below... use Corporate::Std::Cmdline;

# Report intended behaviour... if ($ARGV{-v}) { print "Loading first $ARGV{-l} chunks of file: $ARGV{-i}\n" }

# etc.

_ _END_ _ =head1 NAME orchestrate - Convert a file to Melkor's .orc format =head1 VERSION This documentation refers to orchestrate version 1.9.4 =head1 USAGE orchestrate -in source.txt -out dest.orc -verbose -len=24 =head1 OPTIONS =over =item -l[en] [=] <l> Display length (default is 24 lines) =for Euclid: l.type: integer > 0 l.default: 24 =item -w[id] [=] <w> Display width (default is 78 columns) =for Euclid: w.type: integer > 0 w.default: 78 =back =head1 STANDARD INTERFACE See L<Corporate::Std::Cmdline> for a description of the standard command-line arguments available for all applications in the Strate suite. =begin remainder of documentation here...