File::KDBX::Util(3pm)

💖 File::KDBX::Util 💖

okay bestie so this is the manual for File::KDBX::Util — section 3pm, and it lives in the User Contributed Perl Documentation. it's the lil toolbox full of utility functions for working with KDBX files, and honestly? it's giving ✨essential✨. let's get into it 🫶

---

🌟 VERSION

this is version 0.906 🎀

---

✨ FUNCTIONS ✨

💫 load_xs

$bool = load_xs();
$bool = load_xs($version);

try to load File::KDBX::XS, babe. returns something truthy if it actually loaded 🔥. and if you hand it a $version, it'll double-check that at least that version is the one loaded. no fakes allowed 💅

💫 assert

assert { ... };

it's an executable comment!! literally a comment that runs. only executed if DEBUG is set in the environment, so it's like... a comment with main character energy 🌸

💫 can_fork

$bool = can_fork;

tells you if perl can fork 🍴. the logic is lifted straight from "CAN_FORK" in Test2::Util, no cap.

💫 clone

$clone = clone($thing);

clones deeply 🧬. it's an unadorned alias to Storable's dclone, so no extra ✨spice✨ — just a straight copy situation.

💫 clone_nomagic

$clone = clone_nomagic($thing);

clones deeply but without keeping [most of] the magic ✨🚫.

⚠️ WARNING: at the moment this implementation is naïve 😭 and it will NOT respond well to nontrivial data or recursive structures. proceed with caution bestie.

💫 DEBUG

a constant number that indicates the level of debuggingness 💀 (yes that's the vibe, it's a number, it says how debuggy things are).

💫 dumper

$str = dumper $thing;
dumper $thing;  # in void context, prints to STDERR

like Data::Dumper but slightly terser in some cases that are relevant to File::KDBX 👑. if you call it in void context, it just prints to STDERR instead of returning a string. iykyk.

💫 empty / nonempty

$bool = empty $thing;

$bool = nonempty $thing;

tests whether a thing is empty (or nonempty, obviously 🙈). a thing counts as empty if it's one of these:

• nonexistent
• undef
• zero-length string
• zero-length array
• hash with zero keys
• reference to an empty thing (recursive, yes, we go deep 🌀)

📌 note in particular that zero 0 is not considered empty — because 0 is an actual value, bestie, and we respect it 💅

💫 erase

erase($string, ...);
erase(\$string, ...);

overwrites the memory used by one or more string(s). like, gone. poof. 🧹✨ security girlie behavior.

💫 erase_scoped

$scope_guard = erase_scoped($string, ...);
$scope_guard = erase_scoped(\$string, ...);
undef $scope_guard; # erase happens here

gets you a scope guard that'll make scalars get erased later — aka when the scope ends 🎀. this is so useful when you want to make sure a string gets erased after you're done with it, even if the scope ends abnormally (drama happens 😭).

see "erase" above for the deets.

💫 extends

extends $class;

sets up the current module to inherit from another module 🧬💖

💫 has

has $name => %options;

creates an attribute getter/setter. possible options:

