NAME
    Pragmatic - Adds pragmata to Exporter

SYNOPSIS
    In module MyModule.pm:

      package MyModule;
      require Pragmatic;
      @ISA = qw (Pragmatic);

      %PRAGMATA = (mypragma => sub {...});

    In other files which wish to use MyModule:

        use MyModule qw (-mypragma); # Execute pragma at import time
        use MyModule qw (-mypragma=1,2,3); # Pass pragma argument list

DESCRIPTION
    Pragmatic implements a default "import" method for processing pragmata
    before passing the rest of the import to Exporter.

    Perl automatically calls the "import" method when processing a "use"
    statement for a module. Modules and "use" are documented in perlfunc and
    perlmod.

    (Do not confuse Pragmatic with *pragmatic modules*, such as *less*,
    *strict* and the like. They are standalone pragmata, and are not
    associated with any other module.)

  Using Pragmatic Modules
    Using Pragmatic modules is very simple. To invoke any particular pragma
    for a given module, include it in the argument list to "use" preceded by
    a hyphen:

        use MyModule qw (-mypragma);

    "Pragmatic::import" will filter out these arguments, and pass the
    remainder of the argument list from the "use" statement to
    "Exporter::import" (actually, to "Exporter::export_to_level" so that
    Pragmatic is transparent).

    If you want to pass the pragma arguments, use syntax similar to that of
    the *-M* switch to perl (see perlrun):

        use MyModule qw (-mypragma=abc,1,2,3);

    If there are any warnings or fatal errors, they will appear to come from
    the "use" statement, not from "Pragmatic::import".

  Writing Pragmatic Modules
    Writing Pragmatic modules with Pragmatic is straight-forward. First,
    "require Pragmatic" (you could "use" it instead, but it exports nothing,
    so there is little to gain thereby). Declare a package global %PRAGMATA,
    the keys of which are the names of the pragmata and their corresponding
    values the code references to invoke. Like this:

        package MyPackage;

        require Pragmatic;

        use strict;
        use vars qw (%PRAGMATA);

        sub something_else { 1; }

        %PRAGMATA =
          (first => sub { print "@_: first\n"; },
           second => sub { $SOME_GLOBAL = 1; },
           third => \&something_else,
           fourth => 'name_of_sub');

    When a pragma is given in a "use" statement, the leading hyphen is
    removed, and the code reference corresponding to that key in %PRAGMATA,
    or a subroutine with the value's name, is invoked with the name of the
    package as the first member of the argument list (this is the same as
    what happens with "import"). Additionally, any arguments given by the
    caller are included (see "Using Pragmatic Modules", above).

EXAMPLES
  Using Pragmatic Modules
    1. Simple use:
          use MyModule; # no pragmas

          use MyModule qw (-abc); # invoke C<abc>

          use MyModule qw (-p1 -p2); # invoke C<p1>, then C<p2>

    2. Using an argument list:
          use MyModule qw (-abc=1,2,3); # invoke C<abc> with (1, 2, 3)

          use MyModule qw (-p1 -p2=here); # invoke C<p1>, then C<p2>
                                          # with (1, 2, 3)

    3. Mixing with arguments for Exporter:
        (Please see Exporter for a further explanatation.)

          use MyModule ( ); # no pragmas, no exports

          use MyModule qw (fun1 -abc fun2); # import C<fun1>, invoke C<abc>,
                                            # then import C<fun2>

          use MyModule qw (:set1 -abc=3); # import set C<set1>, invoke C<abc>
                                          # with (3)

  Writing Pragmatic Modules
    1. Setting a package global:
          %PRAGMATA = (debug => sub { $DEBUG = 1; });

    2. Selecting a method:
          my $fred = sub { 'fred'; };
          my $barney = sub { 'barney'; };

          %PRAGMATA =
            (fred => sub {
               local $^W = 0;
               *flintstone = $fred;
             },

             barney => sub {
               local $^W = 0;
               *flintstone = $barney;
             });

    3. Changing inheritance:
          %PRAGMATA = (super => sub { shift; push @ISA, @_; });

    4. Inheriting pragmata:
          package X;
          @ISA = qw(Pragmatic);
          %PRAGMATA = (debug => 'debug');
          $DEBUG = 0;

          sub debug { ${"$_[0]::DEBUG"} = 1; }

          package Y:
          @ISA = qw(X);
          %PRAGMATA = (debug => 'debug');
          $DEBUG = 0;

SEE ALSO
    Exporter

    Exporter does all the heavy-lifting (and is a very interesting module to
    study) after Pragmatic has stripped out the pragmata from the "use".

DIAGNOSTICS
    The following are the diagnostics generated by Pragmatic. Items marked
    "(W)" are non-fatal (invoke "Carp::carp"); those marked "(F)" are fatal
    (invoke "Carp::croak").

    No such pragma '%s'
        (F) The caller tried something like "use MyModule (-xxx)" where
        there was no pragma *xxx* defined for MyModule.

    Invalid pragma '%s'
        (F) The writer of the called package tried something like "%PRAGMATA
        = (xxx => not_a_sub)" and either assigned *xxx* a non-code
        reference, or *xxx* is not a method in that package.

    Pragma '%s' failed
        (W) The pramga returned a false value. The module is possibly in an
        inconsisten state after this. Proceed with caution.

AUTHORS
    B. K. Oxley (binkley) <binkley@alumni.rice.edu>

COPYRIGHT
      Copyright 1999-2005, B. K. Oxley.

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

THANKS
    Thanks to Kevin Caswick <KCaswick@wspackaging.com> for a great patch to
    run under Perl 5.8.