1SQL::Translator::Utils(U3s)er Contributed Perl DocumentatSiQoLn::Translator::Utils(3)
2
6 SQL::Translator::Utils - SQL::Translator Utility functions
7
9 use SQL::Translator::Utils qw(debug);
10 debug("PKG: Bad things happened");
11
13 "SQL::Translator::Utils" contains utility functions designed to be used
14 from the other modules within the "SQL::Translator" modules.
15 Nothing is exported by default.
17
19 debug
20 "debug" takes 0 or more messages, which will be sent to STDERR using
21 "warn". Occurances of the strings PKG, SUB, and LINE will be replaced
22 by the calling package, subroutine, and line number, respectively, as
23 reported by caller(1).
24 For example, from within "foo" in SQL/Translator.pm, at line 666:
26 debug("PKG: Error reading file at SUB/LINE");
28 Will warn
30 [SQL::Translator: Error reading file at foo/666]
32 The entire message is enclosed within "[" and "]" for visual clarity
34 when STDERR is intermixed with STDOUT.
35 normalize_name
37 "normalize_name" takes a string and ensures that it is suitable for use
38 as an identifier. This means: ensure that it starts with a letter or
39 underscore, and that the rest of the string consists of only letters,
40 numbers, and underscores. A string that begins with something other
41 than [a-zA-Z] will be prefixer with an underscore, and all other
42 characters in the string will be replaced with underscores. Finally, a
43 trailing underscore will be removed, because that's ugly.
44 normalize_name("Hello, world");
46 Produces:
48 Hello_world
50 A more useful example, from the "SQL::Translator::Parser::Excel" test
52 suite:
53 normalize_name("silly field (with random characters)");
55 returns:
57 silly_field_with_random_characters
59 header_comment
61 Create the header comment. Takes 1 mandatory argument (the producer
62 classname), an optional comment character (defaults to
63 $DEFAULT_COMMENT), and 0 or more additional comments, which will be
64 appended to the header, prefixed with the comment character. If
65 additional comments are provided, then a comment string must be
66 provided ($DEFAULT_COMMENT is exported for this use). For example,
67 this:
68 package My::Producer;
70 use SQL::Translator::Utils qw(header_comment $DEFAULT_COMMENT);
72 print header_comment(__PACKAGE__,
74 $DEFAULT_COMMENT,
75 "Hi mom!");
76 produces:
78 --
80 -- Created by My::Prodcuer
81 -- Created on Fri Apr 25 06:56:02 2003
82 --
83 -- Hi mom!
84 --
85 Note the gratuitous spacing.
87 parse_list_arg
89 Takes a string, list or arrayref (all of which could contain comma-
90 separated values) and returns an array reference of the values. All of
91 the following will return equivalent values:
92 parse_list_arg('id');
94 parse_list_arg('id', 'name');
95 parse_list_arg( 'id, name' );
96 parse_list_arg( [ 'id', 'name' ] );
97 parse_list_arg( qw[ id name ] );
98 truncate_id_uniquely
100 Takes a string ($desired_name) and int ($max_symbol_length). Truncates
101 $desired_name to $max_symbol_length by including part of the hash of
102 the full name at the end of the truncated name, giving a high
103 probability that the symbol will be unique. For example,
104 truncate_id_uniquely( 'a' x 100, 64 )
106 truncate_id_uniquely( 'a' x 99 . 'b', 64 );
107 truncate_id_uniquely( 'a' x 99, 64 )
108 Will give three different results; specifically:
110 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_7f900025
112 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_6191e39a
113 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_8cd96af2
114 $DEFAULT_COMMENT
116 This is the default comment string, '--' by default. Useful for
117 "header_comment".
118 parse_mysql_version
120 Used by both Parser::MySQL and Producer::MySQL in order to provide a
121 consistent format for both "parser_args->{mysql_parser_version}" and
122 "producer_args->{mysql_version}" respectively. Takes any of the
123 following version specifications:
124 5.0.3
126 4.1
127 3.23.2
128 5
129 5.001005 (perl style)
130 30201 (mysql style)
131 parse_dbms_version
133 Takes a version string (X.Y.Z) or perl style (XX.YYYZZZ) and a target
134 ('perl' or 'native') transforms the string to the given target style.
135 to
136 throw
138 Throws the provided string as an object that will stringify back to the
139 original string. This stops it from being mangled by Moo's "isa" code.
140 ex2err
142 Wraps an attribute accessor to catch any exception raised using "throw"
143 and store them in "$self->error()", finally returning undef. A
144 reference to this function can be passed directly to "around" in Moo.
145 around foo => \&ex2err;
147 around bar => sub {
149 my ($orig, $self) = (shift, shift);
150 return ex2err($orig, $self, @_) if @_;
151 ...
152 };
153 carp_ro
155 Takes a field name and returns a reference to a function can be used
156 around a read-only accessor to make it carp instead of die when passed
157 an argument.
158 batch_alter_table_statements
160 Takes diff and argument hashes as passed to batch_alter_table and an
161 optional list of producer functions to call on the calling package.
162 Returns the list of statements returned by the producer functions.
163 If no producer functions are specified, the following functions in the
165 calling package are called:
166 1. rename_table
168 2. alter_drop_constraint
169 3. alter_drop_index
170 4. drop_field
171 5. add_field
172 5. alter_field
173 6. rename_field
174 7. alter_create_index
175 8. alter_create_constraint
176 9. alter_table
177 If the corresponding array in the hash has any elements, but the caller
179 doesn't implement that function, an exception is thrown.
180
182 Darren Chamberlain <darren@cpan.org>, Ken Y. Clark <kclark@cpan.org>.
183perl v5.36.0 2022-07-22 SQL::Translator::Utils(3)