The package declaration should always match the name of the file that contains
it. For example, package Foo::Bar; should be in a file called Bar.pm.
This makes it easier for developers to figure out which file a symbol comes
from when they see it in your code. For instance, when you see Foo::Bar->new(), you should be able to find the class definition for a
Foo::Bar in a file called Bar.pm
Therefore, this Policy requires the last component of the first package name
declared in the file to match the physical filename. Or if #line
directives are used, then it must match the logical filename defined by the
prevailing #line directive at the point of the package declaration. Here
are some examples:
# Any of the following in file "Foo/Bar/Baz.pm":
package Foo::Bar::Baz; # ok
package Baz; # ok
package Nuts; # not ok (doesnt match physical filename)
# using #line directives in file "Foo/Bar/Baz.pm":
#line 1 Nuts.pm
package Nuts; # ok
package Baz; # not ok (contradicts #line directive)
If the file is not deemed to be a module, then this Policy does not apply.
Also, if the first package namespace found in the file is main then this
Policy does not apply.