/ 
DBIx-Squirrel-1.5.5-TRIAL
River stage zero No dependents
/ DBIx::Squirrel::util

NAME

DBIx::Squirrel::util - Utilities

DESCRIPTION

A collection of helper functions used by other DBIx::Squirrel packages.

EXPORTS

Nothing is exported by default.

cluckf

Emits a warning with a stack-trace.

cluckf();

The warning will be set to $@ if it contains something useful. Otherwise an "Unhelpful warning" will be emitted.

cluckf($message);
cluckf(\@message);

The warning will be set to $message, or the concatenated @message array, or $@, if there is no viable message. If there is still no viable message then an "Unhelpful warning" is emitted.

During concatenation, the elements of the @message array are separated by a single space. The intention is to allow for long warning messages to be split apart in a tidier manner.

cluckf($format, @arguments);
cluckf(\@format, @arguments);

The warning is composed using a sprintf format-string ($format), together with any remaining arguments. Alternatively, the format-string may be produced by concatenating the @format array whose elements are separated by a single space.

confessf

Throws and exception with a stack-trace.

confessf();

The error will be set to $@ if it contains something useful (effectivly re-throwing the previous exception). Otherwise it will an "Unknown error" exception is thrown.

confessf($message);
confessf(\@message);

The error will be set to $message, or the concatenated @message array, or $@, if there is no viable message. If there is still no viable message then an "Unknown error" is thrown.

During concatenation, the elements of the @message array are separated by a single space. The intention is to allow for long error messages to be split apart in a tidier manner.

confessf($format, @arguments);
confessf(\@format, @arguments);

The error message is composed using a sprintf format-string ($format), together with any remaining arguments. Alternatively, the format-string may be produced by concatenating the @format array whose elements are separated by a single space.

decrypt

$buffer = decrypt($fernet_key);
$buffer = decrypt($buffer, $fernet_key);

Decrypts a Fernet-encrypted buffer, returning the decrypted data.

A Fernet key can be provided as the second argument, and this can be a Base64-encoded string or a DBIx::Squirrel::Crypt::Fernet instance. If no second argument is defined, the function will fall back to using the FERNET_KEY environment variable, and if that isn't defined then an exception will be thrown.

If $buffer is omitted then $_ will be used.

get_file_contents

$contents = get_file_contents($filename[, \%options]);

Return the entire contents of a file to the caller.

The file is read in raw (binary) mode. What happens to the contents after reading depends on the file's name and/or the contents of %options:

  • If ".encrypted" forms part of the file's name or the decrypt option is true, then the file contents will be decrypted after they have been read using the Fernet key provided in the fernet option or the FERNET_KEY environment variable.

  • If ".bz2" forms part of the file's name or the uncompress option is true, then the file contents will be uncompressed after they have been read and possibly decrypted.

  • If ".json" forms part of the file's name or the unmarshal option is true, then the file contents will be unmarshalled after they have been read, possibly decrypted, and possibly uncompressed.

  • If the utf8decode option is true, then the file contents will be decoded as a UTF-8 string.

global_destruct_phase

$bool = global_destruct_phase();

Detects whether the Perl program is in the Global Destruct Phase. Knowing this can make DESTROY methods safer. Perl versions older than 5.14 don't support the ${^GLOBAL_PHASE} variable, so provide a shim that works regardless of Perl version.

isolate_callbacks

(\@callbacks, @arguments) = isolate_callbacks(@argments);

When using DBIx::Squirrel, some calls allow the caller to reshape results before they are returned, using transformation pipelines. A transformation pipeline is one or more contiguous code-references presented at the end of a call's argument list.

Th isolate_callbacks function inspects an array of arguments, moving any trailing code-references from the source array into a separate array — the transformation pipeline. It returns a reference to that array, followed by any remaining arguments, to the caller.

(\@callbacks, @arguments) = &isolate_callbacks;

The terse &-sigil calling style causes isolate_callbacks to use the calling function's @_ array.

slurp

$buffer = slurp();
$buffer = slurp($filename);

Reads the entirety of the specified file in raw mode, returning the contents.

If $filename is omitted then $_ will be used.

uncompress

$buffer = uncompress();
$buffer = uncompress($buffer);

Uncompresses a Bzip2-compressed buffer, returning the uncompressed data.

If $buffer is omitted then $_ will be used.

unmarshal

$data = unmarshal($json);
$data = unmarshal($json, $decode);

Unmarshals a JSON-encoded buffer into the data-structure it represents. By default, UTF-8 binaries are properly decoded, and this behaviour can be inhibited by setting $decode to false.

utf8decode

$string = utf8decode();
$string = utf8decode($buffer);

Decode a byte buffer, returning a UTF-8 string.

If $buffer is omitted then $_ will be used.

AUTHORS

Iain Campbell <cpanic@cpan.org>

COPYRIGHT AND LICENSE

The DBIx::Squirrel module is Copyright (c) 2020-2025 Iain Campbell. All rights reserved.

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl 5.10.0 README file.

SUPPORT / WARRANTY

DBIx::Squirrel is free Open Source software. IT COMES WITHOUT WARRANTY OF ANY KIND.