1package Data::UUID;
2
3use strict;
4
5use Carp;
6use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
7
8require Exporter;
9require DynaLoader;
10require AutoLoader;
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.148';
23
24# Preloaded methods go here.
25
26sub AUTOLOAD {
27    # This AUTOLOAD is used to 'autoload' constants from the constant()
28    # XS function.  If a constant is not found then control is passed
29    # to the AUTOLOAD in AutoLoader.
30
31    my $constname;
32    our $AUTOLOAD;
33    ($constname = $AUTOLOAD) =~ s/.*:://;
34    croak "& not defined" if $constname eq 'constant';
35    my $val = constant($constname, @_ ? $_[0] : 0);
36    if ($! != 0) {
37      if ($! =~ /Invalid/ || $!{EINVAL}) {
38        $AutoLoader::AUTOLOAD = $AUTOLOAD;
39        goto &AutoLoader::AUTOLOAD;
40      } else {
41        croak "Your vendor has not defined Data::UUID macro $constname";
42      }
43    }
44    {
45      no strict 'refs';
46      # Fixed between 5.005_53 and 5.005_61
47      *$AUTOLOAD = sub { $val };
48    }
49    goto &$AUTOLOAD;
50}
51
52bootstrap Data::UUID $VERSION;
53
54# Autoload methods go after =cut, and are processed by the autosplit program.
55
561;
57__END__
58# Below is the stub of documentation for your module. You better edit it!
59
60=head1 NAME
61
62Data::UUID - Perl extension for generating Globally/Universally
63Unique Identifiers (GUIDs/UUIDs).
64
65=head1 SYNOPSIS
66
67  use Data::UUID;
68
69  $ug    = new Data::UUID;
70  $uuid1 = $ug->create();
71  $uuid2 = $ug->create_from_name(<namespace>, <name>);
72
73  $res   = $ug->compare($uuid1, $uuid2);
74
75  $str   = $ug->to_string( $uuid );
76  $uuid  = $ug->from_string( $str );
77
78=head1 DESCRIPTION
79
80This module provides a framework for generating UUIDs (Universally Unique
81Identifiers, also known as GUIDs (Globally Unique Identifiers). A UUID is 128
82bits long, and is guaranteed to be different from all other UUIDs/GUIDs
83generated until 3400 CE.
84
85UUIDs were originally used in the Network Computing System (NCS) and later in
86the Open Software Foundation's (OSF) Distributed Computing Environment.
87Currently many different technologies rely on UUIDs to provide unique identity
88for various software components. Microsoft COM/DCOM for instance, uses GUIDs
89very extensively to uniquely identify classes, applications and components
90across network-connected systems.
91
92The algorithm for UUID generation, used by this extension, is described in the
93Internet Draft "UUIDs and GUIDs" by Paul J. Leach and Rich Salz
94(L<http://hegel.ittc.ku.edu/topics/internet/internet-drafts/draft-l/draft-leach-uuids-guids-01.txt>).
95It provides reasonably efficient and reliable framework for generating UUIDs
96and supports fairly high allocation rates -- 10 million per second per machine
97-- and therefore is suitable for identifying both extremely short-lived and
98very persistent objects on a given system as well as across the network.
99
100This modules provides several methods to create a UUID:
101
102   # creates binary (16 byte long binary value) UUID.
103   $ug->create();
104   $ug->create_bin();
105
106   # creates binary (16-byte long binary value) UUID based on particular
107   # namespace and name string.
108   $ug->create_from_name(<namespace>, <name>);
109   $ug->create_from_name_bin(<namespace>, <name>);
110
111   # creates UUID string, using conventional UUID string format,
112   # such as: 4162F712-1DD2-11B2-B17E-C09EFE1DC403
113   $ug->create_str();
114   $ug->create_from_name_str(<namespace>, <name>);
115
116   # creates UUID string as a hex string,
117   # such as: 0x4162F7121DD211B2B17EC09EFE1DC403
118   $ug->create_hex();
119   $ug->create_from_name_hex(<namespace>, <name>);
120
121   # creates UUID string as a Base64-encoded string
122   $ug->create_b64();
123   $ug->create_from_name_b64(<namespace>, <name>);
124
125   Binary UUIDs can be converted to printable strings using following methods:
126
127   # convert to conventional string representation
128   $ug->to_string(<uuid>);
129
130   # convert to hex string
131   $ug->to_hexstring(<uuid>);
132
133   # convert to Base64-encoded string
134   $ug->to_b64string(<uuid>);
135
136   Conversly, string UUIDs can be converted back to binary form:
137
138   # recreate binary UUID from string
139   $ug->from_string(<uuid>);
140   $ug->from_hexstring(<uuid>);
141
142   # recreate binary UUID from Base64-encoded string
143   $ug->from_b64string(<uuid>);
144
145   Finally, two binary UUIDs can be compared using the following method:
146
147   # returns -1, 0 or 1 depending on whether uuid1 less
148   # than, equals to, or greater than uuid2
149   $ug->compare(<uuid1>, <uuid2>);
150
151Examples:
152
153   use Data::UUID qw(:all);
154
155   # this creates a new UUID in string form, based on the standard namespace
156   # UUID NameSpace_URL and name "www.mycompany.com"
157
158   $ug = new Data::UUID;
159   print $ug->create_from_name_str(NameSpace_URL, "www.mycompany.com");
160
161=head2 EXPORT
162
163The module allows exporting of several standard namespace UUIDs:
164
165=over
166
167=item NameSpace_DNS
168
169=item NameSpace_URL
170
171=item NameSpace_OID
172
173=item NameSpace_X500
174
175=back
176
177=head1 AUTHOR
178
179Alexander Golomshtok <agolomsh@cpan.org>
180
181=head1 SEE ALSO
182
183The Internet Draft "UUIDs and GUIDs" by Paul J. Leach and Rich Salz:
184L<http://www.globecom.net/ietf/draft/draft-leach-uuids-guids-01.html>
185"Primary Key Reengineering Projects: The Problem" by Tom Johnston
186L<http://www.dmreview.com/editorial/dmreview/print_action.cfm?EdID=1866>
187"Primary Key Reengineering Projects: The Solution" by Tom Johnston
188L<http://www.dmreview.com/editorial/dmreview/print_action.cfm?EdID=2004>
189=cut
190