• "is" — either "rw" (that's the default) or "ro"
• "default" — a default value
• "coerce" — a coercive function

💫 format_uuid

$string_uuid = format_uuid($raw_uuid);
$string_uuid = format_uuid($raw_uuid, $delimiter);

formats a 128-bit UUID (given as a string of 16 octets) into a hexadecimal string 🦋. optionally you can pass a $delimiter to break up the UUID visually into five parts. examples, bestie:

my $uuid = uuid('01234567-89AB-CDEF-0123-456789ABCDEF');
say format_uuid($uuid);         # -> 0123456789ABCDEF0123456789ABCDEF
say format_uuid($uuid, '-');    # -> 01234567-89AB-CDEF-0123-456789ABCDEF

this is the inverse of "uuid" 🔁

💫 generate_uuid

$uuid = generate_uuid;
$uuid = generate_uuid(\%set);
$uuid = generate_uuid(\&test_uuid);

generates a brand new random UUID 🎲✨. it's pretty unlikely this'll generate a repeat, but if you're the anxious type (same 😭), you can hand over either:

• a set of existing UUIDs — as a hashref where the keys are the elements of a set
• or a function to check for existing UUIDs

and this thing will make sure it doesn't return a UUID that's already in the set you gave it. maybe an example will make it crystal clear 💎:

my %uuid_set = (
    uuid('12345678-9ABC-DEFG-1234-56789ABCDEFG') => 'whatever',
);
$uuid = generate_uuid(\%uuid_set);
# OR
$uuid = generate_uuid(sub { !$uuid_set{$_} });

here, $uuid can't be "12345678-9ABC-DEFG-1234-56789ABCDEFG" 🚫. this example uses "uuid" to easily pack a 16-byte UUID from a literal, but it otherwise is not a consequential part of the example, fr fr.

💫 gunzip

$unzipped = gunzip($string);

decompresses an octet stream 📦➡️✨

💫 gzip

$zipped = gzip($string);

compresses an octet stream ✨➡️📦

💫 int64

$int = int64($string);

gets you a scalar integer capable of holding 64-bit values, initialized with a given default value 🔢. on a 64-bit perl it returns a regular SvIV. on a 32-bit perl it returns a Math::BigInt. flexible queen 💅

💫 pack_Ql

$bytes = pack_Ql($int);

like "pack('Q<', $int)", but it also works on 32-bit perls 👑 the little overachiever.

💫 pack_ql

$bytes = pack_ql($int);

like "pack('q<', $int)", but also works on 32-bit perls 💖

💫 unpack_Ql

$int = unpack_Ql($bytes);

like "unpack('Q<', $bytes)", but also works on 32-bit perls 🌈

💫 unpack_ql

$int = unpack_ql($bytes);

like "unpack('q<', $bytes)", but also works on 32-bit perls 🦋

💫 is_uuid

$bool = is_uuid($thing);

checks if a thing is a UUID — meaning a scalar string of length 16 🎀

💫 list_attributes

@attributes = list_attributes($package);

gets you a list of attributes for a class 📝✨

💫 load_optional

$package = load_optional($package);

loads a module that isn't required but can provide extra functionality 🌟. if the module isn't available, it throws 😤. no silent failures here.

💫 memoize

\&memoized_code = memoize(\&code, ...);

memoizes a function 🧠✨. any extra arguments get passed through to &code when it gets called.

💫 pad_pkcs7

$padded_string = pad_pkcs7($string, $block_size),

pads a block using the PKCS#7 method 🧱💖

💫 query

$query = query(@where);
$query->(\%data);

generates a function that'll run a series of tests on a passed hashref and return true or false depending on whether the data record in the hash matched the specified logic 🕵️♀️✨

the logic can be specified in a manner similar to "WHERE CLAUSES" in SQL::Abstract — which was the inspiration for this function, bestie — but heads up: this code is distinct. it supports an overlapping but not identical feature set, and it has its own bugs 💀 (we love honesty).

see "Declarative Syntax" in File::KDBX for examples 🫶

💫 query_any

gets you either a "query" or a "simple_expression_query", depending on the arguments you pass 🎭✨

💫 read_all

$size = read_all($fh, my $buffer, $size);
$size = read_all($fh, my $buffer, $size, $offset);

like "read FILEHANDLE,SCALAR,LENGTH,OFFSET" in perlfunc, BUT it returns "undef" if not all $size bytes are read 📖. that counts as an error, and you can tell it apart from other errors by the fact that $! is not set 👀

💫 recurse_limit

\&limited_code = recurse_limit(\&code);
\&limited_code = recurse_limit(\&code, $max_depth);
\&limited_code = recurse_limit(\&code, $max_depth, \&error_handler);

wraps a function with a guard to prevent deep recursion 🌀🚧 (protect urself from the spiral bestie)

💫 search

# Generate a query on-the-fly:
\@matches = search(\@records, @where);

# Use a pre-compiled query:
$query = query(@where);
\@matches = search(\@records, $query);

# Use a simple expression:
\@matches = search(\@records, \'query terms', @fields);
\@matches = search(\@records, \'query terms', $operator, @fields);

# Use your own subroutine:
\@matches = search(\@records, \&query);
\@matches = search(\@records, sub { $record = shift; ... });

executes a linear search over an array of records using a "query" 🔍✨. a "record" is usually a hash, just so you know.

💫 simple_expression_query

$query = simple_expression_query($expression, @fields);
$query = simple_expression_query($expression, $operator, @fields);

generates a query, like "query", to be used with "search" — but built from a "simple expression" as described here: <https://keepass.info/help/base/search.html#mode_se> 🌸

so here's how an expression works, bestie:

• an expression is a string with one or more space-separated terms
• terms that have spaces in them can be enclosed in double quotes "like this"
• terms get negated if they're prefixed with a minus sign -
• a record must match every term on at least one of the given fields ✅

💫 snakify

$string = snakify($string);

turns a CamelCase string into snake_case 🐍✨ honestly iconic

💫 split_url

($scheme, $auth, $host, $port, $path, $query, $hash, $usename, $password) = split_url($url);

splits a URL into its parts 🦋✂️

for example, "http://user:pass@localhost:4000/path?query#hash" gets split like:

• "http"
• "user:pass"
• "host"
• 4000
• "/path"
• "?query"
• "#hash"
• "user"
• "pass"

💫 to_bool / to_number / to_string / to_time / to_tristate / to_uuid

various typecasting / coercive functions 🎀✨ (a whole squad of converters, slay)

💫 trim

$string = trim($string);

the ubiquitous "trim" function 💅. removes all whitespace from both ends of a string. the classic. the icon. the moment.

💫 try_load_optional

$package = try_load_optional($package);

tries to load a module that isn't required but can provide extra functionality, and returns true if it worked ✅🌟

💫 uri_escape_utf8

$string = uri_escape_utf8($string);

percent-encodes arbitrary text strings, like for a URI 🔗✨

💫 uri_unescape_utf8

$string = uri_unescape_utf8($string);

inverse of "uri_escape_utf8" 🔁

💫 uuid

$raw_uuid = uuid($string_uuid);

packs a 128-bit UUID (given as a hexadecimal string with optional "-"'s, like "12345678-9ABC-DEFG-1234-56789ABCDEFG") into a string of exactly 16 octets 🎀📦

this is the inverse of "format_uuid" 🔁

💫 UUID_NULL

gets you the null UUID — aka a string of 16 null bytes 🕳️✨

---

🐛 BUGS

pls pls pls report any bugs or feature requests on the bugtracker website 🫶: <https://github.com/chazmcgarvey/File-KDBX/issues>

when you submit a bug or a request, please include a test-file or a patch to an existing test-file that illustrates the bug or the desired feature 🙏 (it makes everything so much easier bestie, we literally need the receipts)

---

👑 AUTHOR

Charles McGarvey <ccm@cpan.org> 💌

---

📜 COPYRIGHT AND LICENSE

this software is copyright (c) 2022 by Charles McGarvey.

this is free software 🕊️ — you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. periodt 💅

---

and that's the whole page bestie!! this doc shipped with perl v5.40.1 and it's dated 2025-05-04 🌈 go forth and use those utilities, you're gonna eat 💖✨