Author: lwall Date: 2009-02-24 20:58:11 +0100 (Tue, 24 Feb 2009) New Revision: 25529
Modified: docs/Perl6/Spec/S02-bits.pod docs/Perl6/Spec/S06-routines.pod Log: initial whack at describing how settings are snapshotted and how they interact with invocation of MAIN for settings that want to install flow control around the user code. Modified: docs/Perl6/Spec/S02-bits.pod =================================================================== --- docs/Perl6/Spec/S02-bits.pod 2009-02-24 18:33:56 UTC (rev 25528) +++ docs/Perl6/Spec/S02-bits.pod 2009-02-24 19:58:11 UTC (rev 25529) @@ -1823,7 +1823,12 @@ in which case C<CORE> remains the scope of the standard language, while C<SETTING> represents the scope defining the DSL that functions as the setting of the current file. See also the C<-L>/C<--language> -switch described in L<S19-commandline>. +switch described in L<S19-commandline>. If a setting wishes +to gain control of the main execution, it merely needs to declare +a C<MAIN> routine as documented in S06. In this case the ordinary +execution of the user's code is suppressed; instead, execution +of the user's code is entirely delegated to the setting's C<MAIN> routine, +which calls back to the user's lexically embedded code with C<YOU_ARE_HERE>. Note that, since the C<UNIT> of an eval is the eval string itself, the C<SETTING> of an eval is the language in effect at the point Modified: docs/Perl6/Spec/S06-routines.pod =================================================================== --- docs/Perl6/Spec/S06-routines.pod 2009-02-24 18:33:56 UTC (rev 25528) +++ docs/Perl6/Spec/S06-routines.pod 2009-02-24 19:58:11 UTC (rev 25529) @@ -15,7 +15,7 @@ Date: 21 Mar 2003 Last Modified: 24 Feb 2009 Number: 6 - Version: 102 + Version: 103 This document summarizes Apocalypse 6, which covers subroutines and the @@ -2370,8 +2370,7 @@ }; You can get the current routine name by calling C<&?ROUTINE.name>. -(The outermost routine at a file-scoped compilation unit is always -named C<&MAIN> in the file's package.) +Outside of any sub declaration, this call returns failure. Note that C<&?ROUTINE> refers to the current single sub, even if it is declared "multi". To redispatch to the entire suite under a given short @@ -2839,6 +2838,34 @@ particular parameter, an attempt will be made to match it as if it had been written C<-a -b -c>. +=head2 Relationship of MAIN routine with lexical setting + +The preceding section describes the use of C<MAIN> in the user's code. +There may also be an implicit C<MAIN> routine supplied by the setting +of the current compilation unit. (The C<-n> and C<-p> command-line +switches are implemented this way.) In this case the user's mainline +code is not automatically executed; instead, execution is controlled +by the setting's C<MAIN> routine. That routine calls C<YOU_ARE_HERE> +at the point where the user's code is to be lexically inserted (in +the abstract). A setting may also call C<YOU_ARE_HERE> outside of +a C<MAIN> routine, in which case it functions as a normal setting, +and the C<YOU_ARE_HERE> merely indicates where the user's code +goes logically. (Or from the compiler's point of view, which the +lexical scope to dump a snapshot of for later use by the compiler +as the setting for a different compilation unit.) In this case the +execution of the user code proceeds as normal. In fact, the C<CORE> +setting ends with a C<YOU_ARE_HERE> to dump the C<CORE> lexical +scope as the standard setting. In this sense, C<CORE> functions as +an ordinary prelude. + +If a C<MAIN> routine is declared both in the setting and in the +user's code, the setting's C<MAIN> functions as the actual mainline +entry point. The user's C<MAIN> functions in an embedded fashion; +the setting's invocation of C<YOU_ARE_HERE> functions as the main +invocation from the point of view of the user's code, and the +user's C<MAIN> routine will be invoked at the end of each call to +C<YOU_ARE_HERE>. + =head2 Implementation note on autothreading of only subs The natural way to implement autothreading for multi subs is to