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