Author: larry
Date: Sat Mar 10 16:02:36 2007
New Revision: 14329
Modified:
doc/trunk/design/syn/S06.pod
Log:
Whack in rethink of caller/context
Modified: doc/trunk/design/syn/S06.pod
==============================================================================
--- doc/trunk/design/syn/S06.pod (original)
+++ doc/trunk/design/syn/S06.pod Sat Mar 10 16:02:36 2007
@@ -13,9 +13,9 @@
Maintainer: Larry Wall <[EMAIL PROTECTED]>
Date: 21 Mar 2003
- Last Modified: 8 Mar 2007
+ Last Modified: 10 Mar 2007
Number: 6
- Version: 74
+ Version: 75
This document summarizes Apocalypse 6, which covers subroutines and the
@@ -1678,24 +1678,65 @@
C<Capture> object is generated, not when it is later bound (which
could happen more than once).
-=head2 The C<caller> function
+=head2 The C<context> and C<caller> functions
-The C<caller> function returns an object that describes a particular
-"higher" dynamic scope, from which the current scope was called.
+The C<context> function returns an object that describes a particular
+dynamic scope, either the current dynamic scope or some outer dynamic
+scope from which the current scope was called. The current context
+is numbered 0, and the immediate caller is numbered 1:
- say "In ", caller.sub,
- " called from ", caller.file,
- " line ", caller.line;
-
-C<caller> may be given arguments telling it what kind of higher scope to
-look for, and how many such scopes to skip over when looking:
-
- $caller = caller; # immediate caller
- $caller = caller Method; # nearest caller that is method
- $caller = caller Bare; # nearest caller that is bare block
- $caller = caller Sub, :skip(2); # caller three levels up
- $caller = caller Block where { .label eq 'Foo' };
- # caller whose label is 'Foo'
+ say " file ", context(1).file,
+ " line ", context(1).line;
+
+The C<caller> function is defined as
+
+ &caller ::= &context.assuming(1);
+
+so the preceding example can also be written:
+
+ say " file ", caller.file,
+ " line ", caller.line;
+
+or even
+
+ say " file ", CALLER::<$?FILE>,
+ " line ", CALLER::<$?LINE>;
+
+The C<caller> function always returns the immediate caller's context,
+but the more general C<context> function may be given arguments
+telling it which higher scope to look for. The first argument is always
+a count of how many contexts to skip:
+
+ $ctx = context(0); # context(0), my own context
+ $ctx = context(1); # context(1), my caller's context
+ $ctx = context(2); # context(2), my caller's caller's context
+ $ctx = context($i); # $i'th caller's context
+
+The second argument is optional and is a matcher to apply against the
+context object.
+
+ $ctx = context(0, Method); # nearest context that is method
+ $ctx = context(1, Method); # 2nd nearest context that is method
+ $ctx = context(0, Block); # nearest context that is block
+ $ctx = context(2, Sub); # 3rd nearest sub context
+ $ctx = context(0, Block where { .label eq 'Foo' });
+ # nearest context whose label is 'Foo'
+
+Note that this last potentially differs from the answer returned by
+
+ Foo.context
+
+which returns the context of the innermost Foo block in the lexical scope
+rather than the dynamic scope.
+
+The returned context object has the following methods:
+
+ .want
+ .file
+ .line
+ .subname
+
+and basically anything else defined as C<$?NAME> there. (XXX cop out)
=head2 The C<want> function
