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.

UUID >= 0.35: 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: 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 - slow: 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.
Data::UUID - Not Suitible for Databases: 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

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

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/