UUID::Tiny(3)

🌸 NAME 🌸

okay bestie, you're on the UUID::Tiny(3) page — yes, the User Contributed Perl Documentation one — and the NAME situation is literally: UUID::Tiny — Pure Perl UUID Support With Functional Interface. That's the whole vibe: tiny, pure Perl, functional, no OO drama. 💖

🔥 VERSION 🔥

Version 1.04. Slay. ✨

🎀 SYNOPSIS 🎀

Bestie, here's the group-chat cheat sheet for creating version 1, 3, 4 and 5 UUIDs. The code is doing the actual work, so copy it exactly, mwah:

use UUID::Tiny ':std';

my $v1_mc_UUID      = create_uuid();
my $v1_mc_UUID_2    = create_uuid(UUID_V1);
my $v1_mc_UUID_3    = create_uuid(UUID_TIME);
my $v3_md5_UUID     = create_uuid(UUID_V3, $str);
my $v3_md5_UUID_2   = create_uuid(UUID_MD5, UUID_NS_DNS, 'caugustin.de');
my $v4_rand_UUID    = create_uuid(UUID_V4);
my $v4_rand_UUID_2  = create_uuid(UUID_RANDOM);
my $v5_sha1_UUID    = create_uuid(UUID_V5, $str);
my $v5_with_NS_UUID = create_uuid(UUID_SHA1, UUID_NS_DNS, 'caugustin.de');

my $v1_mc_UUID_string  = create_uuid_as_string(UUID_V1);
my $v3_md5_UUID_string = uuid_to_string($v3_md5_UUID);

if ( version_of_uuid($v1_mc_UUID) == 1   ) { ... };
if ( version_of_uuid($v5_sha1_UUID) == 5 ) { ... };
if ( is_uuid_string($v1_mc_UUID_string)  ) { ... };
if ( equal_uuids($uuid1, $uuid2)         ) { ... };

my $uuid_time    = time_of_uuid($v1_mc_UUID);
my $uuid_clk_seq = clk_seq_of_uuid($v1_mc_UUID);

🦋 DESCRIPTION 🦋

UUID::Tiny is a lightweight, low-dependency Pure Perl module for UUID creation and testing. It gives you version 1 time-based UUIDs (using random multicast MAC addresses), version 3 MD5-based UUIDs, version 4 random UUIDs, and version 5 SHA-1-based UUIDs. Iconic. 💅

ATTENTION! UUID::Tiny uses Perl's rand() to create the basic random numbers, so the created v4 UUIDs are not cryptographically strong! No cap, bestie, don't use them for secrets. 😭

There's no fancy OO interface and no huge pile of different UUID representation formats and transformations — it's just string and binary. The conversion, test and time functions accept both UUIDs and UUID strings, so you literally don't have to convert anything first. Obsessed. 🫶

In the 1.0x versions, all constants and public functions are exported by default, but that's going to change in the future (see below, iykyk). 🌈

UUID::Tiny deliberately keeps a minimal functional interface for UUID creation (and conversion/testing), because OO here looked like overkill to the author and makes creating and using UUIDs unnecessarily complicated. Main character energy: minimal, functional, done. ✨

If you need raw performance for UUID creation, or the real MAC address in version 1 UUIDs, or an OO interface — and you can afford compiling and installing a module on the target system — then go look at other CPAN UUID modules like Data::UUID. That's the tea. 🍓

