---
name: "Test2::Util::UUID"
section: "3pm"
platform: "linux"
package: "libtest2-plugin-uuid-perl"
version: "0.002010-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Test2::Util::UUID"
---

# Test2::Util::UUID(3pm)

Utils for generating UUIDs under Test2.

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

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/*