Debian Codegraph @

README

raw
1 NAME
2 Data::Validate - common data validation methods
3
4 SYNOPSIS
5 use Data::Validate wq(:math);
6
7 if(defined(is_integer($suspect))){
8 print "Looks like an integer\n";
9 }
10
11 my $name = is_alphanumeric($suspect);
12 if(defined($name)){
13 print "$name is alphanumeric, and has been untainted\n";
14 } else {
15 print "$suspect was not alphanumeric"
16 }
17
18 # or as an object
19 my $v = Data::Validate->new();
20
21 die "'foo' is not an integer" unless defined($v->is_integer('foo'));
22
23 DESCRIPTION
24 This module collects common validation routines to make input
25 validation, and untainting easier and more readable. Most of the
26 functions are not much shorter than their direct perl equivalent (and
27 are much longer in some cases), but their names make it clear what
28 you're trying to test for.
29
30 Almost all functions return an untainted value if the test passes, and
31 undef if it fails. This means that you should always check for a defined
32 status explicitly. Don't assume the return will be true. (e.g.
33 is_integer(0))
34
35 The value to test is always the first (and often only) argument.
36
37 FUNCTIONS
38 new - constructor for OO usage
39 new();
40
41 *Description*
42 Returns a Data::Validator object. This lets you access all the
43 validator function calls as methods without importing them into
44 your namespace or using the clumsy
45 Data::Validate::function_name() format.
46
47 *Arguments*
48 None
49
50 *Returns*
51 Returns a Data::Validate object
52
53 is_integer - is the value an integer?
54 is_integer($value);
55
56 *Description*
57 Returns the untainted number if the test value is an integer, or
58 can be cast to one without a loss of precision. (i.e. 1.0 is
59 considered an integer, but 1.0001 is not.)
60
61 *Arguments*
62
63 $value
64 The potential integer to test.
65
66 *Returns*
67 Returns the untainted integer on success, undef on failure. Note
68 that the return can be 0, so always check with defined()
69
70 *Notes, Exceptions, & Bugs*
71 Number translation is done by POSIX casting tools (strtol).
72
73 is_numeric - is the value numeric?
74 is_numeric($value);
75
76 *Description*
77 Returns the untainted number if the test value is numeric, or
78 can be cast to a number without a any bits being left over.
79 (i.e. 1.0 is considered a number, 1.0hello is not.)
80
81 *Arguments*
82
83 $value
84 The potential number to test.
85
86 *Returns*
87 Returns the untainted number on success, undef on failure. Note
88 that the return can be 0, so always check with defined()
89
90 *Notes, Exceptions, & Bugs*
91 Number translation is done by POSIX casting tools (strtol).
92
93 is_hex - is the value a hex number?
94 is_hex($value);
95
96 *Description*
97 Returns the untainted number if the test value is a hex number.
98
99 *Arguments*
100
101 $value
102 The potential number to test.
103
104 *Returns*
105 Returns the untainted number on success, undef on failure. Note
106 that the return can be 0, so always check with defined()
107
108 *Notes, Exceptions, & Bugs*
109 None
110
111 is_oct - is the value an octal number?
112 is_oct($value);
113
114 *Description*
115 Returns the untainted number if the test value is a octal
116 number.
117
118 *Arguments*
119
120 $value
121 The potential number to test.
122
123 *Returns*
124 Returns the untainted number on success, undef on failure. Note
125 that the return can be 0, so always check with defined()
126
127 *Notes, Exceptions, & Bugs*
128 None
129
130 is_between - is the value between to numbers?
131 is_between($value, $min, $max);
132
133 *Description*
134 Returns the untainted number if the test value is numeric, and
135 falls between $min and $max inclusive. Note that either $min or
136 $max can be undef, which means 'unlimited'. i.e.
137 is_between($val, 0, undef) would pass for any number zero or
138 larger.
139
140 *Arguments*
141
142 $value
143 The potential number to test.
144
145 $min
146 The minimum valid value. Unlimited if set to undef
147
148 $max
149 The maximum valid value. Unlimited if set to undef
150
151 *Returns*
152 Returns the untainted number on success, undef on failure. Note
153 that the return can be 0, so always check with defined()
154
155 is_greater_than - is the value greater than a threshold?
156 is_greater_than($value, $threshold);
157
158 *Description*
159 Returns the untainted number if the test value is numeric, and
160 is greater than $threshold. (not inclusive)
161
162 *Arguments*
163
164 $value
165 The potential number to test.
166
167 $threshold
168 The minimum value (non-inclusive)
169
170 *Returns*
171 Returns the untainted number on success, undef on failure. Note
172 that the return can be 0, so always check with defined()
173
174 is_less_than - is the value less than a threshold?
175 is_less_than($value, $threshold);
176
177 *Description*
178 Returns the untainted number if the test value is numeric, and
179 is less than $threshold. (not inclusive)
180
181 *Arguments*
182
183 $value
184 The potential number to test.
185
186 $threshold
187 The maximum value (non-inclusive)
188
189 *Returns*
190 Returns the untainted number on success, undef on failure. Note
191 that the return can be 0, so always check with defined()
192
193 is_equal_to - do a string/number neutral ==
194 is_equal_to($value, $target);
195
196 *Description*
197 Returns the target if $value is equal to it. Does a math
198 comparison if both $value and $target are numeric, or a string
199 comparison otherwise. Both the $value and $target must be
200 defined to get a true return. (i.e. undef != undef)
201
202 *Arguments*
203
204 $value
205 The value to test.
206
207 $target
208 The value to test against
209
210 *Returns*
211 Unlike most validator routines, this one does not necessarily
212 untaint its return value, it just returns $target. This has the
213 effect of untainting if the target is a constant or other clean
214 value. (i.e. is_equal_to($bar, 'foo')). Note that the return can
215 be 0, so always check with defined()
216
217 is_even - is a number even?
218 is_even($value);
219
220 *Description*
221 Returns the untainted $value if it's numeric, an integer, and
222 even.
223
224 *Arguments*
225
226 $value
227 The value to test.
228
229 *Returns*
230 Returns $value (untainted). Note that the return can be 0, so
231 always check with defined().
232
233 is_odd - is a number odd?
234 is_odd($value);
235
236 *Description*
237 Returns the untainted $value if it's numeric, an integer, and
238 odd.
239
240 *Arguments*
241
242 $value
243 The value to test.
244
245 *Returns*
246 Returns $value (untainted). Note that the return can be 0, so
247 always check with defined().
248
249 is_alphanumeric - does it only contain letters and numbers?
250 is_alphanumeric($value);
251
252 *Description*
253 Returns the untainted $value if it is defined and only contains
254 letters (upper or lower case) and numbers. Also allows an empty
255 string - ''.
256
257 *Arguments*
258
259 $value
260 The value to test.
261
262 *Returns*
263 Returns $value (untainted). Note that the return can be 0, so
264 always check with defined().
265
266 is_printable - does it only contain printable characters?
267 is_alphanumeric($value);
268
269 *Description*
270 Returns the untainted $value if it is defined and only contains
271 printable characters as defined by the composite POSIX character
272 class [[:print:][:space:]]. Also allows an empty string - ''.
273
274 *Arguments*
275
276 $value
277 The value to test.
278
279 *Returns*
280 Returns $value (untainted). Note that the return can be 0, so
281 always check with defined().
282
283 length_is_between - is the string length between two limits?
284 length_is_between($value, $min, $max);
285
286 *Description*
287 Returns $value if it is defined and its length is between $min
288 and $max inclusive. Note that this function does not untaint the
289 value.
290
291 If either $min or $max are undefined they are treated as
292 no-limit.
293
294 *Arguments*
295
296 $value
297 The value to test.
298
299 $min
300 The minimum length of the string (inclusive).
301
302 $max
303 The maximum length of the string (inclusive).
304
305 *Returns*
306 Returns $value. Note that the return can be 0, so always check
307 with defined(). The value is not automatically untainted.
308
309 AUTHOR
310 Richard Sonnen <[email protected]>.
311
312 COPYRIGHT
313 Copyright (c) 2004 Richard Sonnen. All rights reserved.
314
315 This program is free software; you can redistribute it and/or modify it
316 under the same terms as Perl itself.
317