The following two things are roughly equivalent...

Using Scope::Upper...

use 5.010;
use Scope::Upper qw(localize UP);
our $foo = 42;
sub foo {
  localize '$foo', 1, UP;
}
sub bar {
  say "start bar: ", $foo;
  foo();
  say "end bar: ", $foo;
}
say "before bar: ", $foo;
bar();
say "after bar: ", $foo;
[download]

Without Scope::Upper...

use 5.010;
our $foo = 42;
sub bar {
  say "start bar: ", $foo;
  local $foo = 1;
  say "end bar: ", $foo;
}
say "before bar: ", $foo;
bar();
say "after bar: ", $foo;
[download]

So, essentially, what it does is allows you to change the value of a variable in your caller's scope, with the change reverting once the caller scope is finished.

This was uniquely helpful. Thank you for answering the question asked.

It would be helpful if you explain what you want to accomplish. There might be simpler or better solutions someone could provide. Otherwise we'll end up typing a bunch of stuff and find out it isn't what you want at all.

I second this, asking for a tutorial, a Far More Than You Ever Wanted To Know - type tutorial, for a module, is asking a bit much

Not a while module, just one function within it.

Not any kind of tutorial, just an example of use.

Any explanation of how it does whatever it does would be a bonus, but not a requirement to answer the question.

If you can't answer the question, move on. Probably someone else can.

It violates encapsulation in surprising ways.

If you are having a problem understanding it, then that just adds to why you should not be using it.

Refactor your code so that the resulting encapsulation helps you instead of sending you looking for ways to thwart it.

Take a look in Scope::Upper's MANIFEST.

There's three example scripts in the samples/ directory and over fifty examples of usage in the t/ directory.

If you, as you claim, do have a real use case for Scope::Upper, I'm really interested in hearing about it.

The only "use case" I can come up with is getting a callback or releasing a resource once the calling scope is left. And I think that is much better achieved by cooperating with the calling scope and returning a Guard object (there are many implementations of that, on CPAN and outside). Especially as returning a guard object allows you to easily write a shim that can go between the scope that is relevant for leaving and the scope in which the callback is installed.

Maybe my imagination is just too limited, and I'd welcome if you can show where Scope::Upper is a solution.

One reason I can think of would be if you need to localize variables $A, @B, %C in a lot of different places.

OK, you can repeat:

local($A, @B, %C);
[download]

all over the place... but it's good to not repeat yourself.

perl -E'sub Monkey::do{say$_,for@_,do{($monkey=[caller(0)]->[3])=~s{::}{ }and$monkey}}"Monkey say"->Monkey::do'

Well, that particular usage case is code-smell

Can you think of any usage for local?

If so, you've thought of a candidate for localize(), if the work involved in deriving the value assigned locally, requires multiple lines of boilerplate, and is used in more than one place.

If not, you will probably never want to look at the module again.

Certainly, but I imagine that this use case is better solved by Guard, with the benefit of having a finer grained control than just block scope.

I'm not sure what functionality outside of logging would make sense to add to local, so still my imagination is not inspired to come up with use cases where Scope::Upper feels like a solution.