1UUID::Tiny(3)         User Contributed Perl Documentation        UUID::Tiny(3)
2
3
4

NAME

6       UUID::Tiny - Pure Perl UUID Support With Functional Interface
7

VERSION

9       Version 1.04
10

SYNOPSIS

12       Create version 1, 3, 4 and 5 UUIDs:
13
14           use UUID::Tiny ':std';
15
16           my $v1_mc_UUID      = create_uuid();
17           my $v1_mc_UUID_2    = create_uuid(UUID_V1);
18           my $v1_mc_UUID_3    = create_uuid(UUID_TIME);
19           my $v3_md5_UUID     = create_uuid(UUID_V3, $str);
20           my $v3_md5_UUID_2   = create_uuid(UUID_MD5, UUID_NS_DNS, 'caugustin.de');
21           my $v4_rand_UUID    = create_uuid(UUID_V4);
22           my $v4_rand_UUID_2  = create_uuid(UUID_RANDOM);
23           my $v5_sha1_UUID    = create_uuid(UUID_V5, $str);
24           my $v5_with_NS_UUID = create_uuid(UUID_SHA1, UUID_NS_DNS, 'caugustin.de');
25
26           my $v1_mc_UUID_string  = create_uuid_as_string(UUID_V1);
27           my $v3_md5_UUID_string = uuid_to_string($v3_md5_UUID);
28
29           if ( version_of_uuid($v1_mc_UUID) == 1   ) { ... };
30           if ( version_of_uuid($v5_sha1_UUID) == 5 ) { ... };
31           if ( is_uuid_string($v1_mc_UUID_string)  ) { ... };
32           if ( equal_uuids($uuid1, $uuid2)         ) { ... };
33
34           my $uuid_time    = time_of_uuid($v1_mc_UUID);
35           my $uuid_clk_seq = clk_seq_of_uuid($v1_mc_UUID);
36

DESCRIPTION

38       UUID::Tiny is a lightweight, low dependency Pure Perl module for UUID
39       creation and testing. This module provides the creation of version 1
40       time based UUIDs (using random multicast MAC addresses), version 3 MD5
41       based UUIDs, version 4 random UUIDs, and version 5 SHA-1 based UUIDs.
42
43       ATTENTION! UUID::Tiny uses Perl's rand() to create the basic random
44       numbers, so the created v4 UUIDs are not cryptographically strong!
45
46       No fancy OO interface, no plethora of different UUID representation
47       formats and transformations - just string and binary. Conversion, test
48       and time functions equally accept UUIDs and UUID strings, so don't
49       bother to convert UUIDs for them!
50
51       Continuing with 1.0x versions all constants and public functions are
52       exported by default, but this will change in the future (see below).
53
54       UUID::Tiny deliberately uses a minimal functional interface for UUID
55       creation (and conversion/testing), because in this case OO looks like
56       overkill to me and makes the creation and use of UUIDs unnecessarily
57       complicated.
58
59       If you need raw performance for UUID creation, or the real MAC address
60       in version 1 UUIDs, or an OO interface, and if you can afford module
61       compilation and installation on the target system, then better look at
62       other CPAN UUID modules like Data::UUID.
63
64       This module is "fork safe", especially for random UUIDs (it works
65       around Perl's rand() problem when forking processes).
66
67       This module is currently not "thread safe". Even though I've
68       incorporated some changes proposed by Michael G. Schwern (thanks!),
69       Digest::MD5 and Digest::SHA seem so have trouble with threads. There is
70       a test file for threads, but it is de-activated. So use at your own
71       risk!
72

DEPENDENCIES

74       This module should run from Perl 5.8 up and uses mostly standard (5.8
75       core) modules for its job. No compilation or installation required.
76       These are the modules UUID::Tiny depends on:
77
78           Carp
79           Digest::MD5   Perl 5.8 core
80           Digest::SHA   Perl 5.10 core (or Digest::SHA1, or Digest::SHA::PurePerl)
81           MIME::Base64  Perl 5.8 core
82           Time::HiRes   Perl 5.8 core
83           POSIX         Perl 5.8 core
84
85       If you are using this module on a Perl prior to 5.10 and you don't have
86       Digest::SHA1 installed, you can use Digest::SHA::PurePerl instead.
87

ATTENTION! NEW STANDARD INTERFACE

89       After some debate I'm convinced that it is more Perlish (and far easier
90       to write) to use all-lowercase function names - without exceptions. And
91       that it is more polite to export symbols only on demand.
92
93       While the 1.0x versions will continue to export the old, "legacy"
94       interface on default, the future standard interface is available using
95       the ":std" tag on import from version 1.02 on:
96
97           use UUID::Tiny ':std';
98           my $md5_uuid = create_uuid(UUID_MD5, $str);
99
100       In preparation for future version of UUID::Tiny you have to use the
101       ":legacy" tag if you want to stay with the version 1.0 interface:
102
103           use UUID::Tiny ':legacy';
104           my $md5_uuid = create_UUID(UUID_V3, $str);
105

