NAME

IPC::System::Options - Perl's system() and backtick/qx replacement/wrapper, with options

VERSION

This document describes version 0.20 of IPC::System::Options (from Perl distribution IPC-System-Options), released on 2015-07-27.

SYNOPSIS

 use IPC::System::Options qw(system backtick);

 # use exactly like system()
 system(...);

 # use exactly like backtick (qx, ``)
 my $res = backtick(...);

 # but it accepts an optional hash first argument to specify options
 system({...}, ...);

 # run without shell, even though there is only one argument
 system({shell=>0}, "ls");
 system({shell=>0}, "ls -lR"); # will fail, as there is no 'ls -lR' binary

 # set LC_ALL/LANGUAGE/LANG environment variable
 system({lang=>"de_DE.UTF-8"}, "df");

 # log using Log::Any, die on failure
 system({log=>1, die=>1}, "blah", ...);

Set default options for all calls (prefix each option with dash):

 use IPC::System::Options 'system', 'backtick', -log=>1, -die=>1;

DESCRIPTION

FUNCTIONS

system([ \%opts ], @args)

Just like perl's system() except that it accepts an optional hash first argument to specify options. Currently known options:

  • shell => bool

    Can be set to 0 to always avoid invoking the shell. The default is to use the shell under certain conditions, like Perl's system().

  • lang => str

    Temporarily set locale-related environment variables: LC_ALL (this is the highest precedence, even higher than the other LC_* variables including LC_MESSAGES), LANGUAGE (this is used in Linux, with precedence higher than LANG but lower than LC_*), and LANG.

    Of course you can set the environment variables manually (or use the env option), this option is just for convenience.

  • env => hashref

    Temporarily set environment variables.

  • log => bool

    If set to true, then will log invocation as well as return/result value. Will log using Log::Any at the trace level.

  • die => bool

    If set to true, will die on failure.

  • capture_stdout => scalarref

    Capture stdout using Capture::Tiny.

  • capture_stderr => scalarref

    Capture stderr using Capture::Tiny.

backtick([ \%opts ], @args)

Just like perl's backtick operator (qx()) except that it accepts an optional hash first argument to specify options.

Known options:

  • lang => str

    See option documentation in system().

  • env => hash

    See option documentation in system().

  • log => bool

    See option documentation in system().

  • die => bool

    See option documentation in system().

  • capture_stdout => scalarref

    See option documentation in system().

  • capture_stderr => scalarref

    See option documentation in system().

  • max_log_output => int

    If set, will limit result length being logged. It's a good idea to set this (e.g. to 1024) if you expect some command to return large output.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/IPC-System-Options.

SOURCE

Source repository is at https://github.com/perlancar/perl-IPC-System-Options.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=IPC-System-Options

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.