This module is "fork safe", especially for random UUIDs (it works around Perl's rand() problem when forking processes). 🌸

This module is currently not "thread safe". Even though the author incorporated some changes proposed by Michael G. Schwern (thanks!), Digest::MD5 and Digest::SHA seem to have trouble with threads. There is a test file for threads, but it is de-activated. So use at your own risk! 💀

📦 DEPENDENCIES 📦

This module should run from Perl 5.8 up and uses mostly standard (5.8 core) modules for its job. No compilation or installation required. These are the modules UUID::Tiny depends on:

Carp
Digest::MD5   Perl 5.8 core
Digest::SHA   Perl 5.10 core (or Digest::SHA1, or Digest::SHA::PurePerl)
MIME::Base64  Perl 5.8 core
Time::HiRes   Perl 5.8 core
POSIX         Perl 5.8 core

If you are using this module on a Perl prior to 5.10 and you don't have Digest::SHA1 installed, you can use Digest::SHA::PurePerl instead. 🧚

🚨 ATTENTION! NEW STANDARD INTERFACE 🚨

After some debate, the author is convinced that it is more Perlish (and far easier to write) to use all-lowercase function names — without exceptions. And that it is more polite to export symbols only on demand. Periodt. 💜

While the 1.0x versions will continue to export the old, "legacy" interface on default, the future standard interface is available using the ":std" tag on import from version 1.02 on:

use UUID::Tiny ':std';
my $md5_uuid = create_uuid(UUID_MD5, $str);

In preparation for future version of UUID::Tiny you have to use the ":legacy" tag if you want to stay with the version 1.0 interface:

use UUID::Tiny ':legacy';
my $md5_uuid = create_UUID(UUID_V3, $str);

🔮 CONSTANTS 🔮

NIL UUID

This module provides the NIL UUID (shown with its string representation):

UUID_NIL: '00000000-0000-0000-0000-000000000000'

Pre-defined Namespace UUIDs

This module provides the common pre-defined namespace UUIDs (shown with their string representation):

UUID_NS_DNS:  '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
UUID_NS_URL:  '6ba7b811-9dad-11d1-80b4-00c04fd430c8'
UUID_NS_OID:  '6ba7b812-9dad-11d1-80b4-00c04fd430c8'
UUID_NS_X500: '6ba7b814-9dad-11d1-80b4-00c04fd430c8'

UUID versions

This module provides the UUID version numbers as constants:

UUID_V1
UUID_V3
UUID_V4
UUID_V5

With use UUID::Tiny ':std'; you get additional, "speaking" constants:

UUID_TIME
UUID_MD5
UUID_RANDOM
UUID_SHA1

UUID_SHA1_AVAIL

my $uuid = create_UUID( UUID_SHA1_AVAIL? UUID_V5 : UUID_V3, $str );

This function returns 1 if a module to create SHA-1 digests could be loaded, 0 otherwise. 🦋

UUID::Tiny (since version 1.02) tries to load Digest::SHA, Digest::SHA1 or Digest::SHA::PurePerl, but does not die if none of them is found. Instead create_UUID() and create_UUID_as_string() die when trying to create an SHA-1 based UUID without an appropriate module available. Big "read the room" energy. 💀

🛠️ FUNCTIONS 🛠️

All public functions are exported by default (they should not collide with other functions). Slay. ✨

create_UUID() creates standard binary UUIDs in network byte order (MSB first), create_UUID_as_string() creates the standard string representation of UUIDs. 🎀

All query and test functions (except "is_UUID_string") accept both representations. Bestie, that means less converting, more living. 💅

create_UUID(), create_uuid() (:std)

my $v1_mc_UUID   = create_UUID();
my $v1_mc_UUID   = create_UUID(UUID_V1);
my $v3_md5_UUID  = create_UUID(UUID_V3, $ns_uuid, $name_or_filehandle);
my $v3_md5_UUID  = create_UUID(UUID_V3, $name_or_filehandle);
my $v4_rand_UUID = create_UUID(UUID_V4);
my $v5_sha1_UUID = create_UUID(UUID_V5, $ns_uuid, $name_or_filehandle);
my $v5_sha1_UUID = create_UUID(UUID_V5, $name_or_filehandle);

Creates a binary UUID in network byte order (MSB first). For v3 and v5 UUIDs a "SCALAR" (normally a string), "GLOB" ("classic" file handle) or "IO" object (i.e. "IO::File") can be used; files have to be opened for reading. 🍓

ngl, the author found no hint if and how UUIDs should be created from file content. It seems to be undefined, but it is useful — so the suggestion is to use UUID_NIL as the namespace UUID, because no "real name" is used; UUID_NIL is used by default if a namespace UUID is missing (only 2 arguments are used). 🌈

create_UUID_as_string(), create_uuid_as_string() (:std)

Similar to "create_UUID", but creates a UUID string. Cute, concise, iconic. 🎀

is_UUID_string(), is_uuid_string() (:std)

my $bool = is_UUID_string($str);

Drop your string in, get $bool back. 💖

UUID_to_string(), uuid_to_string() (:std)

my $uuid_str = UUID_to_string($uuid);

This function returns $uuid unchanged if it is a UUID string already. No unnecessary glow-up. 💅

string_to_UUID(), string_to_uuid() (:std)

my $uuid = string_to_UUID($uuid_str);

This function returns $uuid_str unchanged if it is a UUID already. 🦋

In addition to the standard UUID string representation and its URN forms (starting with "urn:uuid:" or "uuid:"), this function accepts 32 digit hex strings, variants with different positions of "-" and Base64 encoded UUIDs. Versatile queen. 👑

Throws an exception if string can't be interpreted as a UUID. 😭

If you want to make sure to have a "pure" standard UUID representation, check with "is_UUID_string"! ⭐

version_of_UUID(), version_of_uuid() (:std)

my $version = version_of_UUID($uuid);

This function accepts binary and string UUIDs. 🌸

time_of_UUID(), time_of_uuid() (:std)

my $uuid_time = time_of_UUID($uuid);

This function accepts UUIDs and UUID strings. Returns the time as a floating point value, so use int() to get a time() compatible value. 🕰️

Returns "undef" if the UUID is not version 1. No v1, no time for you. 💀

clk_seq_of_UUID(), clk_seq_of_uuid() (:std)

my $uuid_clk_seq = clk_seq_of_UUID($uuid);

This function accepts UUIDs and UUID strings. Returns the clock sequence for a version 1 UUID. Returns "undef" if UUID is not version 1. 🎀

equal_UUIDs(), equal_uuids() (:std)

my $bool = equal_UUIDs($uuid1, $uuid2);

Returns true if the provided UUIDs are equal. Accepts UUIDs and UUID strings (can be mixed). Bestie, mix and match responsibly. 🫶

💬 DISCUSSION 💬

Why version 1 only with random multi-cast MAC addresses?

The random multi-cast MAC address gives privacy, and getting the real MAC address with Perl is really dirty (and slow). Privacy slay. 🌈

Should version 3 or version 5 be used?

Using SHA-1 reduces the probability of collisions and provides a better "randomness" of the resulting UUID compared to MD5. Version 5 is recommended in RFC 4122 if backward compatibility is not an issue. 🔥

Using MD5 (version 3) has a better performance. This could be important with creating UUIDs from file content rather than names. Performance queen behavior. 💅

📚 UUID DEFINITION 📚

See RFC 4122 (<http://www.ietf.org/rfc/rfc4122.txt>) for technical details on UUIDs. Wikipedia gives a more palatable description at <http://en.wikipedia.org/wiki/Universally_unique_identifier>. 🦋

👑 AUTHOR 👑

Christian Augustin, "<mail at caugustin.de>" 💖

🫶 CONTRIBUTORS 🫶

Some of this code is based on UUID::Generator by ITO Nobuaki <banb@cpan.org>. But that module is announced to be marked as "deprecated" in the future and it is much too complicated for my liking. 🙈

So the author decided to reduce it to the necessary parts and to re-implement those parts with a functional interface ... functional era. ✨

Jesse Vincent, "<jesse at bestpractical.com>", improved version 1.02 with his tips and a heavy refactoring. 🔥

Michael G. Schwern provided a patch for better thread support (as far as UUID::Tiny can be improved itself) that is incorporated in version 1.04. 🫶

💀 BUGS 💀

Please report any bugs or feature requests to "bug-uuid-tiny at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=UUID-Tiny>. The author will be notified, and then you'll automatically be notified of progress on your bug as changes are made. 🎀

💖 SUPPORT 💖

Okay bestie, you are never stranded, fr fr. Whenever you're like "wait how does this thing work again 😭", the docs are literally right there:

perldoc UUID::Tiny

That's it. That's the whole command. Type it, hit enter, ✨ knowledge ✨.

And if you wanna go browse around the internet like the main character you are, here's where the info lives:

• RT: CPAN's request tracker — this is the place to file bugs and requests, iykyk

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=UUID-Tiny>

• AnnoCPAN: Annotated CPAN documentation — docs with the community's commentary vibes all over them 🫶

<http://annocpan.org/dist/UUID-Tiny>

• CPAN Ratings — go leave your honest review, no cap

<http://cpanratings.perl.org/d/UUID-Tiny>

• Search CPAN — the ultimate scavenger hunt for anything CPAN-related 🔍

<http://search.cpan.org/dist/UUID-Tiny/>

---

🌸 ACKNOWLEDGEMENTS 🌸

Okay so this entire module is giving "standing on the shoulders of icons" and I need to give credit where credit is due, periodt.

Huge kudos to ITO Nobuaki <banb@cpan.org> for his UUID::Generator::PurePerl module! The whole thing is built on his code, and honestly? Without it I would have been absolutely lost in all those incomprehensible RFC texts and C codes ... like, genuinely lost. 😭 Those RFCs do not read like a group chat, bestie, they read like a threat.

And thanks to Jesse Vincent ("<jesse at bestpractical.com>") for his feedback, tips and refactoring! The glow-up this code got from that is real. 💅

---

🎀 COPYRIGHT & LICENSE 🎀

Copyright 2009, 2010, 2013 Christian Augustin, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🦋 (Yes, the good license. The iconic one.)

ITO Nobuaki has very graciously given me permission to take over copyright for the portions of code that are copied from or resemble his work (see rt.cpan.org #53642 <https://rt.cpan.org/Public/Bug/Display.html?id=53642>) — which is honestly such a slay of him, we love a generous king. 👑

---

And that's a wrap on UUID::Tiny(3), bestie! 🎉 You made it to the end. This version is perl v5.42.0 and it's dated 2013-09-28 — yes, an elder, but she still ate and left no crumbs. Go forth, generate those UUIDs, and remember: unique identifiers are just UUIDs with main character energy. 💜🌈

mwah 💋 — bye bestie! 🎀✨