README
1NAME
2 Pragmatic - Adds pragmata to Exporter
3
4SYNOPSIS
5 In module MyModule.pm:
6
7 package MyModule;
8 require Pragmatic;
9 @ISA = qw (Pragmatic);
10
11 %PRAGMATA = (mypragma => sub {...});
12
13 In other files which wish to use MyModule:
14
15 use MyModule qw (-mypragma); # Execute pragma at import time
16 use MyModule qw (-mypragma=1,2,3); # Pass pragma argument list
17
18DESCRIPTION
19 Pragmatic implements a default "import" method for processing pragmata
20 before passing the rest of the import to Exporter.
21
22 Perl automatically calls the "import" method when processing a "use"
23 statement for a module. Modules and "use" are documented in perlfunc and
24 perlmod.
25
26 (Do not confuse Pragmatic with *pragmatic modules*, such as *less*,
27 *strict* and the like. They are standalone pragmata, and are not
28 associated with any other module.)
29
30 Using Pragmatic Modules
31 Using Pragmatic modules is very simple. To invoke any particular pragma
32 for a given module, include it in the argument list to "use" preceded by
33 a hyphen:
34
35 use MyModule qw (-mypragma);
36
37 "Pragmatic::import" will filter out these arguments, and pass the
38 remainder of the argument list from the "use" statement to
39 "Exporter::import" (actually, to "Exporter::export_to_level" so that
40 Pragmatic is transparent).
41
42 If you want to pass the pragma arguments, use syntax similar to that of
43 the *-M* switch to perl (see perlrun):
44
45 use MyModule qw (-mypragma=abc,1,2,3);
46
47 If there are any warnings or fatal errors, they will appear to come from
48 the "use" statement, not from "Pragmatic::import".
49
50 Writing Pragmatic Modules
51 Writing Pragmatic modules with Pragmatic is straight-forward. First,
52 "require Pragmatic" (you could "use" it instead, but it exports nothing,
53 so there is little to gain thereby). Declare a package global %PRAGMATA,
54 the keys of which are the names of the pragmata and their corresponding
55 values the code references to invoke. Like this:
56
57 package MyPackage;
58
59 require Pragmatic;
60
61 use strict;
62 use vars qw (%PRAGMATA);
63
64 sub something_else { 1; }
65
66 %PRAGMATA =
67 (first => sub { print "@_: first\n"; },
68 second => sub { $SOME_GLOBAL = 1; },
69 third => \&something_else,
70 fourth => 'name_of_sub');
71
72 When a pragma is given in a "use" statement, the leading hyphen is
73 removed, and the code reference corresponding to that key in %PRAGMATA,
74 or a subroutine with the value's name, is invoked with the name of the
75 package as the first member of the argument list (this is the same as
76 what happens with "import"). Additionally, any arguments given by the
77 caller are included (see "Using Pragmatic Modules", above).
78
79EXAMPLES
80 Using Pragmatic Modules
81 1. Simple use:
82 use MyModule; # no pragmas
83
84 use MyModule qw (-abc); # invoke C<abc>
85
86 use MyModule qw (-p1 -p2); # invoke C<p1>, then C<p2>
87
88 2. Using an argument list:
89 use MyModule qw (-abc=1,2,3); # invoke C<abc> with (1, 2, 3)
90
91 use MyModule qw (-p1 -p2=here); # invoke C<p1>, then C<p2>
92 # with (1, 2, 3)
93
94 3. Mixing with arguments for Exporter:
95 (Please see Exporter for a further explanatation.)
96
97 use MyModule ( ); # no pragmas, no exports
98
99 use MyModule qw (fun1 -abc fun2); # import C<fun1>, invoke C<abc>,
100 # then import C<fun2>
101
102 use MyModule qw (:set1 -abc=3); # import set C<set1>, invoke C<abc>
103 # with (3)
104
105 Writing Pragmatic Modules
106 1. Setting a package global:
107 %PRAGMATA = (debug => sub { $DEBUG = 1; });
108
109 2. Selecting a method:
110 my $fred = sub { 'fred'; };
111 my $barney = sub { 'barney'; };
112
113 %PRAGMATA =
114 (fred => sub {
115 local $^W = 0;
116 *flintstone = $fred;
117 },
118
119 barney => sub {
120 local $^W = 0;
121 *flintstone = $barney;
122 });
123
124 3. Changing inheritance:
125 %PRAGMATA = (super => sub { shift; push @ISA, @_; });
126
127 4. Inheriting pragmata:
128 package X;
129 @ISA = qw(Pragmatic);
130 %PRAGMATA = (debug => 'debug');
131 $DEBUG = 0;
132
133 sub debug { ${"$_[0]::DEBUG"} = 1; }
134
135 package Y:
136 @ISA = qw(X);
137 %PRAGMATA = (debug => 'debug');
138 $DEBUG = 0;
139
140SEE ALSO
141 Exporter
142
143 Exporter does all the heavy-lifting (and is a very interesting module to
144 study) after Pragmatic has stripped out the pragmata from the "use".
145
146DIAGNOSTICS
147 The following are the diagnostics generated by Pragmatic. Items marked
148 "(W)" are non-fatal (invoke "Carp::carp"); those marked "(F)" are fatal
149 (invoke "Carp::croak").
150
151 No such pragma '%s'
152 (F) The caller tried something like "use MyModule (-xxx)" where
153 there was no pragma *xxx* defined for MyModule.
154
155 Invalid pragma '%s'
156 (F) The writer of the called package tried something like "%PRAGMATA
157 = (xxx => not_a_sub)" and either assigned *xxx* a non-code
158 reference, or *xxx* is not a method in that package.
159
160 Pragma '%s' failed
161 (W) The pramga returned a false value. The module is possibly in an
162 inconsisten state after this. Proceed with caution.
163
164AUTHORS
165 B. K. Oxley (binkley) <binkley@alumni.rice.edu>
166
167COPYRIGHT
168 Copyright 1999-2005, B. K. Oxley.
169
170 This library is free software; you may redistribute it and/or modify it
171 under the same terms as Perl itself.
172
173THANKS
174 Thanks to Kevin Caswick <KCaswick@wspackaging.com> for a great patch to
175 run under Perl 5.8.
176
177