There's plenty of existing doc, but in the name of TMTOWTDI...
Asbestos suit donned. Criticisms welcome.
--------------
If you are wondering about things like:
use strict;
my $foo;
our $bar;
local $baz;
"explicit package"
then this article might be of help.
--------------
Before we can understand a noun, like "Paris", or a verb,
like "move", we need to understand the context. Does
Paris refer to the town in Texas, USA, or the city in France?
A perl script is aware of multiple "namespaces" and the
meaning of a word is often established by associating
it with one or other of these namespaces.
One important job you have in coding anything but the
simplest perl script is to let perl know which namespaces
should be available and which namespace should be
used for context when you use a given word.
--------------
In perl, namespaces are called packages.
Every perl script automatically knows of two packages,
main and MY*.
--------------
Unless you declare a name as being in some other
package, a name is assumed to be in the main package:
$_ = 1;
# $_ is in main.
--------------
In general, you should not be lazy and let your names
fall in to the default main package. Instead, you should
declare variables you create as being in MY package:
my $foo = 1;
foreach my $element (@array) {
Unless you are writing a perl one liner, make sure you
declare your variables with my. Don't be lazy or you will
get in to trouble later...
--------------
Beyond main and MY, the other packages you are
most likely to use are packages written by others.
Before we look at the syntax involved, a brief digression
as a motivation for learning this package stuff:
Amazingly, a huge number of high quality packages
are available publically for free in one nice big catalog
called CPAN. Some come with perl as standard.
Others need to be pulled in from the Internet. You can
browse and search CPAN using a web browser:
http://search.cpan.org/
More on this in a footnote**.
--------------
Apart from main and MY, all other packages have to be
given a name.
In a similar fashion to use of / (or \) in directory names
on hard drives, package names often include '::' to
separate logical levels of the package name. For
example, one package on CPAN is:
File::Copy
--------------
To use another package written by someone else,
you write something like:
use File::Copy;
this makes the File::Copy namespace available.
So you can write things like:
use File::Copy;
# Invoke File::Copy's move() procedure:
File::Copy::move("file1", "file2");
This is very explicit. There is no room for ambiguity.
But it sure is long.
Fortunately, the 'use File::Copy' statement does more
than make the namespace available. It also imports
some names right in to your main package. So you
could write:
use File::Copy;
# Invoke File::Copy's move() procedure:
move("file1", "file2");
Which names get imported in to your main package
depends on a combination of what the author of the
package decides, and what options you specify
when you use the module. For example, you can say:
use File::Copy ();
and File::Copy won't import any names in to main.
--------------
If you are writing more than a one liner, you should
start your scripts with:
#!/usr/bin/perl
use warnings;
use strict;
Once this is done, if you don't say where a name is
from, perl will complain that you have not provided
an explicit package name. This is a good thing, as
it forces you to be careful, and this particular form
of care will save you countless hours of frustration.
As already stated, most of the names you come up
with will refer to things that are, well, yours, so you
typically write things like:
my $foo;
so that $foo now belongs in the MY package.
If you want to refer to something from another
package, you can either specify the longhand:
$Foo::bar = 1; # set $bar from package Foo.
or introduce a shorthand version of the name
like so:
package Foo;
our $bar = 1; # set $bar from package Foo.
our $baz = 2; # set $baz from package Foo.
$_, @_, STDIN and other standard Perl variables
are exempt from 'use strict' complaints. Indeed,
you can't my these variables even if you wanted to.
--------------
If a my or our declaration is inside braces, Perl loses
all memory of that declaration when it encounters the
enclosing end brace:
#!/usr/bin/perl;
my $foo;
{
my $bar;
# MY namespace contains the names $foo and $bar.
}
# MY namespace no longer contains the name $bar.
--------------
My/our declarations stack variables on top of each other
(and unstack too) and hide other variables with the
same name:
#!/usr/bin/perl;
$foo = 1; $bar = 1;
# main package now contains a $foo and a $bar.
my $foo = 2;
# MY package now contains a $foo.
print $foo;
# Refers to MY foo in preference to $main::foo, so prints 2.
{
my $bar = 2;
print $bar; # prints 2. Uses the MY name.
{
my $bar = 3;
print $bar; # prints 3. Uses the inner MY name.
}
print $bar; # prints 2.
}
print $bar; # prints 1.
# The above line uses the main name.
If you redeclare a my, you throw away the old value:
my $foo = 1;
my $foo;
# $foo is undefined.
--------------
You almost never need to use local. If you are allowed to
name a variable with my, then you should usually do so:
$bar = "foo";
{
my $bar; # sets MY $bar to undef.
}
print $bar; # prints "foo".
Only use local if you can't do what you want with my.
--------------
* In Perl 5, the package I call MY package is not often
called a package and can't be accessed in the same
way that other packages can be accessed. However,
in Perl 6, there will be a MY package, and, imo, it is
simpler to use the term package for all namespaces.
** To pull one of these packages in to your own program,
you first have to have installed the corresponding module.
Typically this is done using a program called cpan used
at a shell prompt (command line on Windows):
[......]$ cpan
cpan> install File::Copy
