File Coverage

blib/lib/String/Random/NiceURL.pm
Criterion Covered Total %
statement 22 22 100.0
branch 2 2 100.0
condition 6 6 100.0
subroutine 6 6 100.0
pod 1 1 100.0
total 37 37 100.0


line stmt bran cond sub pod time code
1             package String::Random::NiceURL;
2              
3 3     3   121415 use warnings;
  3         6  
  3         96  
4 3     3   16 use strict;
  3         5  
  3         125  
5 3     3   17 use Carp qw(croak);
  3         10  
  3         234  
6 3     3   14 use base 'Exporter';
  3         6  
  3         288  
7 3     3   19 use Scalar::Util qw(looks_like_number);
  3         6  
  3         1302  
8              
9             our @EXPORT_OK = qw(id);
10             our $VERSION = '0.02';
11              
12             # the end chars will be the first and last chars of the ID
13             # the modified base 64 chars are as follows: http://en.wikipedia.org/wiki/Base64#URL_applications
14             my @end_chars = ( 'A'..'Z', 'a'..'z', '0'..'9' );
15             my @modified_b64 = ( @end_chars, '-', '_' );
16             my $end_chars_length = scalar @end_chars;
17             my $modified_b64_length = scalar @modified_b64;
18              
19             sub id {
20 24     24 1 29004 my ($length) = @_;
21              
22             # make the arg numeric
23             # $length = int $length;
24              
25 24 100 100     309 croak "Please provide a length greater than or equal to 2"
      100        
26             unless defined $length and looks_like_number($length) and $length >= 2;
27              
28 20         31 my $str = '';
29              
30             # firstly, make up the central part using the modified base 64 chars
31 20         50 foreach ( 1..$length-2 ) {
32 90         140 my $rand = int(rand() * $modified_b64_length);
33 90         165 $str .= $modified_b64[$rand];
34             }
35              
36             # and return it with the end chars in place
37 20         222 return $end_chars[int(rand() * $end_chars_length)] . $str . $end_chars[int(rand() * $end_chars_length)];
38             }
39              
40             1;
41              
42             =head1 NAME
43              
44             String::Random::NiceURL - random ID strings suitable for URLs.
45              
46             =head1 VERSION
47              
48             Version 0.02
49              
50             =head1 SYNOPSIS
51              
52             use String::Random::NiceURL qw(id);
53             my $id = id(6);
54             print "id=$id\n";
55              
56             =head1 DESCRIPTION
57              
58             This module allows you to create sparse and distributed IDs such as those used
59             for YouTube videos. It uses the modified base 64 character set so that the IDs
60             are suitable for use in URLs. It also makes sure that the first and last chars
61             of your ID are not the dash or underscore characters (this helps some programs
62             detect the URLs correctly, for example when double-clicking to highlight the
63             text).
64              
65             Any length IDs (greater than two chars) can be created and could be used for
66             blog posts, short URLs, images, videos and many other entities.
67              
68             Other uses could be salts, session IDs, tokens when checking email addresses
69             and nonces for XSRF tokens.
70              
71             As an example, let's generate some IDs of varying lengths (just as we did in
72             the SYNOPSIS): For example, for lengths of 2, 6, 11 and 32:
73              
74             id(2) => 6p
75             id(6) => NIK_qV
76             id(11) => 2qUROkj-1X6
77             id(32) => sTQ9TP-Y-2cpKlL1f2-6VCgWvAYTZTDB
78             ...etc...
79              
80             =head1 EXPORT_OK
81              
82             =head2 id
83              
84             This is the only method provided by this module. It can be exported, or called
85             as such:
86              
87             String::Random::NiceURL::id($length)
88              
89             It returns an ID string of the specified number of characters.
90              
91             If the length if not provided, non-numeric or less than two, the function will
92             croak with a user-error message.
93              
94             =head1 THE MODIFIED BASE64 CHARACTER SET
95              
96             The normal Base64 char set includes all the characters, number and the two
97             characters (+) and (/). Since URLs don't usually like the + or / (they have to
98             be URL encoded), the modified set uses the dash (-) and underscore (_)
99             instead. There is also no use or need for (=) at the end since we are not
100             encoding a value, merely creating a random string.
101              
102             Therefore the complete set of 64 chars used is:
103              
104             A-Za-z0-9-_
105              
106             See: L for further info.
107              
108             =head1 BUGS
109              
110             Please report any bugs or feature requests to C,
111             or through the web interface at L.
112             I will be notified, and then you'll automatically be notified of progress on your
113             bug as I make changes.
114              
115             =head1 SUPPORT
116              
117             You can find documentation for this module with the perldoc command.
118              
119             perldoc String::Random::NiceURL
120              
121             You can also look for information at:
122              
123             =over 4
124              
125             =item * RT: CPAN's request tracker
126              
127             L
128              
129             =item * AnnoCPAN: Annotated CPAN documentation
130              
131             L
132              
133             =item * CPAN Ratings
134              
135             L
136              
137             =item * Search CPAN
138              
139             L
140              
141             =back
142              
143             =head1 AUTHOR, COPYRIGHT & LICENSE
144              
145             Andrew Chilton, C<< >>
146              
147             Copyright (c) 2010, Apps Attic Ltd, all rights reserved.
148              
149             L
150              
151             This module is free software. You can redistribute it and/or modify it under
152             the terms of the Artistic License 2.0.
153              
154             This program is distributed in the hope that it will be useful, but without any
155             warranty; without even the implied warranty of merchantability or fitness for a
156             particular purpose.
157              
158             =cut