/ 
File-KDBX-0.800
River stage one • 1 direct dependent • 2 total dependents
/ File::KDBX::Util

NAME

File::KDBX::Util - Utility functions for working with KDBX files

VERSION

version 0.800

FUNCTIONS

load_xs

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

Attempt to load File::KDBX::XS. Return truthy if XS 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.

assert_64bit

assert_64bit();

Throw if perl doesn't support 64-bit IVs.

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.

is_readable

is_writable

$bool = is_readable($mode);
$bool = is_writable($mode);

Determine of an fopen-style mode is readable, writable or both.

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 "QUERY" 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" in functions 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.

# 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.

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.