add 5.20 warning categories

[p5sagit/strictures.git] / lib / strictures.pm

diff --git a/lib/strictures.pm b/lib/strictures.pm
index 85ea622..01ccd8c 100644 (file)
--- a/lib/strictures.pm
+++ b/lib/strictures.pm
@@ -15,9 +15,12 @@ our @WARNING_CATEGORIES = grep { exists $warnings::Offsets{$_} } qw(
   deprecated
   exiting
   experimental
+    experimental::autoderef
     experimental::lexical_subs
     experimental::lexical_topic
+    experimental::postderef
     experimental::regex_sets
+    experimental::signatures
     experimental::smartmatch
   glob
   imprecision
@@ -27,6 +30,7 @@ our @WARNING_CATEGORIES = grep { exists $warnings::Offsets{$_} } qw(
     layer
     newline
     pipe
+    syscalls
     unopened
   misc
   numeric
@@ -125,18 +129,18 @@ sub _enable_1 {
   }
 }
 
-our @V2_NONFATAL = grep { exists $warnings::Offsets{$_} } qw(
-  exec
-  recursion
-  internal
-  malloc
-  newline
-  experimental
-  deprecated
-  portable
+our @V2_NONFATAL = grep { exists $warnings::Offsets{$_} } (
+  'exec',         # not safe to catch
+  'recursion',    # will be caught by other mechanisms
+  'internal',     # not safe to catch
+  'malloc',       # not safe to catch
+  'newline',      # stat on nonexistent file with a newline in it
+  'experimental', # no reason for these to be fatal
+  'deprecated',   # unfortunately can't make these fatal
+  'portable',     # everything worked fine here, just may not elsewhere
 );
-our @V2_DISABLE = grep { exists $warnings::Offsets{$_} } qw(
-  once
+our @V2_DISABLE = grep { exists $warnings::Offsets{$_} } (
+  'once'          # triggers inconsistently, can't be fatalized
 );
 
 sub _enable_2 {
@@ -229,12 +233,23 @@ strictures - turn on strict and make all warnings fatal
 
 =head1 SYNOPSIS
 
-  use strictures 1;
+  use strictures 2;
 
 is equivalent to
 
   use strict;
   use warnings FATAL => 'all';
+  use warnings NONFATAL => qw(
+    exec
+    recursion
+    internal
+    malloc
+    newline
+    experimental
+    deprecated
+    portable
+  );
+  no warnings 'once';
 
 except when called from a file which matches:
 
@@ -247,12 +262,23 @@ C<dist.ini> (which would indicate we are in a C<dzil test> operation, via
 L<Dist::Zilla>) -- or when the C<PERL_STRICTURES_EXTRA> environment variable is
 set, in which case
 
-  use strictures 1;
+  use strictures 2;
 
 is equivalent to
 
   use strict;
   use warnings FATAL => 'all';
+  use warnings NONFATAL => qw(
+    exec
+    recursion
+    internal
+    malloc
+    newline
+    experimental
+    deprecated
+    portable
+  );
+  no warnings 'once';
   no indirect 'fatal';
   no multidimensional;
   no bareword::filehandles;
@@ -295,20 +321,47 @@ increase (e.g. 1.000000 to 1.001000 (1.1.0) or similar). Any fixes only to the
 mechanism of this code will result in a sub-version increase (e.g. 1.000000 to
 1.000001 (1.0.1)).
 
-If the behaviour of C<use strictures> in normal mode changes in any way, that
-will constitute a major version increase -- and the code already checks
-when its version is tested to ensure that
+=head1 VERSIONS
+
+Depending on the version of strictures requested, different warnings will be
+enabled.  If no specific version is requested, the current version's behavior
+will be used.  Versions can be requested using perl's standard mechanism:
+
+  use strictures 2;
 
-  use strictures 1;
+Or, by passing in a C<version> option:
 
-will continue to only introduce the current set of strictures even if 2.0 is
-installed.
+  use strictures version => 2;
+
+=head2 VERSION 2
+
+Equivalent to:
+
+  use strict;
+  use warnings FATAL => 'all';
+  use warnings NONFATAL => 'deprecated', 'experimental';
+  # and if in dev mode:
+  no indirect 'fatal';
+  no multidimensional;
+  no bareword::filehandles;
+
+=head2 VERSION 1
+
+Equivalent to:
+
+  use strict;
+  use warnings FATAL => 'all';
+  # and if in dev mode:
+  no indirect 'fatal';
+  no multidimensional;
+  no bareword::filehandles;
 
 =head1 METHODS
 
 =head2 import
 
-This method does the setup work described above in L</DESCRIPTION>
+This method does the setup work described above in L</DESCRIPTION>.  Optionally
+accepts a C<version> option to request a specific version's behavior.
 
 =head2 VERSION