NAME
    Perl500503Syntax::OrDie - Validate that source code is compatible with
    Perl 5.005_03

VERSION
    0.01

SYNOPSIS
        # Place at the top of any script you wish to guard:
        use Perl500503Syntax::OrDie;

        # The rest of the script is validated automatically.
        use strict;
        use vars qw($x);
        $x = 42;
        open(FH, ">output.txt") or die $!;   # OK: 2-argument form
        print FH "$x\n";
        close FH;
        mkdir("newdir", 0755);               # OK: explicit mode

        # Programmatic API:
        use Perl500503Syntax::OrDie ();
        my @violations = Perl500503Syntax::OrDie::check_source($source_text, 'label.pl');
        Perl500503Syntax::OrDie::check_file('/path/to/script.pl');

        # Command-line (stdin supported):
        perl lib/Perl500503Syntax/OrDie.pm script.pl
        perl lib/Perl500503Syntax/OrDie.pm script1.pl script2.pl ...
        perl lib/Perl500503Syntax/OrDie.pm -

DESCRIPTION
    Perl500503Syntax::OrDie helps authors who target Perl 5.005_03
    compatibility detect incompatible constructs before deploying code
    to legacy systems.

    When loaded with "use Perl500503Syntax::OrDie;", the module:

    1. Uses caller() to locate the calling source file.
    2. Reads that file and runs a two-stage scan:
       Stage 1: masked source (comments and string/regex literals
                replaced with X, preserving newlines) scanned against
                @BLACKLIST.
       Stage 2: content of each regex literal (m//, s///, qr//, //)
                scanned against @REGEX_BLACKLIST (constructs only
                meaningful inside a regex pattern).
    3. Dies with file name and line number on any violation.
    4. Installs CORE::GLOBAL:: overrides that enforce correct runtime
       behaviour for open() and mkdir().

    String and regex contents are intentionally not inspected: a string
    literal may contain any text (including keywords such as "say" or
    format flags such as "%v") without triggering a violation, because
    those are runtime values, not syntax constructs.

    No source-filter infrastructure (Filter::Util::Call, etc.) is
    required or used.  The module itself runs on every Perl from
    5.005_03 through the current release.

PROGRAMMATIC API
    check_source($source, $label)
        Scans $source (a string) and returns a list of violation strings.
        Returns an empty list when no violations are found.  Does NOT die
        automatically; the caller decides what to do with the list.

            my @v = Perl500503Syntax::OrDie::check_source($src, 'foo.pl');
            if (@v) { warn $_ for @v }

    check_file($path)
        Reads $path and calls check_source.  Dies with the violation list
        if any violations are found; returns normally otherwise.

CHECKED CONSTRUCTS
  Static (compile-time)
    Perl 5.6
      our $var / our @arr / our %hash      (use "use vars" instead)
      open(FH, MODE, PATH)                 3-argument form
      use utf8
      use VERSION  where VERSION >= 5.6
      use vVERSION where VERSION >= v5.6
      \x{HHHH}                             Unicode hex escape
      \N{name}                             Named character escape
      @+ / @-  and  $+[N] / $-[N]         Match-position arrays
      CHECK { } / INIT { }                 Phase blocks
      v1.2.3                               v-string notation
      $^V                                  Version object (use $] instead)
      sub foo :lvalue { }                  :lvalue attribute
      *name{SLOT}                          Typeglob component access
      \p{} / \P{}                          Unicode property in regex

    Perl 5.8
      use encoding
      use constant { A => 1, B => 2 }      Multi-constant hashref form

    Perl 5.10
      //=                                  Defined-or assignment
      //                                   Defined-or operator (standalone)
      say                                  (->say() method calls excluded)
      state $var
      given(...) / when(...)
      ~~                                   Smart-match
      use feature
      \K                                   Keep in regex
      (?<name>...) / \k<name>              Named capture/backreference
      (?|...)                              Branch reset group
      (*VERB)                              Backtrack control verb
      \h \H \v \V \R                       Whitespace escapes in regex
      UNITCHECK { }                        Phase block
      a++ / a*+ / a?+                      Possessive quantifiers
      (?1) / (?&name) / (?R)               Recursive patterns
      ${^MATCH} ${^PREMATCH} ${^POSTMATCH} Match variables (with /p)
      \g{N}                                Relative/absolute backreference

    Perl 5.12
      package NAME VERSION
      ...                                  Yada-yada operator

    Perl 5.14
      s///r  tr///r                        Non-destructive flag

    Perl 5.16
      __SUB__

    Perl 5.18
      my sub foo { }                       Lexical subroutine declaration
      state sub foo { }

    Perl 5.20
      sub foo ($x, $y) { }                 Subroutine signatures
      $ref->@*  $ref->%*                   Postfix dereference
      %hash{LIST}  %array[LIST]            Key/value (index/value) slices

    Perl 5.22
      <<>>                                 Double-diamond operator
      /n                                   Non-capturing regex flag
      $a &. $b  $a |. $b  $a ^. $b  ~.$a  String bitwise operators
      foreach \$x (@list)                  Reference aliasing in foreach

    Perl 5.26
      <<~                                  Indented heredoc

    Perl 5.30
      (?<=.{2,}X)                          Variable-length lookbehind

    Perl 5.32
      $obj isa ClassName                   isa infix operator
                                           (->isa() and isa() calls excluded)

    Perl 5.34
      try { } catch ($e) { }

    Perl 5.36
      use builtin
      for my ($a, $b) (@list)              Paired iteration

    Perl 5.38
      class Foo { }                        class keyword
      Variable-length lookbehind (stable)

    Perl 5.40
      $x ^^ $y  /  $x ^^= $y              High-precedence logical XOR
      __CLASS__

    Perl 5.42
      any { EXPR } @list                   Keyword operators
      all { EXPR } @list                   (suppressed when List::Util
                                            imports any/all)
      my method foo () { }                 Lexical method declaration
      $obj->&foo()                         Lexical method call

  Runtime (via CORE::GLOBAL:: overrides)
    open(FH, MODE, PATH)                   3-argument open
    open(FH, \$ref)                        Reference-as-mode open
    mkdir(PATH)                            mkdir without explicit mode

