Commit | Line | Data |
1a24938d |
1 | package SQL::Translator::Utils; |
2 | |
44659089 |
3 | # ---------------------------------------------------------------------- |
4 | # Copyright (C) 2002-2009 SQLFairy Authors |
5 | # |
6 | # This program is free software; you can redistribute it and/or |
7 | # modify it under the terms of the GNU General Public License as |
8 | # published by the Free Software Foundation; version 2. |
9 | # |
10 | # This program is distributed in the hope that it will be useful, but |
11 | # WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
13 | # General Public License for more details. |
14 | # |
15 | # You should have received a copy of the GNU General Public License |
16 | # along with this program; if not, write to the Free Software |
17 | # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA |
18 | # 02111-1307 USA |
19 | # ------------------------------------------------------------------- |
20 | |
1a24938d |
21 | use strict; |
22 | use base qw(Exporter); |
da06ac74 |
23 | use vars qw($VERSION $DEFAULT_COMMENT @EXPORT_OK); |
f5405d47 |
24 | use Digest::SHA1 qw( sha1_hex ); |
1a24938d |
25 | use Exporter; |
26 | |
11ad2df9 |
27 | $VERSION = '1.59'; |
a2ba36ba |
28 | $DEFAULT_COMMENT = '-- '; |
118bb73f |
29 | @EXPORT_OK = qw( |
7b4b17aa |
30 | debug normalize_name header_comment parse_list_arg truncate_id_uniquely |
31 | $DEFAULT_COMMENT parse_mysql_version parse_dbms_version |
118bb73f |
32 | ); |
11ad2df9 |
33 | use constant COLLISION_TAG_LENGTH => 8; |
1a24938d |
34 | |
35 | # ---------------------------------------------------------------------- |
36 | # debug(@msg) |
37 | # |
38 | # Will send debugging messages to STDERR, if the caller's $DEBUG global |
39 | # is set. |
40 | # |
41 | # This debug() function has a neat feature: Occurances of the strings |
42 | # PKG, LINE, and SUB in each message will be replaced with elements |
43 | # from caller(): |
44 | # |
45 | # debug("PKG: Bad things happened on line LINE!"); |
46 | # |
47 | # Will be warned as: |
48 | # |
49 | # [SQL::Translator: Bad things happened on line 643] |
50 | # |
51 | # If called from Translator.pm, on line 643. |
52 | # ---------------------------------------------------------------------- |
53 | sub debug { |
a2ba36ba |
54 | my ($pkg, $file, $line, $sub) = caller(0); |
1a24938d |
55 | { |
56 | no strict qw(refs); |
57 | return unless ${"$pkg\::DEBUG"}; |
58 | } |
59 | |
60 | $sub =~ s/^$pkg\:://; |
61 | |
62 | while (@_) { |
63 | my $x = shift; |
64 | chomp $x; |
65 | $x =~ s/\bPKG\b/$pkg/g; |
66 | $x =~ s/\bLINE\b/$line/g; |
67 | $x =~ s/\bSUB\b/$sub/g; |
68 | #warn '[' . $x . "]\n"; |
69 | print STDERR '[' . $x . "]\n"; |
70 | } |
71 | } |
72 | |
118bb73f |
73 | # ---------------------------------------------------------------------- |
93d12e9c |
74 | sub normalize_name { |
ae48473b |
75 | my $name = shift or return ''; |
93d12e9c |
76 | |
77 | # The name can only begin with a-zA-Z_; if there's anything |
78 | # else, prefix with _ |
79 | $name =~ s/^([^a-zA-Z_])/_$1/; |
80 | |
81 | # anything other than a-zA-Z0-9_ in the non-first position |
82 | # needs to be turned into _ |
83 | $name =~ tr/[a-zA-Z0-9_]/_/c; |
84 | |
85 | # All duplicated _ need to be squashed into one. |
86 | $name =~ tr/_/_/s; |
87 | |
88 | # Trim a trailing _ |
89 | $name =~ s/_$//; |
90 | |
91 | return $name; |
92 | } |
93 | |
118bb73f |
94 | # ---------------------------------------------------------------------- |
a2ba36ba |
95 | sub header_comment { |
96 | my $producer = shift || caller; |
97 | my $comment_char = shift; |
98 | my $now = scalar localtime; |
99 | |
100 | $comment_char = $DEFAULT_COMMENT |
101 | unless defined $comment_char; |
102 | |
103 | my $header_comment =<<"HEADER_COMMENT"; |
104 | ${comment_char} |
105 | ${comment_char}Created by $producer |
106 | ${comment_char}Created on $now |
107 | ${comment_char} |
108 | HEADER_COMMENT |
109 | |
110 | # Any additional stuff passed in |
111 | for my $additional_comment (@_) { |
112 | $header_comment .= "${comment_char}${additional_comment}\n"; |
113 | } |
114 | |
115 | return $header_comment; |
116 | } |
117 | |
118bb73f |
118 | # ---------------------------------------------------------------------- |
51bb6fe0 |
119 | # parse_list_arg |
120 | # |
121 | # Meant to accept a list, an array reference, or a string of |
122 | # comma-separated values. Retuns an array reference of the |
123 | # arguments. Modified to also handle a list of references. |
124 | # ---------------------------------------------------------------------- |
e545d971 |
125 | sub parse_list_arg { |
126 | my $list = UNIVERSAL::isa( $_[0], 'ARRAY' ) ? shift : [ @_ ]; |
127 | |
51bb6fe0 |
128 | # |
129 | # This protects stringification of references. |
130 | # |
131 | if ( @$list && ref $list->[0] ) { |
132 | return $list; |
133 | } |
134 | # |
135 | # This processes string-like arguments. |
136 | # |
137 | else { |
138 | return [ |
139 | map { s/^\s+|\s+$//g; $_ } |
140 | map { split /,/ } |
141 | grep { defined && length } @$list |
142 | ]; |
143 | } |
118bb73f |
144 | } |
145 | |
f5405d47 |
146 | # ---------------------------------------------------------------------- |
147 | # truncate_id_uniquely( $desired_name, $max_symbol_length ) |
148 | # |
149 | # Truncates the name $desired_name to the $max_symbol_length by |
150 | # including part of the hash of the full name at the end of the |
151 | # truncated name, giving a high probability that the symbol will be |
152 | # unique. |
153 | # ---------------------------------------------------------------------- |
f5405d47 |
154 | sub truncate_id_uniquely { |
155 | my ( $desired_name, $max_symbol_length ) = @_; |
156 | |
16fa91c0 |
157 | return $desired_name |
158 | unless defined $desired_name && length $desired_name > $max_symbol_length; |
f5405d47 |
159 | |
16fa91c0 |
160 | my $truncated_name = substr $desired_name, 0, |
11ad2df9 |
161 | $max_symbol_length - COLLISION_TAG_LENGTH - 1; |
f5405d47 |
162 | |
163 | # Hex isn't the most space-efficient, but it skirts around allowed |
164 | # charset issues |
165 | my $digest = sha1_hex($desired_name); |
11ad2df9 |
166 | my $collision_tag = substr $digest, 0, COLLISION_TAG_LENGTH; |
f5405d47 |
167 | |
168 | return $truncated_name |
169 | . '_' |
170 | . $collision_tag; |
171 | } |
172 | |
5d666b31 |
173 | |
174 | #--------------------------------------------------------------------- |
175 | # parse_mysql_version ( $version_string, $result_target) |
176 | # |
177 | # Attempts to parse an arbitrary string as a mysql version number. |
178 | # Returns either a floating point perl style string, or a mysql style |
179 | # 5 digit string, depending on the supplied $result_target |
180 | #--------------------------------------------------------------------- |
181 | sub parse_mysql_version { |
182 | my ($v, $target) = @_; |
183 | |
184 | return undef unless $v; |
185 | |
186 | $target ||= 'perl'; |
187 | |
188 | my @vers; |
189 | |
190 | # X.Y.Z style |
191 | if ( $v =~ / ^ (\d+) \. (\d{1,3}) (?: \. (\d{1,3}) )? $ /x ) { |
192 | push @vers, $1, $2, $3; |
193 | } |
194 | |
195 | # XYYZZ (mysql) style |
196 | elsif ( $v =~ / ^ (\d) (\d{2}) (\d{2}) $ /x ) { |
197 | push @vers, $1, $2, $3; |
198 | } |
199 | |
200 | # XX.YYYZZZ (perl) style or simply X |
201 | elsif ( $v =~ / ^ (\d+) (?: \. (\d{3}) (\d{3}) )? $ /x ) { |
202 | push @vers, $1, $2, $3; |
203 | } |
204 | else { |
205 | #how do I croak sanely here? |
206 | die "Unparseable MySQL version '$v'"; |
207 | } |
208 | |
209 | if ($target eq 'perl') { |
210 | return sprintf ('%d.%03d%03d', map { $_ || 0 } (@vers) ); |
211 | } |
212 | elsif ($target eq 'mysql') { |
213 | return sprintf ('%d%02d%02d', map { $_ || 0 } (@vers) ); |
214 | } |
215 | else { |
216 | #how do I croak sanely here? |
217 | die "Unknown version target '$target'"; |
218 | } |
219 | } |
220 | |
7b4b17aa |
221 | #--------------------------------------------------------------------- |
222 | # parse_dbms_version ( $version_string, $target ) |
223 | # |
224 | # Attempts to parse either a native or perl-style version string into |
225 | # a version number format as specified by $target, which can be either |
226 | # 'perl' for a perl-style version number, or 'native' for an X.X.X |
227 | # style version number. |
228 | #--------------------------------------------------------------------- |
229 | sub parse_dbms_version { |
230 | my ($v, $target) = @_; |
231 | |
232 | return undef unless $v; |
233 | |
234 | my @vers; |
235 | |
236 | # X.Y.Z style |
237 | if ( $v =~ / ^ (\d+) \. (\d{1,3}) (?: \. (\d{1,3}) )? $ /x ) { |
238 | push @vers, $1, $2, $3; |
239 | } |
240 | |
241 | # XX.YYYZZZ (perl) style or simply X |
242 | elsif ( $v =~ / ^ (\d+) (?: \. (\d{3}) (\d{3}) )? $ /x ) { |
243 | push @vers, $1, $2, $3; |
244 | } |
245 | else { |
246 | #how do I croak sanely here? |
247 | die "Unparseable database server version '$v'"; |
248 | } |
249 | |
250 | if ($target eq 'perl') { |
251 | return sprintf ('%d.%03d%03d', map { $_ || 0 } (@vers) ); |
252 | } |
253 | elsif ($target eq 'native') { |
e0d18105 |
254 | return join '.' => grep defined, @vers; |
7b4b17aa |
255 | } |
256 | else { |
257 | #how do I croak sanely here? |
258 | die "Unknown version target '$target'"; |
259 | } |
260 | } |
5d666b31 |
261 | |
1a24938d |
262 | 1; |
263 | |
118bb73f |
264 | # ---------------------------------------------------------------------- |
265 | |
266 | =pod |
1a24938d |
267 | |
268 | =head1 NAME |
269 | |
270 | SQL::Translator::Utils - SQL::Translator Utility functions |
271 | |
272 | =head1 SYNOPSIS |
273 | |
274 | use SQL::Translator::Utils qw(debug); |
275 | debug("PKG: Bad things happened"); |
276 | |
277 | =head1 DESCSIPTION |
278 | |
279 | C<SQL::Translator::Utils> contains utility functions designed to be |
280 | used from the other modules within the C<SQL::Translator> modules. |
281 | |
a2ba36ba |
282 | Nothing is exported by default. |
1a24938d |
283 | |
a2ba36ba |
284 | =head1 EXPORTED FUNCTIONS AND CONSTANTS |
1a24938d |
285 | |
286 | =head2 debug |
287 | |
288 | C<debug> takes 0 or more messages, which will be sent to STDERR using |
289 | C<warn>. Occurances of the strings I<PKG>, I<SUB>, and I<LINE> |
290 | will be replaced by the calling package, subroutine, and line number, |
e545d971 |
291 | respectively, as reported by C<caller(1)>. |
1a24938d |
292 | |
293 | For example, from within C<foo> in F<SQL/Translator.pm>, at line 666: |
294 | |
295 | debug("PKG: Error reading file at SUB/LINE"); |
296 | |
297 | Will warn |
298 | |
299 | [SQL::Translator: Error reading file at foo/666] |
300 | |
301 | The entire message is enclosed within C<[> and C<]> for visual clarity |
302 | when STDERR is intermixed with STDOUT. |
93d12e9c |
303 | |
304 | =head2 normalize_name |
305 | |
306 | C<normalize_name> takes a string and ensures that it is suitable for |
307 | use as an identifier. This means: ensure that it starts with a letter |
308 | or underscore, and that the rest of the string consists of only |
309 | letters, numbers, and underscores. A string that begins with |
310 | something other than [a-zA-Z] will be prefixer with an underscore, and |
311 | all other characters in the string will be replaced with underscores. |
312 | Finally, a trailing underscore will be removed, because that's ugly. |
313 | |
314 | normalize_name("Hello, world"); |
315 | |
316 | Produces: |
317 | |
318 | Hello_world |
319 | |
320 | A more useful example, from the C<SQL::Translator::Parser::Excel> test |
321 | suite: |
322 | |
323 | normalize_name("silly field (with random characters)"); |
324 | |
325 | returns: |
326 | |
327 | silly_field_with_random_characters |
328 | |
a2ba36ba |
329 | =head2 header_comment |
330 | |
331 | Create the header comment. Takes 1 mandatory argument (the producer |
332 | classname), an optional comment character (defaults to $DEFAULT_COMMENT), |
333 | and 0 or more additional comments, which will be appended to the header, |
334 | prefixed with the comment character. If additional comments are provided, |
335 | then a comment string must be provided ($DEFAULT_COMMENT is exported for |
336 | this use). For example, this: |
337 | |
338 | package My::Producer; |
339 | |
340 | use SQL::Translator::Utils qw(header_comment $DEFAULT_COMMENT); |
341 | |
342 | print header_comment(__PACKAGE__, |
e545d971 |
343 | $DEFAULT_COMMENT, |
a2ba36ba |
344 | "Hi mom!"); |
345 | |
346 | produces: |
347 | |
e545d971 |
348 | -- |
a2ba36ba |
349 | -- Created by My::Prodcuer |
350 | -- Created on Fri Apr 25 06:56:02 2003 |
e545d971 |
351 | -- |
a2ba36ba |
352 | -- Hi mom! |
e545d971 |
353 | -- |
a2ba36ba |
354 | |
355 | Note the gratuitous spacing. |
356 | |
118bb73f |
357 | =head2 parse_list_arg |
358 | |
359 | Takes a string, list or arrayref (all of which could contain |
360 | comma-separated values) and returns an array reference of the values. |
361 | All of the following will return equivalent values: |
362 | |
363 | parse_list_arg('id'); |
364 | parse_list_arg('id', 'name'); |
365 | parse_list_arg( 'id, name' ); |
366 | parse_list_arg( [ 'id', 'name' ] ); |
367 | parse_list_arg( qw[ id name ] ); |
368 | |
f5405d47 |
369 | =head2 truncate_id_uniquely |
370 | |
371 | Takes a string ($desired_name) and int ($max_symbol_length). Truncates |
372 | $desired_name to $max_symbol_length by including part of the hash of |
373 | the full name at the end of the truncated name, giving a high |
374 | probability that the symbol will be unique. For example, |
375 | |
376 | truncate_id_uniquely( 'a' x 100, 64 ) |
377 | truncate_id_uniquely( 'a' x 99 . 'b', 64 ); |
378 | truncate_id_uniquely( 'a' x 99, 64 ) |
379 | |
380 | Will give three different results; specifically: |
381 | |
382 | aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_7f900025 |
383 | aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_6191e39a |
384 | aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_8cd96af2 |
385 | |
a2ba36ba |
386 | =head2 $DEFAULT_COMMENT |
387 | |
388 | This is the default comment string, '-- ' by default. Useful for |
389 | C<header_comment>. |
390 | |
5d666b31 |
391 | =head2 parse_mysql_version |
392 | |
393 | Used by both L<Parser::MySQL|SQL::Translator::Parser::MySQL> and |
394 | L<Producer::MySQL|SQL::Translator::Producer::MySQL> in order to provide a |
395 | consistent format for both C<< parser_args->{mysql_parser_version} >> and |
396 | C<< producer_args->{mysql_version} >> respectively. Takes any of the following |
397 | version specifications: |
398 | |
399 | 5.0.3 |
400 | 4.1 |
401 | 3.23.2 |
402 | 5 |
403 | 5.001005 (perl style) |
404 | 30201 (mysql style) |
405 | |
118bb73f |
406 | =head1 AUTHORS |
407 | |
408 | Darren Chamberlain E<lt>darren@cpan.orgE<gt>, |
11ad2df9 |
409 | Ken Y. Clark E<lt>kclark@cpan.orgE<gt>. |
118bb73f |
410 | |
411 | =cut |