Provided by: libfile-kdbx-perl_0.906-2_all 
NAME
File::KDBX::Util - Utility functions for working with KDBX files
VERSION
version 0.906
FUNCTIONS
load_xs
$bool = load_xs();
$bool = load_xs($version);
Attempt to load File::KDBX::XS. Return truthy if it is loaded. If $version is given, it will check that
at least the given version is loaded.
assert
assert { ... };
Write an executable comment. Only executed if "DEBUG" is set in the environment.
can_fork
$bool = can_fork;
Determine if perl can fork, with logic lifted from "CAN_FORK" in Test2::Util.
clone
$clone = clone($thing);
Clone deeply. This is an unadorned alias to Storable "dclone".
clone_nomagic
$clone = clone_nomagic($thing);
Clone deeply without keeping [most of] the magic.
WARNING: At the moment the implementation is naïve and won't respond well to nontrivial data or recursive
structures.
DEBUG
Constant number indicating the level of debuggingness.
dumper
$str = dumper $thing;
dumper $thing; # in void context, prints to STDERR
Like Data::Dumper but slightly terser in some cases relevent to File::KDBX.
empty
nonempty
$bool = empty $thing;
$bool = nonempty $thing;
Test whether a thing is empty (or nonempty). An empty thing is one of these:
• nonexistent
• "undef"
• zero-length string
• zero-length array
• hash with zero keys
• reference to an empty thing (recursive)
Note in particular that zero 0 is not considered empty because it is an actual value.
erase
erase($string, ...);
erase(\$string, ...);
Overwrite the memory used by one or more string.
erase_scoped
$scope_guard = erase_scoped($string, ...);
$scope_guard = erase_scoped(\$string, ...);
undef $scope_guard; # erase happens here
Get a scope guard that will cause scalars to be erased later (i.e. when the scope ends). This is useful
if you want to make sure a string gets erased after you're done with it, even if the scope ends
abnormally.
See "erase".
extends
extends $class;
Set up the current module to inheret from another module.
has
has $name => %options;
Create an attribute getter/setter. Possible options:
• "is" - Either "rw" (default) or "ro"
• "default" - Default value
• "coerce" - Coercive function
format_uuid
$string_uuid = format_uuid($raw_uuid);
$string_uuid = format_uuid($raw_uuid, $delimiter);
Format a 128-bit UUID (given as a string of 16 octets) into a hexidecimal string, optionally with a
delimiter to break up the UUID visually into five parts. Examples:
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);
Generate a new random UUID. It's pretty unlikely that this will generate a repeat, but if you're worried
about that you can provide 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 will be sure to not return a UUID already
in provided set. Perhaps an example will make it 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.
gunzip
$unzipped = gunzip($string);
Decompress an octet stream.
gzip
$zipped = gzip($string);
Compress an octet stream.
int64
$int = int64($string);
Get a scalar integer capable of holding 64-bit values, initialized with a given default value. On a
64-bit perl, it will return a regular SvIV. On a 32-bit perl it will return a Math::BigInt.
pack_Ql
$bytes = pack_Ql($int);
Like "pack('Q<', $int)", but also works on 32-bit perls.
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);
Check if a thing is a UUID (i.e. scalar string of length 16).
list_attributes
@attributes = list_attributes($package);
Get a list of attributes for a class.
load_optional
$package = load_optional($package);
Load a module that isn't required but can provide extra functionality. Throw if the module is not
available.
memoize
\&memoized_code = memoize(\&code, ...);
Memoize a function. Extra arguments are passed through to &code when it is called.
pad_pkcs7
$padded_string = pad_pkcs7($string, $block_size),
Pad a block using the PKCS#7 method.
query
$query = query(@where);
$query->(\%data);
Generate a function that will run a series of tests on a passed hashref and return true or false
depending on if 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, but this code is distinct, supporting an overlapping but not identical
feature set and having its own bugs.
See "Declarative Syntax" in File::KDBX for examples.
query_any
Get either a "query" or "simple_expression_query", depending on the arguments.
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 returns "undef" if not all $size bytes are
read. This is considered an error, distinguishable from other errors by $! not being set.
recurse_limit
\&limited_code = recurse_limit(\&code);
\&limited_code = recurse_limit(\&code, $max_depth);
\&limited_code = recurse_limit(\&code, $max_depth, \&error_handler);
Wrap a function with a guard to prevent deep recursion.
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; ... });
Execute a linear search over an array of records using a "query". A "record" is usually a hash.
simple_expression_query
$query = simple_expression_query($expression, @fields);
$query = simple_expression_query($expression, $operator, @fields);
Generate 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>.
An expression is a string with one or more space-separated terms. Terms with spaces can be enclosed in
double quotes. Terms are negated if they are prefixed with a minus sign. A record must match every term
on at least one of the given fields.
snakify
$string = snakify($string);
Turn a CamelCase string into snake_case.
split_url
($scheme, $auth, $host, $port, $path, $query, $hash, $usename, $password) = split_url($url);
Split 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.
trim
$string = trim($string);
The ubiquitous "trim" function. Removes all whitespace from both ends of a string.
try_load_optional
$package = try_load_optional($package);
Try to load a module that isn't required but can provide extra functionality, and return true if
successful.
uri_escape_utf8
$string = uri_escape_utf8($string);
Percent-encode 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);
Pack a 128-bit UUID (given as a hexidecimal 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
Get the null UUID (i.e. string of 16 null bytes).
BUGS
Please report any bugs or feature requests on the bugtracker website
<https://github.com/chazmcgarvey/File-KDBX/issues>
When submitting a bug or request, please include a test-file or a patch to an existing test-file that
illustrates the bug or desired feature.
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.
perl v5.36.0 2022-11-20 File::KDBX::Util(3pm)