/ 
File-KDBX-0.901
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.901

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

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