I tend to start my modules in exactly the same way as my scripts:

#! perl -slw
use strict;
package fred;
...
[download]

But that's because I often end my modules with:

return 1 if caller;
package main;
fred->import;

## code that tests the package above goes here.
[download]

In this way, running the module as a perl fred.pm runs the test.

This keeps the tests with the tested code, ensures it is kept up to date with that code and acts as documentation for its use. To my mind, this is a 3 way win.

If the -l switch is not lexically scoped (I don't think it could be), then print statements will behave differently when running testing than when run as a module, if the consumer using your code isn’t using such a switch.

then print statements will behave differently when running testing than when run as a module, if the consumer using your code isn’t using such a switch.

Only if the module uses print. And I consider this to be exactly as I want it.

If modules want to use $\, or any other global variable, then they *must* localise and set it. The main program *always* own the globals. So if modules want predictable behaviour from their use of globals, they must localise and set to their requirements.

If my modules need to print to a predefined (global) filehandle, and I want $\ = "\n", then I will localise and set it so either on a case by case basis, or more likely, for (say) debug purposes, I define a private debug function that does so and call that rather than print.

But, most modules don't print directly to STDOUT or STDERR. We'd mostly be pissed off if they did.

Test scripts frequently do print stuff, and when the module is run as a script for testing, the -l is in force.

As for -s, I frequently use runtime configuration in my test scripts like our $MAX //= 1e6;. Then if I want to run a quick test, I can use

perl fred.pm -MAX=1e3
[download]

Silly eg:

#! perl -slw
use strict;

package fred;

sub new {
    my $class = shift;
   return bless { @_ }, $class;
}

sub method {
    my $self = shift;
    return keys %{ $self };
}

return 1 if caller;
package main;

our $MAX //= 10;
print 'Max: ', $MAX;

my $o = fred->new( 'a' .. 'z' );

print for $o->method;

__END__
C:\test>perl -s fred.pm -MAX=123
Max: 123
w
e
a
m
s
y
u
c
k
q
g
i
o
[download]

---

Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.

"Science is about questioning the status quo. Questioning authority".

In the absence of evidence, opinion is indistinguishable from prejudice.

It is very important that package be the first non-comment token in a module.

Because?

use Module;
use warnings;
[download]

use warnings;
use Module;
[download]

So, putting use warnings as far down as possible (after the module includes) can enable the most warnings?

But Moose and 5.12 both enable warnings so we don't need to say it again... maybe that's not strictly true? Checking perldelta, it says 5.12 turns on strict. But I thought Moose and various "modern" boilerplates turn on warnings, and would do so fairly early.

It would be more awkward to have multiple packages defined in one file, if they used different modules and thus had different custom warnings available to them, since warnings pragma isn't scoped to the package. Normally I would not have multiple packages except for one-offs or an internal object that's very simple, but needs to be blessed.

So, putting use warnings as far down as possible (after the module includes) can enable the most warnings?

Yes. I was bitten by this recently, but now I'm struggling to find an example of where it matters.

But Moose and 5.12 both enable warnings

Neither use 5.12;, nor use 5.14; (5.14 is scheduled to be released today) enable warnings. Some people have proposed that use 5.16; enables warnings.

Question: does no Moose; turn off warnings?

But Moose and 5.12 both enable warnings

No, 5.12 most assuredly does not. I guarantee this.

And that Moose continues to do so is a design flaw so serious that it really cannot be considered anything less than a genuine bug.

Modules that act like Acme:: modules without being in that namespace are a problem.

I treat the use strict; and use warnings; declarations as a way to document the beginning of the actual code. I therefore put them immediately after all my other use statements and obviously after the package statement as well.

use MyTest qw(mysub);

use strict;
use warnings;

my $foo = 'bar';

mysub($foo);
[download]

This serves no purpose. The code would work the same if the strictures requirement was placed sooner.

I believe sometimes people put them later because they are lazy about their @EXPORT declarations, and don't always use our.

order of strict and package

Wow, ten years later and I'm still looking for an answer.

I think you should put the package declaration on the first non comment line of the file, and before any use statements. Two reasons:

Firstly if you use a modlue that exports symbols into the caller's namespace, then those symbols will only visable in the package that used the module. eg:

package foo;

use File::Copy;

# Code here.

package bar;

# Won't work, as File::Copy was not used in this package.
copy('source','dest');
[download]

If you put the use line before the package line, then you are importing into the default package (main), if you then change packages then your imports will not be visable.

I don't know if the situation is different with pragmas such as strict, but I would say it is a poor habit to get into.

Secondly, in the Perl 6 specification it says in Synopsis 10: Packages that:

As a special exception, if a braceless package declaration occurs as the first executable statement in a file, then it's taken to mean that the rest of the file is Perl 5 code.

In other words, If you write your perl 5 packages and classes so that the package statement comes first, the they are less likey to break when run by a perl 6 aware interpreter.

Firstly if you use a modlue that exports symbols into the caller's namespace, then those symbols will only visable in the package that used the module.

Eh, no.

Global symbols, whether exported or not, are just that. Global. Visible from everywhere. Sure, if you import something in package A, then switch to package B, you may need to use a fully qualified name, but both the exported and imported name are visible.

use File::Copy;
package Foo;
::copy($from, $to);   # Not a problem.
[download]

Believing that the package statement should come first is equivalent of saying no meaningful code can be written that has more than one package statement in a file.

CPAN begs to differ.

I would think that if the package line itself used syntax that did not work in older perls, then the use or feature would certainly have to come first!

package NAMESPACE VERSION;

And that’s not all. You can also do this:

package NAMESPACE BLOCK

package NAMESPACE VERSION BLOCK

I'm putting

use 5.10.1;
use utf8;
[download]

as the very first things. I'm not afraid of very old perls not liking the dotted syntax since the installer already checked the version once. I agree, this documents the version I wrote it under and tested it under, and can ensure some backward compatibility if even newer ones changed things.

The meaning of utf8 in modern versions is simply to state that the source file is UTF-8. That really really affects the entire file, not a block, not a package.

Based on what I learned on this thread, I'll put other stuff after the module's package line. I'm trying autodie for example, and I had supposed that to be more global and not per-package, but it was on your list.

As for the referenced ranteditorial concerning warnings in production servers, I think that ought to be fixed once and for all in the logging system. Just piping stderr to a file and archiving that file is rather brute simple. I've worked on systems where logging was more engineered. At the very least it has quotas with purging so it won't fill up the disk!

My current semi-working boilerplate for new programs tends to look like this:

#!/usr/bin/env perl

use 5.012;  # want unicode strings!
use utf8;
use strict;
use autodie;
use warnings;  # defer FATAL till runtime 
use open        qw< :std  :utf8   >;
use charnames   qw< :full >;

use File::Basename      qw< basename >;
use Carp                qw< carp croak confess cluck >;

$0 = basename($0);  # shorter messages
$| = 1; 
binmode(DATA, ":utf8");

# give a full stack dump on any untrapped exceptions
$SIG{__DIE__} = sub {
    confess "Uncaught exception: $@" unless $^S;
};

# now promote run-time warnings into stackdumped exceptions
#   *unless* we're in an try block, in which 
#   case just generate a clucking stackdump instead
$SIG{__WARN__} = sub {
    if ($^S) { cluck   "Trapped warning: @_" } 
    else     { confess "Deadly warning: @_"  }
};
[download]

But that suffers form a couple of bugs. There is a bug in the implementation of autodie that screws up the layers imposed by use open. Witness:

% perl -e 'use open qw(:std :utf8); open(F, ">/tmp/out"); print F "\xD
+F"'; wc /tmp/out
       0       1       2 /tmp/out
% perl -e 'use autodie; use open qw(:std :utf8); open(F, ">/tmp/out");
+ print F "\xDF"' ; wc /tmp/out
       0       1       1 /tmp/out
% perl -e ' use open qw(:std :utf8); use autodie; open(F, ">/tmp/out")
+; print F "\xDF"' ; wc /tmp/out
       0       1       1 /tmp/out
[download]

The other problem is that use utf8 doesn’t really work well on globals, because there are issues with how the package symbol tables are accessed as byte strings. There is also an issue of what to do about something like:

use Weather::El_Niño;

That has to map to the filesystem, and now what do you do? Just use the bytes as they are? Normalize to UTF‑8? Downgrade to Latin1 (which it might have already been)? Did you know that (for very good reasons) the Darwin HSF+ filesystem always converts filenames into NFD, their canonically decomposed form? So be careful when checking filenames!! You can’t just say:

@files = grep { /Niñ/ } glob("{El,La}_*");

Because if you input it in the normal way, your pattern is going to have a U+00F1 LATIN SMALL LETTER N WITH TILDE there (which is the NFC form) but the results from the filesystem will have an "n" followed by U+0303 COMBINING TILDE (the NFD version), which is suddenly two separate code points, not one.

There is a Google Summer of Code project for cleaning up Perl’s tokenizer vis‐à‐vis 8‑bit names, including for UTF‑8. I am convinced that this can and shall be fixed.

---

I see my stalker is back. Yawn!

it does make some sense to put a use 5.014 before that [the package line] in your code.

Now you see, that is rational thinking. I knew you were capable of it.

It does make sense to use some pragmas before the package statement in a module.

They may be few and far between, and require you to test that the positioning works as you'd want and expect it to, but such pragmas do exist.

And strict is one of them. Chosen through a process of applied rationality, in direct contrast with blanket imposition of dogma every bit as bad as that which you (rightly) rail against.

---

Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.

"Science is about questioning the status quo. Questioning authority".

In the absence of evidence, opinion is indistinguishable from prejudice.