CONSTANTS

107       NIL UUID
108           This module provides the NIL UUID (shown with its string
109           representation):
110
111               UUID_NIL: '00000000-0000-0000-0000-000000000000'
112
113       Pre-defined Namespace UUIDs
114           This module provides the common pre-defined namespace UUIDs (shown
115           with their string representation):
116
117               UUID_NS_DNS:  '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
118               UUID_NS_URL:  '6ba7b811-9dad-11d1-80b4-00c04fd430c8'
119               UUID_NS_OID:  '6ba7b812-9dad-11d1-80b4-00c04fd430c8'
120               UUID_NS_X500: '6ba7b814-9dad-11d1-80b4-00c04fd430c8'
121
122       UUID versions
123           This module provides the UUID version numbers as constants:
124
125               UUID_V1
126               UUID_V3
127               UUID_V4
128               UUID_V5
129
130           With "use UUID::Tiny ':std';" you get additional, "speaking"
131           constants:
132
133               UUID_TIME
134               UUID_MD5
135               UUID_RANDOM
136               UUID_SHA1
137
138       UUID_SHA1_AVAIL
139               my $uuid = create_UUID( UUID_SHA1_AVAIL? UUID_V5 : UUID_V3, $str );
140
141           This function returns 1 if a module to create SHA-1 digests could
142           be loaded, 0 otherwise.
143
144           UUID::Tiny (since version 1.02) tries to load Digest::SHA,
145           Digest::SHA1 or Digest::SHA::PurePerl, but does not die if none of
146           them is found. Instead create_UUID() and create_UUID_as_string()
147           die when trying to create an SHA-1 based UUID without an
148           appropriate module available.
149

FUNCTIONS

151       All public functions are exported by default (they should not collide
152       with other functions).
153
154       create_UUID() creates standard binary UUIDs in network byte order (MSB
155       first), create_UUID_as_string() creates the standard string
156       representation of UUIDs.
157
158       All query and test functions (except "is_UUID_string") accept both
159       representations.
160
161       create_UUID(), create_uuid() (:std)
162               my $v1_mc_UUID   = create_UUID();
163               my $v1_mc_UUID   = create_UUID(UUID_V1);
164               my $v3_md5_UUID  = create_UUID(UUID_V3, $ns_uuid, $name_or_filehandle);
165               my $v3_md5_UUID  = create_UUID(UUID_V3, $name_or_filehandle);
166               my $v4_rand_UUID = create_UUID(UUID_V4);
167               my $v5_sha1_UUID = create_UUID(UUID_V5, $ns_uuid, $name_or_filehandle);
168               my $v5_sha1_UUID = create_UUID(UUID_V5, $name_or_filehandle);
169
170           Creates a binary UUID in network byte order (MSB first). For v3 and
171           v5 UUIDs a "SCALAR" (normally a string), "GLOB" ("classic" file
172           handle) or "IO" object (i.e. "IO::File") can be used; files have to
173           be opened for reading.
174
175           I found no hint if and how UUIDs should be created from file
176           content. It seems to be undefined, but it is useful - so I would
177           suggest to use UUID_NIL as the namespace UUID, because no "real
178           name" is used; UUID_NIL is used by default if a namespace UUID is
179           missing (only 2 arguments are used).
180
181       create_UUID_as_string(), create_uuid_as_string() (:std)
182           Similar to "create_UUID", but creates a UUID string.
183
184       is_UUID_string(), is_uuid_string() (:std)
185               my $bool = is_UUID_string($str);
186
187       UUID_to_string(), uuid_to_string() (:std)
188               my $uuid_str = UUID_to_string($uuid);
189
190           This function returns $uuid unchanged if it is a UUID string
191           already.
192
193       string_to_UUID(), string_to_uuid() (:std)
194               my $uuid = string_to_UUID($uuid_str);
195
196           This function returns $uuid_str unchanged if it is a UUID already.
197
198           In addition to the standard UUID string representation and its URN
199           forms (starting with "urn:uuid:" or "uuid:"), this function accepts
200           32 digit hex strings, variants with different positions of "-" and
201           Base64 encoded UUIDs.
202
203           Throws an exception if string can't be interpreted as a UUID.
204
205           If you want to make sure to have a "pure" standard UUID
206           representation, check with "is_UUID_string"!
207
208       version_of_UUID(), version_of_uuid() (:std)
209               my $version = version_of_UUID($uuid);
210
211           This function accepts binary and string UUIDs.
212
213       time_of_UUID(), time_of_uuid() (:std)
214               my $uuid_time = time_of_UUID($uuid);
215
216           This function accepts UUIDs and UUID strings. Returns the time as a
217           floating point value, so use int() to get a time() compatible
218           value.
219
220           Returns "undef" if the UUID is not version 1.
221
222       clk_seq_of_UUID(), clk_seq_of_uuid() (:std)
223               my $uuid_clk_seq = clk_seq_of_UUID($uuid);
224
225           This function accepts UUIDs and UUID strings. Returns the clock
226           sequence for a version 1 UUID. Returns "undef" if UUID is not
227           version 1.
228
229       equal_UUIDs(), equal_uuids() (:std)
230               my $bool = equal_UUIDs($uuid1, $uuid2);
231
232           Returns true if the provided UUIDs are equal. Accepts UUIDs and
233           UUID strings (can be mixed).
234

