.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Params::Classify 3pm"
.TH Params::Classify 3pm "2017-05-20" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Params::Classify \- argument type classification
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 12
\&        use Params::Classify qw(
\&                scalar_class
\&                is_undef check_undef
\&                is_string check_string
\&                is_number check_number
\&                is_glob check_glob
\&                is_regexp check_regexp
\&                is_ref check_ref ref_type
\&                is_blessed check_blessed blessed_class
\&                is_strictly_blessed check_strictly_blessed
\&                is_able check_able
\&        );
\&
\&        $c = scalar_class($arg);
\&
\&        if(is_undef($arg)) {
\&        check_undef($arg);
\&
\&        if(is_string($arg)) {
\&        check_string($arg);
\&        if(is_number($arg)) {
\&        check_number($arg);
\&
\&        if(is_glob($arg)) {
\&        check_glob($arg);
\&        if(is_regexp($arg)) {
\&        check_regexp($arg);
\&
\&        if(is_ref($arg)) {
\&        check_ref($arg);
\&        $t = ref_type($arg);
\&        if(is_ref($arg, "HASH")) {
\&        check_ref($arg, "HASH");
\&
\&        if(is_blessed($arg)) {
\&        check_blessed($arg);
\&        if(is_blessed($arg, "IO::Handle")) {
\&        check_blessed($arg, "IO::Handle");
\&        $c = blessed_class($arg);
\&        if(is_strictly_blessed($arg, "IO::Pipe::End")) {
\&        check_strictly_blessed($arg, "IO::Pipe::End");
\&        if(is_able($arg, ["print", "flush"])) {
\&        check_able($arg, ["print", "flush"]);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides various type-testing functions.  These are intended
for functions that, unlike most Perl code, care what type of data they
are operating on.  For example, some functions wish to behave differently
depending on the type of their arguments (like overloaded functions
in \*(C+).
.PP
There are two flavours of function in this module.  Functions of the first
flavour only provide type classification, to allow code to discriminate
between argument types.  Functions of the second flavour package up the
most common type of type discrimination: checking that an argument is
of an expected type.  The functions come in matched pairs, of the two
flavours, and so the type enforcement functions handle only the simplest
requirements for arguments of the types handled by the classification
functions.  Enforcement of more complex types may, of course, be built
using the classification functions, or it may be more convenient to use
a module designed for the more complex job, such as Params::Validate.
.PP
This module is implemented in \s-1XS,\s0 with a pure Perl backup version for
systems that can't handle \s-1XS.\s0
.SH "TYPE CLASSIFICATION"
.IX Header "TYPE CLASSIFICATION"
This module divides up scalar values into the following classes:
.IP "\(bu" 4
undef
.IP "\(bu" 4
string (defined ordinary scalar)
.IP "\(bu" 4
typeglob (yes, typeglobs fit into scalar variables)
.IP "\(bu" 4
regexp (first-class regular expression objects in Perl 5.11 onwards)
.IP "\(bu" 4
reference to unblessed object (further classified by physical data type
of the referenced object)
.IP "\(bu" 4
reference to blessed object (further classified by class blessed into)
.PP
These classes are mutually exclusive and should be exhaustive.  This
classification has been chosen as the most useful when one wishes to
discriminate between types of scalar.  Other classifications are possible.
(For example, the two reference classes are distinguished by a feature of
the referenced object; Perl does not internally treat this as a feature
of the reference.)
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
Each of these functions takes one scalar argument (\fI\s-1ARG\s0\fR) to be tested,
possibly with other arguments specifying details of the test.  Any scalar
value is acceptable for the argument to be tested.  Each \f(CW\*(C`is_\*(C'\fR function
returns a simple truth value result, which is true iff \fI\s-1ARG\s0\fR is of the
type being checked for.  Each \f(CW\*(C`check_\*(C'\fR function will return normally
if the argument is of the type being checked for, or will \f(CW\*(C`die\*(C'\fR if it
is not.
.SS "Classification"
.IX Subsection "Classification"
.IP "scalar_class(\s-1ARG\s0)" 4
.IX Item "scalar_class(ARG)"
Determines which of the five classes described above \fI\s-1ARG\s0\fR falls into.
Returns "\fB\s-1UNDEF\s0\fR\*(L", \*(R"\fB\s-1STRING\s0\fR\*(L", \*(R"\fB\s-1GLOB\s0\fR\*(L", \*(R"\fB\s-1REGEXP\s0\fR\*(L", \*(R"\fB\s-1REF\s0\fR\*(L", or
\&\*(R"\fB\s-1BLESSED\s0\fR" accordingly.
.SS "The Undefined Value"
.IX Subsection "The Undefined Value"
.IP "is_undef(\s-1ARG\s0)" 4
.IX Item "is_undef(ARG)"
.PD 0
.IP "check_undef(\s-1ARG\s0)" 4
.IX Item "check_undef(ARG)"
.PD
Check whether \fI\s-1ARG\s0\fR is \f(CW\*(C`undef\*(C'\fR.  \f(CW\*(C`is_undef(ARG)\*(C'\fR is precisely
equivalent to \f(CW\*(C`!defined(ARG)\*(C'\fR, and is included for completeness.
.SS "Strings"
.IX Subsection "Strings"
.IP "is_string(\s-1ARG\s0)" 4
.IX Item "is_string(ARG)"
.PD 0
.IP "check_string(\s-1ARG\s0)" 4
.IX Item "check_string(ARG)"
.PD
Check whether \fI\s-1ARG\s0\fR is defined and is an ordinary scalar value (not a
reference, typeglob, or regexp).  This is what one usually thinks of as a
string in Perl.  In fact, any scalar (including \f(CW\*(C`undef\*(C'\fR and references)
can be coerced to a string, but if you're trying to classify a scalar
then you don't want to do that.
.IP "is_number(\s-1ARG\s0)" 4
.IX Item "is_number(ARG)"
.PD 0
.IP "check_number(\s-1ARG\s0)" 4
.IX Item "check_number(ARG)"
.PD
Check whether \fI\s-1ARG\s0\fR is defined and an ordinary scalar (i.e.,
satisfies \*(L"is_string\*(R" above) and is an acceptable number to Perl.
This is what one usually thinks of as a number.
.Sp
Note that simple (\*(L"is_string\*(R"\-satisfying) scalars may have independent
numeric and string values, despite the usual pretence that they have
only one value.  Such a scalar is deemed to be a number if \fIeither\fR it
already has a numeric value (e.g., was generated by a numeric literal
or an arithmetic computation) \fIor\fR its string value has acceptable
syntax for a number (so it can be converted).  Where a scalar has
separate numeric and string values (see \*(L"dualvar\*(R" in Scalar::Util), it is
possible for it to have an acceptable numeric value while its string
value does \fInot\fR have acceptable numeric syntax.  Be careful to use
such a value only in a numeric context, if you are using it as a number.
\&\*(L"scalar_num_part\*(R" in Scalar::Number extracts the numeric part of a
scalar as an ordinary number.  (\f(CW\*(C`0+ARG\*(C'\fR suffices for that unless you
need to preserve floating point signed zeroes.)
.Sp
A number may be either a native integer or a native floating point
value, and there are several subtypes of floating point value.
For classification, and other handling of numbers in scalars, see
Scalar::Number.  For details of the two numeric data types, see
Data::Integer and Data::Float.
.Sp
This function differs from \f(CW\*(C`looks_like_number\*(C'\fR (see
\&\*(L"looks_like_number\*(R" in Scalar::Util; also \*(L"looks_like_number\*(R" in perlapi
for a lower-level description) in excluding \f(CW\*(C`undef\*(C'\fR, typeglobs,
and references.  Why \f(CW\*(C`looks_like_number\*(C'\fR returns true for \f(CW\*(C`undef\*(C'\fR
or typeglobs is anybody's guess.  References, if treated as numbers,
evaluate to the address in memory that they reference; this is useful
for comparing references for equality, but it is not otherwise useful
to treat references as numbers.  Blessed references may have overloaded
numeric operators, but if so then they don't necessarily behave like
ordinary numbers.  \f(CW\*(C`looks_like_number\*(C'\fR is also confused by dualvars:
it looks at the string portion of the scalar.
.SS "Typeglobs"
.IX Subsection "Typeglobs"
.IP "is_glob(\s-1ARG\s0)" 4
.IX Item "is_glob(ARG)"
.PD 0
.IP "check_glob(\s-1ARG\s0)" 4
.IX Item "check_glob(ARG)"
.PD
Check whether \fI\s-1ARG\s0\fR is a typeglob.
.SS "Regexps"
.IX Subsection "Regexps"
.IP "is_regexp(\s-1ARG\s0)" 4
.IX Item "is_regexp(ARG)"
.PD 0
.IP "check_regexp(\s-1ARG\s0)" 4
.IX Item "check_regexp(ARG)"
.PD
Check whether \fI\s-1ARG\s0\fR is a regexp object.
.SS "References to Unblessed Objects"
.IX Subsection "References to Unblessed Objects"
.IP "is_ref(\s-1ARG\s0)" 4
.IX Item "is_ref(ARG)"
.PD 0
.IP "check_ref(\s-1ARG\s0)" 4
.IX Item "check_ref(ARG)"
.PD
Check whether \fI\s-1ARG\s0\fR is a reference to an unblessed object.  If it
is, then the referenced data type can be determined using \f(CW\*(C`ref_type\*(C'\fR
(see below), which will return a string such as \*(L"\s-1HASH\*(R"\s0 or \*(L"\s-1SCALAR\*(R".\s0
.IP "ref_type(\s-1ARG\s0)" 4
.IX Item "ref_type(ARG)"
Returns \f(CW\*(C`undef\*(C'\fR if \fI\s-1ARG\s0\fR is not a reference to an unblessed object.
Otherwise, determines what type of object is referenced.  Returns
"\fB\s-1SCALAR\s0\fR\*(L", \*(R"\fB\s-1ARRAY\s0\fR\*(L", \*(R"\fB\s-1HASH\s0\fR\*(L", \*(R"\fB\s-1CODE\s0\fR\*(L", \*(R"\fB\s-1FORMAT\s0\fR\*(L", or \*(R"\fB\s-1IO\s0\fR"
accordingly.
.Sp
Note that, unlike \f(CW\*(C`ref\*(C'\fR, this does not distinguish between different
types of referenced scalar.  A reference to a string and a reference to
a reference will both return "\fB\s-1SCALAR\s0\fR".  Consequently, what \f(CW\*(C`ref_type\*(C'\fR
returns for a particular reference will not change due to changes in
the value of the referent, except for the referent being blessed.
.IP "is_ref(\s-1ARG, TYPE\s0)" 4
.IX Item "is_ref(ARG, TYPE)"
.PD 0
.IP "check_ref(\s-1ARG, TYPE\s0)" 4
.IX Item "check_ref(ARG, TYPE)"
.PD
Check whether \fI\s-1ARG\s0\fR is a reference to an unblessed object of type
\&\fI\s-1TYPE\s0\fR, as determined by \*(L"ref_type\*(R".  \fI\s-1TYPE\s0\fR must be a string.
Possible \fI\s-1TYPE\s0\fRs are "\fB\s-1SCALAR\s0\fR\*(L", \*(R"\fB\s-1ARRAY\s0\fR\*(L", \*(R"\fB\s-1HASH\s0\fR\*(L", \*(R"\fB\s-1CODE\s0\fR\*(L",
\&\*(R"\fB\s-1FORMAT\s0\fR\*(L", and \*(R"\fB\s-1IO\s0\fR".
.SS "References to Blessed Objects"
.IX Subsection "References to Blessed Objects"
.IP "is_blessed(\s-1ARG\s0)" 4
.IX Item "is_blessed(ARG)"
.PD 0
.IP "check_blessed(\s-1ARG\s0)" 4
.IX Item "check_blessed(ARG)"
.PD
Check whether \fI\s-1ARG\s0\fR is a reference to a blessed object.  If it is,
then the class into which the object was blessed can be determined using
\&\*(L"blessed_class\*(R".
.IP "is_blessed(\s-1ARG, CLASS\s0)" 4
.IX Item "is_blessed(ARG, CLASS)"
.PD 0
.IP "check_blessed(\s-1ARG, CLASS\s0)" 4
.IX Item "check_blessed(ARG, CLASS)"
.PD
Check whether \fI\s-1ARG\s0\fR is a reference to a blessed object that claims to
be an instance of \fI\s-1CLASS\s0\fR (via its \f(CW\*(C`isa\*(C'\fR method; see \*(L"isa\*(R" in perlobj).
\&\fI\s-1CLASS\s0\fR must be a string, naming a Perl class.
.IP "blessed_class(\s-1ARG\s0)" 4
.IX Item "blessed_class(ARG)"
Returns \f(CW\*(C`undef\*(C'\fR if \fI\s-1ARG\s0\fR is not a reference to a blessed object.
Otherwise, returns the class into which the object is blessed.
.Sp
\&\f(CW\*(C`ref\*(C'\fR (see \*(L"ref\*(R" in perlfunc) gives the same result on references
to blessed objects, but different results on other types of value.
\&\f(CW\*(C`blessed_class\*(C'\fR is actually identical to \*(L"blessed\*(R" in Scalar::Util.
.IP "is_strictly_blessed(\s-1ARG\s0)" 4
.IX Item "is_strictly_blessed(ARG)"
.PD 0
.IP "check_strictly_blessed(\s-1ARG\s0)" 4
.IX Item "check_strictly_blessed(ARG)"
.PD
Check whether \fI\s-1ARG\s0\fR is a reference to a blessed object, identically
to \*(L"is_blessed\*(R".  This exists only for symmetry; the useful form of
\&\f(CW\*(C`is_strictly_blessed\*(C'\fR appears below.
.IP "is_strictly_blessed(\s-1ARG, CLASS\s0)" 4
.IX Item "is_strictly_blessed(ARG, CLASS)"
.PD 0
.IP "check_strictly_blessed(\s-1ARG, CLASS\s0)" 4
.IX Item "check_strictly_blessed(ARG, CLASS)"
.PD
Check whether \fI\s-1ARG\s0\fR is a reference to an object blessed into \fI\s-1CLASS\s0\fR
exactly.  \fI\s-1CLASS\s0\fR must be a string, naming a Perl class.  Because this
excludes subclasses, this is rarely what one wants, but there are some
specialised occasions where it is useful.
.IP "is_able(\s-1ARG\s0)" 4
.IX Item "is_able(ARG)"
.PD 0
.IP "check_able(\s-1ARG\s0)" 4
.IX Item "check_able(ARG)"
.PD
Check whether \fI\s-1ARG\s0\fR is a reference to a blessed object, identically
to \*(L"is_blessed\*(R".  This exists only for symmetry; the useful form of
\&\f(CW\*(C`is_able\*(C'\fR appears below.
.IP "is_able(\s-1ARG, METHODS\s0)" 4
.IX Item "is_able(ARG, METHODS)"
.PD 0
.IP "check_able(\s-1ARG, METHODS\s0)" 4
.IX Item "check_able(ARG, METHODS)"
.PD
Check whether \fI\s-1ARG\s0\fR is a reference to a blessed object that claims to
implement the methods specified by \fI\s-1METHODS\s0\fR (via its \f(CW\*(C`can\*(C'\fR method;
see \*(L"can\*(R" in perlobj).  \fI\s-1METHODS\s0\fR must be either a single method name or
a reference to an array of method names.  Each method name is a string.
This interface check is often more appropriate than a direct ancestry
check (such as \*(L"is_blessed\*(R" performs).
.SH "BUGS"
.IX Header "BUGS"
Probably ought to handle something like Params::Validate's scalar
type specification system, which makes much the same distinctions.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Data::Float,
Data::Integer,
Params::Validate,
Scalar::Number,
Scalar::Util
.SH "AUTHOR"
.IX Header "AUTHOR"
Andrew Main (Zefram) <zefram@fysh.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2004, 2006, 2007, 2009, 2010
Andrew Main (Zefram) <zefram@fysh.org>
.PP
Copyright (C) 2009, 2010 PhotoBox Ltd
.SH "LICENSE"
.IX Header "LICENSE"
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.