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.