X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2FScope-Context.git;a=blobdiff_plain;f=README;h=3f96b7f6e0085079365a3eb0821442f94c8bb338;hp=1fb1ccb34f51f74ccda9fd551818f7574a7e02f1;hb=55e6f9cdc5b648bb45bed890330dee677f3773ae;hpb=f4699824df48f41d756111418704fca0d6d4d89e diff --git a/README b/README index 1fb1ccb..3f96b7f 100644 --- a/README +++ b/README @@ -3,7 +3,7 @@ NAME upper scope frames. VERSION - Version 0.01 + Version 0.02 SYNOPSIS use Scope::Context; @@ -11,7 +11,7 @@ SYNOPSIS for (1 .. 5) { sub { eval { - # create Scope::Context objects + # Create Scope::Context objects for different upper frames. my ($block, $sub, $eval, $loop); { $block = Scope::Context->new; @@ -28,7 +28,7 @@ SYNOPSIS # This prints "hello" when the eval block above ends. $eval->reap(sub { print "hello\n" }); - # Ignore $SIG{__DIE__} just for the loop. + # Ignore $SIG{__DIE__} just for the loop body. $loop->localize_delete('%SIG', '__DIE__'); # Execute the callback as if it ran in place of the sub. @@ -38,8 +38,15 @@ SYNOPSIS # Immediately return (1, 2, 3) from the sub, bypassing the eval. $sub->unwind(@values, 3); + + # Not reached. } + + # Not reached. }->(); + + # unwind() returns here. "hello\n" was printed, and now + # $SIG{__DIE__} is undefined. } DESCRIPTION @@ -58,56 +65,140 @@ DESCRIPTION thrown if you attempt to act on a context that has already expired. This means that : - my $sc; + my $cxt; { - $sc = Scope::Context->new; + $cxt = Scope::Context->new; } - $sc->reap(sub { print "hello\n }); + $cxt->reap(sub { print "hello\n }); will croak when "reap" is called. METHODS - "new [ $context ]" + "new" + my $cxt = Scope::Context->new; + my $cxt = Scope::Context->new($scope_upper_cxt); + Creates a new immutable Scope::Context object from the - Scope::Upper-comptabile context $context. If omitted, $context defaults - to the current context. + Scope::Upper-comptabile context identifier $context. If omitted, + $context defaults to the current context. "here" A synonym for "new". "cxt" - Read-only accessor to the Scope::Upper context corresponding to the - topic Scope::Context object. + my $scope_upper_cxt = $cxt->cxt; + + Read-only accessor to the Scope::Upper context identifier associated + with the invocant. "uid" - Read-only accessor to the Scope::Upper UID of the topic Scope::Context - object. + my $uid = $cxt->uid; + + Read-only accessor to the Scope::Upper unique identifier representing + the Scope::Upper context associated with the invocant. This class also overloads the "==" operator, which will return true if and only if its two operands are Scope::Context objects that have the same UID. "is_valid" - Returns true if and only if the topic context is still valid (that is, - it designates a scope that is higher than the topic context in the call - stack). + my $is_valid = $cxt->is_valid; + + Returns true if and only if the invocant is still valid (that is, it + designates a scope that is higher on the call stack than the current + scope). "assert_valid" - Throws an exception if the topic context has expired and is no longer - valid. Returns true otherwise. + $cxt->assert_valid; + + Throws an exception if the invocant has expired and is no longer valid. + Returns true otherwise. + + "package" + $cxt->package; + + Returns the namespace in use when the scope denoted by the invocant + begins. + + "file" + $cxt->file; + + Returns the name of the file where the scope denoted by the invocant + belongs to. + + "line" + $cxt->line; + + Returns the line number where the scope denoted by the invocant begins. + + "sub_name" + $cxt->sub_name; + + Returns the name of the subroutine called for this context, or "undef" + if this is not a subroutine context. + + "sub_has_args" + $cxt->sub_has_args; + + Returns a boolean indicating whether a new instance of @_ was set up for + this context, or "undef" if this is not a subroutine context. + + "gimme" + $cxt->gimme; + + Returns the context (in the sense of "wantarray" in perlfunc) in which + the scope denoted by the invocant is executed. + + "eval_text" + $cxt->eval_text; + + Returns the contents of the string being compiled for this context, or + "undef" if this is not an eval context. + + "is_require" + $cxt->is_require; + + Returns a boolean indicating whether this eval context was created by + "require", or "undef" if this is not an eval context. + + "hints_bits" + $cxt->hints_bits; + + Returns the value of the lexical hints bit mask (available as $^H at + compile time) in use when the scope denoted by the invocant begins. + + "warnings_bits" + $cxt->warnings_bits; + + Returns the bit string representing the warnings (available as + "${^WARNING_BITS}" at compile time) in use when the scope denoted by the + invocant begins. + + "hints_hash" + $cxt->hints_hash; + + Returns a reference to the lexical hints hash (available as "%^H" at + compile time) in use when the scope denoted by the invocant begins. This + method is available only on perl 5.10 and greater. "want" + my $want = $cxt->want; + Returns the Perl context (in the sense of "wantarray" : "undef" for void context, '' for scalar context, and true for list context) in which is - executed the scope corresponding to the topic Scope::Context object. + executed the scope pointed by the invocant. + + "up" + my $up_cxt = $cxt->up; + my $up_cxt = $cxt->up($frames); + my $up_cxt = Scope::Context->up; - "up [ $frames ]" Returns a new Scope::Context object pointing to the $frames-th upper - scope above the topic context. + scope above the scope pointed by the invocant. This method can also be invoked as a class method, in which case it is - equivalent to calling "up" on a Scope::Context object for the current - context. + equivalent to calling "up" on a Scope::Context object representing the + current context. If omitted, $frames defaults to 1. @@ -120,16 +211,20 @@ METHODS } } - "sub [ $frames ]" + "sub" + my $sub_cxt = $cxt->sub; + my $sub_cxt = $cxt->sub($frames); + my $sub_cxt = Scope::Context->sub; + Returns a new Scope::Context object pointing to the $frames-th - subroutine scope above the topic context. + subroutine scope above the scope pointed by the invocant. This method can also be invoked as a class method, in which case it is equivalent to calling "sub" on a Scope::Context object for the current context. If omitted, $frames defaults to 0, which results in the closest sub - enclosing the topic context. + enclosing the scope pointed by the invocant. outer(); @@ -138,20 +233,24 @@ METHODS } sub inner { - my $sub = Scope::Context->new->sub(1); # = Scope::Context->sub + my $sub = Scope::Context->new->sub(1); # = Scope::Context->sub(1) # $sub points to the context for the outer() sub. } - "eval [ $frames ]" + "eval" + my $eval_cxt = $cxt->eval; + my $eval_cxt = $cxt->eval($frames); + my $eval_cxt = Scope::Context->eval; + Returns a new Scope::Context object pointing to the $frames-th "eval" - scope above the topic context. + scope above the scope pointed by the invocant. This method can also be invoked as a class method, in which case it is equivalent to calling "eval" on a Scope::Context object for the current context. If omitted, $frames defaults to 0, which results in the closest eval - enclosing the topic context. + enclosing the scope pointed by the invocant. eval { sub { @@ -160,46 +259,68 @@ METHODS }->() } - "reap $code" - Execute $code when the topic context ends. + "reap" + $cxt->reap($code); + + Execute $code when the scope pointed by the invocant ends. See "reap" in Scope::Upper for details. - "localize $what, $value" + "localize" + $cxt->localize($what, $value); + Localize the variable described by $what to the value $value when the - control flow returns to the scope pointed by the topic context. + control flow returns to the scope pointed by the invocant. See "localize" in Scope::Upper for details. - "localize_elem $what, $key, $value" + "localize_elem" + $cxt->localize_elem($what, $key, $value); + Localize the element $key of the variable $what to the value $value when - the control flow returns to the scope pointed by the topic context. + the control flow returns to the scope pointed by the invocant. See "localize_elem" in Scope::Upper for details. - "localize_delete $what, $key" + "localize_delete" + $cxt->localize_delete($what, $key); + Delete the element $key from the variable $what when the control flow - returns to the scope pointed by the topic context. + returns to the scope pointed by the invocant. See "localize_delete" in Scope::Upper for details. - "unwind @values" + "unwind" + $cxt->unwind(@values); + Immediately returns the scalars listed in @values from the closest - subroutine enclosing the topic context. + subroutine enclosing the scope pointed by the invocant. See "unwind" in Scope::Upper for details. - "uplevel $code, @args" + "yield" + $cxt->yield(@values); + + Immediately returns the scalars listed in @values from the scope pointed + by the invocant, whatever it may be (except a substitution eval + context). + + See "yield" in Scope::Upper for details. + + "uplevel" + my @ret = $cxt->uplevel($code, @args); + Executes the code reference $code with arguments @args in the same - setting as the closest subroutine enclosing the topic context, then - returns to the current scope the values returned by $code. + setting as the closest subroutine enclosing the scope pointed by the + invocant, then returns to the current scope the values returned by + $code. See "uplevel" in Scope::Upper for details. DEPENDENCIES Carp (core module since perl 5), Scalar::Util (since 5.7.3). - Scope::Upper 0.18. + Scope::Upper 0.21. SEE ALSO Scope::Upper. @@ -224,7 +345,7 @@ SUPPORT perldoc Scope::Context COPYRIGHT & LICENSE - Copyright 2011 Vincent Pit, all rights reserved. + Copyright 2011,2012,2013 Vincent Pit, all rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.