/ 
ExtUtils-Scriptlet-1.132640
River stage zero No dependents
/ ExtUtils::Scriptlet

NAME

ExtUtils::Scriptlet - run perl code in a new process without quoting it, on any OS

VERSION

version 1.132640

SYNOPSIS

use ExtUtils::Scriptlet 'perl';

my $module = "ExtUtils::Scriptlet";

my $ret = perl <<"PERL_END", at_argv => [ 13 ];
    use lib "lib";
    require $module;
    print "$module ok\n";
    exit \$ARGV[0];
PERL_END

print $ret;

results in:

ExtUtils::Scriptlet ok
3328

DESCRIPTION

In short, this module allows you to dodge shell quoting to the largest extent possible when you need to run some Perl in a child process. If you're not sure why you need or want this, please read the MOTIVATION section further down.

WARNING

This is a very young module and its semantics might still change. Be sure to read the change log before upgrading. Similarly, if you have suggestions to be implemented in this regarding changes of data handling, additional functions or additional options, please let me know.

FUNCTIONS

my $ret = perl( $code, %options )

Executes a given piece of perl code in a new process. Further arguments or data can be sent to the child process with the options hash. Unless otherwise noted, these options do not need any shell quoting whatsoever. If noted, all shell quoting is your responsibility, and use is discouraged.

Returns the return value of the child process as it would be stored in $? or returned by system().

at_argv

This option expects a reference to an array that can be safely serialized with Data::Dumper. The contents of that array are then stored and accessible in @ARGV in the child process. $ARGV or ARGV will not be populated.

payload

This option expects a single string. That string will be sent into the child process' STDIN. Perl's newline conversion is not a factor in this, as it will be disabled on both the host and child side. The encoding of the string on the host side will be assumed to be UTF-8 by default, on the child side the contents of STDIN will always be raw bytes.

encoding

If necessary this option can be used to change the encoding with which the payload string is converted to bytes on the host side. It expects a single encoding name ( iso-8859-7, utf8, UTF-8, etc. ).

perl

WARNING: Subject to shell quoting!

This is the path to the perl interpreter used to launch the child process. By default it is $^X. It expects a single string.

args

WARNING: Subject to shell quoting! Use not encouraged.

This option expects a single string. That string can contain shell arguments passed to the child perl, i.e. "-Ilib" and others. While some Perl options can only be passed this way, most of the ones typically passed to child perls (like -I) can be implemented in the code of the child instead.

argv

WARNING: Subject to shell quoting! Use not encouraged.

This option expects a single string. That string can contain can contain arbitrary data that will be passed to the child perl as shell arguments that end up in @ARGV, $ARGV or ARGV as per normal perlrun semantics. For your own safety you are encouraged to use at_argv instead. Only use this if you NEED to use $ARGV or ARGV and have no other option.

MOTIVATION

Consider this piece of code:

system($^X, '-Ilib', '-e', qq{require strict; print "module ok"});

It looks reasonable, but it will break on windows. This is because system will just send this as the command line:

C:\Perl\bin\perl.exe -Ilib -e require strict; print "module ok"

So you need to quote the arguments manually. And if you're used to quoting your -e with ', you make another mistake before you arrive on this:

my $q = $^O eq 'MSWin32' ? '"' : '';
system($^X, '-Ilib', '-e', qq|${q}require strict; print "module ok"${q}|);

That's pretty gross. But still not right, since the quotes around the string won't be escaped properly. So you try this:

my $q = $^O eq 'MSWin32' ? '"' : '';
system($^X, '-Ilib', '-e', qq|${q}require strict; print \\"module ok\\"${q}|);

But that doesn't work, since Windows has different escaping rules. What you need is this:

my $q = $^O eq 'MSWin32' ? '"' : '';
my $e = $^O eq 'MSWin32' ? '""' : '';
system($^X, '-Ilib', '-e', qq|${q}require strict; print $e"module ok$e"${q}|);

However depending on the number of quotes in your string, and the command parsing library you hit, that might not work either, so you need this:

my $q = $^O eq 'MSWin32' ? '"' : '';
system($^X, '-Ilib', '-e', qq|${q}require strict; print qq[module ok]${q}|);

That will work cross-platform. Unfortunately it's kind of a horror to get there and it is hell to read after the fact. Plus, when you need to get more complicated in the code you want to run you might end up running out of quoting delimiters. And i haven't even touched on quoting the OTHER arguments, or dealing with more fancy things like %PATH%, ^ or UTF-8.

Now you might say "Well, just use Win32::ShellQuote to take care of that!", but sadly that's not 100% reliable either and i'm not even sure what other surprises might lurk on other OSes or other shells. The best way is really to just avoid the shell and quoting altogether.

ExtUtils::Scriptlet does that.

FUTURE

These are implementation points that i am considering, but not sure about yet. If you have thoughts on these, let me know, please.

Right now it is necessary to use Capture::Tiny to get STDOUT and STDERR of the child process. I am considering switching the implementation to IPC::Open3 in the future to enable perl to return handles to those, or maybe just directly capture STDOUT and STDERR and return them as strings.

Right now encoding only determines how the payload is converted to bytes. It could also be used to decode in the child directly. I am not sure if that is a good idea or not.

THANKS

First off, thanks belong to mst for having the brilliant idea of separating this technique out of Object::Remote and making it a generalized module for this task. I did not have the idea, I just implemented it for him.

Further thanks go to, in no particular order, to these people from irc.perl.org: mauke, brother, dolmen, haarg, xdg, ether

All of them helped me a lot in figuring out the intricacies of making this possible and work comfortably.

SUPPORT

Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at http://rt.cpan.org/Public/Dist/Display.html?Name=ExtUtils-Scriptlet. You will be notified automatically of any progress on your issue.

Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license.

https://github.com/wchristian/ExtUtils-Scriptlet

git clone https://github.com/wchristian/ExtUtils-Scriptlet.git

AUTHOR

Christian Walde <walde.christian@googlemail.com>

COPYRIGHT AND LICENSE

Christian Walde has dedicated the work to the Commons by waiving all of his or her rights to the work worldwide under copyright law and all related or neighboring legal rights he or she had in the work, to the extent allowable by law.

Works under CC0 do not require attribution. When citing the work, you should not imply endorsement by the author.