NAME

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

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

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 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
    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.

PARAMETERS

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

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

  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 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.

  NO:* flags/aliases

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

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

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

  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.)

  The Default

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

 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 use statements. Well, they are all flags
    so that it fits into a giant bitmap, and that bitmap can be compressed
    into a large ASCII (or UTF-8) "number".

    This number can be calculated using the flag PRINT_PRAGMA_HASH:

       # This is merely the definition of uni::perl
       use sanity (qw(
          v5.10 strict feature/5.10
       ), (
          map { "warnings/$_/FATAL" } qw(closed threads internal debugging pack substr malloc
          unopened portable prototype inplace io pipe unpack regexp deprecated exiting glob
          digit printf utf8 layer reserved parenthesis taint closure semicolon)
       ), qw(
          -warnings/exec/FATAL
          -warnings/newline/FATAL
          utf8
          open/utf8
          open/std
          mro/c3
          Carp
       ), 'PRINT_PRAGMA_HASH');
    
       # Outputs:
       # use sanity '!04[D{9Fhfqc-7m738S4HK6B#D5=v{,T$(0)F5i';  # Safer ASCII version
       # use sanity '¡05༕ቑ釩腜쥸봱楇䐍퇥熠ᾯ緻褻真堩';  # Shorter UTF8 version

    You can use that hash as the output illustrates without having to type
    out the entire big set of commands or flags.

 Other Meta Pragmas

    Have your own set that is too long, and you don't like the ugliness of
    the hash? Send me your suggestion and I'll probably add it in.

CAVEATS

 'NO:' ne '-'

    A NO: flag is NOT the same as negating a flag! You also cannot remove
    the NO: from a flag, as it's part of the name of the flag, not a
    special modifier.

       # These two are NOT the same!
       use sanity 'NO:indirect';  # runs indirect->unimport()
       use sanity '-indirect';    # Dies, as there is no such flag/alias
    
       # This runs through the strictures alias and runs autovivification->unimport()
       use sanity qw(strictures NO:autovivification);
    
       # This runs through the strictures alias WITHOUT running indirect->unimport()
       use sanity qw(strictures -NO:indirect);
    
       use sanity '-indirect';    # This isn't what you want...
       no  sanity 'NO:indirect';  # ...you really meant to do this...
       use indirect;              # ...but this is better

 Special clearing of strict/warnings

    Since most people want exactly the strictness and warnings they
    specify, sanity will clear these out first before running through the
    list.

       # This...
       use sanity qw(strict -strict/vars);
    
       # ...is the same as this...
       no strict;
       use strict qw(subs refs);

    Also, some special magic is in place to ensure that newer
    warnings/features aren't fatal to older Perls. See
    https://rt.perl.org/rt3/Ticket/Display.html?id=112920.

 "Author" pragmas

    Certain pragmas really only exist to make sure the code is designed
    right. These pragmas are deemed "optional" by sanity. In other words,
    if the user doesn't have them, it will just silently ignore them and
    move on. If sanity thinks you're an author/coder of the module itself
    (.git/svn/$ENV checks), it will give you a warning that they are
    missing, but move on.

    The following modules don't "instadie". Modules that fall under this
    list don't change the nature of how Perl works, or would let you do
    something that would normally fatally error.

       overloading
       autovivification
       indirect
       multidimensional
       bareword::filehandles
       criticism
    
       # (autovivification probably shouldn't be here, since it actually
       # prevents autoviv, but it's generally used as an author tool.)

    This feature was borrowed from strictures and tweaked.

