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...