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

   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 <[email protected]>

CONTRIBUTOR
   Graham Knop <[email protected]>

COPYRIGHT AND LICENSE
   This software is Copyright (c) 2013 by Brendan Byrd.

   This is free software, licensed under:

     The Artistic License 2.0 (GPL Compatible)

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.