SQL::Tr...::Utils(3)

📦
version 1.660.0 · 10 versions
, in opensuse-leap 16.0

✨ SQL::Translator::Utils(3) — the utility drawer bestie ✨

okay so this is the manual page for SQL::Translator::Utils, and it's literally the little utility pouch for the SQL::Translator modules. User Contributed Perl Documentation, if you were wondering. We're gonna go through every single thing, no cap 💅

🎀 NAME 🎀

SQL::Translator::Utils — SQL::Translator Utility functions. That's it. That's the name. Iconic.

🦋 SYNOPSIS 🦋

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

Like, that's the whole vibe check: you load it, you call debug, you move on with your life ✨

😭 DESCSIPTION 😭 (yes, that's the spelling in the source, bestie)

SQL::Translator::Utils contains utility functions designed to be used from the other modules within the SQL::Translator modules.

Nothing is exported by default. Periodt. You gotta ask for what you want.

👑 EXPORTED FUNCTIONS AND CONSTANTS 👑

🫶 debug

debug takes 0 or more messages, which will be sent to STDERR using warn. Occurances of the strings PKG, SUB, and LINE will be replaced by the calling package, subroutine, and line number, respectively, as reported by caller(1).

For example, from within foo in SQL/Translator.pm, at line 666:

debug("PKG: Error reading file at SUB/LINE");

Will warn:

[SQL::Translator: Error reading file at foo/666]

The entire message is enclosed within [ and ] for visual clarity when STDERR is intermixed with STDOUT. So cute, so readable, so “I can tell what came from where” 💖

🌸 normalize_name

normalize_name takes a string and ensures that it is suitable for use as an identifier. This means: ensure that it starts with a letter or underscore, and that the rest of the string consists of only letters, numbers, and underscores.

A string that begins with something other than [a-zA-Z] will be prefixer with an underscore — yeah, the page says “prefixer”, and honestly I respect it 😭 — and all other characters in the string will be replaced with underscores. Finally, a trailing underscore will be removed, because that's ugly. We do not stan a trailing underscore.

normalize_name("Hello, world");

Produces:

Hello_world

A more useful example, from the SQL::Translator::Parser::Excel test suite:

normalize_name("silly field (with random characters)");

returns:

silly_field_with_random_characters

slay, honestly 🌈

💖 header_comment

Create the header comment. Takes 1 mandatory argument (the producer classname), an optional comment character (defaults to $DEFAULT_COMMENT), and 0 or more additional comments, which will be appended to the header, prefixed with the comment character.

If additional comments are provided, then a comment string must be provided ($DEFAULT_COMMENT is exported for this use). For example, this:

package My::Producer;

use SQL::Translator::Utils qw(header_comment $DEFAULT_COMMENT);

print header_comment(__PACKAGE__,
                     $DEFAULT_COMMENT,
                     "Hi mom!");

produces:

--
-- Created by My::Prodcuer
-- Created on Fri Apr 25 06:56:02 2003
--
-- Hi mom!
--

Note the gratuitous spacing. It's giving “I have a consistent header and I want you to know it” energy 💅 Also yes, the output says My::Prodcuer in the source — we keep it exactly, bestie, character for character 🫶

🧚 parse_list_arg

Takes a string, list or arrayref (all of which could contain comma-separated values) and returns an array reference of the values. All of the following will return equivalent values:

parse_list_arg('id');
parse_list_arg('id', 'name');
parse_list_arg( 'id, name' );
parse_list_arg( [ 'id', 'name' ] );
parse_list_arg( qw[ id name ] );

Five different looks, same energy. We love a flexible icon ✨

🍓 truncate_id_uniquely

Takes a string ($desired_name) and int ($max_symbol_length). Truncates $desired_name to $max_symbol_length by including part of the hash of the full name at the end of the truncated name, giving a high probability that the symbol will be unique. For example:

truncate_id_uniquely( 'a' x 100, 64 )
truncate_id_uniquely( 'a' x 99 . 'b', 64 );
truncate_id_uniquely( 'a' x 99,  64 )

Will give three different results; specifically:

aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_7f900025
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_6191e39a
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa_8cd96af2

Three near-identical strings, three different hash endings. The way that uniqueness is literally built in 😭👑

💀 $DEFAULT_COMMENT

This is the default comment string, '--' by default. Useful for header_comment.

It's the little '--' that could. Respect.

🔥 parse_mysql_version

Used by both Parser::MySQL and Producer::MySQL in order to provide a consistent format for both parser_args->{mysql_parser_version} and producer_args->{mysql_version} respectively. Takes any of the following version specifications:

5.0.3
4.1
3.23.2
5
5.001005  (perl style)
30201     (mysql style)

Version strings really said “I contain multitudes” and this function said “bet” 💅

🌈 parse_dbms_version

Takes a version string (X.Y.Z) or perl style (XX.YYYZZZ) and a target ('perl' or 'native') transforms the string to the given target style. to

And then the page just says to on its own line. That's the whole sentence, bestie. We preserve the mystery. 😭

💜 throw

Throws the provided string as an object that will stringify back to the original string. This stops it from being mangled by Moo's isa code.

No mangling, no weird surprises, just your string coming back to you exactly as it left. We love a faithful queen 💖

🎀 ex2err

Wraps an attribute accessor to catch any exception raised using throw and store them in $self->error(), finally returning undef. A reference to this function can be passed directly to around in Moo.

around foo => \&ex2err;

around bar => sub {
    my ($orig, $self) = (shift, shift);
    return ex2err($orig, $self, @_) if @_;
    ...
};

Error handling but make it cozy. Catch the exception, stash the error, return undef, keep it moving ✨

🦋 carp_ro

Takes a field name and returns a reference to a function can be used around a read-only accessor to make it carp instead of die when passed an argument.

Read-only accessor said “don't touch”, and this function said “okay but I'm gonna carp about it instead of dying” 💅

⭐ batch_alter_table_statements

Takes diff and argument hashes as passed to batch_alter_table and an optional list of producer functions to call on the calling package. Returns the list of statements returned by the producer functions.

If no producer functions are specified, the following functions in the calling package are called:

  • 1. rename_table
  • 2. alter_drop_constraint
  • 3. alter_drop_index
  • 4. drop_field
  • 5. add_field
  • 5. alter_field
  • 6. rename_field
  • 7. alter_create_index
  • 8. alter_create_constraint
  • 9. alter_table

Yep, there are two 5.s in the source list. Not me fixing it, bestie — we keep the lore exactly as it is 💅

If the corresponding array in the hash has any elements, but the caller doesn't implement that function, an exception is thrown. Like, if you signed up for the data but not the function? Exception. Periodt.

🌸 AUTHORS 🌸

Darren Chamberlain <darren@cpan.org>, Ken Y. Clark <kclark@cpan.org>.

Legends. Icons. The blueprint. 🫶

This lil page is from perl v5.42.0, dated 2024-12-12, and it's User Contributed Perl Documentation. Byeee bestie, go normalize some names and throw some strings 💖✨🎀🦋

📦 where this page comes from