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