From: Vincent Pit Date: Fri, 8 Feb 2013 16:42:33 +0000 (-0200) Subject: This is 0.02 X-Git-Tag: v0.02 X-Git-Url: http://git.vpit.fr/?a=commitdiff_plain;h=b502d412570a531d4176da4a0f050f5908d430b5;p=perl%2Fmodules%2FScope-Context.git This is 0.02 --- diff --git a/Changes b/Changes index 337e7d5..1cd7e42 100644 --- a/Changes +++ b/Changes @@ -1,4 +1,12 @@ Revision history for Scope-Context +0.02 2013-02-08 16:45 UTC + + Add : The methods yield(), package(), file(), line(), sub_name(), + sub_has_args(), gimme(), eval_text(), is_require(), hints_bits(), + warnings_bits() and hints_hash() were implemented. + + Chg : Scope::Upper 0.21 is now required. + + Doc : POD tweaks and clarifications. + + Tst : Author tests overhaul. + 0.01 2011-10-11 13:10 UTC First version, released on an unsuspecting world. diff --git a/META.json b/META.json index 167ea85..50cbe2c 100644 --- a/META.json +++ b/META.json @@ -4,7 +4,7 @@ "Vincent Pit " ], "dynamic_config" : 0, - "generated_by" : "ExtUtils::MakeMaker version 6.59, CPAN::Meta::Converter version 2.112621", + "generated_by" : "ExtUtils::MakeMaker version 6.64, CPAN::Meta::Converter version 2.120921", "license" : [ "perl_5" ], @@ -22,21 +22,21 @@ "prereqs" : { "build" : { "requires" : { - "ExtUtils::MakeMaker" : 0, - "Scalar::Util" : 0, - "Scope::Upper" : "0.18", - "Test::More" : 0 + "ExtUtils::MakeMaker" : "0", + "Scalar::Util" : "0", + "Scope::Upper" : "0.21", + "Test::More" : "0" } }, "configure" : { "requires" : { - "ExtUtils::MakeMaker" : 0 + "ExtUtils::MakeMaker" : "0" } }, "runtime" : { "requires" : { - "Scalar::Util" : 0, - "Scope::Upper" : "0.18", + "Scalar::Util" : "0", + "Scope::Upper" : "0.21", "perl" : "5.006" } } @@ -54,5 +54,5 @@ "url" : "http://git.profvince.com/?p=perl%2Fmodules%2FScope-Context.git" } }, - "version" : "0.01" + "version" : "0.02" } diff --git a/META.yml b/META.yml index b4c5a5e..731242b 100644 --- a/META.yml +++ b/META.yml @@ -5,12 +5,12 @@ author: build_requires: ExtUtils::MakeMaker: 0 Scalar::Util: 0 - Scope::Upper: 0.18 + Scope::Upper: 0.21 Test::More: 0 configure_requires: ExtUtils::MakeMaker: 0 dynamic_config: 0 -generated_by: 'ExtUtils::MakeMaker version 6.59, CPAN::Meta::Converter version 2.112621' +generated_by: 'ExtUtils::MakeMaker version 6.64, CPAN::Meta::Converter version 2.120921' license: perl meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html @@ -22,11 +22,11 @@ no_index: - inc requires: Scalar::Util: 0 - Scope::Upper: 0.18 + Scope::Upper: 0.21 perl: 5.006 resources: bugtracker: http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scope-Context homepage: http://search.cpan.org/dist/Scope-Context/ license: http://dev.perl.org/licenses/ repository: http://git.profvince.com/?p=perl%2Fmodules%2FScope-Context.git -version: 0.01 +version: 0.02 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. diff --git a/lib/Scope/Context.pm b/lib/Scope/Context.pm index aa422e1..2789f5d 100644 --- a/lib/Scope/Context.pm +++ b/lib/Scope/Context.pm @@ -16,11 +16,11 @@ Scope::Context - Object-oriented interface for inspecting or acting upon upper s =head1 VERSION -Version 0.01 +Version 0.02 =cut -our $VERSION = '0.01'; +our $VERSION = '0.02'; =head1 SYNOPSIS