Documentation and interface tweaking, preparation for release

.gitignore

@@ -1,3 +1,2 @@
 Makefile
 inc
-libb64

Changes

@@ -0,0 +1,2 @@
+0.01 Wednesday June 10 09:52:38 PDT 2009:
+    - Initial release

MANIFEST

@@ -2,3 +2,18 @@ Changes
 MANIFEST
 Makefile.PL
 README
+inc/Module/AutoInstall.pm
+inc/Module/Install.pm
+inc/Module/Install/AutoInstall.pm
+inc/Module/Install/Base.pm
+inc/Module/Install/Can.pm
+inc/Module/Install/Fetch.pm
+inc/Module/Install/Include.pm
+inc/Module/Install/Makefile.pm
+inc/Module/Install/Metadata.pm
+inc/Module/Install/Win32.pm
+inc/Module/Install/WriteAll.pm
+lib/Data/TUID.pm
+META.yml
+t/00-load.t
+t/01-basic.t

Makefile.PL

@@ -26,6 +26,8 @@ Test::Most
 _END_
 
     map { my ($pk, $vr) = split m/\s/; requires $pk => $vr || 0 } grep { ! /^\s*#/ } split m/\n/, <<_END_;
+Encode::Base32::Crockford
+Data::UUID::LibUUID
 _END_
 }
 

README

@@ -4,6 +4,64 @@ NAME
 VERSION
     Version 0.01
 
+SYNOPSIS
+        use Data::TUID
+
+        my $tuid = tuid             # Generate a TUID of (default) length 8
+        $tuid = tuid length => 4    # Generate a TUID of length 4
+        $tuid = Data::TUID->tuid    # Generate a TUID with the default length
+
+        $tuid = tuid uuid => '1bf4d967-9e4c-4414-9be0-26f31c16fb53' # Generate a TUID based of the give UUID
+
+    A sample run (length 4):
+
+    rrry ggf5 m1qb xczx pv9y
+
+    A sample run (length 8):
+
+    5xcfw8nj 2q255fyg pn3xns4k 1xcamd3y eczzca9c
+
+    A sample run (no length limit):
+
+    2kdk8wzjmfapj28cvexj6qndq7 2tmzr1f3k46tr813dtrxx2vhkqkd
+    1x3608c39mb1n726dhmxedjy72d pre6tg2dm37zbw9amxg2c8bghn
+    3ys0kw21rmtpf54gsmnd28r99pj
+
+DESCRIPTION
+    Data::TUID is a tool for creating small, communicable pseudo-unique
+    identifiers. Essentially it will take a UUID, pass the result through
+    Encode::Base32::Crockford, and resize accordingly (via "substr")
+
+    Although I've tried to sample the UUID evenly, this technique does not
+    give any guarantee on uniqueness. Caveat emptor.
+
+    Finally, the result is more communicable (and smaller) due to the
+    Crockford base 32 encoding. The Crockford technique uses:
+
+        A case-insensitive mapping
+        1 in place of '1','I', 'i', and 'L'
+        0 in place of '0', 'O', and 'o'
+
+    So, given a TUID (say something a user typed in for a URL), you can
+    translate ambiguous characters (1, I, i, L, 0, 0, and o) into to 1 and
+    0.
+
+USAGE
+Data::TUID->tuid( ... )
+Data::TUID::tuid( ... )
+tuid ...
+    The arguments are:
+
+        uuid    The UUID to use as a basis for the TUID. If none is given, one will be generated for you
+
+        length  The length of the TUID returned. By default 8. A length of -1 will result in the whole
+                UUID being used, and a variable length TUID being returned (somewhere between 25 to 28)
+
+SEE ALSO
+    Encode::Base32::Crockford
+
+    Data::UUID::LibUUID
+
 AUTHOR
     Robert Krimen, "<rkrimen at cpan.org>"
 

lib/Data/TUID.pm

@@ -11,20 +11,95 @@ Data::TUID - A smaller and more communicable pseudo-UUID
 
 Version 0.01
 
