Author: lwall
Date: 2009-02-24 20:58:11 +0100 (Tue, 24 Feb 2009)
New Revision: 25529

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<&?>.
-(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
 =head2 Implementation note on autothreading of only subs
 The natural way to implement autothreading for multi subs is to

Reply via email to