File::KDBX::Util(3p)

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.