1package Data::UUID;
2
3use strict;
4
5use Carp;
6use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
7
8require Exporter;
9require DynaLoader;
10require Digest::MD5;
11
12@ISA = qw(Exporter DynaLoader);
13# Items to export into callers namespace by default. Note: do not export
14# names by default without a very good reason. Use EXPORT_OK instead.
15# Do not simply export all your public functions/methods/constants.
16@EXPORT = qw(
17   NameSpace_DNS
18   NameSpace_OID
19   NameSpace_URL
20   NameSpace_X500
21);
22$VERSION = '1.218';
23
24bootstrap Data::UUID $VERSION;
25
261;
27__END__
28
29=head1 NAME
30
31Data::UUID - Perl extension for generating Globally/Universally
32Unique Identifiers (GUIDs/UUIDs).
33
34=head1 SYNOPSIS
35
36  use Data::UUID;
37
38  $ug    = new Data::UUID;
39  $uuid1 = $ug->create();
40  $uuid2 = $ug->create_from_name(<namespace>, <name>);
41
42  $res   = $ug->compare($uuid1, $uuid2);
43
44  $str   = $ug->to_string( $uuid );
45  $uuid  = $ug->from_string( $str );
46
47=head1 DESCRIPTION
48
49This module provides a framework for generating v3 UUIDs (Universally Unique
50Identifiers, also known as GUIDs (Globally Unique Identifiers). A UUID is 128
51bits long, and is guaranteed to be different from all other UUIDs/GUIDs
52generated until 3400 CE.
53
54UUIDs were originally used in the Network Computing System (NCS) and later in
55the Open Software Foundation's (OSF) Distributed Computing Environment.
56Currently many different technologies rely on UUIDs to provide unique identity
57for various software components. Microsoft COM/DCOM for instance, uses GUIDs
58very extensively to uniquely identify classes, applications and components
59across network-connected systems.
60
61The algorithm for UUID generation, used by this extension, is described in the
62Internet Draft "UUIDs and GUIDs" by Paul J. Leach and Rich Salz.  (See RFC
634122.)  It provides reasonably efficient and reliable framework for generating
64UUIDs and supports fairly high allocation rates -- 10 million per second per
65machine -- and therefore is suitable for identifying both extremely short-lived
66and very persistent objects on a given system as well as across the network.
67
68This modules provides several methods to create a UUID:
69
70   # creates binary (16 byte long binary value) UUID.
71   $ug->create();
72   $ug->create_bin();
73
74   # creates binary (16-byte long binary value) UUID based on particular
75   # namespace and name string.
76   $ug->create_from_name(<namespace>, <name>);
77   $ug->create_from_name_bin(<namespace>, <name>);
78
79   # creates UUID string, using conventional UUID string format,
80   # such as: 4162F712-1DD2-11B2-B17E-C09EFE1DC403
81   $ug->create_str();
82   $ug->create_from_name_str(<namespace>, <name>);
83
84   # creates UUID string as a hex string,
85   # such as: 0x4162F7121DD211B2B17EC09EFE1DC403
86   $ug->create_hex();
87   $ug->create_from_name_hex(<namespace>, <name>);
88
89   # creates UUID string as a Base64-encoded string
90   $ug->create_b64();
91   $ug->create_from_name_b64(<namespace>, <name>);
92
93   Binary UUIDs can be converted to printable strings using following methods:
94
95   # convert to conventional string representation
96   $ug->to_string(<uuid>);
97
98   # convert to hex string
99   $ug->to_hexstring(<uuid>);
100
101   # convert to Base64-encoded string
102   $ug->to_b64string(<uuid>);
103
104   Conversly, string UUIDs can be converted back to binary form:
105
106   # recreate binary UUID from string
107   $ug->from_string(<uuid>);
108   $ug->from_hexstring(<uuid>);
109
110   # recreate binary UUID from Base64-encoded string
111   $ug->from_b64string(<uuid>);
112
113   Finally, two binary UUIDs can be compared using the following method:
114
115   # returns -1, 0 or 1 depending on whether uuid1 less
116   # than, equals to, or greater than uuid2
117   $ug->compare(<uuid1>, <uuid2>);
118
119Examples:
120
121   use Data::UUID;
122
123   # this creates a new UUID in string form, based on the standard namespace
124   # UUID NameSpace_URL and name "www.mycompany.com"
125
126   $ug = new Data::UUID;
127   print $ug->create_from_name_str(NameSpace_URL, "www.mycompany.com");
128
129=head2 EXPORT
130
131The module allows exporting of several standard namespace UUIDs:
132
133=over
134
135=item NameSpace_DNS
136
137=item NameSpace_URL
138
139=item NameSpace_OID
140
141=item NameSpace_X500
142
143=back
144
145=head1 AUTHOR
146
147Alexander Golomshtok <agolomsh@cpan.org>
148
149=head1 SEE ALSO
150
151The Internet Draft "UUIDs and GUIDs" by Paul J. Leach and Rich Salz (RFC 4122)
152
153=cut
154