Provided by: libuuid-tiny-perl_1.0300-2_all bug

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>).