Commit | Line | Data |
1a24938d |
1 | package SQL::Translator::Utils; |
2 | |
3 | # ---------------------------------------------------------------------- |
a2ba36ba |
4 | # $Id: Utils.pm,v 1.3 2003-04-25 11:44:20 dlc Exp $ |
1a24938d |
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); |
a2ba36ba |
25 | use vars qw($VERSION $DEFAULT_COMMENT @EXPORT_OK); |
1a24938d |
26 | |
27 | use Exporter; |
28 | |
29 | $VERSION = 1.00; |
a2ba36ba |
30 | $DEFAULT_COMMENT = '-- '; |
31 | @EXPORT_OK = qw(debug normalize_name header_comment $DEFAULT_COMMENT); |
1a24938d |
32 | |
33 | # ---------------------------------------------------------------------- |
34 | # debug(@msg) |
35 | # |
36 | # Will send debugging messages to STDERR, if the caller's $DEBUG global |
37 | # is set. |
38 | # |
39 | # This debug() function has a neat feature: Occurances of the strings |
40 | # PKG, LINE, and SUB in each message will be replaced with elements |
41 | # from caller(): |
42 | # |
43 | # debug("PKG: Bad things happened on line LINE!"); |
44 | # |
45 | # Will be warned as: |
46 | # |
47 | # [SQL::Translator: Bad things happened on line 643] |
48 | # |
49 | # If called from Translator.pm, on line 643. |
50 | # ---------------------------------------------------------------------- |
51 | sub debug { |
a2ba36ba |
52 | my ($pkg, $file, $line, $sub) = caller(0); |
1a24938d |
53 | { |
54 | no strict qw(refs); |
55 | return unless ${"$pkg\::DEBUG"}; |
56 | } |
57 | |
58 | $sub =~ s/^$pkg\:://; |
59 | |
60 | while (@_) { |
61 | my $x = shift; |
62 | chomp $x; |
63 | $x =~ s/\bPKG\b/$pkg/g; |
64 | $x =~ s/\bLINE\b/$line/g; |
65 | $x =~ s/\bSUB\b/$sub/g; |
66 | #warn '[' . $x . "]\n"; |
67 | print STDERR '[' . $x . "]\n"; |
68 | } |
69 | } |
70 | |
93d12e9c |
71 | |
72 | sub normalize_name { |
73 | my $name = shift; |
74 | |
75 | # The name can only begin with a-zA-Z_; if there's anything |
76 | # else, prefix with _ |
77 | $name =~ s/^([^a-zA-Z_])/_$1/; |
78 | |
79 | # anything other than a-zA-Z0-9_ in the non-first position |
80 | # needs to be turned into _ |
81 | $name =~ tr/[a-zA-Z0-9_]/_/c; |
82 | |
83 | # All duplicated _ need to be squashed into one. |
84 | $name =~ tr/_/_/s; |
85 | |
86 | # Trim a trailing _ |
87 | $name =~ s/_$//; |
88 | |
89 | return $name; |
90 | } |
91 | |
a2ba36ba |
92 | sub header_comment { |
93 | my $producer = shift || caller; |
94 | my $comment_char = shift; |
95 | my $now = scalar localtime; |
96 | |
97 | $comment_char = $DEFAULT_COMMENT |
98 | unless defined $comment_char; |
99 | |
100 | my $header_comment =<<"HEADER_COMMENT"; |
101 | ${comment_char} |
102 | ${comment_char}Created by $producer |
103 | ${comment_char}Created on $now |
104 | ${comment_char} |
105 | HEADER_COMMENT |
106 | |
107 | # Any additional stuff passed in |
108 | for my $additional_comment (@_) { |
109 | $header_comment .= "${comment_char}${additional_comment}\n"; |
110 | } |
111 | |
112 | return $header_comment; |
113 | } |
114 | |
1a24938d |
115 | 1; |
116 | |
117 | __END__ |
118 | |
119 | =head1 NAME |
120 | |
121 | SQL::Translator::Utils - SQL::Translator Utility functions |
122 | |
123 | =head1 SYNOPSIS |
124 | |
125 | use SQL::Translator::Utils qw(debug); |
126 | debug("PKG: Bad things happened"); |
127 | |
128 | =head1 DESCSIPTION |
129 | |
130 | C<SQL::Translator::Utils> contains utility functions designed to be |
131 | used from the other modules within the C<SQL::Translator> modules. |
132 | |
a2ba36ba |
133 | Nothing is exported by default. |
1a24938d |
134 | |
a2ba36ba |
135 | =head1 EXPORTED FUNCTIONS AND CONSTANTS |
1a24938d |
136 | |
137 | =head2 debug |
138 | |
139 | C<debug> takes 0 or more messages, which will be sent to STDERR using |
140 | C<warn>. Occurances of the strings I<PKG>, I<SUB>, and I<LINE> |
141 | will be replaced by the calling package, subroutine, and line number, |
142 | respectively, as reported by C<caller(1)>. |
143 | |
144 | For example, from within C<foo> in F<SQL/Translator.pm>, at line 666: |
145 | |
146 | debug("PKG: Error reading file at SUB/LINE"); |
147 | |
148 | Will warn |
149 | |
150 | [SQL::Translator: Error reading file at foo/666] |
151 | |
152 | The entire message is enclosed within C<[> and C<]> for visual clarity |
153 | when STDERR is intermixed with STDOUT. |
93d12e9c |
154 | |
155 | =head2 normalize_name |
156 | |
157 | C<normalize_name> takes a string and ensures that it is suitable for |
158 | use as an identifier. This means: ensure that it starts with a letter |
159 | or underscore, and that the rest of the string consists of only |
160 | letters, numbers, and underscores. A string that begins with |
161 | something other than [a-zA-Z] will be prefixer with an underscore, and |
162 | all other characters in the string will be replaced with underscores. |
163 | Finally, a trailing underscore will be removed, because that's ugly. |
164 | |
165 | normalize_name("Hello, world"); |
166 | |
167 | Produces: |
168 | |
169 | Hello_world |
170 | |
171 | A more useful example, from the C<SQL::Translator::Parser::Excel> test |
172 | suite: |
173 | |
174 | normalize_name("silly field (with random characters)"); |
175 | |
176 | returns: |
177 | |
178 | silly_field_with_random_characters |
179 | |
a2ba36ba |
180 | =head2 header_comment |
181 | |
182 | Create the header comment. Takes 1 mandatory argument (the producer |
183 | classname), an optional comment character (defaults to $DEFAULT_COMMENT), |
184 | and 0 or more additional comments, which will be appended to the header, |
185 | prefixed with the comment character. If additional comments are provided, |
186 | then a comment string must be provided ($DEFAULT_COMMENT is exported for |
187 | this use). For example, this: |
188 | |
189 | package My::Producer; |
190 | |
191 | use SQL::Translator::Utils qw(header_comment $DEFAULT_COMMENT); |
192 | |
193 | print header_comment(__PACKAGE__, |
194 | $DEFAULT_COMMENT, |
195 | "Hi mom!"); |
196 | |
197 | produces: |
198 | |
199 | -- |
200 | -- Created by My::Prodcuer |
201 | -- Created on Fri Apr 25 06:56:02 2003 |
202 | -- |
203 | -- Hi mom! |
204 | -- |
205 | |
206 | Note the gratuitous spacing. |
207 | |
208 | =head2 $DEFAULT_COMMENT |
209 | |
210 | This is the default comment string, '-- ' by default. Useful for |
211 | C<header_comment>. |
212 | |