UUID::Tiny - Pure Perl UUID Support With Functional Interface
Version 1.01_06
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);
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.
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 should be thread save, because the (necessary) global variables are locked in the functions that access them. (Not tested.)
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
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:
:std
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:
:legacy
use UUID::Tiny ':legacy'; my $md5_uuid = create_UUID(UUID_V3, $str);
This module provides the NIL UUID (shown with its string representation):
UUID_NIL: '00000000-0000-0000-0000-000000000000'
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'
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:
use UUID::Tiny ':std';
UUID_TIME UUID_MD5 UUID_RANDOM UUID_SHA1
my $uuid = create_UUID( UUID_SHA1_AVAIL? UUID_V5 : UUID_V3, $str );
This function returns a positive value if a module to create SHA-1 digests could be loaded, 0 otherwise.
UUID::Tiny (since version 1.02) tries to load Digest::SHA (1), Digest::SHA1 (2) or Digest::SHA::PurePerl (3), 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.
create_UUID()
create_UUID_as_string()
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.
is_UUID_string
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.
SCALAR
GLOB
IO
IO::File
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).
Similar to create_UUID, but creates a UUID string.
create_UUID
my $bool = is_UUID_string($str);
my $uuid_str = UUID_to_string($uuid);
This function returns $uuid unchanged if it is a UUID string already.
$uuid
my $uuid = string_to_UUID($uuid_str);
This function returns $uuid_str unchanged if it is a UUID already.
$uuid_str
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.
urn:uuid:
uuid:
-
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!
my $version = version_of_UUID($uuid);
This function accepts binary and string UUIDs.
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.
int()
time()
Returns undef if the UUID is not version 1.
undef
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.
my $bool = equal_UUIDs($uuid1, $uuid2);
Returns true if the provided UUIDs are equal. Accepts UUIDs and UUID strings (can be mixed).
The random multi-cast MAC address gives privacy, and getting the real MAC address with Perl is really dirty (and slow);
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.
See RFC 4122 (http://www.ietf.org/rfc/rfc4122.txt) for technical details on UUIDs.
Much of this code is borrowed from 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 ...
Christian Augustin, <mail at caugustin.de>
<mail at caugustin.de>
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. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-uuid-tiny at rt.cpan.org
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
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/UUID-Tiny
CPAN Ratings
http://cpanratings.perl.org/d/UUID-Tiny
Search CPAN
http://search.cpan.org/dist/UUID-Tiny/
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 for his feedback and tips.
Copyright 2009 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.
To install Prophet, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Prophet
CPAN shell
perl -MCPAN -e shell install Prophet
For more information on module installation, please visit the detailed CPAN module installation guide.