############################################################################
## $Id: CommandUtil.pm,v 1.2 2002/04/18 05:42:45 ehood Exp $
############################################################################
##	Documentation after __END__
############################################################################

package CommandUtil;

require Exporter;
@ISA = qw(Exporter);
@EXPORT = qw(
  &usage
);

#== Print usage statement.
#=#
sub usage {
  require Pod::Usage;
  my $verbose   = shift || 0;
  my $exit_code	= shift;

  if ($verbose == 0) {
    Pod::Usage::pod2usage(-verbose => $verbose);
  } else {
    my $pager = $ENV{'PAGER'} || 'more';
    local(*PAGER);
    my $fh = (-t STDOUT && open(PAGER, "|$pager")) ? \*PAGER : \*STDOUT;
    Pod::Usage::pod2usage(-verbose => $verbose,
                          -output  => $fh);
    close(PAGER)  if ($fh == \*PAGER);
  }
  defined($exit_code) && exit($exit_code);
}


1;

__END__

=head1 NAME

CommandUtil - Utility routines for devtools commands.

=head1 SYNOPSIS

  use CommandUtil;

=head1 DESCRIPTION

A collection of common utility routines for command-line programs.

=head1 FUNCTIONS

=over

=item C<usage>

Print embedded POD by using L<Pod::Usage>.  The POD is converted with
Pod::Text and piped to the user's pager.  If execution of the pager
fails, or STDOUT is not a terminal, the documentation goes to STDOUT.

The C<usage> function can be invoked as follows:

  usage();		       # Verbosity set to 0
  usage($verbose);
  usage($verbose, $exit_code);

The C<$verbose> argument is treated the same as in L<Pod::Usage>.
If and only if the C<$exit_code> is specified, C<exit> will be called
with specified value.

=back

=head1 AUTHOR

Earl Hood, earl@earlhood.com

=cut