From: LAUN Wolfgang Date: Tue, 1 Jun 2004 07:52:58 +0000 (+0200) Subject: Shell.pm: pod rewrite and new mini-feature $Shell::raw X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=96412ebcb3bce14f7f7bdd47f6c65619f1860bf9;p=p5sagit%2Fp5-mst-13.2.git Shell.pm: pod rewrite and new mini-feature $Shell::raw Message-ID: p4raw-id: //depot/perl@22883 --- diff --git a/lib/Shell.pm b/lib/Shell.pm index a89db69..a84d9a9 100644 --- a/lib/Shell.pm +++ b/lib/Shell.pm @@ -4,9 +4,9 @@ use strict; use warnings; use File::Spec::Functions; -our($capture_stderr, $VERSION, $AUTOLOAD); +our($capture_stderr, $raw, $VERSION, $AUTOLOAD); -$VERSION = '0.5.2'; +$VERSION = '0.6'; sub new { bless \my $foo, shift } sub DESTROY { } @@ -68,7 +68,8 @@ sub AUTOLOAD { } else { my \$a; my \@arr = \@_; - if ('$^O' eq 'MSWin32') { + unless( \$Shell::raw ){ + if ('$^O' eq 'MSWin32') { # XXX this special-casing should not be needed # if we do quoting right on Windows. :-( # @@ -84,11 +85,12 @@ sub AUTOLOAD { s/\\\\\\\\"/\\\\\\\\"""/g; \$_ = qq["\$_"] if /\\s/; } - } else { + } else { for (\@arr) { s/(['\\\\])/\\\\\$1/g; \$_ = \$_; - } + } + } } push \@arr, '2>&1' if \$Shell::capture_stderr == 1; push \@arr, '2>$null' if \$Shell::capture_stderr == -1; @@ -122,10 +124,82 @@ Shell - run shell commands transparently within perl =head1 SYNOPSIS -See below. + use Shell qw(cat ps cp); + $passwd = cat('new; + print $sh->ls('-l'); =head1 DESCRIPTION +=head2 Caveats + +This package is included as a show case, illustrating a few Perl features. +It shouldn't be used for production programs. Although it does provide a +simple interface for obtaining the standard output of arbitrary commands, +there may be better ways of achieving what you need. + +Running shell commands while obtaining standard output can be done with the +C operator, or by calling C with a filename expression that +ends with C<|>, giving you the option to process one line at a time. +If you don't need to process standard output at all, you might use C +(in preference of doing a print with the collected standard output). + +Since Shell.pm and all of the aforementioned techniques use your system's +shell to call some local command, none of them is portable across different +systems. Note, however, that there are several built in functions and +library packages providing portable implementations of functions operating +on files, such as: C, C and C, C and C, +C, C, C, C etc. + +Using Shell.pm while importing C creates a subroutine C in the +namespace of the importing package. Calling C with arguments C, +C,... results in a shell command C, where the +function name and the arguments are joined with a blank. (See the subsection +on Escaping magic characters.) Since the result is essentially a command +line to be passed to the shell, your notion of arguments to the Perl +function is not necessarily identical to what the shell treats as a +command line token, to be passed as an individual argument to the program. +Furthermore, note that this implies that C is callable by file name +only, which frequently depends on the setting of the program's environment. + +Creating a Shell object gives you the opportunity to call any command +in the usual OO notation without requiring you to announce it in the +C statement. Don't assume any additional semantics being +associated with a Shell object: in no way is it similar to a shell +process with its environment or current working directory or any +other setting. + +=head2 Escaping Magic Characters + +It is, in general, impossible to take care of quoting the shell's +magic characters. For some obscure reason, however, Shell.pm quotes +apostrophes (C<'>) and backslashes (C<\>) on UNIX, and spaces and +quotes (C<">) on Windows. + +=head2 Configuration + +If you set $Shell::capture_stderr to true, the module will attempt to +capture the standard error output of the process as well. This is +done by adding C<2E&1> to the command line, so don't try this on +a system not supporting this redirection. + +If you set $Shell::raw to true no quoting whatsoever is done. + +=head1 BUGS + +Quoting should be off by default. + +It isn't possible to call shell built in commands, but it can be +done by using a workaround, e.g. shell( '-c', 'set' ). + +Capturing standard error does not work on some systems (e.g. VMS). + +=head1 AUTHOR + Date: Thu, 22 Sep 94 16:18:16 -0700 Message-Id: <9409222318.AA17072@scalpel.netlabs.com> To: perl5-porters@isu.edu @@ -155,58 +229,12 @@ usage should be use Shell qw(echo cat ps cp); -Larry - - -If you set $Shell::capture_stderr to 1, the module will attempt to -capture the STDERR of the process as well. - -If you set $Shell::capture_stderr to -1, the module will discard the -STDERR of the process. - -The module now should work on Win32. - - Jenda - -There seemed to be a problem where all arguments to a shell command were -quoted before being executed. As in the following example: - - cat('new; - print $sh->ls; - -Casey - -=head1 AUTHOR - Larry Wall -Changes by Jenda@Krynicky.cz and Dave Cottle +Changes by Jenda@Krynicky.cz and Dave Cottle . + +Changes for OO syntax and bug fixes by Casey West . -Changes and bug fixes by Casey West +C<$Shell::raw> and pod rewrite by Wolfgang Laun. =cut