perlmod - Perl modules (packages and symbol tables)
There are other documents which might contain the information that you're looking for:
Perl's packages, namespaces, and some info on classes.
Tutorial on making a new module.
Best practices for making a new module.
Unlike Perl 4, in which all the variables were dynamic and shared one global name space, causing maintainability problems, Perl 5 provides two mechanisms for protecting code from having its variables stomped on by other code: lexically scoped variables created with my or state and namespaced global variables, which are exposed via the vars pragma, or the our keyword. Any global variable is considered to be part of a namespace and can be accessed via a "fully qualified form". Conversely, any lexically scoped variable is considered to be part of that lexical-scope, and does not have a "fully qualified form".
In perl namespaces are called "packages" and the package declaration tells the compiler which namespace to prefix to our variables and unqualified dynamic names. This both protects against accidental stomping and provides an interface for deliberately clobbering global dynamic variables declared and used in other scopes or packages, when that is what you want to do.
The scope of the package declaration is from the declaration itself through the end of the enclosing block, eval, or file, whichever comes first (the same scope as the my(), our(), state(), and local() operators, and also the effect of the experimental "reference aliasing," which may change), or until the next package declaration. Unqualified dynamic identifiers will be in this namespace, except for those few identifiers that, if unqualified, default to the main package instead of the current one as described below. A package statement affects only dynamic global symbols, including subroutine names, and variables you've used local() on, but not lexical variables created with my(), our() or state().
Typically, a package statement is the first declaration in a file included in a program by one of the do, require, or use operators. You can switch into a package in more than one place: package has no effect beyond specifying which symbol table the compiler will use for dynamic symbols for the rest of that block or until the next package statement. You can refer to variables and filehandles in other packages by prefixing the identifier with the package name and a double colon: $Package::Variable. If the package name is null, the main package is assumed. That is, $::sail is equivalent to $main::sail.
The old package delimiter was a single quote, but double colon is now the preferred delimiter, in part because it's more readable to humans, and in part because it's more readable to emacs macros. It also makes C++ programmers feel like they know what's going on--as opposed to using the single quote as separator, which was there to make Ada programmers feel like they knew what was going on. Because the old-fashioned syntax is still supported for backwards compatibility, if you try to use a string like "This is $owner's house", you'll be accessing $owner::s; that is, the $s variable in package owner, which is probably not what you meant. Use braces to disambiguate, as in "This is ${owner}'s house".
Use of ' as a package delimiter can be disabled with:
no feature 'apostrophe_as_package_separator';and is also disabled by use v5.42; or later.
Packages may themselves contain package separators, as in $OUTER::INNER::var. This implies nothing about the order of name lookups, however. There are no relative packages: all symbols are either local to the current package, or must be fully qualified from the outer package name down. For instance, there is nowhere within package OUTER that $INNER::var refers to $OUTER::INNER::var. INNER refers to a totally separate global package. The custom of treating package names as a hierarchy is very strong, but the language in no way enforces it.
Only identifiers starting with letters (or underscore) are stored in a package's symbol table. All other symbols are kept in package main, including all punctuation variables, like $_. In addition, when unqualified, the identifiers STDIN, STDOUT, STDERR, ARGV, ARGVOUT, ENV, INC, and SIG are forced to be in package main, even when used for other purposes than their built-in ones. If you have a package called m, s, or y, then you can't use the qualified form of an identifier because it would be instead interpreted as a pattern match, a substitution, or a transliteration.
Variables beginning with underscore used to be forced into package main, but we decided it was more useful for package writers to be able to use leading underscore to indicate private variables and method names. However, variables and functions named with a single _, such as $_ and sub _, are still forced into the package main. See also "The Syntax of Variable Names" in perlvar.
evaled strings are compiled in the package in which the eval() was compiled. (Assignments to $SIG{}, however, assume the signal handler specified is in the main package. Qualify the signal handler name if you wish to have a signal handler in a package.) For an example, examine perldb.pl in the Perl library. It initially switches to the DB package so that the debugger doesn't interfere with variables in the program you are trying to debug. At various points, however, it temporarily switches back to the main package to evaluate various expressions in the context of the main package (or wherever you came from). See perldebug.
The special symbol __PACKAGE__ contains the current package, but cannot (easily) be used to construct variable names. After my($foo) has hidden package variable $foo, it can still be accessed, without knowing what package you are in, as ${__PACKAGE__.'::foo'}.
See perlsub for other scoping issues related to my() and local(), and perlref regarding closures.