Provided by: libparams-classify-perl_0.015-2build5_amd64 bug

NAME

       Params::Classify - argument type classification

SYNOPSIS

           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"]);

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++).

       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.

       This module is implemented in XS, with a pure Perl backup version for systems that can't handle XS.

TYPE CLASSIFICATION

       This module divides up scalar values into the following classes:

       •   undef

       •   string (defined ordinary scalar)

       •   typeglob (yes, typeglobs fit into scalar variables)

       •   regexp (first-class regular expression objects in Perl 5.11 onwards)

       •   reference to unblessed object (further classified by physical data type of the referenced object)

       •   reference to blessed object (further classified by class blessed into)

       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.)

FUNCTIONS

       Each of these functions takes one scalar argument (ARG) to  be  tested,  possibly  with  other  arguments
       specifying  details  of  the  test.   Any scalar value is acceptable for the argument to be tested.  Each
       "is_" function returns a simple truth value result, which is true iff ARG is of the  type  being  checked
       for.   Each  "check_"  function will return normally if the argument is of the type being checked for, or
       will "die" if it is not.

   Classification
       scalar_class(ARG)
           Determines which of the five classes described above ARG  falls  into.   Returns  "UNDEF",  "STRING",
           "GLOB", "REGEXP", "REF", or "BLESSED" accordingly.

   The Undefined Value
       is_undef(ARG)
       check_undef(ARG)
           Check  whether  ARG  is  "undef".   is_undef(ARG)  is precisely equivalent to "!defined(ARG)", and is
           included for completeness.

   Strings
       is_string(ARG)
       check_string(ARG)
           Check whether ARG 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 "undef" 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.

       is_number(ARG)
       check_number(ARG)
           Check whether ARG is defined and an ordinary scalar (i.e., satisfies "is_string"  above)  and  is  an
           acceptable number to Perl.  This is what one usually thinks of as a number.

           Note  that  simple  ("is_string"-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
           either  it  already  has  a  numeric value (e.g., was generated by a numeric literal or an arithmetic
           computation) or its string value has acceptable syntax for a number (so it can be converted).   Where
           a  scalar  has separate numeric and string values (see "dualvar" in Scalar::Util), it is possible for
           it to have an acceptable numeric value while its  string  value  does  not  have  acceptable  numeric
           syntax.   Be  careful to use such a value only in a numeric context, if you are using it as a number.
           "scalar_num_part" in Scalar::Number extracts the numeric part of a  scalar  as  an  ordinary  number.
           ("0+ARG" suffices for that unless you need to preserve floating point signed zeroes.)

           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.

           This  function  differs  from  "looks_like_number"  (see  "looks_like_number"  in  Scalar::Util; also
           "looks_like_number" in perlapi for a lower-level description) in excluding  "undef",  typeglobs,  and
           references.   Why  "looks_like_number"  returns  true  for  "undef"  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.  "looks_like_number" is also confused by dualvars: it looks
           at the string portion of the scalar.

   Typeglobs
       is_glob(ARG)
       check_glob(ARG)
           Check whether ARG is a typeglob.

   Regexps
       is_regexp(ARG)
       check_regexp(ARG)
           Check whether ARG is a regexp object.

   References to Unblessed Objects
       is_ref(ARG)
       check_ref(ARG)
           Check whether ARG is a reference to an unblessed object.  If it is, then the referenced data type can
           be determined using "ref_type" (see below), which will return a string such as "HASH" or "SCALAR".

       ref_type(ARG)
           Returns "undef" if ARG is not a reference to an unblessed object.  Otherwise, determines what type of
           object is referenced.  Returns "SCALAR", "ARRAY", "HASH", "CODE", "FORMAT", or "IO" accordingly.

           Note  that,  unlike "ref", this does not distinguish between different types of referenced scalar.  A
           reference to a string and a reference to a reference will both return "SCALAR".   Consequently,  what
           "ref_type"  returns  for  a  particular  reference will not change due to changes in the value of the
           referent, except for the referent being blessed.

       is_ref(ARG, TYPE)
       check_ref(ARG, TYPE)
           Check whether ARG is a reference to an unblessed object of type TYPE, as  determined  by  "ref_type".
           TYPE must be a string.  Possible TYPEs are "SCALAR", "ARRAY", "HASH", "CODE", "FORMAT", and "IO".

   References to Blessed Objects
       is_blessed(ARG)
       check_blessed(ARG)
           Check whether ARG is a reference to a blessed object.  If it is, then the class into which the object
           was blessed can be determined using "blessed_class".

       is_blessed(ARG, CLASS)
       check_blessed(ARG, CLASS)
           Check  whether ARG is a reference to a blessed object that claims to be an instance of CLASS (via its
           "isa" method; see "isa" in perlobj).  CLASS must be a string, naming a Perl class.

       blessed_class(ARG)
           Returns "undef" if ARG is not a reference to a blessed object.  Otherwise,  returns  the  class  into
           which the object is blessed.

           "ref"  (see  "ref" in perlfunc) gives the same result on references to blessed objects, but different
           results on other types of value.  "blessed_class" is actually identical to "blessed" in Scalar::Util.

       is_strictly_blessed(ARG)
       check_strictly_blessed(ARG)
           Check whether ARG is a reference to a blessed object, identically to "is_blessed".  This exists  only
           for symmetry; the useful form of "is_strictly_blessed" appears below.

       is_strictly_blessed(ARG, CLASS)
       check_strictly_blessed(ARG, CLASS)
           Check  whether  ARG  is a reference to an object blessed into CLASS exactly.  CLASS 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.

       is_able(ARG)
       check_able(ARG)
           Check  whether ARG is a reference to a blessed object, identically to "is_blessed".  This exists only
           for symmetry; the useful form of "is_able" appears below.

       is_able(ARG, METHODS)
       check_able(ARG, METHODS)
           Check whether ARG is a reference to a blessed object that claims to implement the  methods  specified
           by METHODS (via its "can" method; see "can" in perlobj).  METHODS 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 "is_blessed" performs).

BUGS

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

SEE ALSO

       Data::Float, Data::Integer, Params::Validate, Scalar::Number, Scalar::Util

AUTHOR

       Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

       Copyright (C) 2004, 2006, 2007, 2009, 2010, 2017 Andrew Main (Zefram) <zefram@fysh.org>

       Copyright (C) 2009, 2010 PhotoBox Ltd

LICENSE

       This  module  is  free  software;  you  can redistribute it and/or modify it under the same terms as Perl
       itself.

perl v5.38.2                                       2024-03-31                              Params::Classify(3pm)