Commit | Line | Data |
---|---|---|
351625bd SP |
1 | package Pod::Simple::Debug; |
2 | use strict; | |
3afe1500 | 3 | our $VERSION = '3.45'; |
351625bd SP |
4 | |
5 | sub import { | |
6 | my($value,$variable); | |
3afe1500 | 7 | |
351625bd SP |
8 | if(@_ == 2) { |
9 | $value = $_[1]; | |
10 | } elsif(@_ == 3) { | |
11 | ($variable, $value) = @_[1,2]; | |
3afe1500 | 12 | |
351625bd SP |
13 | ($variable, $value) = ($value, $variable) |
14 | if defined $value and ref($value) eq 'SCALAR' | |
15 | and not(defined $variable and ref($variable) eq 'SCALAR') | |
16 | ; # tolerate getting it backwards | |
3afe1500 | 17 | |
351625bd SP |
18 | unless( defined $variable and ref($variable) eq 'SCALAR') { |
19 | require Carp; | |
20 | Carp::croak("Usage:\n use Pod::Simple::Debug (NUMVAL)\nor" | |
21 | . "\n use Pod::Simple::Debug (\\\$var, STARTNUMVAL)\nAborting"); | |
22 | } | |
23 | } else { | |
24 | require Carp; | |
25 | Carp::croak("Usage:\n use Pod::Simple::Debug (NUMVAL)\nor" | |
26 | . "\n use Pod::Simple::Debug (\\\$var, STARTNUMVAL)\nAborting"); | |
27 | } | |
28 | ||
29 | if( defined &Pod::Simple::DEBUG ) { | |
30 | require Carp; | |
31 | Carp::croak("It's too late to call Pod::Simple::Debug -- " | |
32 | . "Pod::Simple has already loaded\nAborting"); | |
33 | } | |
3afe1500 | 34 | |
351625bd SP |
35 | $value = 0 unless defined $value; |
36 | ||
37 | unless($value =~ m/^-?\d+$/) { | |
38 | require Carp; | |
39 | Carp::croak( "$value isn't a numeric value." | |
40 | . "\nUsage:\n use Pod::Simple::Debug (NUMVAL)\nor" | |
41 | . "\n use Pod::Simple::Debug (\\\$var, STARTNUMVAL)\nAborting"); | |
42 | } | |
43 | ||
44 | if( defined $variable ) { | |
45 | # make a not-really-constant | |
46 | *Pod::Simple::DEBUG = sub () { $$variable } ; | |
47 | $$variable = $value; | |
a4a12576 | 48 | print STDERR "# Starting Pod::Simple::DEBUG = non-constant $variable with val $value\n"; |
351625bd SP |
49 | } else { |
50 | *Pod::Simple::DEBUG = eval " sub () { $value } "; | |
a4a12576 | 51 | print STDERR "# Starting Pod::Simple::DEBUG = $value\n"; |
351625bd | 52 | } |
3afe1500 | 53 | |
351625bd SP |
54 | require Pod::Simple; |
55 | return; | |
56 | } | |
57 | ||
58 | 1; | |
59 | ||
60 | ||
61 | __END__ | |
62 | ||
63 | =head1 NAME | |
64 | ||
65 | Pod::Simple::Debug -- put Pod::Simple into trace/debug mode | |
66 | ||
67 | =head1 SYNOPSIS | |
68 | ||
69 | use Pod::Simple::Debug (5); # or some integer | |
70 | ||
71 | Or: | |
72 | ||
73 | my $debuglevel; | |
74 | use Pod::Simple::Debug (\$debuglevel, 0); | |
75 | ...some stuff that uses Pod::Simple to do stuff, but which | |
76 | you don't want debug output from... | |
77 | ||
78 | $debug_level = 4; | |
79 | ...some stuff that uses Pod::Simple to do stuff, but which | |
80 | you DO want debug output from... | |
81 | ||
82 | $debug_level = 0; | |
83 | ||
84 | =head1 DESCRIPTION | |
85 | ||
86 | This is an internal module for controlling the debug level (a.k.a. trace | |
87 | level) of Pod::Simple. This is of interest only to Pod::Simple | |
88 | developers. | |
89 | ||
90 | ||
91 | =head1 CAVEATS | |
92 | ||
93 | Note that you should load this module I<before> loading Pod::Simple (or | |
94 | any Pod::Simple-based class). If you try loading Pod::Simple::Debug | |
95 | after &Pod::Simple::DEBUG is already defined, Pod::Simple::Debug will | |
96 | throw a fatal error to the effect that | |
f23676cb | 97 | "It's too late to call Pod::Simple::Debug". |
351625bd SP |
98 | |
99 | Note that the C<use Pod::Simple::Debug (\$x, I<somenum>)> mode will make | |
100 | Pod::Simple (et al) run rather slower, since &Pod::Simple::DEBUG won't | |
101 | be a constant sub anymore, and so Pod::Simple (et al) won't compile with | |
102 | constant-folding. | |
103 | ||
104 | ||
105 | =head1 GUTS | |
106 | ||
107 | Doing this: | |
108 | ||
109 | use Pod::Simple::Debug (5); # or some integer | |
110 | ||
111 | is basically equivalent to: | |
112 | ||
113 | BEGIN { sub Pod::Simple::DEBUG () {5} } # or some integer | |
114 | use Pod::Simple (); | |
115 | ||
116 | And this: | |
117 | ||
118 | use Pod::Simple::Debug (\$debug_level,0); # or some integer | |
119 | ||
120 | is basically equivalent to this: | |
121 | ||
122 | my $debug_level; | |
123 | BEGIN { $debug_level = 0 } | |
124 | BEGIN { sub Pod::Simple::DEBUG () { $debug_level } | |
125 | use Pod::Simple (); | |
126 | ||
127 | =head1 SEE ALSO | |
128 | ||
129 | L<Pod::Simple> | |
130 | ||
131 | The article "Constants in Perl", in I<The Perl Journal> issue | |
9d65762f | 132 | 21. See L<http://interglacial.com/tpj/21/> |
351625bd | 133 | |
a242eeb4 JV |
134 | =head1 SUPPORT |
135 | ||
136 | Questions or discussion about POD and Pod::Simple should be sent to the | |
137 | pod-people@perl.org mail list. Send an empty email to | |
138 | pod-people-subscribe@perl.org to subscribe. | |
139 | ||
140 | This module is managed in an open GitHub repository, | |
a4a12576 | 141 | L<https://github.com/perl-pod/pod-simple/>. Feel free to fork and contribute, or |
3afe1500 | 142 | to clone L<https://github.com/perl-pod/pod-simple.git> and send patches! |
a242eeb4 JV |
143 | |
144 | Patches against Pod::Simple are welcome. Please send bug reports to | |
145 | <bug-pod-simple@rt.cpan.org>. | |
146 | ||
351625bd SP |
147 | =head1 COPYRIGHT AND DISCLAIMERS |
148 | ||
433cf6b4 | 149 | Copyright (c) 2002 Sean M. Burke. |
351625bd SP |
150 | |
151 | This library is free software; you can redistribute it and/or modify it | |
152 | under the same terms as Perl itself. | |
153 | ||
154 | This program is distributed in the hope that it will be useful, but | |
155 | without any warranty; without even the implied warranty of | |
156 | merchantability or fitness for a particular purpose. | |
157 | ||
158 | =head1 AUTHOR | |
159 | ||
a242eeb4 JV |
160 | Pod::Simple was created by Sean M. Burke <sburke@cpan.org>. |
161 | But don't bother him, he's retired. | |
351625bd | 162 | |
a242eeb4 JV |
163 | Pod::Simple is maintained by: |
164 | ||
165 | =over | |
351625bd | 166 | |
a242eeb4 JV |
167 | =item * Allison Randal C<allison@perl.org> |
168 | ||
169 | =item * Hans Dieter Pearcey C<hdp@cpan.org> | |
170 | ||
171 | =item * David E. Wheeler C<dwheeler@cpan.org> | |
172 | ||
173 | =back | |
174 | ||
175 | =cut | |
3afe1500 | 176 | use warnings; |