global-symbol-requires-explicit-package-name.tt

=title Global symbol requires explicit package name
=timestamp 2012-09-13T12:45:56
=indexes strict, my, package, global symbol
=status show
=books beginner_book
=author szabgab
=index 1
=archive 1
=feed 1
=comments 1
=social 1

=abstract start

<b>Global symbol requires explicit package name</b> is a common,
and IMHO very misleading error message of Perl. At least for beginners.

The quick translation would be "You need to declare the variable using <b>my</b>."

=abstract end

<h2>The simplest example</h2>

<code lang="perl">
use strict;
use warnings;

$x = 42;
</code>

And the error is

<code>
Global symbol "$x" requires explicit package name at ...
</code>

While the actual error message is correct,
this is little use for the beginner Perl programmer.
They have probably not learned what packages are.
Nor do they know what can be more explicit than $x ?

This error is generated by <b>use strict</b>.

The explanation in the documentation is:

<i>
This generates a compile-time error if you access a variable that wasn't
declared via "our" or "use vars", localized via "my()", or wasn't fully qualified.
</i>

A beginner will hopefully start every script with <b>use strict</b>,
and will probably learn about <b>my</b> long before any of the other possibilities.

I don't know if the actual text can and should be changed in perl. That's not the point
of this post. The point is to help beginners understand in their own language what does
this error message mean.

To eliminate the above error message one needs to write:

<code lang="perl">
use strict;
use warnings;

my $x = 42;
</code>

That is, one needs to <b>declare the variable using my before its first use.</b>.

<h2>The bad solution</h2>

The other "solution" is to remove <b>strict</b>:

<code lang="perl">
#use strict;
use warnings;

$x = 23;
</code>

that would work but this code will generate a
<a href="/name-used-only-once-possible-typo">Name "main::x" used only once: possible typo at ...</a>
warning.

In any case, normally you would not drive a car without the safety belt, would you?

<h2>Example 2: scope</h2>

Another case I often see with beginners looks like this:

<code lang="perl">
use strict;
use warnings;

my $x = 1;

if ($x) {
my $y = 2;
}

print $y;
</code>

The error we get is the same as above:

<code>
Global symbol "$y" requires explicit package name at ...
</code>

which is surprising for many people. Especially when they start their coding.
After all they declared <hl>$y</hl> using <hl>my</hl>.

First, there is a little visual problem. The indentation of <hl>my $y = 2;</hl> is missing.
If it was indented a few spaces or a tab to the right, as in the next example,
the source of the problem might be more obvious:

<code lang="perl">
use strict;
use warnings;

my $x = 1;

if ($x) {
    my $y = 2;
}

print $y;
</code>

The problem is, that the variable <hl>$y</hl> is declared within the block,
(the pair of curly braces) which means it does not exist outside of that block.
This is called the <b>scope</b> of the variable.

The whole idea of <b>scope</b> is different among programming languages.
In Perl, a block enclosed in curly braces creates a scope.
What is declared inside using <hl>my</hl> will not be accessible outside the block.

(BTW the <hl>$x = 1</hl> is there only to have a legitimate-looking condition that creates the scope.)

The solution is either to call the <hl>print</hl> inside the block:

<code lang="perl">
use strict;
use warnings;

my $x = 1;

if ($x) {
    my $y = 2;
    print $y;
}
</code>

or to declare the variable outside the block (and not inside!):

<code lang="perl">
use strict;
use warnings;

my $x = 1;
my $y;

if ($x) {
    $y = 2;
}

print $y;
</code>

Which way you do will depend on the actual task. These are just the syntactically possible correct solutions.

Of course, if we forget to remove the <hl>my</hl> from inside the block, or if <hl>$x</hl> is false,
then we get a <a href="/use-of-uninitialized-value">Use of uninitialized value</a> warning.

<h2>The other ways</h2>

Explaining what <hl>our</hl>, and <hl>use vars</hl> do, or how can one
fully qualify a variable name is left to another post.