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,
           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 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, @_; });

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

