NAME¶
UUID::Tiny - Pure Perl UUID Support With Functional Interface
VERSION¶
Version 1.03
SYNOPSIS¶
Create version 1, 3, 4 and 5 UUIDs:
use UUID::Tiny;
my $v1_mc_UUID = create_UUID();
my $v3_md5_UUID = create_UUID(UUID_V3, $str);
my $v3_md5_UUID = create_UUID(UUID_V3, UUID_NS_DNS, 'caugustin.de');
my $v4_rand_UUID = create_UUID(UUID_V4);
my $v5_sha1_UUID = create_UUID(UUID_V5, $str);
my $v5_with_NS_UUID = create_UUID(UUID_V5, 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. This module provides the creation of 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.
ATTENTION! UUID::Tiny uses Perl's "rand()" to create the basic random
numbers, so the created v4 UUIDs are
not cryptographically strong!
No fancy OO interface, no plethora of different UUID representation formats and
transformations - just string and binary. Conversion, test and time functions
equally accept UUIDs and UUID strings, so don't bother to convert UUIDs for
them!
All constants and public functions are exported by default, because if you
didn't need/want them, you wouldn't use this module ...
UUID::Tiny deliberately uses a minimal functional interface for UUID creation
(and conversion/testing), because in this case OO looks like overkill to me
and makes the creation and use of UUIDs unnecessarily complicated.
If you need raw performance for UUID creation, or the real MAC address in
version 1 UUIDs, or an OO interface, and if you can afford module compilation
and installation on the target system, then better look at other CPAN UUID
modules like Data::UUID.
This module is "fork safe", especially for random UUIDs (it works
around Perl's
rand() problem when forking processes).
This module should be "thread safe," because its global variables are
locked in the functions that access them. (Not tested - if you can provide
some tests, please tell me!)
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 (IN PREPARATION FOR V2.00)¶
After some debate I'm 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.
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 the upcoming version 2.00 of UUID::Tiny you should use the
":legacy" tag if you want to stay with the version 1.0x 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.
FUNCTIONS¶
All public functions are exported by default (they should not collide with other
functions).
"create_UUID()" creates standard binary UUIDs in network byte order
(MSB first), "create_UUID_as_string()" creates the standard string
represantion of UUIDs.
All query and test functions (except "is_UUID_string") accept both
representations.
- 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.
I found no hint if and how UUIDs should be created from file content. It
seems to be undefined, but it is useful - so I would suggest 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.
- is_UUID_string(),
is_uuid_string() (:std)
-
my $bool = is_UUID_string($str);
- 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.
- 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.
Throws an exception if string can't be interpreted as a UUID.
If you want to make shure 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.
- 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).
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);
- Should version 3 or version 5 be used?
- Using SHA-1 reduces the probabillity 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.
UUID DEFINITION¶
See RFC 4122 (<
http://www.ietf.org/rfc/rfc4122.txt>) for technical details
on UUIDs.
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 I decided to reduce it to the necessary parts and to re-implement those parts
with a functional interface ...
Jesse Vincent, "<jesse at bestpractical.com>", improved version
1.02 with his tips and a heavy refactoring.
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
<
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=UUID-Tiny>. I will be
notified, and then you'll automatically be notified of progress on your bug as
I make changes.
SUPPORT¶
You can find documentation for this module with the perldoc command.
perldoc UUID::Tiny
You can also look for information at:
- •
- RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=UUID-Tiny
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=UUID-Tiny>
- •
- AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/UUID-Tiny
<http://annocpan.org/dist/UUID-Tiny>
- •
- CPAN Ratings
http://cpanratings.perl.org/d/UUID-Tiny
<http://cpanratings.perl.org/d/UUID-Tiny>
- •
- Search CPAN
http://search.cpan.org/dist/UUID-Tiny/
<http://search.cpan.org/dist/UUID-Tiny/>
ACKNOWLEDGEMENTS¶
Kudos to ITO Nobuaki <banb@cpan.org> for his UUID::Generator::PurePerl
module! My work is based on his code, and without it I would've been lost with
all those incomprehensible RFC texts and C codes ...
Thanks to Jesse Vincent ("<jesse at bestpractical.com>") for his
feedback, tips and refactoring!
COPYRIGHT & LICENSE¶
Copyright 2009, 2010 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.
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>).