view release on metacpan or  search on metacpan

lib/sanity.pm  view on Meta::CPAN

sanity - The ONLY meta pragma you'll ever need!

=head1 SYNOPSIS

   use sanity;
   use sanity 'strictures';
   use sanity 'Modern::Perl';

   use sanity qw(
      strictures -warnings/uninitialized/FATAL
      NO:autovivification NO:autovivification/store
      PRINT_PRAGMA_HASH
   );
   use sanity '!0*b^Npow{8T7_yZt<?cT6/?ZCO=Y0LV_Duoc';  # Safer ASCII version
   use sanity '¡0Dz鵆㤧뱞⡫瘑빸ን둈댬嚝⠨舁聼䮋';  # Shorter UTF8 version

=head1 DESCRIPTION

Modern::Perl?  common::sense?  no nonsense?  use latest?

Everybody has their own opinion on what pragmas and modules are "required"
for every person to use.  These opinions turn into "personal pragmas", so that
people don't have to type several C<use> lines of header in front of every module
they write.

Personal opinions and pragmas don't really belong in the CPAN namespace.  (It's
CPAN, not Personal PAN.  If you want a Personal PAN, go call Pizza Hut.)  But
copying code on potentially hundreds of modules doesn't make sense, either.

That was my mentality when I had a personal opinion of my own.  Why repeat the same
problem like everybody else?

This "sanity" module attempts to level the playing field by making it a
B<customizable> personal pragma, allowing you to both reduce the code needed and
still implement all of the modules/pragmas you need.

As an illustration to what it's capable of, this pragma will emulate all of the
other personal pragmas, most of them 100% working exactly how they do it.

=head1 PARAMETERS

Sanity's parameters fall into three types: flags, aliases, and hashes.  (Oh my!)

=head2 Flags and Aliases

Flags are single pragma/module declarations, strict/warning flags, or other
items that need flags.  Aliases are merely one or more flags, grouped
together to better emulate the pragma/module's functionality.

Let's start off with an example:

   # These three statements do the same thing as...
   use Modern::Perl;
   use sanity 'Modern::Perl';
   use sanity qw(strict warnings mro/dfs feature IO::File IO::Handle);

   # ...these statements
   use strict;
   use warnings;
   use mro 'dfs';
   use feature ':all';
   use IO::File;
   use IO::Handle;

Basically, it does the same thing as the meta pragma L<Modern::Perl>, except
you actually don't need that module for it to work.  While there is some magic
to make sure, say, C<feature> gets loaded with various versions of Perl, it typically
just works using a standard C<import> call.  The C<strict> and C<warnings> flags
are combined aliases that enable all of the warnings that they would do via a standard
call.

=head3 Negating flags/aliases

You can turn off flags in the statement:

   use sanity qw(Modern::Perl -mro/dfs);

This does the same thing as above, except it doesn't import the C<mro> pragma.  You
can negate any flag, including combined aliases, as long as it makes sense.  In other
words, you need a positive included before you can negate something.

=head3 NO:* flags/aliases

Some pragmas work by using the C<B<unimport>> function, so that the English makes sense.
To keep that syntax, these pragmas are included with a C<NO:> prefix:

   use sanity 'NO:multidimensional';
   use sanity 'NO:indirect/FATAL';

This will run the C<unimport> function on these pragmas, even though sanity was called
via the C<import> function (via C<use>).

=head3 Perl versions

Sanity also supports Perl versions as a special kind of alias to specify minimum Perl
versions:

   # These are all the same:
   use v5.10.1;
   use sanity 'v5.10.1';
   use sanity v5.10.1;  # as a VSTRING
   use sanity 5.10.1;   # works too

   # Upgrade the Perl version of your favorite pragma
   use sanity qw(NO:nonsense v5.12);

Note that the version must be at least v5.8.  This should be fine for most people.  (If
I get a ticket requesting support for a Perl version older than one released in 2002, I
will hunt you down and break your keyboard in half.)

=head3 The Default

What does C<sanity> do without any parameters?  Why my personal preference, of course :)
It's listed in the C<meta pragma> section of the L<LIST OF FLAGS> below.  I detail the
reasons behind my choices L<here|sanity::sanity>.

=head2 Hashes

So, there's all of these flags, but unless you're using one of the combined aliases,
typing them all out is usually just as much (or more) code as the several lines of C<use>
statements.  Well, they are all flags so that it fits into a giant bitmap, and that