1Params::Classify(3)   User Contributed Perl Documentation  Params::Classify(3)
2
3
4

NAME

6       Params::Classify - argument type classification
7

SYNOPSIS

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);
22
23           if(is_undef($arg)) {
24           check_undef($arg);
25
26           if(is_string($arg)) {
27           check_string($arg);
28           if(is_number($arg)) {
29           check_number($arg);
30
31           if(is_glob($arg)) {
32           check_glob($arg);
33           if(is_regexp($arg)) {
34           check_regexp($arg);
35
36           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
42           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

DESCRIPTION

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
59       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
71       This module is implemented in XS, with a pure Perl backup version for
72       systems that can't handle XS.
73

TYPE CLASSIFICATION

75       This module divides up scalar values into the following classes:
76
77       •   undef
78
79       •   string (defined ordinary scalar)
80
81       •   typeglob (yes, typeglobs fit into scalar variables)
82
83       •   regexp (first-class regular expression objects in Perl 5.11
84           onwards)
85
86       •   reference to unblessed object (further classified by physical data
87           type of the referenced object)
88
89       •   reference to blessed object (further classified by class blessed
90           into)
91
92       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

FUNCTIONS

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
108   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
114   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
120   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
129       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
135           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
150           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
156           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
169   Typeglobs
170       is_glob(ARG)
171       check_glob(ARG)
172           Check whether ARG is a typeglob.
173
174   Regexps
175       is_regexp(ARG)
176       check_regexp(ARG)
177           Check whether ARG is a regexp object.
178
179   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
186       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
191           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
198       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
205   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
212       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
218       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
222           "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
226       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
232       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
239       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
245       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

BUGS

255       Probably ought to handle something like Params::Validate's scalar type
256       specification system, which makes much the same distinctions.
257

SEE ALSO

259       Data::Float, Data::Integer, Params::Validate, Scalar::Number,
260       Scalar::Util
261

AUTHOR

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
269       Copyright (C) 2009, 2010 PhotoBox Ltd
270

LICENSE

272       This module is free software; you can redistribute it and/or modify it
273       under the same terms as Perl itself.
274
275
276
277perl v5.36.0                      2023-01-20               Params::Classify(3)
Impressum