5 use File::Spec::Functions;
7 our($capture_stderr, $raw, $VERSION, $AUTOLOAD);
11 sub new { bless \my $foo, shift }
16 my ($callpack, $callfile, $callline) = caller;
23 foreach my $sym (@EXPORT) {
25 *{"${callpack}::$sym"} = \&{"Shell::$sym"};
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;
41 $sub = _make_cmd($cmd);
42 $sub = $shell->_make_cmd($cmd);
44 Creates a closure which invokes the system command C<$cmd>.
53 shift if ref $_[0] && $_[0]->isa( 'Shell' );
55 my $null = File::Spec::Functions::devnull();
56 $Shell::capture_stderr ||= 0;
57 # closing over $^O, $cmd, and $null
59 shift if ref $_[0] && $_[0]->isa( 'Shell' );
61 $Shell::capture_stderr == 1 ? `$cmd 2>&1` :
62 $Shell::capture_stderr == -1 ? `$cmd 2>$null` :
64 } elsif (OS eq 'os2') {
65 local(*SAVEOUT, *READ, *WRITE);
67 open SAVEOUT, '>&STDOUT' or die;
68 pipe READ, WRITE or die;
69 open STDOUT, '>&WRITE' or die;
72 my $pid = system(1, $cmd, @_);
73 die "Can't execute $cmd: $!\n" if $pid < 0;
75 open STDOUT, '>&SAVEOUT' or die;
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. :-(
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
108 $_ = qq["$_"] if /\s/;
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";
123 close SUBPROC; # XXX Oughta use a destructor.
136 shift if ref $_[0] && $_[0]->isa( 'Shell' );
140 *$AUTOLOAD = _make_cmd($cmd);
150 Shell - run shell commands transparently within perl
154 use Shell qw(cat ps cp);
155 $passwd = cat('</etc/passwd');
156 @pslines = ps('-ww'),
157 cp("/etc/passwd", "/tmp/passwd");
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.
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).
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.
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.
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
203 =head2 Escaping Magic Characters
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.
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.
217 If you set $Shell::raw to true no quoting whatsoever is done.
221 Quoting should be off by default.
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' ).
226 Capturing standard error does not work on some systems (e.g. VMS).
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
236 Here's one that'll whack your mind a little out.
242 $foo = echo("howdy", "<funny>", "world");
245 $passwd = cat("</etc/passwd");
251 cp("/etc/passwd", "/etc/passwd.orig");
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
257 use Shell qw(echo cat ps cp);
261 Changes by Jenda@Krynicky.cz and Dave Cottle <d.cottle@csc.canterbury.ac.nz>.
263 Changes for OO syntax and bug fixes by Casey West <casey@geeknest.com>.
265 C<$Shell::raw> and pod rewrite by Wolfgang Laun.
267 Rewritten to use closures rather than C<eval "string"> by Adriano Ferreira.