view release on metacpan or  search on metacpan

Argv.html  view on Meta::CPAN

    $obj->dfltsets({'-' => 1});
    $obj-&gt;system;</pre>
<p>By default the <a href="#system"><code>$obj-&gt;system</code></a> method autoquotes its arguments <em>iff</em>
the platform is Windows and the arguments are a list, because in this
case a shell is always used. This behavior can be toggled with
<a href="#autoquote"><code>$obj-&gt;autoquote</code></a>.</p>
</li>
<li><strong>exec([&lt;optset-list&gt;])</strong>

<p>Similar to <em>system</em> above, but never returns. On Windows, it blocks
until the new process finishes for a more UNIX-like behavior than the
<em>exec</em> implemented by the MSVCRT, if the <strong>execwait</strong> attribute is set.
This is actually implemented as</p>
<pre>
    exit($obj-&gt;system(LIST));</pre>
<p>on Windows, and thus all <a href="#system"><code>system</code></a> shell-quoting issues apply</p>
<p>Option sets are handled as described in <em>system</em> above.</p>
</li>
<li><strong><a name="qx" class="item">qx([&lt;optset-list&gt;])</a></strong>

<p>Same semantics as described in <em>perlfunc/&quot;qx&quot;</em> but has the capability
to process only a set command line length at a time to avoid exceeding
OS line-length limits. This value is settable with the <em>qxargs</em>
method.</p>
<p>One difference from the builtin <em>perlfunc/&quot;qx&quot;</em> is that the builtin
allows you to leave off the double quotes around the command string
(though they are always there implicitly), whereas the <em>qv()</em>
functional interface <em>must use literal quotes</em>. For instance, using
<em>qx()</em> you can use either of:</p>
<pre>
    my @results = qx(command string here);
    my @results = qx(&quot;command string here&quot;);</pre>
<p>which are semantically identical, but with <em>qv()</em> you must use the
latter form.</p>
<p>Also, if <em>autoquote</em> is set the arguments are escaped to protect them
against the platform-standard shell <em>on all platforms</em>.</p>
<p>Option sets are handled as described in <em>system</em> above.</p>
</li>
<li><strong><a name="pipe" class="item">pipe([&lt;optset-list&gt;])</a></strong>

<p>Provides functionality to use the 'open' process pipe mechanism in
order to read output line by line and optionally stop reading early.
This is useful if the process you are reading can be lengthy but where
you can quickly determine whether you need to let the process finish or
if you need to save all output.  This can save a lot of time and/or
memory in many scenarios.</p>
<p>You must pass in a callback code reference using <code>-&gt;pipecb</code>. This
callback will receive one line at a time (autochomp is active). The
callback can do whatever it likes with this line. The callback should
return a false value to abort early, but for this to be honored, the
Argv instance should be marked 'readonly' using the <a href="#readonly"><code>-&gt;readonly</code></a>
method. A default callback is in effect at start that merely prints the
output.</p>
<p><a href="#pipe"><code>-&gt;pipe</code></a> is otherwise similar to, and reuses settings for <em>qx</em>
(except for the ability to limit command line lengths).</p>
<p>Without exhaustive testing, this is believed to work in a well-behaved
manner on Unix.</p>
<p>However, on Windows a few caveats apply. These appear to be limitations
in the underlying implementation of both Perl and Windows.</p>
<ol>
<li><strong><a name="windows_has_no_concept_of_sigpipe_thus_just_closing_the_pipe_handle_will_not_necessarily_cause_the_child_process_to_quit_bummer" class="item">Windows has no concept of SIGPIPE. Thus, just closing the pipe handle
will not necessarily cause the child process to quit. Bummer :-(.</a></strong>

</li>
<li><strong><a name="stderr" class="item">Sometimes an extra process is inserted. For example, if stderr
has been redirected using $obj-&gt;<code>stderr(1)</code> (send stderr to stdout), this
causes Perl to utilize the shell as an intermediary process, meaning
that even if the shell process quits, its child will continue.</a></strong>

</li>
</ol>
<p>For the above reasons, in case of an abort request, on Windows we take it
further and forcibly kill the process tree stemming from the pipe. However,
to make this kill the full tree, some nonstandard packages are required.
Currently any of these will work:</p>
</li>
</ul>
<ul>
<li><strong><a name="win32_process_info" class="item">Win32::Process::Info</a></strong>

</li>
<li><strong><a name="win32_toolhelp" class="item">Win32::ToolHelp</a></strong>

<p>Both are available as PPM packages for ActiveState perls, or on CPAN.</p>
</li>
</ul>
<p>
</p>
<h2><a name="execution_attributes">EXECUTION ATTRIBUTES</a></h2>
<p>The behavior of the <em>execution methods</em> <code>system, exec, and qx</code> is
governed by a set of <em>execution attributes</em>, which are in turn
manipulated via a set of eponymous methods. These methods are
auto-generated and thus share certain common characteristics:</p>
<ul>
<li><strong><a name="translucency" class="item">Translucency</a></strong>

<p>They can all be invoked as class or instance methods.  If used as an
instance method the attribute is set only on that object; if used on
the class it sets or gets the default for all instances which haven't
overridden it.  This is inspired by the section on <em>translucent
attributes</em> in Tom Christiansen's <em>perltootc</em> tutorial.</p>
</li>
<li><strong><a name="class_defaults" class="item">Class Defaults</a></strong>

<p>Each attribute has a class default which may be overridden with an
environment variable by prepending the class name, e.g. ARGV_QXARGS=256
or ARGV_STDERR=0;</p>
</li>
<li><strong><a name="context_sensitivity" class="item">Context Sensitivity</a></strong>

<p>The attribute value is always a scalar. If a value is passed it
becomes the new value of the attribute and the object or class is
returned. If no value is passed <em>and there is a valid return
context</em>, the current value is returned. In a void context with no
parameter, the attribute value is set to 1.</p>
</li>
<li><strong><a name="stickiness" class="item">Stickiness (deprecated)</a></strong>

<p>A subtlety: if an <em>execution attribute</em> is set in a void context, that
attribute is <em>&quot;sticky&quot;</em>, i.e. it retains its state until explicitly
changed. But <em>if a new value is provided and the context is not void</em>,