+=head1 SYNOPSIS
+
+    use Data::TUID
+
+    my $tuid = tuid             # Generate a TUID of (default) length 8
+    $tuid = tuid length => 4    # Generate a TUID of length 4
+    $tuid = Data::TUID->tuid    # Generate a TUID with the default length
+
+    $tuid = tuid uuid => '1bf4d967-9e4c-4414-9be0-26f31c16fb53' # Generate a TUID based of the give UUID
+
+A sample run (length 4):
+
+rrry
+ggf5
+m1qb
+xczx
+pv9y
+
+A sample run (length 8):
+
+5xcfw8nj
+2q255fyg
+pn3xns4k
+1xcamd3y
+eczzca9c
+
+A sample run (no length limit):
+
+2kdk8wzjmfapj28cvexj6qndq7
+2tmzr1f3k46tr813dtrxx2vhkqkd
+1x3608c39mb1n726dhmxedjy72d
+pre6tg2dm37zbw9amxg2c8bghn
+3ys0kw21rmtpf54gsmnd28r99pj
+
+=head1 DESCRIPTION
+
+Data::TUID is a tool for creating small, communicable pseudo-unique identifiers. Essentially it
+will take a UUID, pass the result through L<Encode::Base32::Crockford>, and resize accordingly (via
+C<substr>)
+
+Although I've tried to sample the UUID evenly, this technique does not give any guarantee on uniqueness. Caveat emptor.
+
+Finally, the result is more communicable (and smaller) due to the Crockford base 32 encoding. The Crockford technique
+uses:
+
+    A case-insensitive mapping
+    1 in place of '1','I', 'i', and 'L'
+    0 in place of '0', 'O', and 'o'
+
+So, given a TUID (say something a user typed in for a URL), you can translate ambiguous characters (1, I, i, L, 0, 0, and o) into to 1 and 0.
+
+=head1 USAGE
+
+=head1 Data::TUID->tuid( ... )
+
+=head1 Data::TUID::tuid( ... )
+
+=head1 tuid ...
+
+The arguments are:
+
+    uuid    The UUID to use as a basis for the TUID. If none is given, one will be generated for you
+
+    length  The length of the TUID returned. By default 8. A length of -1 will result in the whole
+            UUID being used, and a variable length TUID being returned (somewhere between 25 to 28)
+            
+=head1 SEE ALSO
+
+L<Encode::Base32::Crockford>
+
+L<Data::UUID::LibUUID>
+
 =cut
 
 our $VERSION = '0.01';
+use vars qw/@ISA @EXPORT/; @ISA = qw/Exporter/; @EXPORT = qw/tuid/;
 
 use Encode::Base32::Crockford qw/base32_encode/;
 use Data::UUID::LibUUID qw/new_uuid_binary uuid_to_binary/;
 
-sub generate {
-    return shift->tuid( @_ );
-}
-
 sub tuid {
-    my $self = shift;
-    my %given = @_;
+    shift if @_ && $_[0] eq __PACKAGE__;
+    my %given;
+    if ( @_ == 1 ) {
+        %given = ( length => shift );
+    }
+    else {
+        %given = @_;
+    }
 
     my $uuid = $given{uuid} || new_uuid_binary;
     $uuid = uuid_to_binary $uuid;

t/01-basic.t

@@ -15,5 +15,9 @@ is( length Data::TUID->tuid( size => 2 ), 8 );
 is( length Data::TUID->tuid( length => 5 ), 5 );
 is( length Data::TUID->tuid( length => 20 ), 20 );
 is( length Data::TUID->tuid( size => 5 ), 20 );
+is( length Data::TUID->tuid( 5 ), 5 );
+is( length Data::TUID->tuid( 20 ), 20 );
+is( length tuid, 8 );
+is( length tuid( 20 ), 20 );
 
-warn Data::TUID::->tuid( length => -1 );
+#warn length tuid( length => -1 ), "\n" for 0 .. 30;