phpman > perldoc > Params::Classify(3pm)

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 *TYPE*s 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 AT fysh.org>

COPYRIGHT
    Copyright (C) 2004, 2006, 2007, 2009, 2010, 2017 Andrew Main (Zefram) <zefram AT 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.