[% setvar title Compilation: Remove requirement for final true value in require-d and do-ed files %]
<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>Compilation: Remove requirement for final true value in require-d and do-ed files</p>
<a name='VERSION'></a><h1>VERSION</h1>
<pre>  Maintainer: Damian Conway &lt;<a href='mailto:damian@conway.org'>damian@conway.org</a>&gt;
  Date: 7 Aug 2000
  Last Modified: 25 Sep 2000
  Mailing List: <a href='mailto:perl6-language@perl.org'>perl6-language@perl.org</a>
  Number: 55
  Version: 3
  Status: Frozen
  Frozen since: v2</pre>
<a name='ABSTRACT'></a><h1>ABSTRACT</h1>
<p>This RFC proposes that files compiled via a <code>require</code> no longer
be required to end in a true value.</p>
<a name='DESCRIPTION'></a><h1>DESCRIPTION</h1>
<p>It is proposed that the final value in a file that is compiled using
<code>require</code> no longer be significant.</p>
<p>Instead it is proposed that files that wish to fail during compilation
should throw an exception. Furthermore, any valueless exception (i.e.
thrown with a simple <code>die;</code>) that propagates through a <code>require</code>
should automatically take the appropriate message string:</p>
<pre>        &quot;require failed: file &quot;%s&quot; threw an exception&quot;

        &quot;do failed: file &quot;%s&quot; threw an exception&quot;</pre>
<p>Note that exceptions with a value would be passed through unchanged,
allowing a compiled file to signal exactly why it failed.</p>
<p>Note too that, if the calling module wants to abort when a <code>require</code>'d
file returns a false value, it is still free to do that.</p>
<p>The 'module initialization' feature is little-used.  99 the of 102
files in Perl 5.6 lib/*.{pl,pm} end with <code>1;</code>.  AnyDBM_File invokes
'die' explicitly.  The only real exceptions are diagnostics.pm and
timelocal.pl.</p>
<a name='IMPLEMENTATION'></a><h1>IMPLEMENTATION</h1>
<p><code>require</code> should execute code in a file and return the result, as
before, but it should not call Perl_die when the result is false.</p>
<p>However, see below.</p>
<a name='MIGRATION'></a><h1>MIGRATION</h1>
<p>In 98% of cases, no translation is necessary.  The first version of
the translator can ignore the issue entirely.  Strategies to cover the
other 2% follow:</p>
<p>Is general, direct source translation of this feature of Perl 5
modules would probably be impossible.</p>
<p>It's tempting to say that the translator should simply translate the
last statement or block in the module from this:</p>
<pre>        STATEMENT</pre>
<p>to this:</p>
<pre>        unless (do {STATEMENT}) {
          require Carp;
          Carp::croak &quot;... did not return a true value&quot;;
        }</pre>
<p>However, I think that is impractical.  The module might contain code
that looks like this:</p>
<pre>        if (something()) {
          return $v1;
        }

        ...


        $v2;</pre>
<p>In this case the 'return $v1' statement would <i>also</i> have to be
translated.  In general, there might be many, many statements that
would need to be translated.  This would look awful.</p>
<p>If complete coverage is desired, the best choice would probably be
to introduce a new pragma, which would enable the old behavior.  A
translated module would begin with</p>
<pre>        package Foo;
        use perl5 'require';

        ...</pre>
<p>When this file was <code>require</code>d, the pragma would set a flag.  The
<code>pp_require</code> opcode would check the flag after compiling the file,
and would call <code>Perl_die</code> as before if the file returned a false
value and if the flag was set.  If Foo <code>require</code>d any other modules,
the flag would be cleared before loading them, and restored again
afterwards.  (That is, the flag would have file scope.)</p>
<a name='ACKNOWLEDGEMENTS'></a><h1>ACKNOWLEDGEMENTS</h1>
<p>Most of this proposal was written by Mark-Jason Dominus.</p>
</div>