1SQL::Translator::Utils(U3s)er Contributed Perl DocumentatSiQoLn::Translator::Utils(3)
2
3
4

NAME

6       SQL::Translator::Utils - SQL::Translator Utility functions
7

SYNOPSIS

9         use SQL::Translator::Utils qw(debug);
10         debug("PKG: Bad things happened");
11

DESCSIPTION

13       "SQL::Translator::Utils" contains utility functions designed to be used
14       from the other modules within the "SQL::Translator" modules.
15
16       Nothing is exported by default.
17

EXPORTED FUNCTIONS AND CONSTANTS

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
25       For example, from within "foo" in SQL/Translator.pm, at line 666:
26
27         debug("PKG: Error reading file at SUB/LINE");
28
29       Will warn
30
31         [SQL::Translator: Error reading file at foo/666]
32
33       The entire message is enclosed within "[" and "]" for visual clarity
34       when STDERR is intermixed with STDOUT.
35
36   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
45         normalize_name("Hello, world");
46
47       Produces:
48
49         Hello_world
50
51       A more useful example, from the "SQL::Translator::Parser::Excel" test
52       suite:
53
54         normalize_name("silly field (with random characters)");
55
56       returns:
57
58         silly_field_with_random_characters
59
60   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
69         package My::Producer;
70
71         use SQL::Translator::Utils qw(header_comment $DEFAULT_COMMENT);
72
73         print header_comment(__PACKAGE__,
74                              $DEFAULT_COMMENT,
75                              "Hi mom!");
76
77       produces:
78
79         --
80         -- Created by My::Prodcuer
81         -- Created on Fri Apr 25 06:56:02 2003
82         --
83         -- Hi mom!
84         --
85
86       Note the gratuitous spacing.
87
88   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
93         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
99   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
105         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
109       Will give three different results; specifically:
110
111         aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_7f900025
112         aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_6191e39a
113         aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_8cd96af2
114
115   $DEFAULT_COMMENT
116       This is the default comment string, '--' by default.  Useful for
117       "header_comment".
118
119   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
125         5.0.3
126         4.1
127         3.23.2
128         5
129         5.001005  (perl style)
130         30201     (mysql style)
131
132   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
137   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
141   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
146           around foo => \&ex2err;
147
148           around bar => sub {
149               my ($orig, $self) = (shift, shift);
150               return ex2err($orig, $self, @_) if @_;
151               ...
152           };
153
154   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
159   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
164       If no producer functions are specified, the following functions in the
165       calling package are called:
166
167       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
178       If the corresponding array in the hash has any elements, but the caller
179       doesn't implement that function, an exception is thrown.
180

AUTHORS

182       Darren Chamberlain <darren@cpan.org>, Ken Y. Clark <kclark@cpan.org>.
183
184
185
186perl v5.36.0                      2023-02-27         SQL::Translator::Utils(3)
Impressum