add WebGUI::GUID and make WebGUI::Session::Id a wrapper around that

lib/WebGUI/GUID.pm

@@ -0,0 +1,130 @@
+package WebGUI::GUID;
+
+
+=head1 LEGAL
+
+ -------------------------------------------------------------------
+  WebGUI is Copyright 2001-2009 Plain Black Corporation.
+ -------------------------------------------------------------------
+  Please read the legal notices (docs/legal.txt) and the license
+  (docs/license.txt) that came with this distribution before using
+  this software.
+ -------------------------------------------------------------------
+  http://www.plainblack.com                     info@plainblack.com
+ -------------------------------------------------------------------
+
+=cut
+
+use strict;
+use WebGUI::BestPractices;
+use MIME::Base64::URLSafe;
+use UUID::Tiny;
+
+my $idValidator = qr/^[A-Za-z0-9_-]{22}$/;
+
+=head1 NAME
+
+Package WebGUI::GUID;
+
+=head1 DESCRIPTION
+
+This package generates global unique ids, sometimes called GUIDs. A global unique ID is guaranteed to be unique everywhere and at everytime.
+
+B<NOTE:> There is no such thing as perfectly unique ID's, but the chances of a duplicate ID are so minute that they are effectively unique.
+
+=head1 SYNOPSIS
+
+ my $id = WebGUI::GUID->generate;
+
+=head1 METHODS
+
+These methods are available from this class:
+
+=cut
+
+#-------------------------------------------------------------------
+
+=head2 fromHex ( hexId )
+
+Returns the guid corresponding to hexId.  Converse of toHex.
+
+=head3 hexId
+
+Hex value to convert to guid.
+
+=cut
+
+sub fromHex {
+    shift;
+    my $hexId = shift;
+    my $binId = pack( 'H2' x 16, unpack( 'A2' x 16, $hexId ) );
+    my $id    = substr( urlsafe_b64encode($binId), 0, 22 );
+    return $id;
+}
+
+#-------------------------------------------------------------------
+
+=head2 getValidator
+
+Get the regular expression used to validate generated GUIDs.  This is just to prevent
+regular expressions from being duplicated all over the place.
+
+=cut
+
+sub getValidator {
+    return $idValidator;
+}
+
+#-------------------------------------------------------------------
+
+=head2 generate
+
+This function generates a global unique id.
+
+=cut
+
+sub generate {
+    shift;
+    return urlsafe_b64encode( create_UUID( UUID_V4 ) );
+}
+
+#-------------------------------------------------------------------
+
+=head2 toHex ( guid )
+
+Returns the hex value of a guid.  For all GUIDs generated by the generate method, the return value will be 32 characters long.  For some manually created invalid GUIDs, it may be 33 characters long.
+
+=head3 guid
+
+guid to convert to hex value.
+
+=cut
+
+sub toHex {
+    shift;
+    my $id   = shift;
+    $id .= 'AA';
+    my $bin_id = urlsafe_b64decode($id);
+    my $hex_id = unpack("H*", $bin_id);
+    $hex_id =~ s/0{3,4}$//;
+    return $hex_id;
+}
+
+
+#-------------------------------------------------------------------
+
+=head2 valid ( $idString )
+
+Returns true if $idString is a valid WebGUI guid.
+
+=cut
+
+sub valid {
+    shift;
+    my $idString = shift;
+    return $idString =~ m/$idValidator/;
+}
+
+
+1;
+