Docs on “my” should mention dynamic variables

[briandfoy]

The documentation for my starts with:

Declaring a variable with my gives it lexical scope.

But this isn't true in the sense that people expect since it does something different with dynamic variables (those with the * twigil). S04 says:

We use the phrase "lexical scoping" in its industry-standard meaning to indicate those blocks that surround the current textual location.

And later,

Except for such formal parameter declarations, all lexically scoped declarations are visible from the point of declaration to the end of the enclosing block. Period. Lexicals may not "leak" from a block to any other external scope

But, that's not what my does with dynamic variables, say, as in Moritz's Testing say article) where he temporarily replaces $*OUT's value for a different scope that doesn't enclose it:

my $output = do {
	my $*OUT = OutputCapture.new;
	doublespeak(42);
	$*OUT.captured;
};

There's a cryptic note at the end of the my docs that seems to contradict the rest of the documentation so far:

To make new-location() print nowhere, make $location a dynamic variable using the * twigil.

That is, if $location were $*location, it's not a lexical variable anymore despite the my.

The example for the * Twigil shows the same thing. A dynamic variable declared with my isn't lexical in the sense that S04 defines or that people will expect.

[jonathanstowe]

I'm not sure, the effect of a "my dynamic variable" is lexical, The difference with a dynamic variable is that you get a run-time failure if you try to refer to one if it isn't defined, rather than compile time.

sub foo() {
    say $*FOO || "boop";
}

foo();

{
     my $*FOO = "blar";

     foo();
}

foo();

The difference is that unless it has been introduced globally say with PROCESS::<$FOO> you will need to introduce ir with ```my```` or get the compile time failure if you want to assign to it.

I think the difficulty is that dynamic variables are a different category of thing that may have a lexical scope, not just a normal variable.

[jnthn]

The * twigil means "can be resolved dynamically". The my is talking about the storage, and my $*a is indeed stored just the same as my $a. Note that our $*var is also completely valid with the usual meaning of our applying:

> sub foo() { say $*a }
sub foo () { #`(Sub|91195816) ... }
> { my $*a = 42; foo(); say MY::.keys; say OUR::.keys }
42
($_ $*DISPATCHER $*a)
()
> { our $*a = 42; foo(); say MY::.keys; say OUR::.keys }
42
($_ $*DISPATCHER $*a)
($*a)

[briandfoy]

I don't think most people care how you store it. They will care about what they expect based on what is documented. If you tell them it's lexical, they won't expect it to be visible outside of the scope where it was defined. Indeed, they shouldn't have to know the gory details.

If this is the desired behaviour, then the docs should describe in the first paragraph both the lexical effects for "ordinary" variables and the other, leaky effect for dynamic variables. Furthermore, something should clarify why someone would prefer my over temp in the case of dynamic variables.

[briandfoy]

I noticed a comment in IO::Handle's indir that says that temp doesn't work in core settings:

sub indir(Str() $path, $what, :$test = <r w>) {
	my $newCWD := $*CWD.chdir($path,:$test);
	$newCWD // $newCWD.throw;

	{
		my $*CWD = $newCWD;  # temp doesn't work in core settings :-(
		$what();
	}
}

Is this low-level detail relevant to the reason we'd use my with dynamic variables at the user level?

I also asked this on Stackoverflow.

[AlexDaniel]

I've changed the title so that the ticket is easier to approach. It is its defining feature, we just have to discuss dynamic variables a little bit.

[rafaelschipiura]

Solved by #1522