1package Pod::Simple::Debug;
2use strict;
3our $VERSION = '3.45';
4
5sub import {
6  my($value,$variable);
7
8  if(@_ == 2) {
9    $value = $_[1];
10  } elsif(@_ == 3) {
11    ($variable, $value) = @_[1,2];
12
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
17
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  }
34
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;
48    print STDERR "# Starting Pod::Simple::DEBUG = non-constant $variable with val $value\n";
49  } else {
50    *Pod::Simple::DEBUG = eval " sub () { $value } ";
51    print STDERR "# Starting Pod::Simple::DEBUG = $value\n";
52  }
53
54  require Pod::Simple;
55  return;
56}
57
581;
59
60
61__END__
62
63=head1 NAME
64
65Pod::Simple::Debug -- put Pod::Simple into trace/debug mode
66
67=head1 SYNOPSIS
68
69 use Pod::Simple::Debug (5);  # or some integer
70
71Or:
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
86This is an internal module for controlling the debug level (a.k.a. trace
87level) of Pod::Simple.  This is of interest only to Pod::Simple
88developers.
89
90
91=head1 CAVEATS
92
93Note that you should load this module I<before> loading Pod::Simple (or
94any Pod::Simple-based class).  If you try loading Pod::Simple::Debug
95after &Pod::Simple::DEBUG is already defined, Pod::Simple::Debug will
96throw a fatal error to the effect that
97"It's too late to call Pod::Simple::Debug".
98
99Note that the C<use Pod::Simple::Debug (\$x, I<somenum>)> mode will make
100Pod::Simple (et al) run rather slower, since &Pod::Simple::DEBUG won't
101be a constant sub anymore, and so Pod::Simple (et al) won't compile with
102constant-folding.
103
104
105=head1 GUTS
106
107Doing this:
108
109  use Pod::Simple::Debug (5);  # or some integer
110
111is basically equivalent to:
112
113  BEGIN { sub Pod::Simple::DEBUG () {5} }  # or some integer
114  use Pod::Simple ();
115
116And this:
117
118  use Pod::Simple::Debug (\$debug_level,0);  # or some integer
119
120is 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
129L<Pod::Simple>
130
131The article "Constants in Perl", in I<The Perl Journal> issue
13221.  See L<http://interglacial.com/tpj/21/>
133
134=head1 SUPPORT
135
136Questions or discussion about POD and Pod::Simple should be sent to the
137pod-people@perl.org mail list. Send an empty email to
138pod-people-subscribe@perl.org to subscribe.
139
140This module is managed in an open GitHub repository,
141L<https://github.com/perl-pod/pod-simple/>. Feel free to fork and contribute, or
142to clone L<https://github.com/perl-pod/pod-simple.git> and send patches!
143
144Patches against Pod::Simple are welcome. Please send bug reports to
145<bug-pod-simple@rt.cpan.org>.
146
147=head1 COPYRIGHT AND DISCLAIMERS
148
149Copyright (c) 2002 Sean M. Burke.
150
151This library is free software; you can redistribute it and/or modify it
152under the same terms as Perl itself.
153
154This program is distributed in the hope that it will be useful, but
155without any warranty; without even the implied warranty of
156merchantability or fitness for a particular purpose.
157
158=head1 AUTHOR
159
160Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.
161But don't bother him, he's retired.
162
163Pod::Simple is maintained by:
164
165=over
166
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
176use warnings;
177