DISCUSSION

236       Why version 1 only with random multi-cast MAC addresses?
237           The random multi-cast MAC address gives privacy, and getting the
238           real MAC address with Perl is really dirty (and slow);
239
240       Should version 3 or version 5 be used?
241           Using SHA-1 reduces the probability of collisions and provides a
242           better "randomness" of the resulting UUID compared to MD5. Version
243           5 is recommended in RFC 4122 if backward compatibility is not an
244           issue.
245
246           Using MD5 (version 3) has a better performance. This could be
247           important with creating UUIDs from file content rather than names.
248

UUID DEFINITION

250       See RFC 4122 (<http://www.ietf.org/rfc/rfc4122.txt>) for technical
251       details on UUIDs. Wikipedia gives a more palatable description at
252       <http://en.wikipedia.org/wiki/Universally_unique_identifier>.
253

AUTHOR

255       Christian Augustin, "<mail at caugustin.de>"
256

CONTRIBUTORS

258       Some of this code is based on UUID::Generator by ITO Nobuaki
259       <banb@cpan.org>. But that module is announced to be marked as
260       "deprecated" in the future and it is much too complicated for my
261       liking.
262
263       So I decided to reduce it to the necessary parts and to re-implement
264       those parts with a functional interface ...
265
266       Jesse Vincent, "<jesse at bestpractical.com>", improved version 1.02
267       with his tips and a heavy refactoring.
268
269       Michael G. Schwern provided a patch for better thread support (as far
270       as UUID::Tiny can be improved itself) that is incorporated in version
271       1.04.
272

BUGS

274       Please report any bugs or feature requests to "bug-uuid-tiny at
275       rt.cpan.org", or through the web interface at
276       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=UUID-Tiny>.  I will be
277       notified, and then you'll automatically be notified of progress on your
278       bug as I make changes.
279

SUPPORT

281       You can find documentation for this module with the perldoc command.
282
283           perldoc UUID::Tiny
284
285       You can also look for information at:
286
287       •   RT: CPAN's request tracker
288
289           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=UUID-Tiny>
290
291       •   AnnoCPAN: Annotated CPAN documentation
292
293           <http://annocpan.org/dist/UUID-Tiny>
294
295       •   CPAN Ratings
296
297           <http://cpanratings.perl.org/d/UUID-Tiny>
298
299       •   Search CPAN
300
301           <http://search.cpan.org/dist/UUID-Tiny/>
302

ACKNOWLEDGEMENTS

304       Kudos to ITO Nobuaki <banb@cpan.org> for his UUID::Generator::PurePerl
305       module! My work is based on his code, and without it I would've been
306       lost with all those incomprehensible RFC texts and C codes ...
307
308       Thanks to Jesse Vincent ("<jesse at bestpractical.com>") for his
309       feedback, tips and refactoring!
310
312       Copyright 2009, 2010, 2013 Christian Augustin, all rights reserved.
313
314       This program is free software; you can redistribute it and/or modify it
315       under the same terms as Perl itself.
316
317       ITO Nobuaki has very graciously given me permission to take over
318       copyright for the portions of code that are copied from or resemble his
319       work (see rt.cpan.org #53642
320       <https://rt.cpan.org/Public/Bug/Display.html?id=53642>).
321
322
323
324perl v5.38.0                      2023-07-21                     UUID::Tiny(3)
Impressum