Commit | Line | Data |
1a24938d |
1 | package SQL::Translator::Utils; |
2 | |
3 | # ---------------------------------------------------------------------- |
4 | # $Id: Utils.pm,v 1.1 2003-03-12 14:17:11 dlc Exp $ |
5 | # ---------------------------------------------------------------------- |
6 | # Copyright (C) 2003 darren chamberlain <darren@cpan.org> |
7 | # |
8 | # This program is free software; you can redistribute it and/or |
9 | # modify it under the terms of the GNU General Public License as |
10 | # published by the Free Software Foundation; version 2. |
11 | # |
12 | # This program is distributed in the hope that it will be useful, but |
13 | # WITHOUT ANY WARRANTY; without even the implied warranty of |
14 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
15 | # General Public License for more details. |
16 | # |
17 | # You should have received a copy of the GNU General Public License |
18 | # along with this program; if not, write to the Free Software |
19 | # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA |
20 | # 02111-1307 USA |
21 | # ------------------------------------------------------------------- |
22 | |
23 | use strict; |
24 | use base qw(Exporter); |
25 | use vars qw($VERSION @EXPORT_OK); |
26 | |
27 | use Exporter; |
28 | |
29 | $VERSION = 1.00; |
30 | @EXPORT_OK = ('debug'); |
31 | |
32 | # ---------------------------------------------------------------------- |
33 | # debug(@msg) |
34 | # |
35 | # Will send debugging messages to STDERR, if the caller's $DEBUG global |
36 | # is set. |
37 | # |
38 | # This debug() function has a neat feature: Occurances of the strings |
39 | # PKG, LINE, and SUB in each message will be replaced with elements |
40 | # from caller(): |
41 | # |
42 | # debug("PKG: Bad things happened on line LINE!"); |
43 | # |
44 | # Will be warned as: |
45 | # |
46 | # [SQL::Translator: Bad things happened on line 643] |
47 | # |
48 | # If called from Translator.pm, on line 643. |
49 | # ---------------------------------------------------------------------- |
50 | sub debug { |
51 | my ($pkg, $file, $line, $sub) = caller(1); |
52 | { |
53 | no strict qw(refs); |
54 | return unless ${"$pkg\::DEBUG"}; |
55 | } |
56 | |
57 | $sub =~ s/^$pkg\:://; |
58 | |
59 | while (@_) { |
60 | my $x = shift; |
61 | chomp $x; |
62 | $x =~ s/\bPKG\b/$pkg/g; |
63 | $x =~ s/\bLINE\b/$line/g; |
64 | $x =~ s/\bSUB\b/$sub/g; |
65 | #warn '[' . $x . "]\n"; |
66 | print STDERR '[' . $x . "]\n"; |
67 | } |
68 | } |
69 | |
70 | 1; |
71 | |
72 | __END__ |
73 | |
74 | =head1 NAME |
75 | |
76 | SQL::Translator::Utils - SQL::Translator Utility functions |
77 | |
78 | =head1 SYNOPSIS |
79 | |
80 | use SQL::Translator::Utils qw(debug); |
81 | debug("PKG: Bad things happened"); |
82 | |
83 | =head1 DESCSIPTION |
84 | |
85 | C<SQL::Translator::Utils> contains utility functions designed to be |
86 | used from the other modules within the C<SQL::Translator> modules. |
87 | |
88 | No functions are exported by default. |
89 | |
90 | =head1 EXPORTED FUNCTIONS |
91 | |
92 | =head2 debug |
93 | |
94 | C<debug> takes 0 or more messages, which will be sent to STDERR using |
95 | C<warn>. Occurances of the strings I<PKG>, I<SUB>, and I<LINE> |
96 | will be replaced by the calling package, subroutine, and line number, |
97 | respectively, as reported by C<caller(1)>. |
98 | |
99 | For example, from within C<foo> in F<SQL/Translator.pm>, at line 666: |
100 | |
101 | debug("PKG: Error reading file at SUB/LINE"); |
102 | |
103 | Will warn |
104 | |
105 | [SQL::Translator: Error reading file at foo/666] |
106 | |
107 | The entire message is enclosed within C<[> and C<]> for visual clarity |
108 | when STDERR is intermixed with STDOUT. |