LIST OF FLAGS

 Emulation of "meta pragmas"

       ex::caution:
          strict
          warnings
       NO:crap:  # Same as above
       shit:     # Same as above
       latest:
          strict
          warnings
          feature
       sane:
          strict
          warnings
          feature
          utf8
       NO:nonsense:
          strict
          warnings
          true
          namespace::autoclean
       Modern::Perl:
          strict
          warnings
          mro 'dfs'
          feature
          IO::File
          IO::Handle
       strictures: (without the 5.8.4 checks; that crap is old)
          v5.8.4 (forced, to make sure things work)
          strict
          warnings FATAL => 'all'
          no indirect 'fatal'
          no multidimensional
          no bareword::filehandles
       common::sense: (without the "memory usage" BS)
          utf8
          strict qw(subs vars)
          feature qw(say state switch)
          no warnings
          warnings FATAL => qw(closed threads internal debugging pack malloc portable prototype
                               inplace io pipe unpack deprecated glob digit printf
                               layer reserved taint closure semicolon)
          no warnings qw(exec newline unopened);
       uni::perl: (ditto)
          v5.10
          strict
          feature qw(say state switch)
          no warnings
          warnings qw(FATAL closed threads internal debugging pack substr malloc
                          unopened portable prototype inplace io pipe unpack regexp
                          deprecated exiting glob digit printf utf8 layer
                          reserved parenthesis taint closure semicolon)
          no warnings qw(exec newline)
          utf8
          open (:utf8 :std)
          mro 'c3'
          Carp
       sanity:
          v5.10.1
          utf8
          open (:utf8 :std)
          mro 'c3'
          strict qw(subs vars)
          no strict 'refs'
          warnings FATAL => 'all'
          no warnings qw(uninitialized experimental::smartmatch)
          feature '5.10'
          no autovivification qw(fetch exists delete store strict)
          no indirect 'fatal'
          no multidimensional
       perl5i::0 / 1 / 2 / latest:
          [the real module] (the pragma is too insane to try to duplicate here)
       Acme::Very::Modern::Perl:  (a joke, but it's still here all the same)
          strict
          warnings
          mro 'c3'
          feature
          IO::File
          IO::Handle
          utf8
          open (:utf8 :std)
          no warnings
          warnings FATAL => qw(closed threads internal debugging pack malloc portable prototype
                               inplace io pipe unpack deprecated glob digit printf
                               layer reserved taint closure semicolon)
          no warnings qw(exec newline unopened);
          perl5i::latest
          Toolkit
          Carp

 Other flags/aliases

       strict/* => strict '[whatever]'        # supports all flags
       strict   => strict qw(refs subs vars)
    
       # other "hints"
       integer
       locale
       bytes
       re/taint
       re/eval
       filetest
       utf8
       NO:overloading
    
       warnings/*       => warnings NONFATAL => '[whatever]'  # supports all flags, multi or not
       warnings/*/FATAL => warnings    FATAL => '[whatever]'  # supports all flags; FATAL trumps NONFATAL
       warnings         => warnings NONFATAL => 'all'
       warnings/FATAL   => warnings    FATAL => 'all'
    
       feature/*        => feature '[whatever]'  # supports all flags
       feature/5.##     => # similar to feature enabling via 'use v5.##'; major version only
       feature/5.9.5    => # also exists, just like feature/5.10
       feature          => feature ':all'  # not exactly, but in spirit
    
       # Perl versions, described above
       v5.##.##
    
       # autodie
       autodie/* => autodie ':[whatever]'  # supports all _category_ flags, like all, io, shm, etc.
                                           # (Will expand if requested, but I don't want to waste
                                           # all of that bit space right now.)
       autodie   => autodie ':default'
    
       # other CORE pragmas
       bigint
       bignum
       bigrat
       charnames
       charnames/short
       charnames/full
       encoding::warnings
       encoding::warnings/FATAL
       mro/dfs                    # default for 'mro'
       mro/c3
       open/*
    
       # namespace cleaners
       namespace::clean       # included last; adds -except => 'meta'
       namespace::functions   # included last
       namespace::autoclean
       namespace::sweep
    
       # others
       NO:autovivification/*
       NO:autovivification => no autovivification qw(fetch exists delete)
    
       criticism/*
       criticism   => criticism 'gentle'
    
       experimental/*
    
       perl5i::0
       perl5i::1
       perl5i::2
       perl5i::3
       perl5i::latest
    
       NO:indirect
       NO:indirect/global
       NO:indirect/fatal
       NO:multidimensional
       NO:bareword::filehandles
    
       subs::auto
       utf8::all
       IO::File
       IO::Handle
       IO::All
       Carp
       vendorlib
       true
       autolocale
       Toolkit
    
       Function::Parameters
       Function::Parameters/strict
       Switch::Plain
       Quote::Code

    Am I missing something? Let me know.

TODO

    Actually need to write sanity::sanity POD.

AVAILABILITY

    The project homepage is https://github.com/SineSwiper/sanity.

    The latest version of this module is available from the Comprehensive
    Perl Archive Network (CPAN). Visit http://www.perl.com/CPAN/ to find a
    CPAN site near you, or see https://metacpan.org/module/sanity/.

SUPPORT

 Internet Relay Chat

    You can get live help by using IRC ( Internet Relay Chat ). If you
    don't know what IRC is, please read this excellent guide:
    http://en.wikipedia.org/wiki/Internet_Relay_Chat. Please be courteous
    and patient when talking to us, as we might be busy or sleeping! You
    can join those networks/channels and get help:

      * irc.perl.org

      You can connect to the server at 'irc.perl.org' and talk to this
      person for help: SineSwiper.

 Bugs / Feature Requests

    Please report any bugs or feature requests via
    https://github.com/SineSwiper/sanity/issues.

AUTHOR

    Brendan Byrd <BBYRD@CPAN.org>

CONTRIBUTOR

    Graham Knop <haarg@haarg.org>

COPYRIGHT AND LICENSE

    This software is Copyright (c) 2014 by Brendan Byrd.

    This is free software, licensed under:

      The Artistic License 2.0 (GPL Compatible)