lib/Shell.pm

   1 package Shell;
   2 use 5.006_001;
   3 use strict;
   4 use warnings;
   5 use File::Spec::Functions;
   6
   7 our($capture_stderr, $raw, $VERSION, $AUTOLOAD);
   8
   9 $VERSION = '0.7';
  10
  11 sub new { bless \my $foo, shift }
  12 sub DESTROY { }
  13
  14 sub import {
  15     my $self = shift;
  16     my ($callpack, $callfile, $callline) = caller;
  17     my @EXPORT;
  18     if (@_) {
  19         @EXPORT = @_;
  20     } else {
  21         @EXPORT = 'AUTOLOAD';
  22     }
  23     foreach my $sym (@EXPORT) {
  24         no strict 'refs';
  25         *{"${callpack}::$sym"} = \&{"Shell::$sym"};
  26     }
  27 }
  28
  29 # NOTE: this is used to enable constant folding in
  30 # expressions like (OS eq 'MSWin32') and
  31 # (OS eq 'os2') just like it happened in  0.6  version
  32 # which used eval "string" to install subs on the fly.
  33 use constant OS => $^O;
  34
  35 =begin private
  36
  37 =over
  38
  39 =item B<_make_cmd>
  40
  41   $sub = _make_cmd($cmd);
  42   $sub = $shell->_make_cmd($cmd);
  43
  44 Creates a closure which invokes the system command C<$cmd>.
  45
  46 =back
  47
  48 =end private
  49
  50 =cut
  51
  52 sub _make_cmd {
  53     shift if ref $_[0] && $_[0]->isa( 'Shell' );
  54     my $cmd = shift;
  55     my $null = File::Spec::Functions::devnull();
  56     $Shell::capture_stderr ||= 0;
  57     # closing over $^O, $cmd, and $null
  58     return sub {
  59             shift if ref $_[0] && $_[0]->isa( 'Shell' );
  60             if (@_ < 1) {
  61                 $Shell::capture_stderr ==  1 ? `$cmd 2>&1` :
  62                 $Shell::capture_stderr == -1 ? `$cmd 2>$null` :
  63                 `$cmd`;
  64             } elsif (OS eq 'os2') {
  65                 local(*SAVEOUT, *READ, *WRITE);
  66
  67                 open SAVEOUT, '>&STDOUT' or die;
  68                 pipe READ, WRITE or die;
  69                 open STDOUT, '>&WRITE' or die;
  70                 close WRITE;
  71
  72                 my $pid = system(1, $cmd, @_);
  73                 die "Can't execute $cmd: $!\n" if $pid < 0;
  74
  75                 open STDOUT, '>&SAVEOUT' or die;
  76                 close SAVEOUT;
  77
  78                 if (wantarray) {
  79                     my @ret = <READ>;
  80                     close READ;
  81                     waitpid $pid, 0;
  82                     @ret;
  83                 } else {
  84                     local($/) = undef;
  85                     my $ret = <READ>;
  86                     close READ;
  87                     waitpid $pid, 0;
  88                     $ret;
  89                 }
  90             } else {
  91                 my $a;
  92                 my @arr = @_;
  93                 unless( $Shell::raw ){
  94                   if (OS eq 'MSWin32') {
  95                     # XXX this special-casing should not be needed
  96                     # if we do quoting right on Windows. :-(
  97                     #
  98                     # First, escape all quotes.  Cover the case where we
  99                     # want to pass along a quote preceded by a backslash
 100                     # (i.e., C<"param \""" end">).
 101                     # Ugly, yup?  You know, windoze.
 102                     # Enclose in quotes only the parameters that need it:
 103                     #   try this: c:> dir "/w"
 104                     #   and this: c:> dir /w
 105                     for (@arr) {
 106                         s/"/\\"/g;
 107                         s/\\\\"/\\\\"""/g;
 108                         $_ = qq["$_"] if /\s/;
 109                     }
 110                   } else {
 111                     for (@arr) {
 112                         s/(['\\])/\\$1/g;
 113                         $_ = $_;
 114                      }
 115                   }
 116                 }
 117                 push @arr, '2>&1'        if $Shell::capture_stderr ==  1;
 118                 push @arr, '2>$null' if $Shell::capture_stderr == -1;
 119                 open(SUBPROC, join(' ', $cmd, @arr, '|'))
 120                     or die "Can't exec $cmd: $!\n";
 121                 if (wantarray) {
 122                     my @ret = <SUBPROC>;
 123                     close SUBPROC;        # XXX Oughta use a destructor.
 124                     @ret;
 125                 } else {
 126                     local($/) = undef;
 127                     my $ret = <SUBPROC>;
 128                     close SUBPROC;
 129                     $ret;
 130                 }
 131             }
 132         };
 133         }
 134
 135 sub AUTOLOAD {
 136     shift if ref $_[0] && $_[0]->isa( 'Shell' );
 137     my $cmd = $AUTOLOAD;
 138     $cmd =~ s/^.*:://;
 139     no strict 'refs';
 140     *$AUTOLOAD = _make_cmd($cmd);
 141     goto &$AUTOLOAD;
 142 }
 143
 144 1;
 145
 146 __END__
 147
 148 =head1 NAME
 149
 150 Shell - run shell commands transparently within perl
 151
 152 =head1 SYNOPSIS
 153
 154    use Shell qw(cat ps cp);
 155    $passwd = cat('</etc/passwd');
 156    @pslines = ps('-ww'),
 157    cp("/etc/passwd", "/tmp/passwd");
 158
 159    # object oriented
 160    my $sh = Shell->new;
 161    print $sh->ls('-l');
 162
 163 =head1 DESCRIPTION
 164
 165 =head2 Caveats
 166
 167 This package is included as a show case, illustrating a few Perl features.
 168 It shouldn't be used for production programs. Although it does provide a
 169 simple interface for obtaining the standard output of arbitrary commands,
 170 there may be better ways of achieving what you need.
 171
 172 Running shell commands while obtaining standard output can be done with the
 173 C<qx/STRING/> operator, or by calling C<open> with a filename expression that
 174 ends with C<|>, giving you the option to process one line at a time.
 175 If you don't need to process standard output at all, you might use C<system>
 176 (in preference of doing a print with the collected standard output).
 177
 178 Since Shell.pm and all of the aforementioned techniques use your system's
 179 shell to call some local command, none of them is portable across different
 180 systems. Note, however, that there are several built in functions and
 181 library packages providing portable implementations of functions operating
 182 on files, such as: C<glob>, C<link> and C<unlink>, C<mkdir> and C<rmdir>,
 183 C<rename>, C<File::Compare>, C<File::Copy>, C<File::Find> etc.
 184
 185 Using Shell.pm while importing C<foo> creates a subroutine C<foo> in the
 186 namespace of the importing package. Calling C<foo> with arguments C<arg1>,
 187 C<arg2>,... results in a shell command C<foo arg1 arg2...>, where the
 188 function name and the arguments are joined with a blank. (See the subsection
 189 on Escaping magic characters.) Since the result is essentially a command
 190 line to be passed to the shell, your notion of arguments to the Perl
 191 function is not necessarily identical to what the shell treats as a
 192 command line token, to be passed as an individual argument to the program.
 193 Furthermore, note that this implies that C<foo> is callable by file name
 194 only, which frequently depends on the setting of the program's environment.
 195
 196 Creating a Shell object gives you the opportunity to call any command
 197 in the usual OO notation without requiring you to announce it in the
 198 C<use Shell> statement. Don't assume any additional semantics being
 199 associated with a Shell object: in no way is it similar to a shell
 200 process with its environment or current working directory or any
 201 other setting.
 202
 203 =head2 Escaping Magic Characters
 204
 205 It is, in general, impossible to take care of quoting the shell's
 206 magic characters. For some obscure reason, however, Shell.pm quotes
 207 apostrophes (C<'>) and backslashes (C<\>) on UNIX, and spaces and
 208 quotes (C<">) on Windows.
 209
 210 =head2 Configuration
 211
 212 If you set $Shell::capture_stderr to true, the module will attempt to
 213 capture the standard error output of the process as well. This is
 214 done by adding C<2E<gt>&1> to the command line, so don't try this on
 215 a system not supporting this redirection.
 216
 217 If you set $Shell::raw to true no quoting whatsoever is done.
 218
 219 =head1 BUGS
 220
 221 Quoting should be off by default.
 222
 223 It isn't possible to call shell built in commands, but it can be
 224 done by using a workaround, e.g. shell( '-c', 'set' ).
 225
 226 Capturing standard error does not work on some systems (e.g. VMS).
 227
 228 =head1 AUTHOR
 229
 230   Date: Thu, 22 Sep 94 16:18:16 -0700
 231   Message-Id: <9409222318.AA17072@scalpel.netlabs.com>
 232   To: perl5-porters@isu.edu
 233   From: Larry Wall <lwall@scalpel.netlabs.com>
 234   Subject: a new module I just wrote
 235
 236 Here's one that'll whack your mind a little out.
 237
 238     #!/usr/bin/perl
 239
 240     use Shell;
 241
 242     $foo = echo("howdy", "<funny>", "world");
 243     print $foo;
 244
 245     $passwd = cat("</etc/passwd");
 246     print $passwd;
 247
 248     sub ps;
 249     print ps -ww;
 250
 251     cp("/etc/passwd", "/etc/passwd.orig");
 252
 253 That's maybe too gonzo.  It actually exports an AUTOLOAD to the current
 254 package (and uncovered a bug in Beta 3, by the way).  Maybe the usual
 255 usage should be
 256
 257     use Shell qw(echo cat ps cp);
 258
 259 Larry Wall
 260
 261 Changes by Jenda@Krynicky.cz and Dave Cottle <d.cottle@csc.canterbury.ac.nz>.
 262
 263 Changes for OO syntax and bug fixes by Casey West <casey@geeknest.com>.
 264
 265 C<$Shell::raw> and pod rewrite by Wolfgang Laun.
 266
 267 Rewritten to use closures rather than C<eval "string"> by Adriano Ferreira.
 268
 269 =cut