Commit | Line | Data |
1a24938d |
1 | package SQL::Translator::Utils; |
2 | |
3 | # ---------------------------------------------------------------------- |
977651a5 |
4 | # $Id: Utils.pm,v 1.12 2004-02-09 23:04:26 kycl4rk Exp $ |
1a24938d |
5 | # ---------------------------------------------------------------------- |
977651a5 |
6 | # Copyright (C) 2002-4 SQLFairy Authors |
1a24938d |
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 | |
f5405d47 |
27 | use Digest::SHA1 qw( sha1_hex ); |
28 | |
1a24938d |
29 | use Exporter; |
30 | |
977651a5 |
31 | $VERSION = sprintf "%d.%02d", q$Revision: 1.12 $ =~ /(\d+)\.(\d+)/; |
a2ba36ba |
32 | $DEFAULT_COMMENT = '-- '; |
118bb73f |
33 | @EXPORT_OK = qw( |
f5405d47 |
34 | debug normalize_name header_comment parse_list_arg truncate_id_uniquely $DEFAULT_COMMENT |
118bb73f |
35 | ); |
1a24938d |
36 | |
37 | # ---------------------------------------------------------------------- |
38 | # debug(@msg) |
39 | # |
40 | # Will send debugging messages to STDERR, if the caller's $DEBUG global |
41 | # is set. |
42 | # |
43 | # This debug() function has a neat feature: Occurances of the strings |
44 | # PKG, LINE, and SUB in each message will be replaced with elements |
45 | # from caller(): |
46 | # |
47 | # debug("PKG: Bad things happened on line LINE!"); |
48 | # |
49 | # Will be warned as: |
50 | # |
51 | # [SQL::Translator: Bad things happened on line 643] |
52 | # |
53 | # If called from Translator.pm, on line 643. |
54 | # ---------------------------------------------------------------------- |
55 | sub debug { |
a2ba36ba |
56 | my ($pkg, $file, $line, $sub) = caller(0); |
1a24938d |
57 | { |
58 | no strict qw(refs); |
59 | return unless ${"$pkg\::DEBUG"}; |
60 | } |
61 | |
62 | $sub =~ s/^$pkg\:://; |
63 | |
64 | while (@_) { |
65 | my $x = shift; |
66 | chomp $x; |
67 | $x =~ s/\bPKG\b/$pkg/g; |
68 | $x =~ s/\bLINE\b/$line/g; |
69 | $x =~ s/\bSUB\b/$sub/g; |
70 | #warn '[' . $x . "]\n"; |
71 | print STDERR '[' . $x . "]\n"; |
72 | } |
73 | } |
74 | |
118bb73f |
75 | # ---------------------------------------------------------------------- |
93d12e9c |
76 | sub normalize_name { |
ae48473b |
77 | my $name = shift or return ''; |
93d12e9c |
78 | |
79 | # The name can only begin with a-zA-Z_; if there's anything |
80 | # else, prefix with _ |
81 | $name =~ s/^([^a-zA-Z_])/_$1/; |
82 | |
83 | # anything other than a-zA-Z0-9_ in the non-first position |
84 | # needs to be turned into _ |
85 | $name =~ tr/[a-zA-Z0-9_]/_/c; |
86 | |
87 | # All duplicated _ need to be squashed into one. |
88 | $name =~ tr/_/_/s; |
89 | |
90 | # Trim a trailing _ |
91 | $name =~ s/_$//; |
92 | |
93 | return $name; |
94 | } |
95 | |
118bb73f |
96 | # ---------------------------------------------------------------------- |
a2ba36ba |
97 | sub header_comment { |
98 | my $producer = shift || caller; |
99 | my $comment_char = shift; |
100 | my $now = scalar localtime; |
101 | |
102 | $comment_char = $DEFAULT_COMMENT |
103 | unless defined $comment_char; |
104 | |
105 | my $header_comment =<<"HEADER_COMMENT"; |
106 | ${comment_char} |
107 | ${comment_char}Created by $producer |
108 | ${comment_char}Created on $now |
109 | ${comment_char} |
110 | HEADER_COMMENT |
111 | |
112 | # Any additional stuff passed in |
113 | for my $additional_comment (@_) { |
114 | $header_comment .= "${comment_char}${additional_comment}\n"; |
115 | } |
116 | |
117 | return $header_comment; |
118 | } |
119 | |
118bb73f |
120 | # ---------------------------------------------------------------------- |
51bb6fe0 |
121 | # parse_list_arg |
122 | # |
123 | # Meant to accept a list, an array reference, or a string of |
124 | # comma-separated values. Retuns an array reference of the |
125 | # arguments. Modified to also handle a list of references. |
126 | # ---------------------------------------------------------------------- |
e545d971 |
127 | sub parse_list_arg { |
128 | my $list = UNIVERSAL::isa( $_[0], 'ARRAY' ) ? shift : [ @_ ]; |
129 | |
51bb6fe0 |
130 | # |
131 | # This protects stringification of references. |
132 | # |
133 | if ( @$list && ref $list->[0] ) { |
134 | return $list; |
135 | } |
136 | # |
137 | # This processes string-like arguments. |
138 | # |
139 | else { |
140 | return [ |
141 | map { s/^\s+|\s+$//g; $_ } |
142 | map { split /,/ } |
143 | grep { defined && length } @$list |
144 | ]; |
145 | } |
118bb73f |
146 | } |
147 | |
f5405d47 |
148 | # ---------------------------------------------------------------------- |
149 | # truncate_id_uniquely( $desired_name, $max_symbol_length ) |
150 | # |
151 | # Truncates the name $desired_name to the $max_symbol_length by |
152 | # including part of the hash of the full name at the end of the |
153 | # truncated name, giving a high probability that the symbol will be |
154 | # unique. |
155 | # ---------------------------------------------------------------------- |
156 | my $COLLISION_TAG_LENGTH = 8; |
157 | sub truncate_id_uniquely { |
158 | my ( $desired_name, $max_symbol_length ) = @_; |
159 | |
160 | return $desired_name unless defined $desired_name && length $desired_name > $max_symbol_length; |
161 | |
162 | my $truncated_name = substr $desired_name, 0, $max_symbol_length - $COLLISION_TAG_LENGTH - 1; |
163 | |
164 | # Hex isn't the most space-efficient, but it skirts around allowed |
165 | # charset issues |
166 | my $digest = sha1_hex($desired_name); |
167 | my $collision_tag = substr $digest, 0, $COLLISION_TAG_LENGTH; |
168 | |
169 | return $truncated_name |
170 | . '_' |
171 | . $collision_tag; |
172 | } |
173 | |
1a24938d |
174 | 1; |
175 | |
118bb73f |
176 | # ---------------------------------------------------------------------- |
177 | |
178 | =pod |
1a24938d |
179 | |
180 | =head1 NAME |
181 | |
182 | SQL::Translator::Utils - SQL::Translator Utility functions |
183 | |
184 | =head1 SYNOPSIS |
185 | |
186 | use SQL::Translator::Utils qw(debug); |
187 | debug("PKG: Bad things happened"); |
188 | |
189 | =head1 DESCSIPTION |
190 | |
191 | C<SQL::Translator::Utils> contains utility functions designed to be |
192 | used from the other modules within the C<SQL::Translator> modules. |
193 | |
a2ba36ba |
194 | Nothing is exported by default. |
1a24938d |
195 | |
a2ba36ba |
196 | =head1 EXPORTED FUNCTIONS AND CONSTANTS |
1a24938d |
197 | |
198 | =head2 debug |
199 | |
200 | C<debug> takes 0 or more messages, which will be sent to STDERR using |
201 | C<warn>. Occurances of the strings I<PKG>, I<SUB>, and I<LINE> |
202 | will be replaced by the calling package, subroutine, and line number, |
e545d971 |
203 | respectively, as reported by C<caller(1)>. |
1a24938d |
204 | |
205 | For example, from within C<foo> in F<SQL/Translator.pm>, at line 666: |
206 | |
207 | debug("PKG: Error reading file at SUB/LINE"); |
208 | |
209 | Will warn |
210 | |
211 | [SQL::Translator: Error reading file at foo/666] |
212 | |
213 | The entire message is enclosed within C<[> and C<]> for visual clarity |
214 | when STDERR is intermixed with STDOUT. |
93d12e9c |
215 | |
216 | =head2 normalize_name |
217 | |
218 | C<normalize_name> takes a string and ensures that it is suitable for |
219 | use as an identifier. This means: ensure that it starts with a letter |
220 | or underscore, and that the rest of the string consists of only |
221 | letters, numbers, and underscores. A string that begins with |
222 | something other than [a-zA-Z] will be prefixer with an underscore, and |
223 | all other characters in the string will be replaced with underscores. |
224 | Finally, a trailing underscore will be removed, because that's ugly. |
225 | |
226 | normalize_name("Hello, world"); |
227 | |
228 | Produces: |
229 | |
230 | Hello_world |
231 | |
232 | A more useful example, from the C<SQL::Translator::Parser::Excel> test |
233 | suite: |
234 | |
235 | normalize_name("silly field (with random characters)"); |
236 | |
237 | returns: |
238 | |
239 | silly_field_with_random_characters |
240 | |
a2ba36ba |
241 | =head2 header_comment |
242 | |
243 | Create the header comment. Takes 1 mandatory argument (the producer |
244 | classname), an optional comment character (defaults to $DEFAULT_COMMENT), |
245 | and 0 or more additional comments, which will be appended to the header, |
246 | prefixed with the comment character. If additional comments are provided, |
247 | then a comment string must be provided ($DEFAULT_COMMENT is exported for |
248 | this use). For example, this: |
249 | |
250 | package My::Producer; |
251 | |
252 | use SQL::Translator::Utils qw(header_comment $DEFAULT_COMMENT); |
253 | |
254 | print header_comment(__PACKAGE__, |
e545d971 |
255 | $DEFAULT_COMMENT, |
a2ba36ba |
256 | "Hi mom!"); |
257 | |
258 | produces: |
259 | |
e545d971 |
260 | -- |
a2ba36ba |
261 | -- Created by My::Prodcuer |
262 | -- Created on Fri Apr 25 06:56:02 2003 |
e545d971 |
263 | -- |
a2ba36ba |
264 | -- Hi mom! |
e545d971 |
265 | -- |
a2ba36ba |
266 | |
267 | Note the gratuitous spacing. |
268 | |
118bb73f |
269 | =head2 parse_list_arg |
270 | |
271 | Takes a string, list or arrayref (all of which could contain |
272 | comma-separated values) and returns an array reference of the values. |
273 | All of the following will return equivalent values: |
274 | |
275 | parse_list_arg('id'); |
276 | parse_list_arg('id', 'name'); |
277 | parse_list_arg( 'id, name' ); |
278 | parse_list_arg( [ 'id', 'name' ] ); |
279 | parse_list_arg( qw[ id name ] ); |
280 | |
f5405d47 |
281 | =head2 truncate_id_uniquely |
282 | |
283 | Takes a string ($desired_name) and int ($max_symbol_length). Truncates |
284 | $desired_name to $max_symbol_length by including part of the hash of |
285 | the full name at the end of the truncated name, giving a high |
286 | probability that the symbol will be unique. For example, |
287 | |
288 | truncate_id_uniquely( 'a' x 100, 64 ) |
289 | truncate_id_uniquely( 'a' x 99 . 'b', 64 ); |
290 | truncate_id_uniquely( 'a' x 99, 64 ) |
291 | |
292 | Will give three different results; specifically: |
293 | |
294 | aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_7f900025 |
295 | aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_6191e39a |
296 | aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_8cd96af2 |
297 | |
a2ba36ba |
298 | =head2 $DEFAULT_COMMENT |
299 | |
300 | This is the default comment string, '-- ' by default. Useful for |
301 | C<header_comment>. |
302 | |
118bb73f |
303 | =head1 AUTHORS |
304 | |
305 | Darren Chamberlain E<lt>darren@cpan.orgE<gt>, |
306 | Ken Y. Clark E<lt>kclark@cpan.orgE<gt>. |
307 | |
308 | =cut |
309 | |
310 | =cut |