[% setvar title List context return from filesystem functions %]
<div id="archive-notice">
    <h3>This file is part of the Perl 6 Archive</h3>
    <table bgcolor="red"><tr><td><font color="white"> Note: these documents may be out of date. Do <b>not</b> use as reference!</font></tr></td></table>
    <p>To see what is currently happening visit <a href="http://www.perl6.org/">http://www.perl6.org/</a></p>
</div>
<div class='pod'>
<a name='TITLE'></a><h1>TITLE</h1>
<p>List context return from filesystem functions</p>
<a name='VERSION'></a><h1>VERSION</h1>
<pre>  Maintainer: Peter Scott &lt;<a href='mailto:peter@psdt.com'>peter@psdt.com</a>&gt;
  Date: 6 Aug 2000
  Last Modified: 3 Sep 2000
  Mailing List: <a href='mailto:perl6-language@perl.org'>perl6-language@perl.org</a>
  Number: 52
  Version: 3
  Status: Withdrawn</pre>
<a name='ABSTRACT'></a><h1>ABSTRACT</h1>
<p>*** THIS RFC IS WITHDRAWN. ***</p>
<p>Text of the last version is preserved below so that we have some memory of
the bad ideas as well as the good ones, in case it helps.</p>
<p>Reason for withdrawal: while the idea of keeping error codes for individual
failures of filesystem calls affecting multiple files is good, the syntax
isn't; it is just wrong to return a non-empty list in the case of even
partial failure but an empty list in the case of complete success.  This
little one's not worth the trouble.</p>
<p>*** READ NO FURTHER EXCEPT FOR HISTORICAL CURIOSITY. ***</p>
<p><code>chmod</code>, <code>chown</code>, and <code>unlink</code> return the <i>number</i> of successfully
affected files.  I suggest that in a list context, they return the <i>names</i>
of the <i>unsuccessfully</i> affected files.  Add <code>rmdir</code> to that list as
well, since although it currently only takes one directory name as input,
there is no reason it shouldn't take a list.</p>
<a name='DESCRIPTION'></a><h1>DESCRIPTION</h1>
<p>In a scalar context, the result should remain the same as it is now.  It is
very tempting to make the list context return be the <i>successfully</i>
altered files, which is far more intuitive given the scalar context
behavior; but that is almost certainly not the list the user will be
interested in and they'd just end up doing the <code>grep</code> suggested in the
docs (Camel III) anyway, which calls the filesystem function once for each
file.</p>
<a name='Hash Context'></a><h2>Hash Context</h2>
<p>When the result is assigned to a hash, the list returned could be the names
of the unsuccessfully modified files and their corresponding <code>$!</code> errors.</p>
<a name='IMPLEMENTATION'></a><h1>IMPLEMENTATION</h1>
<p>Examples of use:</p>
<pre>       # Current behavior: scalar context
       chmod 755, grep -d, glob '*' or die &quot;Couldn't chmod dirs&quot;

       # List context behavior
       warn &quot;Unable to modify $_&quot; for chown $uid, $gid, @files;

       # Hash context behavior
       %error = rmdir grep -d, glob '*';
       warn &quot;Couldn't remove $_: $error{$_}&quot; for keys %error;</pre>
<p>It would be nice to include <code>mkdir</code> in this list as well, but there
appears to be no way of doing that without radically changing its
interface, or forcing the <i>MASK</i> argument to be included, or interpreting
an initial argument that looks like a <i>MASK</i> to be one.  None of those appeal.</p>
<a name='REFERENCES'></a><h1>REFERENCES</h1>
<p><i><a href='http://search.cpan.org/perldoc?perlfunc'>perlfunc</a></i></p>
<p>Camel III function list (the entry for <code>chmod</code> is different from the one
in perl-current at the moment).</p>
</div>