|
Packit |
fc16e3 |
package Data::UUID;
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
use strict;
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
use Carp;
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
require Exporter;
|
|
Packit |
fc16e3 |
require DynaLoader;
|
|
Packit |
fc16e3 |
require Digest::MD5;
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
our @ISA = qw(Exporter DynaLoader);
|
|
Packit |
fc16e3 |
our @EXPORT = qw(
|
|
Packit |
fc16e3 |
NameSpace_DNS
|
|
Packit |
fc16e3 |
NameSpace_OID
|
|
Packit |
fc16e3 |
NameSpace_URL
|
|
Packit |
fc16e3 |
NameSpace_X500
|
|
Packit |
fc16e3 |
);
|
|
Packit |
fc16e3 |
our $VERSION = '1.221';
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
bootstrap Data::UUID $VERSION;
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
1;
|
|
Packit |
fc16e3 |
__END__
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
=head1 NAME
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
Data::UUID - Globally/Universally Unique Identifiers (GUIDs/UUIDs)
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
=head1 SEE INSTEAD?
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
The module L<Data::GUID> provides another interface for generating GUIDs.
|
|
Packit |
fc16e3 |
Right now, it relies on Data::UUID, but it may not in the future. Its
|
|
Packit |
fc16e3 |
interface may be just a little more straightforward for the average Perl
|
|
Packit |
fc16e3 |
programer.
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
=head1 SYNOPSIS
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
use Data::UUID;
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
$ug = Data::UUID->new;
|
|
Packit |
fc16e3 |
$uuid1 = $ug->create();
|
|
Packit |
fc16e3 |
$uuid2 = $ug->create_from_name(<namespace>, <name>);
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
$res = $ug->compare($uuid1, $uuid2);
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
$str = $ug->to_string( $uuid );
|
|
Packit |
fc16e3 |
$uuid = $ug->from_string( $str );
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
=head1 DESCRIPTION
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
This module provides a framework for generating v3 UUIDs (Universally Unique
|
|
Packit |
fc16e3 |
Identifiers, also known as GUIDs (Globally Unique Identifiers). A UUID is 128
|
|
Packit |
fc16e3 |
bits long, and is guaranteed to be different from all other UUIDs/GUIDs
|
|
Packit |
fc16e3 |
generated until 3400 CE.
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
UUIDs were originally used in the Network Computing System (NCS) and later in
|
|
Packit |
fc16e3 |
the Open Software Foundation's (OSF) Distributed Computing Environment.
|
|
Packit |
fc16e3 |
Currently many different technologies rely on UUIDs to provide unique identity
|
|
Packit |
fc16e3 |
for various software components. Microsoft COM/DCOM for instance, uses GUIDs
|
|
Packit |
fc16e3 |
very extensively to uniquely identify classes, applications and components
|
|
Packit |
fc16e3 |
across network-connected systems.
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
The algorithm for UUID generation, used by this extension, is described in the
|
|
Packit |
fc16e3 |
Internet Draft "UUIDs and GUIDs" by Paul J. Leach and Rich Salz. (See RFC
|
|
Packit |
fc16e3 |
4122.) It provides reasonably efficient and reliable framework for generating
|
|
Packit |
fc16e3 |
UUIDs and supports fairly high allocation rates -- 10 million per second per
|
|
Packit |
fc16e3 |
machine -- and therefore is suitable for identifying both extremely short-lived
|
|
Packit |
fc16e3 |
and very persistent objects on a given system as well as across the network.
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
This modules provides several methods to create a UUID. In all methods, C<<
|
|
Packit |
fc16e3 |
<namespace> >> is a UUID and C<< <name> >> is a free form string.
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
# creates binary (16 byte long binary value) UUID.
|
|
Packit |
fc16e3 |
$ug->create();
|
|
Packit |
fc16e3 |
$ug->create_bin();
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
# creates binary (16-byte long binary value) UUID based on particular
|
|
Packit |
fc16e3 |
# namespace and name string.
|
|
Packit |
fc16e3 |
$ug->create_from_name(<namespace>, <name>);
|
|
Packit |
fc16e3 |
$ug->create_from_name_bin(<namespace>, <name>);
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
# creates UUID string, using conventional UUID string format,
|
|
Packit |
fc16e3 |
# such as: 4162F712-1DD2-11B2-B17E-C09EFE1DC403
|
|
Packit |
fc16e3 |
# Note that digits A-F are capitalized, which is contrary to rfc4122
|
|
Packit |
fc16e3 |
$ug->create_str();
|
|
Packit |
fc16e3 |
$ug->create_from_name_str(<namespace>, <name>);
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
# creates UUID string as a hex string,
|
|
Packit |
fc16e3 |
# such as: 0x4162F7121DD211B2B17EC09EFE1DC403
|
|
Packit |
fc16e3 |
# Note that digits A-F are capitalized, which is contrary to rfc4122
|
|
Packit |
fc16e3 |
$ug->create_hex();
|
|
Packit |
fc16e3 |
$ug->create_from_name_hex(<namespace>, <name>);
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
# creates UUID string as a Base64-encoded string
|
|
Packit |
fc16e3 |
$ug->create_b64();
|
|
Packit |
fc16e3 |
$ug->create_from_name_b64(<namespace>, <name>);
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
Binary UUIDs can be converted to printable strings using following methods:
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
# convert to conventional string representation
|
|
Packit |
fc16e3 |
$ug->to_string(<uuid>);
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
# convert to hex string (using upper, rather than lower, case letters)
|
|
Packit |
fc16e3 |
$ug->to_hexstring(<uuid>);
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
# convert to Base64-encoded string
|
|
Packit |
fc16e3 |
$ug->to_b64string(<uuid>);
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
Conversly, string UUIDs can be converted back to binary form:
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
# recreate binary UUID from string
|
|
Packit |
fc16e3 |
$ug->from_string(<uuid>);
|
|
Packit |
fc16e3 |
$ug->from_hexstring(<uuid>);
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
# recreate binary UUID from Base64-encoded string
|
|
Packit |
fc16e3 |
$ug->from_b64string(<uuid>);
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
Finally, two binary UUIDs can be compared using the following method:
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
# returns -1, 0 or 1 depending on whether uuid1 less
|
|
Packit |
fc16e3 |
# than, equals to, or greater than uuid2
|
|
Packit |
fc16e3 |
$ug->compare(<uuid1>, <uuid2>);
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
Examples:
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
use Data::UUID;
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
# this creates a new UUID in string form, based on the standard namespace
|
|
Packit |
fc16e3 |
# UUID NameSpace_URL and name "www.mycompany.com"
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
$ug = Data::UUID->new;
|
|
Packit |
fc16e3 |
print $ug->create_from_name_str(NameSpace_URL, "www.mycompany.com");
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
=head2 EXPORT
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
The module allows exporting of several standard namespace UUIDs:
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
=over
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
=item NameSpace_DNS
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
=item NameSpace_URL
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
=item NameSpace_OID
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
=item NameSpace_X500
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
=back
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
=head1 AUTHOR
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
Alexander Golomshtok <agolomsh@cpan.org>
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
=head1 SEE ALSO
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
The Internet Draft "UUIDs and GUIDs" by Paul J. Leach and Rich Salz (RFC 4122)
|
|
Packit |
fc16e3 |
|
|
Packit |
fc16e3 |
=cut
|