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.