lib/MHArc/Util.pm

   1 ##--------------------------------------------------------------------------##
   2 ##  File:
   3 ##      $Id: Util.pm,v 1.5 2002/09/13 07:24:18 ehood Exp $
   4 ##  Description:
   5 ##      POD at end of file.
   6 ##--------------------------------------------------------------------------##
   7 ##  Copyright (C) 2002  Earl Hood <earl@earlhood.com>
   8 ##
   9 ##  This program is free software; you can redistribute it and/or modify
  10 ##  it under the terms of the GNU General Public License as published by
  11 ##  the Free Software Foundation; either version 2 of the License, or
  12 ##  (at your option) any later version.
  13 ##
  14 ##  This program is distributed in the hope that it will be useful,
  15 ##  but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 ##  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 ##  GNU General Public License for more details.
  18 ##
  19 ##  You should have received a copy of the GNU General Public License
  20 ##  along with this program; if not, write to the Free Software
  21 ##  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
  22 ##  02111-1307, USA
  23 ##--------------------------------------------------------------------------##
  24
  25 package MHArc::Util;
  26
  27 use Exporter;
  28 @ISA = qw(Exporter);
  29
  30 @EXPORT_OK = qw(
  31   &ch_dir
  32   &cmd
  33   &exec_prg
  34   &mk_dir
  35   &run_prg
  36   &usage
  37 );
  38
  39 ##--------------------------------------------------------------------------##
  40
  41 BEGIN {
  42   $ECHO_CMDS = 0;
  43   $ECHO_ONLY = 0;
  44 }
  45
  46 ##--------------------------------------------------------------------------##
  47
  48 sub cmd {
  49   print "@_\n" if $ECHO_CMDS || $ECHO_ONLY;
  50   if ($ECHO_ONLY) {
  51     return 0;   # bogus ok exit status
  52   }
  53   system @_;
  54 }
  55
  56 sub ch_dir {
  57   my $dir = shift;
  58   print "chdir $dir\n" if $ECHO_CMDS || $ECHO_ONLY;
  59   if ($ECHO_ONLY) {
  60     return 0;
  61   }
  62   chdir $dir;
  63 }
  64
  65 sub run_prg {
  66   print "@_\n"  if $ECHO_CMDS || $ECHO_ONLY;
  67   if (!$ECHO_ONLY) {
  68     my $wait = system @_;
  69     die qq/system @_ failed: $?\n/  if $wait;
  70   }
  71 }
  72
  73 sub mk_dir {
  74   my $dir       = shift;
  75   my $mask      = shift;
  76   print "mkdir $dir\n"  if $ECHO_CMDS || $ECHO_ONLY;
  77
  78   if ($ECHO_ONLY) {
  79     return 0;
  80   } else {
  81     if (defined($mask)) {
  82       mkdir $dir, $mask;
  83     } else {
  84       mkdir $dir, 0777;
  85     }
  86   }
  87 }
  88
  89 sub exec_prg {
  90   print "@_\n"  if $ECHO_CMDS || $ECHO_ONLY;
  91   if ($ECHO_ONLY) {
  92     exit 0;
  93   } else {
  94     exec(@_);
  95     die qq/exec @_ failed: $?\n/;
  96   }
  97 }
  98
  99 sub usage {
 100   require Pod::Usage;
 101   my $verbose = shift;
 102   if ($verbose == 0) {
 103     Pod::Usage::pod2usage(-verbose => $verbose);
 104   } else {
 105     my $pager = $ENV{'PAGER'} || 'more';
 106     local(*PAGER);
 107     my $fh = (-t STDOUT && open(PAGER, "|$pager")) ? \*PAGER : \*STDOUT;
 108     Pod::Usage::pod2usage(-verbose => $verbose,
 109                           -output  => $fh);
 110   }
 111 }
 112
 113 ##--------------------------------------------------------------------------##
 114 1;
 115 __END__
 116
 117 =head1 NAME
 118
 119 MHArc::Util - General utilities for mail archiving system.
 120
 121 =head1 SYNOPSIS
 122
 123   use MHArc::Util;
 124
 125 =head1 DESCRIPTION
 126
 127 This module contains a collection of utility routines.
 128
 129 =head1 VARIABLES
 130
 131 The following module variables can be set to affect the behavior
 132 of the utility routines:
 133
 134 =over
 135
 136 =item C<$ECHO_CMDS>
 137
 138 If set to a true value, any routines that execute shell commands,
 139 or external programs, will print the command to be executed to the
 140 default filehandle.
 141
 142 The default value for C<$ECHO_CMDS> is 0.
 143
 144 =item C<$ECHO_ONLY>
 145
 146 If set to a true value, any routines that execute shell commands,
 147 will only print the command to be executed to the default filehandle
 148 if C<$ECHO_CMDS> is true.  The command itself will not be
 149 executed at all.
 150
 151 The default value for C<$ECHO_ONLY> is 0.
 152
 153 =back
 154
 155 =head1 ROUTINES
 156
 157 By default, no routines are exported into the calling namespace.
 158 Routines in this module can be imported by explicitly listing the
 159 routines to import in the C<use> declaration:
 160
 161   use MHArc::Util qw( run_prg );
 162
 163 The following routines are availale:
 164
 165 =over
 166
 167 =item C<ch_dir($dir)>
 168
 169 Change the current working directory.
 170
 171 =item C<cmd(LIST)>
 172
 173 Execute external program.  The return value is the wait(2) status
 174 of the program invoked.
 175
 176 =item C<mk_dir($dir, $mask)>
 177
 178 Create specified directory.  C<$mask> is optional, and if
 179 not specified, will default to C<0777>.
 180
 181 =item C<run_prg(LIST)>
 182
 183 Execute external program and terminate process if program returns
 184 a non-zero status.
 185
 186 =item C<usage($verbosity)>
 187
 188 Display usage information of program based upon embedded POD.
 189 The C<$verbosity> argument has the same meaning as the C<-verbose>
 190 option to C<Pod::Usage::pod2usage>.
 191
 192 =back
 193
 194 =head1 VERSION
 195
 196 C<$Id: Util.pm,v 1.5 2002/09/13 07:24:18 ehood Exp $>
 197
 198 =head1 AUTHOR
 199
 200 Earl Hood, earl@earlhood.com
 201
 202 This module is part of the mharc archiving system and comes with
 203 ABSOLUTELY NO WARRANTY and may be copied only under the terms of
 204 the GNU General Public License, which may be found in the mharc
 205 distribution.
 206
 207 =cut
 208