1Params::Classify(3) User Contributed Perl Documentation Params::Classify(3)
2
6 Params::Classify - argument type classification
7
9 use Params::Classify qw(
10 scalar_class
11 is_undef check_undef
12 is_string check_string
13 is_number check_number
14 is_glob check_glob
15 is_regexp check_regexp
16 is_ref check_ref ref_type
17 is_blessed check_blessed blessed_class
18 is_strictly_blessed check_strictly_blessed
19 is_able check_able
20 );
21 $c = scalar_class($arg);
23 if(is_undef($arg)) {
25 check_undef($arg);
26 if(is_string($arg)) {
28 check_string($arg);
29 if(is_number($arg)) {
30 check_number($arg);
31 if(is_glob($arg)) {
33 check_glob($arg);
34 if(is_regexp($arg)) {
35 check_regexp($arg);
36 if(is_ref($arg)) {
38 check_ref($arg);
39 $t = ref_type($arg);
40 if(is_ref($arg, "HASH")) {
41 check_ref($arg, "HASH");
42 if(is_blessed($arg)) {
44 check_blessed($arg);
45 if(is_blessed($arg, "IO::Handle")) {
46 check_blessed($arg, "IO::Handle");
47 $c = blessed_class($arg);
48 if(is_strictly_blessed($arg, "IO::Pipe::End")) {
49 check_strictly_blessed($arg, "IO::Pipe::End");
50 if(is_able($arg, ["print", "flush"])) {
51 check_able($arg, ["print", "flush"]);
52
54 This module provides various type-testing functions. These are
55 intended for functions that, unlike most Perl code, care what type of
56 data they are operating on. For example, some functions wish to behave
57 differently depending on the type of their arguments (like overloaded
58 functions in C++).
59 There are two flavours of function in this module. Functions of the
61 first flavour only provide type classification, to allow code to
62 discriminate between argument types. Functions of the second flavour
63 package up the most common type of type discrimination: checking that
64 an argument is of an expected type. The functions come in matched
65 pairs, of the two flavours, and so the type enforcement functions
66 handle only the simplest requirements for arguments of the types
67 handled by the classification functions. Enforcement of more complex
68 types may, of course, be built using the classification functions, or
69 it may be more convenient to use a module designed for the more complex
70 job, such as Params::Validate.
71 This module is implemented in XS, with a pure Perl backup version for
73 systems that can't handle XS.
74
76 This module divides up scalar values into the following classes:
77 · undef
79 · string (defined ordinary scalar)
81 · typeglob (yes, typeglobs fit into scalar variables)
83 · regexp (first-class regular expression objects in Perl 5.11
85 onwards)
86 · reference to unblessed object (further classified by physical data
88 type of the referenced object)
89 · reference to blessed object (further classified by class blessed
91 into)
92 These classes are mutually exclusive and should be exhaustive. This
94 classification has been chosen as the most useful when one wishes to
95 discriminate between types of scalar. Other classifications are
96 possible. (For example, the two reference classes are distinguished by
97 a feature of the referenced object; Perl does not internally treat this
98 as a feature of the reference.)
99
101 Each of these functions takes one scalar argument (ARG) to be tested,
102 possibly with other arguments specifying details of the test. Any
103 scalar value is acceptable for the argument to be tested. Each "is_"
104 function returns a simple truth value result, which is true iff ARG is
105 of the type being checked for. Each "check_" function will return
106 normally if the argument is of the type being checked for, or will
107 "die" if it is not.
108 Classification
110 scalar_class(ARG)
111 Determines which of the five classes described above ARG falls
112 into. Returns "UNDEF", "STRING", "GLOB", "REGEXP", "REF", or
113 "BLESSED" accordingly.
114 The Undefined Value
116 is_undef(ARG)
117 check_undef(ARG)
118 Check whether ARG is "undef". "is_undef(ARG)" is precisely
119 equivalent to "!defined(ARG)", and is included for completeness.
120 Strings
122 is_string(ARG)
123 check_string(ARG)
124 Check whether ARG is defined and is an ordinary scalar value (not a
125 reference, typeglob, or regexp). This is what one usually thinks
126 of as a string in Perl. In fact, any scalar (including "undef" and
127 references) can be coerced to a string, but if you're trying to
128 classify a scalar then you don't want to do that.
129 is_number(ARG)
131 check_number(ARG)
132 Check whether ARG is defined and an ordinary scalar (i.e.,
133 satisfies "is_string" above) and is an acceptable number to Perl.
134 This is what one usually thinks of as a number.
135 Note that simple ("is_string"-satisfying) scalars may have
137 independent numeric and string values, despite the usual pretence
138 that they have only one value. Such a scalar is deemed to be a
139 number if either it already has a numeric value (e.g., was
140 generated by a numeric literal or an arithmetic computation) or its
141 string value has acceptable syntax for a number (so it can be
142 converted). Where a scalar has separate numeric and string values
143 (see "dualvar" in Scalar::Util), it is possible for it to have an
144 acceptable numeric value while its string value does not have
145 acceptable numeric syntax. Be careful to use such a value only in
146 a numeric context, if you are using it as a number.
147 "scalar_num_part" in Scalar::Number extracts the numeric part of a
148 scalar as an ordinary number. ("0+ARG" suffices for that unless
149 you need to preserve floating point signed zeroes.)
150 A number may be either a native integer or a native floating point
152 value, and there are several subtypes of floating point value. For
153 classification, and other handling of numbers in scalars, see
154 Scalar::Number. For details of the two numeric data types, see
155 Data::Integer and Data::Float.
156 This function differs from "looks_like_number" (see
158 "looks_like_number" in Scalar::Util; also "looks_like_number" in
159 perlapi for a lower-level description) in excluding "undef",
160 typeglobs, and references. Why "looks_like_number" returns true
161 for "undef" or typeglobs is anybody's guess. References, if
162 treated as numbers, evaluate to the address in memory that they
163 reference; this is useful for comparing references for equality,
164 but it is not otherwise useful to treat references as numbers.
165 Blessed references may have overloaded numeric operators, but if so
166 then they don't necessarily behave like ordinary numbers.
167 "looks_like_number" is also confused by dualvars: it looks at the
168 string portion of the scalar.
169 Typeglobs
171 is_glob(ARG)
172 check_glob(ARG)
173 Check whether ARG is a typeglob.
174 Regexps
176 is_regexp(ARG)
177 check_regexp(ARG)
178 Check whether ARG is a regexp object.
179 References to Unblessed Objects
181 is_ref(ARG)
182 check_ref(ARG)
183 Check whether ARG is a reference to an unblessed object. If it is,
184 then the referenced data type can be determined using "ref_type"
185 (see below), which will return a string such as "HASH" or "SCALAR".
186 ref_type(ARG)
188 Returns "undef" if ARG is not a reference to an unblessed object.
189 Otherwise, determines what type of object is referenced. Returns
190 "SCALAR", "ARRAY", "HASH", "CODE", "FORMAT", or "IO" accordingly.
191 Note that, unlike "ref", this does not distinguish between
193 different types of referenced scalar. A reference to a string and
194 a reference to a reference will both return "SCALAR".
195 Consequently, what "ref_type" returns for a particular reference
196 will not change due to changes in the value of the referent, except
197 for the referent being blessed.
198 is_ref(ARG, TYPE)
200 check_ref(ARG, TYPE)
201 Check whether ARG is a reference to an unblessed object of type
202 TYPE, as determined by "ref_type". TYPE must be a string.
203 Possible TYPEs are "SCALAR", "ARRAY", "HASH", "CODE", "FORMAT", and
204 "IO".
205 References to Blessed Objects
207 is_blessed(ARG)
208 check_blessed(ARG)
209 Check whether ARG is a reference to a blessed object. If it is,
210 then the class into which the object was blessed can be determined
211 using "blessed_class".
212 is_blessed(ARG, CLASS)
214 check_blessed(ARG, CLASS)
215 Check whether ARG is a reference to a blessed object that claims to
216 be an instance of CLASS (via its "isa" method; see "isa" in
217 perlobj). CLASS must be a string, naming a Perl class.
218 blessed_class(ARG)
220 Returns "undef" if ARG is not a reference to a blessed object.
221 Otherwise, returns the class into which the object is blessed.
222 "ref" (see "ref" in perlfunc) gives the same result on references
224 to blessed objects, but different results on other types of value.
225 "blessed_class" is actually identical to "blessed" in Scalar::Util.
226 is_strictly_blessed(ARG)
228 check_strictly_blessed(ARG)
229 Check whether ARG is a reference to a blessed object, identically
230 to "is_blessed". This exists only for symmetry; the useful form of
231 "is_strictly_blessed" appears below.
232 is_strictly_blessed(ARG, CLASS)
234 check_strictly_blessed(ARG, CLASS)
235 Check whether ARG is a reference to an object blessed into CLASS
236 exactly. CLASS must be a string, naming a Perl class. Because
237 this excludes subclasses, this is rarely what one wants, but there
238 are some specialised occasions where it is useful.
239 is_able(ARG)
241 check_able(ARG)
242 Check whether ARG is a reference to a blessed object, identically
243 to "is_blessed". This exists only for symmetry; the useful form of
244 "is_able" appears below.
245 is_able(ARG, METHODS)
247 check_able(ARG, METHODS)
248 Check whether ARG is a reference to a blessed object that claims to
249 implement the methods specified by METHODS (via its "can" method;
250 see "can" in perlobj). METHODS must be either a single method name
251 or a reference to an array of method names. Each method name is a
252 string. This interface check is often more appropriate than a
253 direct ancestry check (such as "is_blessed" performs).
254
256 Probably ought to handle something like Params::Validate's scalar type
257 specification system, which makes much the same distinctions.
258
260 Data::Float, Data::Integer, Params::Validate, Scalar::Number,
261 Scalar::Util
262
264 Andrew Main (Zefram) <zefram@fysh.org>
265
267 Copyright (C) 2004, 2006, 2007, 2009, 2010 Andrew Main (Zefram)
268 <zefram@fysh.org>
269 Copyright (C) 2009, 2010 PhotoBox Ltd
271
273 This module is free software; you can redistribute it and/or modify it
274 under the same terms as Perl itself.
275perl v5.12.2 2010-11-06 Params::Classify(3)