Scroll to navigation

Test2::Util::UUID(3pm) User Contributed Perl Documentation Test2::Util::UUID(3pm)

NAME

Test2::Util::UUID - Utils for generating UUIDs under Test2.

DESCRIPTION

This module provides a consistent UUID source for all of Test2.

SYNOPSIS

    use Test2::Util::UUID qw/gen_uuid looks_like_uuid uuid2bin bin2uuid/;
    my $uuid = gen_uuid;
    my $bin = bin2uuid($uuid);
    my $uuid_again = uuid2bin($uuid);

UNDER THE HOOD

One of the following modules will be used under the hood, they are listed here in order of preference.

When possible this module will use the UUID cpan module, but it must be version 0.35 or greater to avoid a fork related bug. It will generate version 7 UUIDs as they are most suitible for database entry.
Data::UUID::MT is the second choice for UUID generation. With this module version 4 UUIDs are generated as they are fairly usable in databases.
UUID::Tiny is used if the previous 2 are not available. This module is pure perl and thus could be slower than the others. Version 4 UUIDs are generated when this module is used.

A warning will be issued with this module. You can surpress the warning with either the $TEST2_UUID_NO_WARN environment variable or the "warn => 0" import argument.

This is the last resort module. This generates UUIDs fast, but they are of a type/version that is not suitible for database keys.

A warning will be issued with this module. You can surpress the warning with either the $TEST2_UUID_NO_WARN environment variable or the "warn => 0" import argument.

CONTROLLING WARNINGS

AT IMPORT

    use Test2::Util::UUID 'gen_uuid', warn => 0;

Passing in "warn => 0" will disable the warnings normally issued when using UUID::Tiny or Data::UUID as a backend.

SELECTING A BACKEND

AT IMPORT

If you wish to override the order and specify which backend to use you may do so by listing them during import prefixed with ':'.

    use Test2::Util::UUID 'gen_uuid', backends => [':UUID', ':UUID::Tiny'];

The above will try the UUID module first, followed by the UUID::Tiny module. It will not try Data::UUID::MT or Data::UUID.

Note: You must include these import arguments anywhere you import this module, otherwise the other imports will use the default list, resulting in different places using different UUIDs.

THE $TEST2_UUID_BACKEND ENV VAR

Setting the $TEST2_UUID_BACKEND env var to one of the backends, or a comma seperated list will override the default list for all imports. It will NOT override imports that specify their own lists.

EXPORTS

$uuid = gen_uuid()
Generate a UUID, always normalized to upper case.
$uuid_or_undef = looks_like_uuid($UUID)
Checks if the provided value looks like a UUID. Make sure it is defined, 36 characters long, has dashes, and only contains 0-9 a-f and dash (case insensitive).

Returns the input value if it looks like a UUID, otherise it returns undef.

SOURCE

The source code repository for Test2-Plugin-UUID can be found at https://github.com/Test-More/Test2-Plugin-UUID/.

MAINTAINERS

AUTHORS

COPYRIGHT

Copyright Chad Granum <exodist@cpan.org>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://dev.perl.org/licenses/

2024-10-18 perl v5.40.0