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 the perlfunc
    manpage and the perlmod manpage.

    (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 the perlrun manpage):

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

    When a pragma is given in a `use' statement, the leading hyphen is
    removed, and the code reference corresponding to that key in `%PRAGMATA'
    is invoked with the name of the package as its argument list (this is
    the same as what happens with `import'). Additionally, any arguments
    given by the caller are included (see the section on "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 the Exporter manpage 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, @_; });

SEE ALSO
    the Exporter manpage

    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 assigned *xxx* a non-code reference.

    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) at Home <binkley@bigfoot.com>

COPYRIGHT
      Copyright 1999, B. K. Oxley.

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

