.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Pragmatic 3pm"
.TH Pragmatic 3pm "2018-04-07" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Pragmatic \- Adds pragmata to Exporter
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
In module MyModule.pm:
.PP
.Vb 3
\&  package MyModule;
\&  require Pragmatic;
\&  @ISA = qw (Pragmatic);
\&
\&  %PRAGMATA = (mypragma => sub {...});
.Ve
.PP
In other files which wish to use MyModule:
.PP
.Vb 2
\&    use MyModule qw (\-mypragma); # Execute pragma at import time
\&    use MyModule qw (\-mypragma=1,2,3); # Pass pragma argument list
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBPragmatic\fR implements a default \f(CW\*(C`import\*(C'\fR method for processing
pragmata before passing the rest of the import to \fBExporter\fR.
.PP
Perl automatically calls the \f(CW\*(C`import\*(C'\fR method when processing a
\&\f(CW\*(C`use\*(C'\fR statement for a module. Modules and \f(CW\*(C`use\*(C'\fR are documented
in perlfunc and perlmod.
.PP
(Do not confuse \fBPragmatic\fR with \fIpragmatic modules\fR, such as
\&\fIless\fR, \fIstrict\fR and the like.  They are standalone pragmata, and
are not associated with any other module.)
.SS "Using Pragmatic Modules"
.IX Subsection "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 \f(CW\*(C`use\*(C'\fR preceded by a hyphen:
.PP
.Vb 1
\&    use MyModule qw (\-mypragma);
.Ve
.PP
\&\f(CW\*(C`Pragmatic::import\*(C'\fR will filter out these arguments, and pass the
remainder of the argument list from the \f(CW\*(C`use\*(C'\fR statement to
\&\f(CW\*(C`Exporter::import\*(C'\fR (actually, to \f(CW\*(C`Exporter::export_to_level\*(C'\fR so that
\&\fBPragmatic\fR is transparent).
.PP
If you want to pass the pragma arguments, use syntax similar to that
of the \fI\-M\fR switch to \fBperl\fR (see perlrun):
.PP
.Vb 1
\&    use MyModule qw (\-mypragma=abc,1,2,3);
.Ve
.PP
If there are any warnings or fatal errors, they will appear to come
from the \f(CW\*(C`use\*(C'\fR statement, not from \f(CW\*(C`Pragmatic::import\*(C'\fR.
.SS "Writing Pragmatic Modules"
.IX Subsection "Writing Pragmatic Modules"
Writing Pragmatic modules with \fBPragmatic\fR is straight-forward.
First, \f(CW\*(C`require Pragmatic\*(C'\fR (you could \f(CW\*(C`use\*(C'\fR it instead, but it
exports nothing, so there is little to gain thereby).  Declare a
package global \f(CW%PRAGMATA\fR, the keys of which are the names of the
pragmata and their corresponding values the code references to invoke.
Like this:
.PP
.Vb 1
\&    package MyPackage;
\&
\&    require Pragmatic;
\&
\&    use strict;
\&    use vars qw (%PRAGMATA);
\&
\&    sub something_else { 1; }
\&
\&    %PRAGMATA =
\&      (first => sub { print "@_: first\en"; },
\&       second => sub { $SOME_GLOBAL = 1; },
\&       third => \e&something_else,
\&       fourth => \*(Aqname_of_sub\*(Aq);
.Ve
.PP
When a pragma is given in a \f(CW\*(C`use\*(C'\fR statement, the leading hyphen is
removed, and the code reference corresponding to that key in
\&\f(CW%PRAGMATA\fR, 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 \f(CW\*(C`import\*(C'\fR).  Additionally, any
arguments given by the caller are included (see \*(L"Using Pragmatic
Modules\*(R", above).
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Using Pragmatic Modules"
.IX Subsection "Using Pragmatic Modules"
.IP "1. Simple use:" 4
.IX Item "1. Simple use:"
.Vb 1
\&  use MyModule; # no pragmas
\&
\&  use MyModule qw (\-abc); # invoke C<abc>
\&
\&  use MyModule qw (\-p1 \-p2); # invoke C<p1>, then C<p2>
.Ve
.IP "2. Using an argument list:" 4
.IX Item "2. Using an argument list:"
.Vb 1
\&  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)
.Ve
.IP "3. Mixing with arguments for \fBExporter\fR:" 4
.IX Item "3. Mixing with arguments for Exporter:"
(Please see Exporter for a further explanatation.)
.Sp
.Vb 1
\&  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)
.Ve
.SS "Writing Pragmatic Modules"
.IX Subsection "Writing Pragmatic Modules"
.IP "1. Setting a package global:" 4
.IX Item "1. Setting a package global:"
.Vb 1
\&  %PRAGMATA = (debug => sub { $DEBUG = 1; });
.Ve
.IP "2. Selecting a method:" 4
.IX Item "2. Selecting a method:"
.Vb 2
\&  my $fred = sub { \*(Aqfred\*(Aq; };
\&  my $barney = sub { \*(Aqbarney\*(Aq; };
\&
\&  %PRAGMATA =
\&    (fred => sub {
\&       local $^W = 0;
\&       *flintstone = $fred;
\&     },
\&
\&     barney => sub {
\&       local $^W = 0;
\&       *flintstone = $barney;
\&     });
.Ve
.IP "3. Changing inheritance:" 4
.IX Item "3. Changing inheritance:"
.Vb 1
\&  %PRAGMATA = (super => sub { shift; push @ISA, @_; });
.Ve
.IP "4. Inheriting pragmata:" 4
.IX Item "4. Inheriting pragmata:"
.Vb 4
\&  package X;
\&  @ISA = qw(Pragmatic);
\&  %PRAGMATA = (debug => \*(Aqdebug\*(Aq);
\&  $DEBUG = 0;
\&
\&  sub debug { ${"$_[0]::DEBUG"} = 1; }
\&
\&  package Y:
\&  @ISA = qw(X);
\&  %PRAGMATA = (debug => \*(Aqdebug\*(Aq);
\&  $DEBUG = 0;
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Exporter
.PP
\&\fBExporter\fR does all the heavy-lifting (and is a very interesting
module to study) after \fBPragmatic\fR has stripped out the pragmata from
the \f(CW\*(C`use\*(C'\fR.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
The following are the diagnostics generated by \fBPragmatic\fR.  Items
marked \*(L"(W)\*(R" are non-fatal (invoke \f(CW\*(C`Carp::carp\*(C'\fR); those marked \*(L"(F)\*(R"
are fatal (invoke \f(CW\*(C`Carp::croak\*(C'\fR).
.IP "No such pragma '%s'" 4
.IX Item "No such pragma '%s'"
(F) The caller tried something like \*(L"use MyModule (\-xxx)\*(R" where there
was no pragma \fIxxx\fR defined for MyModule.
.IP "Invalid pragma '%s'" 4
.IX Item "Invalid pragma '%s'"
(F) The writer of the called package tried something like \*(L"%PRAGMATA =
(xxx => not_a_sub)\*(R" and either assigned \fIxxx\fR a non-code reference,
or \fIxxx\fR is not a method in that package.
.IP "Pragma '%s' failed" 4
.IX Item "Pragma '%s' failed"
(W) The pramga returned a false value.  The module is possibly in an
inconsisten state after this.  Proceed with caution.
.SH "AUTHORS"
.IX Header "AUTHORS"
B. K. Oxley (binkley) <binkley@alumni.rice.edu>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
.Vb 1
\&  Copyright 1999\-2005, B. K. Oxley.
.Ve
.PP
This library is free software; you may redistribute it and/or modify
it under the same terms as Perl itself.
.SH "THANKS"
.IX Header "THANKS"
Thanks to Kevin Caswick <KCaswick@wspackaging.com> for a great
patch to run under Perl 5.8.