Import Upstream version 0.32

Changes

+Revision history for Scope-Upper
+
+0.32    2019-07-08 12:50 UTC
+        + Fix : [RT #129539] : fails with v5.27.3 and later with DEBUGGING
+                The module has been amended to accomodate with a change of
+                behaviour of a core macro.
+        + Upd : Contact info.
+
+0.31    2018-08-26 19:50 UTC
+        + Fix : [RT #125931] : localized SCALAR doesn't get imported
+                localize '$Foo::x' => $var now properly imports $x into Foo.
+                Thanks Vernon Lyon for reporting.
+
+0.30    2017-11-04 15:55 UTC
+        + Fix : [RT #123481] : Compatibility with CV-in-stash optimisation
+                Thanks Father Chrysostomos for reporting and contributing a
+                patch.
+
+0.29    2016-06-06 12:00 UTC
+        + Chg : A large chunk of boilerplate XS code, which is also used in
+                other XS modules, has been factored out of the main .xs file
+                to a collection of .h files in the xsh subdirectory.
+        + Fix : [RT #112246] : Blead breaks Scope::Upper
+                Dave Mitchell provided a new implementation of reap(),
+                localize_*() and uplevel() to match the new context stack
+                handling in perl 5.24. Many thanks to him.
+
+0.28    2015-08-18 15:00 UTC
+        + Chg : SUB() and EVAL() will now warn if they cannot find an
+                appropriate context in the current stack. They will still
+                return undef in this case, which is interpreted as the current
+                context when combined with other words.
+        + Fix : [RT #104751] : Scope::Upper does not handle exotic stack types
+                Trying to target a scope above the current perl scope will now
+                result in a warning. In that case, the topmost context in the
+                current stack will still be returned.
+                Thanks Rafaël Garcia-Suarez for the report.
+        + Fix : Test failures of threads tests on systems with harsh resource
+                constraints causing the threads to exit() during run.
+        + Opt : Some internal structures were shrunk, resulting in memory
+                savings and small speedups.
+
+0.27    2015-03-27 22:10 UTC
+        + Chg : The new environment variable to enable thread tests on older
+                perls is PERL_FORCE_TEST_THREADS. Note that this variable
+                should only be turned on by authors.
+        + Fix : Segfaults when the module is loaded by several threads (or
+                Windows emulated processes) ran in parallel.
+        + Fix : Memory leak with the uid() feature.
+        + Fix : Update the Windows ActivePerl + gcc 3.4 workaround for
+                ExtUtils::MakeMaker 7.04. Thanks Christian Walde for reporting
+                and feedback on this issue.
+        + Fix : reap(), localize(), localize_elem() and localize_delete()
+                will again work correctly on perl 5.19.4+ when the debugger
+                is enabled.
+        + Fix : Silence some compiler warnings.
+
+0.26    2015-03-12 23:30 UTC
+        + Fix : [RT #100264] : Don't use CvPADLIST on XSUBs
+                Thanks Father Chrysostomos for reporting and contributing a
+                patch.
+        + Fix : Be really compatible with the optional OP_PARENT feature.
+
+0.25    2014-09-21 17:10 UTC
+        + Add : Support for the PERL_OP_PARENT optional feature introduced in
+                perl 5.21.2.
+        + Fix : Work around an assertion failure in perl 5.21.4.
+
+0.24    2013-09-10 11:10 UTC
+        + Fix : Lexicals returned with unwind(), yield() and leave() will no
+                longer be lost on perl 5.19.4 and above.
+
+0.23    2013-09-02 11:30 UTC
+        This is a maintenance release. The code contains no functional change.
+        Satisfied users of version 0.22 can skip this update.
+        + Fix : [RT #87178] : typo fixes.
+                Thanks dsteinbrunner@pobox.com for the patch.
+        + Fix : [RT #88177] : 5.19.3 block hint test breakage
+                t/07-context_info.t has been taught about perl 5.19.3.
+                Thanks Andrew Main for the patch.
+        + Tst : Author tests are no longer bundled with this distribution.
+                They are only made available to authors in the git repository.
+        + Tst : "given is experimental" warnings when running tests on perl
+                5.18 and above have been silenced.
+
+0.22    2013-01-30 23:35 UTC
+        + Chg : perl 5.6.1 is required.
+        + Fix : context_info() now ignores %warnings::Bits for perl 5.8.6 and
+                below, just like caller().
+        + Fix : [RT #82220] : Scope-Upper-0.21 test stuck on Windows perl 5.12.3
+                t/93-pod-spelling.t will not crash anymore on perl 5.12 and
+                below.
+                Thanks Gabor Szabo for reporting and Slaven Rezic for debugging
+                this issue.
+        + Tst : Rare test failures of t/07-context_info.t on perl 5.6,
+                t/55-yield-target.t on perl 5.[68], and t/63-uplevel-ctl.t on
+                perl 5.8.[345] have been addressed.
+
+0.21    2012-09-21 15:10 UTC
+        + Fix : context_info() has been taught about perl 5.17.4.
+        + Fix : t/07-context_info.t will no longer fail with perls that have
+                sitecustomize enabled (like many perl builds for Windows).
+                Thanks Steve Hay and Nicholas Clark for debugging help.
+        + Fix : Broken linkage on Windows with gcc 3.4, which appears in
+                particular when using ActivePerl's default compiler suite.
+                For those setups, the Scope::Upper shared library will now be
+                linked against the perl dll directly (instead of the import
+                library).
+
+0.20    2012-09-17 11:00 UTC
+        + Add : The new yield(@values, $context) function can be used to return
+                values to any upper scope, including do or map blocks.
+                The new leave(@values) function is an alias for
+                yield(@values, HERE).
+        + Add : The new context_info($context) function return information
+                about context $context, similarly to what caller() provides
+                but for any upper scope.
+        + Chg : Contexts are now normalized. In previous versions, it was
+                possible for different contexts to refer to the same scope :
+                for example, "for (my $i = 0; $i < 10; ++$i) { ... }" was
+                reachable through two contexts, while "for (@array) { ... }"
+                only by one. Starting from this version, contexts are
+                normalized so that they always represent an actual scope.
+        + Doc : C++ compilers are officially NOT supported.
+        + Fix : Building with a more recent version of perl 5.17.4.
+        + Fix : Debugger compatibility with perl 5.17.1 and above.
+
+0.19    2012-09-01 13:25 UTC
+        + Doc : POD headings have been made linkable.
+        + Fix : Building with perl 5.17.4.
+        + Fix : BUILD_PREREQS are now set for ExtUtils::MakeMaker.
+        + Opt : uplevel() private data structure is 7% smaller on 64 bits
+                architectures.
+        + Tst : Author tests overhaul.
+
+0.18    2011-10-10 20:50 UTC
+        + Add : The uid() function returns an unique identifier for each dynamic
+                scope. The validate_uid() function can be used to check whether
+                one such identifier is valid (i.e. that the scope it refers to
+                is still alive).
+        + Chg : It is no longer possible on perl 5.6 to call goto() in an
+                uplevel callback to replace the uplevel call. This change was
+                needed in order to ensure consistency between platforms
+                regarding to the following fix just below.
+        + Fix : The uplevel() tests now pass on Windows.
+                Thanks C.H. Kang for bringing this to my attention.
+
+0.17    2011-10-03 21:45 UTC
+        + Fix : uplevel() will now use the correct pad when executing its
+                callback. This fixes at least two issues :
+                - closures defined inside the uplevel callback can now correctly
+                access lexicals from inside and outside the callback.
+                - state variables in the uplevel callback now work properly.
+        + Fix : It is now generally possible to call goto() in the uplevel'd
+                code to replace the uplevel stack frame. There are two cases
+                for which it is still not possible :
+                - if -D flags were set when running perl (as in "perl -Dt ...").
+                - if the perl runloop has been replaced with a custom one by
+                another module.
+                If uplevel() detects that the replacement code contains a goto
+                statement, and is in one of those two cases, then it will refuse
+                to execute the callback and throw an exception.
+                Note that this fix implies a run-time overhead of uplevel()
+                proportional to the size of the the callback in every case
+                (with a small ratio), and proportional to the size of ALL the
+                code executed as the result of the uplevel call (including
+                subroutine calls inside the callback) when a goto statement is
+                found in the uplevel callback.
+        + Fix : uplevel() has been taught how to handle XS callbacks properly.
+        + Fix : The cause of "Attempt to free unreferenced scalar" warnings
+                when using uplevel() has been addressed.
+        + Fix : [RT #71212] : build failure on Windows.
+                The module does no longer rely on calling Perl_cv_clone, which
+                isn't exported.
+                Thanks C.H. Kang for reporting.
+
+0.16    2011-09-03 23:00 UTC
+        + Add : uplevel($code, @args, $cxt) executes $code with arguments @args
+                in the upper context pointed by $cxt.
+                This is an XS version of the well-known uplevel() routine from
+                Sub::Uplevel. There are a few differences between both
+                implmentations that are listed in the documentation.
+                The XS version is roughly 10 times faster than the pure-Perl
+                version.
+
+0.15    2011-08-24 14:20 UTC
+        + Fix : Localizing subroutines in an higher scope will now correctly
+                update the method cache.
+
+0.14    2011-02-27 00:00 UTC
+        + Fix : [RT #64997] : Compatibility with perl 5.13.10.
+                Thanks Dave Mitchell for the notice.
+        + Tst : Lengthy tests have been ported to Test::Leaner, making the
+                whole test suite about 50% faster.
+
+0.13    2010-12-20 01:00 UTC
+        + Fix : [RT #61904] : Stack corruption when using unwind() under
+                Devel::NYTProf.
+                Thanks Sergey Aleynikov for contributing a fix.
+        + Fix : [RT #63378] : Compatibility with perl 5.13.8.
+                Thanks Andreas J. König for bisecting the issue.
+        + Tst : Threads tests are now only run on perl 5.13.4 and higher.
+                They could segfault randomly because of what seems to be an
+                internal bug of Perl, which has been addressed in 5.13.4.
+                There is also an environment variable that allows you to
+                forcefully run those tests, but it should be set only for
+                author testing and not for end users.
+
+0.12    2010-05-19 00:45 UTC
+        + Fix : Compatibility with perl 5.13.
+        + Fix : Test failures with perl 5.8.0.
+        + Fix : A minor leak of SVs when a non array/hash was passed to
+                localize_elem().
+
+0.11    2010-04-16 23:20 UTC
+        + Chg : It's now forbiddent to pass a reference to a non-glob variable
+                as the localization target of localize(), localize_elem() and
+                localize_delete().
+        + Chg : localize_elem() now only accepts localization of arrays or hashs
+                elements. For other types, it used to be a synonym of localize.
+        + Chg : localize_elem() no longer accepts a glob as the target. You now
+                have to specify the variable as a string. This is because it was
+                impossible in this case to handle meaningfully the array or the
+                hash reference passed as the assigned value.
+        + Doc : The synopsys was revamped, and the rest of the documentation was
+                reviewed.
+        + Fix : [RT #55593] : Segfault when localizing hash or array element to
+                different package in different file.
+                Thanks Dagfinn Ilmari Mannsåker for reporting.
+        + Fix : [RT #56301] : reap loses eval context when dying naturally.
+                Thanks Andrew Main for reporting.
+        + Fix : Scope inconsistencies and segfaults when saving several
+                localizations into the same target scope.
+        + Fix : Stop skipping frames as a pop optimization. This caused breakage
+                under the debugger (and most likely outside as well).
+
+0.10    2010-01-18 23:50 UTC
+        + Fix : Properly handle given/when on 5.10.
+        + Fix : Some stack inconsistencies were fixed, though they were unlikely
+                to have an impact on your real-life code.
+        + Fix : Work around Kwalitee test misfailures.
+
+0.09    2009-05-17 20:20 UTC
+        + Add : The new SU_THREADSAFE constant can be used to know whether the
+                module could have been built with thread safety enabled.
+        + Chg : Thread safety is disabled for perl 5.8 on Win32.
+        + Chg : A saner workaround for the "call_sv() during LEAVE clobbers the
+                still used last popped stack element" issue on 5.10.
+
+0.08    2009-04-16 22:50 UTC
+        + Fix : [RT #44204] : Stack corruption with reap(). Thanks Torsten
+                Foertsch for reporting.
+        + Fix : Building with Solaris CC.
+        + Tst : unwind() in threads.
+
+0.07    2009-02-20 00:20 UTC
+        + Chg : The CLONE method will no longer be defined for non-threaded
+                perls.
+        + Doc : Some examples on how to build the target context from the words.
+        + Fix : Some unlikely possible uninitialized reads, indirectly pointed
+                out in a Redhat review request.
+        + Fix : "localize *x, 'y' => $cxt" now matches Perl's behaviour for
+                "local *x = 'y'".
+        + Fix : Miscellanous code cleanups, courtesy of Florian Ragwitz.
+        + Upd : Resources in META.yml.
+
+0.06    2009-01-17 00:05 UTC
+        + Chg : INCOMPATIBLE CHANGE: The level is now absolute and no longer
+                relative to the current frame - we'll call it "context" from now
+                on. You should replace all your raw levels by combinations of
+                words.
+                The old behaviour of "=> $n" can be easily reobtained by using
+                "=> SCOPE($n)".
+        + Fix : As a result of this change, the module now plays nicely with
+                the debugger.
+
+0.05    2009-01-12 18:15 UTC
+        + Fix : Stack mess when using unwind() in scalar context.
+        + Fix : Returning an automatic variable isn't wise, so let's use a
+                context instead.
+        + Doc : Clarifications.
+        + Tst : Stress tests for unwind().
+
+0.04    2009-01-11 18:40 UTC
+        + Add : unwind(@things, $level), that returns to an upper context.
+        + Add : want_at($level), that gives the wantarray for $level.
+        + Add : Control words, to reliably get the level of the n-th upper
+                subroutine or eval scope. TOPLEVEL was renamed to TOP.
+        + Fix : Tests with 5.6.
+        + Tst : Reordering and factoring some of the stress tests so that they
+                aren't needlessly ran several times.
+
+0.03    2009-01-04 15:55 UTC
+        + Add : localize_delete(), that localize array/hash elements in upper
+                scopes.
+        + Fix : Segfault when localizing array elements with an invalid negative
+                index.
+
+0.02    2008-12-28 18:40 UTC
+        + Doc : Clarifications and improvements.
+        + Fix : Missing compatibility macros.
+        + Fix : Localized nonexistant array elements should be deleted when
+                their time comes so that the array recovers its original length.
+
+0.01    2008-12-26 16:05 UTC
+        First version, released on an unsuspecting world.
+

MANIFEST

+Changes
+MANIFEST
+META.json
+META.yml
+Makefile.PL
+README
+Upper.xs
+lib/Scope/Upper.pm
+samples/bench_uplevel.pl
+samples/tag.pl
+samples/try.pl
+t/00-load.t
+t/01-import.t
+t/05-words.t
+t/06-want_at.t
+t/07-context_info.t
+t/09-load-threads.t
+t/11-reap-level.t
+t/12-reap-block.t
+t/13-reap-ctl.t
+t/15-reap-multi.t
+t/16-reap-numerous.t
+t/20-localize-target.t
+t/21-localize-level.t
+t/22-localize-block.t
+t/23-localize-ctl.t
+t/24-localize-magic.t
+t/25-localize-multi.t
+t/26-localize-numerous.t
+t/30-localize_elem-target.t
+t/31-localize_elem-level.t
+t/32-localize_elem-block.t
+t/34-localize_elem-magic.t
+t/36-localize_elem-numerous.t
+t/40-localize_delete-target.t
+t/41-localize_delete-level.t
+t/44-localize_delete-magic.t
+t/46-localize_delete-numerous.t
+t/50-unwind-target.t
+t/51-unwind-multi.t
+t/52-unwind-context.t
+t/53-unwind-misc.t
+t/54-unwind-threads.t
+t/55-yield-target.t
+t/57-yield-context.t
+t/58-yield-misc.t
+t/59-yield-threads.t
+t/60-uplevel-target.t
+t/61-uplevel-args.t
+t/62-uplevel-return.t
+t/63-uplevel-ctl.t
+t/64-uplevel-caller.t
+t/65-uplevel-multi.t
+t/66-uplevel-context.t
+t/67-uplevel-scope.t
+t/69-uplevel-threads.t
+t/70-uid-target.t
+t/74-uid-validate.t
+t/75-uid-uplevel.t
+t/79-uid-threads.t
+t/81-stress-level.t
+t/84-stress-unwind.t
+t/85-stress-yield.t
+t/86-stress-uplevel.t
+t/87-stress-uid.t
+t/lib/Scope/Upper/TestGenerator.pm
+t/lib/Test/Leaner.pm
+t/lib/VPIT/TestHelpers.pm
+xsh/caps.h
+xsh/debug.h
+xsh/mem.h
+xsh/threads.h
+xsh/util.h

META.json

+{
+   "abstract" : "Act on upper scopes.",
+   "author" : [
+      "Vincent Pit <vpit@cpan.org>"
+   ],
+   "dynamic_config" : 1,
+   "generated_by" : "ExtUtils::MakeMaker version 7.34, CPAN::Meta::Converter version 2.150010",
+   "license" : [
+      "perl_5"
+   ],
+   "meta-spec" : {
+      "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec",
+      "version" : 2
+   },
+   "name" : "Scope-Upper",
+   "no_index" : {
+      "directory" : [
+         "t",
+         "inc"
+      ]
+   },
+   "prereqs" : {
+      "build" : {
+         "requires" : {
+            "Config" : "0",
+            "Exporter" : "0",
+            "ExtUtils::MakeMaker" : "0",
+            "POSIX" : "0",
+            "Test::More" : "0",
+            "XSLoader" : "0",
+            "base" : "0"
+         }
+      },
+      "configure" : {
+         "requires" : {
+            "Config" : "0",
+            "ExtUtils::MakeMaker" : "0"
+         }
+      },
+      "runtime" : {
+         "requires" : {
+            "Exporter" : "0",
+            "XSLoader" : "0",
+            "base" : "0",
+            "perl" : "5.006001"
+         }
+      }
+   },
+   "release_status" : "stable",
+   "resources" : {
+      "bugtracker" : {
+         "web" : "http://rt.cpan.org/Dist/Display.html?Name=Scope-Upper"
+      },
+      "homepage" : "http://search.cpan.org/dist/Scope-Upper/",
+      "license" : [
+         "http://dev.perl.org/licenses/"
+      ],
+      "repository" : {
+         "url" : "http://git.vpit.fr/?p=perl%2Fmodules%2FScope-Upper.git"
+      }
+   },
+   "version" : "0.32",
+   "x_serialization_backend" : "JSON::PP version 4.02"
+}

META.yml

+---
+abstract: 'Act on upper scopes.'
+author:
+  - 'Vincent Pit <vpit@cpan.org>'
+build_requires:
+  Config: '0'
+  Exporter: '0'
+  ExtUtils::MakeMaker: '0'
+  POSIX: '0'
+  Test::More: '0'
+  XSLoader: '0'
+  base: '0'
+configure_requires:
+  Config: '0'
+  ExtUtils::MakeMaker: '0'
+dynamic_config: 1
+generated_by: 'ExtUtils::MakeMaker version 7.34, CPAN::Meta::Converter version 2.150010'
+license: perl
+meta-spec:
+  url: http://module-build.sourceforge.net/META-spec-v1.4.html
+  version: '1.4'
+name: Scope-Upper
+no_index:
+  directory:
+    - t
+    - inc
+requires:
+  Exporter: '0'
+  XSLoader: '0'
+  base: '0'
+  perl: '5.006001'
+resources:
+  bugtracker: http://rt.cpan.org/Dist/Display.html?Name=Scope-Upper
+  homepage: http://search.cpan.org/dist/Scope-Upper/
+  license: http://dev.perl.org/licenses/
+  repository: http://git.vpit.fr/?p=perl%2Fmodules%2FScope-Upper.git
+version: '0.32'
+x_serialization_backend: 'CPAN::Meta::YAML version 0.018'

Makefile.PL

+use 5.006_001;
+
+use strict;
+use warnings;
+use ExtUtils::MakeMaker;
+
+use Config;
+
+if ($Config{d_cplusplus}) {
+ print STDERR <<'FAILPLUSPLUS';
+Configuration aborted: C++ compilers are not supported
+
+    Your perl has been built with a C++ compiler, which is then handed to
+    XS extensions as if it were a proper C compiler. This extension is
+    written in C, and naturally only supports C compilers, so it cannot be
+    built with your perl.
+
+    Note that building perl with a C++ compiler is only supposed to be done
+    by core developers in order to check that the perl headers can be
+    included from C++ code. Its use in the wild is not supported by the
+    perl5 porters. If your vendor has built its perl binary with a C++
+    compiler, please consider reporting this issue to them.
+
+    This text will be displayed 10 seconds, and then the configuration
+    script will exit.
+FAILPLUSPLUS
+ sleep 10;
+ exit 0;
+}
+
+my $pl   = $Config{perl_patchlevel};
+my $desc = $Config{git_describe};
+for ($pl, $desc) {
+ $_ = undef unless defined and length;
+}
+
+my @DEFINES;
+my %macro;
+
+print "Checking if this is an official release of perl... ";
+my $is_release = ("$]" < 5.011) ? (defined($pl) || defined($desc) ? 0 : 1)
+                                : (defined($desc)                 ? 0 : 1);
+push @DEFINES, "-DSU_RELEASE=$is_release";
+print $is_release  ? "yes\n" : "no\n";
+
+my $is_gcc_34 = 0;
+print "Checking if this is gcc 3.4 on Windows trying to link against an import library... ";
+if ($^O eq 'MSWin32' and not grep /^LD[A-Z]*=/, @ARGV) {
+ my ($libperl, $gccversion) = map $_ || '', @Config{qw<libperl gccversion>};
+ if ($gccversion =~ /^3\.4\.[0-9]+/ and $libperl =~ s/\.lib$//) {
+  $is_gcc_34 = 1;
+  my ($lddlflags, $ldflags) = @Config{qw<lddlflags ldflags>};
+  $_ ||= '', s/-L(?:".*?"|\S+)//g for $lddlflags, $ldflags;
+  $libperl = "-l$libperl";
+  my $libdirs = join ' ',
+                 map { s/(?<!\\)((?:\\\\)*")/\\$1/g; qq[-L"$_"] }
+                  @Config{qw<bin sitebin>};
+  $macro{LDDLFLAGS}    = "$lddlflags $libdirs $libperl";
+  $macro{LDFLAGS}      = "$ldflags $libdirs $libperl";
+  eval <<'  MY_SECTION';
+   package MY;
+   sub dynamic_lib {
+    my $self = shift;
+    my $inherited = $self->SUPER::dynamic_lib(@_);
+    $inherited =~ s/"?\$\(PERL_ARCHIVE\)"?//g;
+    return $inherited;
+   }
+  MY_SECTION
+  die $@ if $@;
+ }
+}
+print $is_gcc_34 ? "yes\n" : "no\n";
+
+# Threads, Windows and 5.8.x don't seem to be best friends
+if ($^O eq 'MSWin32' && "$]" < 5.009) {
+ push @DEFINES, '-DXSH_MULTIPLICITY=0';
+}
+
+@DEFINES = (DEFINE => join ' ', @DEFINES) if @DEFINES;
+%macro   = (macro  => { %macro })         if %macro; # Beware of the cycle
+
+my $dist = 'Scope-Upper';
+
+(my $name = $dist) =~ s{-}{::}g;
+
+(my $file = $dist) =~ s{-}{/}g;
+$file = "lib/$file.pm";
+
+my %PREREQ_PM = (
+ 'Exporter' => 0,
+ 'XSLoader' => 0,
+ 'base'     => 0,
+);
+
+my %BUILD_REQUIRES = (
+ 'ExtUtils::MakeMaker' => 0,
+ 'Config'              => 0,
+ 'POSIX'               => 0,
+ 'Test::More'          => 0,
+ %PREREQ_PM,
+);
+
+my %META = (
+ configure_requires => {
+  'Config'              => 0,
+  'ExtUtils::MakeMaker' => 0,
+ },
+ build_requires => {
+  %BUILD_REQUIRES,
+ },
+ dynamic_config => 1,
+ resources => {
+  bugtracker => "http://rt.cpan.org/Dist/Display.html?Name=$dist",
+  homepage   => "http://search.cpan.org/dist/$dist/",
+  license    => 'http://dev.perl.org/licenses/',
+  repository => "http://git.vpit.fr/?p=perl%2Fmodules%2F$dist.git",
+ },
+);
+
+WriteMakefile(
+ NAME             => $name,
+ AUTHOR           => 'Vincent Pit <vpit@cpan.org>',
+ LICENSE          => 'perl',
+ VERSION_FROM     => $file,
+ ABSTRACT_FROM    => $file,
+ PL_FILES         => {},
+ @DEFINES,
+ BUILD_REQUIRES   => \%BUILD_REQUIRES,
+ PREREQ_PM        => \%PREREQ_PM,
+ MIN_PERL_VERSION => '5.006001',
+ META_MERGE       => \%META,
+ dist             => {
+  PREOP    => "pod2text -u $file > \$(DISTVNAME)/README",
+  COMPRESS => 'gzip -9f', SUFFIX => 'gz'
+ },
+ clean            => {
+  FILES => "$dist-* *.gcov *.gcda *.gcno cover_db Debian_CPANTS.txt*"
+ },
+ %macro,
+);
+
+package MY;
+
+sub postamble {
+ return <<'POSTAMBLE';
+testdeb: all
+	PERL_DL_NONLAZY=1 PERLDB_OPTS="NonStop=1" $(FULLPERLRUN) -MTAP::Harness -e 'TAP::Harness->new({verbosity => q{$(TEST_VERBOSE)}, lib => [ q{$(INST_LIB)}, q{$(INST_ARCHLIB)} ], switches => [ q{-d} ]})->runtests(@ARGV)' $(TEST_FILES)
+POSTAMBLE
+}

samples/bench_uplevel.pl

+#!perl
+
+use strict;
+use warnings;
+
+use blib;
+
+use Benchmark qw<cmpthese>;
+
+use Scope::Upper qw<:words>;
+BEGIN { *uplevel_xs = \&Scope::Upper::uplevel }
+
+use Sub::Uplevel;
+BEGIN { *uplevel_pp = \&Sub::Uplevel::uplevel }
+
+sub void { }
+
+sub foo_t  { void { } }
+
+sub foo_pp { uplevel_pp(0, sub { }) }
+
+sub foo_xs { uplevel_xs { } }
+
+print "\nuplevel to current scope:\n";
+cmpthese -1, {
+ tare => sub { foo_t() },
+ pp   => sub { foo_pp() },
+ xs   => sub { foo_xs() },
+};
+
+sub bar_1_t  { bar_2_t() }
+sub bar_2_t  { void() }
+
+sub bar_1_pp { bar_2_pp() }
+sub bar_2_pp { uplevel_pp(1, sub { }) }
+
+sub bar_1_xs { bar_2_xs() }
+sub bar_2_xs { uplevel_xs { } UP }
+
+print "\nuplevel to one scope above:\n";
+cmpthese -1, {
+ tare => sub { bar_2_t() },
+ pp   => sub { bar_2_pp() },
+ xs   => sub { bar_2_xs() },
+};
+
+sub hundred { 1 .. 100 }
+
+sub baz_t  { hundred() }
+
+sub baz_pp { uplevel_pp(0, sub { 1 .. 100 }) }
+
+sub baz_xs { uplevel_xs { 1 .. 100 } }
+
+print "\nreturning 100 values:\n";
+cmpthese -1, {
+ tare => sub { my @r = baz_t() },
+ pp   => sub { my @r = baz_pp() },
+ xs   => sub { my @r = baz_xs() },
+};
+
+my $n = 10_000;
+my $tare_code = "sub { my \@c; \@c = caller(0) for 1 .. $n }->()";
+
+print "\ncaller() slowdown:\n";
+cmpthese 30, {
+ tare => sub { system { $^X } $^X, '-e', "use blib; use List::Util; $tare_code" },
+ pp   => sub { system { $^X } $^X, '-e', "use blib; use Sub::Uplevel; $tare_code" },
+ xs   => sub { system { $^X } $^X, '-e', "use blib; use Scope::Upper; $tare_code" },
+}

samples/tag.pl

+#!perl
+
+use strict;
+use warnings;
+
+use blib;
+
+package Scope;
+
+use Scope::Upper qw<reap localize localize_elem localize_delete :words>;
+
+sub new {
+ my ($class, $name) = @_;
+
+ localize '$tag' => bless({ name => $name }, $class) => UP;
+
+ reap { print Scope->tag->name, ": end\n" } UP;
+}
+
+# Get the tag stored in the caller namespace
+sub tag {
+ my $l   = 0;
+ my $pkg = __PACKAGE__;
+ $pkg    = caller $l++ while $pkg eq __PACKAGE__;
+
+ no strict 'refs';
+ ${$pkg . '::tag'};
+}
+
+sub name { shift->{name} }
+
+# Locally capture warnings and reprint them with the name prefixed
+sub catch {
+ localize_elem '%SIG', '__WARN__' => sub {
+  print Scope->tag->name, ': ', @_;
+ } => UP;
+}
+
+# Locally clear @INC
+sub private {
+ for (reverse 0 .. $#INC) {
+  # First UP is the for loop, second is the sub boundary
+  localize_delete '@INC', $_ => UP UP;
+ }
+}
+
+package UserLand;
+
+{
+ Scope->new("top");      # initializes $UserLand::tag
+
+ {
+  Scope->catch;
+  my $one = 1 + undef;   # prints "top: Use of uninitialized value..."
+
+  {
+   Scope->private;
+   eval { delete $INC{"Cwd.pm"}; require Cwd }; # blib loads Cwd
+   print $@;             # prints "Can't locate Cwd.pm in @INC (@INC contains:) at..."
+  }
+
+  require Cwd;           # loads Cwd.pm
+ }
+
+}                        # prints "top: done"

samples/try.pl

+#!perl
+
+use strict;
+use warnings;
+
+use blib;
+
+use Scope::Upper qw<unwind want_at :words>;
+
+sub try (&) {
+ my @result = shift->();
+ my $cx = SUB UP; # Point to the sub above this one
+ unwind +(want_at($cx) ? @result : scalar @result) => $cx;
+}
+
+sub zap {
+ try {
+  my @things = qw<a b c>;
+  return @things; # returns to try() and then outside zap()
+ };
+ print "NOT REACHED\n";
+}
+
+my @stuff = zap(); # @stuff contains qw<a b c>
+my $stuff = zap(); # $stuff contains 3
+
+print "zap() returns @stuff in list context and $stuff in scalar context\n";
+
+{
+ package Uplevel;
+
+ use Scope::Upper qw<uplevel CALLER>;
+
+ sub target {
+  faker(@_);
+ }
+
+ sub faker {
+  uplevel {
+   my $sub = (caller 0)[3];
+   print "$_[0] from $sub()\n";
+  } @_ => CALLER(1);
+ }
+
+ target('hello'); # "hello from Uplevel::target()"
+}

t/00-load.t

+#!perl -T
+
+use strict;
+use warnings;
+
+use Test::More tests => 1;
+
+BEGIN {
+ use_ok( 'Scope::Upper' );
+}
+
+diag( "Testing Scope::Upper $Scope::Upper::VERSION, Perl $], $^X" );