README
1NAME
2 Data::Validate::URI - common url validation methods
3
4SYNOPSIS
5 use Data::Validate::URI qw(is_uri);
6
7 if(is_uri($suspect)){
8 print "Looks like an URI\n";
9 } else {
10 print "Not a URI\n";
11 }
12
13 # or as an object
14 my $v = Data::Validate::URI->new();
15
16 die "not a URI" unless ($v->is_uri('foo'));
17
18DESCRIPTION
19 This module collects common URI validation routines to make input
20 validation, and untainting easier and more readable.
21
22 All functions return an untainted value if the test passes, and undef if
23 it fails. This means that you should always check for a defined status
24 explicitly. Don't assume the return will be true.
25
26 The value to test is always the first (and often only) argument.
27
28 There are a number of other URI validation modules out there as well
29 (see below.) This one focuses on being fast, lightweight, and relatively
30 'real-world'. i.e. it's good if you want to check user input, and don't
31 need to parse out the URI/URL into chunks.
32
33 Right now the module focuses on HTTP URIs, since they're arguably the
34 most common. If you have a specialized scheme you'd like to have
35 supported, let me know.
36
37FUNCTIONS
38 new - constructor for OO usage
39 new();
40
41 *Description*
42 Returns a Data::Validator::URI object. This lets you access all
43 the validator function calls as methods without importing them
44 into your namespace or using the clumsy
45 Data::Validate::URI::function_name() format.
46
47 *Arguments*
48 None
49
50 *Returns*
51 Returns a Data::Validate::URI object
52
53 is_uri - is the value a well-formed uri?
54 is_uri($value);
55
56 *Description*
57 Returns the untainted URI if the test value appears to be
58 well-formed. Note that you may really want one of the more
59 practical methods like is_http_uri or is_https_uri, since the
60 URI standard (RFC 3986) allows a lot of things you probably
61 don't want.
62
63 *Arguments*
64
65 $value
66 The potential URI to test.
67
68 *Returns*
69 Returns the untainted URI on success, undef on failure.
70
71 *Notes, Exceptions, & Bugs*
72 This function does not make any attempt to check whether the URI
73 is accessible or 'makes sense' in any meaningful way. It just
74 checks that it is formatted correctly.
75
76 is_http_uri - is the value a well-formed HTTP uri?
77 is_http_uri($value);
78
79 *Description*
80 Specialized version of is_uri() that only likes http:// urls. As
81 a result, it can also do a much more thorough job validating.
82 Also, unlike is_uri() it is more concerned with only allowing
83 real-world URIs through. Things like relative hostnames are
84 allowed by the standards, but probably aren't wise. Conversely,
85 null paths aren't allowed per RFC 2616 (should be '/' instead),
86 but are allowed by this function.
87
88 This function only works for fully-qualified URIs. /bob.html
89 won't work. See RFC 3986 for the appropriate method to turn a
90 relative URI into an absolute one given its context.
91
92 Returns the untainted URI if the test value appears to be
93 well-formed.
94
95 Note that you probably want to either call this in combo with
96 is_https_uri(). i.e.
97
98 print "Good" if(is_http_uri($uri) || is_https_uri($uri));
99
100 or use the convenience method is_web_uri which is equivalent.
101
102 *Arguments*
103
104 $value
105 The potential URI to test.
106
107 *Returns*
108 Returns the untainted URI on success, undef on failure.
109
110 *Notes, Exceptions, & Bugs*
111 This function does not make any attempt to check whether the URI
112 is accessible or 'makes sense' in any meaningful way. It just
113 checks that it is formatted correctly.
114
115 is_https_uri - is the value a well-formed HTTPS uri?
116 is_https_uri($value);
117
118 *Description*
119 See is_http_uri() for details. This version only likes the https
120 URI scheme. Otherwise it's identical to is_http_uri()
121
122 *Arguments*
123
124 $value
125 The potential URI to test.
126
127 *Returns*
128 Returns the untainted URI on success, undef on failure.
129
130 *Notes, Exceptions, & Bugs*
131 This function does not make any attempt to check whether the URI
132 is accessible or 'makes sense' in any meaningful way. It just
133 checks that it is formatted correctly.
134
135 is_web_uri - is the value a well-formed HTTP or HTTPS uri?
136 is_web_uri($value);
137
138 *Description*
139 This is just a convinience method that combines is_http_uri and
140 is_https_uri to accept most common real-world URLs.
141
142 *Arguments*
143
144 $value
145 The potential URI to test.
146
147 *Returns*
148 Returns the untainted URI on success, undef on failure.
149
150 *Notes, Exceptions, & Bugs*
151 This function does not make any attempt to check whether the URI
152 is accessible or 'makes sense' in any meaningful way. It just
153 checks that it is formatted correctly.
154
155 is_tel_uri - is the value a well-formed telephone uri?
156 is_tel_uri($value);
157
158 *Description*
159 Specialized version of is_uri() that only likes tel: urls. As a
160 result, it can also do a much more thorough job validating
161 according to RFC 3966.
162
163 Returns the untainted URI if the test value appears to be
164 well-formed.
165
166 *Arguments*
167
168 $value
169 The potential URI to test.
170
171 *Returns*
172 Returns the untainted URI on success, undef on failure.
173
174 *Notes, Exceptions, & Bugs*
175 This function does not make any attempt to check whether the URI
176 is accessible or 'makes sense' in any meaningful way. It just
177 checks that it is formatted correctly.
178
179SEE ALSO
180 URI, RFC 3986, RFC 3966, RFC 4694, RFC 4759, RFC 4904
181
182AUTHOR
183 Richard Sonnen <sonnen@richardsonnen.com>.
184
185 is_tel_uri by David Dick <ddick@cpan.org>.
186
187COPYRIGHT
188 Copyright (c) 2005 Richard Sonnen. All rights reserved.
189
190 This program is free software; you can redistribute it and/or modify it
191 under the same terms as Perl itself.
192
193