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