DOCUMENTATION
    Multilingual cheatsheets are provided in the doc/ directory:

        doc/Perl500503Syntax-OrDie_cheatsheet.EN.txt  (English)
        doc/Perl500503Syntax-OrDie_cheatsheet.JA.txt  (Japanese)
        doc/Perl500503Syntax-OrDie_cheatsheet.ZH.txt  (Chinese)
        doc/Perl500503Syntax-OrDie_cheatsheet.KO.txt  (Korean)
        doc/Perl500503Syntax-OrDie_cheatsheet.FR.txt  (French)
        doc/Perl500503Syntax-OrDie_cheatsheet.DE.txt  (German)
        doc/Perl500503Syntax-OrDie_cheatsheet.ES.txt  (Spanish)
        doc/Perl500503Syntax-OrDie_cheatsheet.IT.txt  (Italian)
        doc/Perl500503Syntax-OrDie_cheatsheet.PT.txt  (Portuguese)
        doc/Perl500503Syntax-OrDie_cheatsheet.RU.txt  (Russian)
        doc/Perl500503Syntax-OrDie_cheatsheet.AR.txt  (Arabic)
        doc/Perl500503Syntax-OrDie_cheatsheet.HI.txt  (Hindi)
        doc/Perl500503Syntax-OrDie_cheatsheet.NL.txt  (Dutch)
        doc/Perl500503Syntax-OrDie_cheatsheet.PL.txt  (Polish)
        doc/Perl500503Syntax-OrDie_cheatsheet.SV.txt  (Swedish)
        doc/Perl500503Syntax-OrDie_cheatsheet.TR.txt  (Turkish)
        doc/Perl500503Syntax-OrDie_cheatsheet.VI.txt  (Vietnamese)
        doc/Perl500503Syntax-OrDie_cheatsheet.ID.txt  (Indonesian)
        doc/Perl500503Syntax-OrDie_cheatsheet.TH.txt  (Thai)
        doc/Perl500503Syntax-OrDie_cheatsheet.UK.txt  (Ukrainian)
        doc/Perl500503Syntax-OrDie_cheatsheet.CS.txt  (Czech)
        doc/perldelta_summary.txt  (perldelta feature summary with URLs)

INSTALL
    perl Makefile.PL
    make
    make test
    make install

DEPENDENCIES
    No non-core dependencies.  Perl 5.005_03 or later.

AUTHOR
    INABA Hitoshi <ina@cpan.org>

LICENSE
    This library is free software; you may redistribute it and/or
    modify it under the same terms as Perl itself.
