Params::Classify - argument type classification

        use Params::Classify qw(scalar_class
                is_undef
                is_string is_number
                is_glob
                is_ref ref_type
                is_blessed blessed_class
                is_strictly_blessed is_able);

        $c = scalar_class($foo);

        $ok = is_undef($foo);

        $ok = is_string($foo);
        $ok = is_number($foo);

        $ok = is_glob($foo);

        $ok = is_ref($foo);
        $t = ref_type($foo);
        $ok = is_ref($foo, "HASH");

        $ok = is_blessed($foo);
        $ok = is_blessed($foo, "IO::Handle");
        $c = blessed_class($foo);
        $ok = is_strictly_blessed($foo, "IO::Pipe::End");
        $ok = is_able($foo, ["print", "flush"]);

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

These functions only provide type classification; they do not enforce type restrictions. Type enforcement may, of course, be built using these classification functions, but the reader's attention is drawn to Params::Validate.

This module divides up scalar values into the following classes:

•

undef

•

string (defined ordinary scalar)

•

typeglob

•

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

Each of these functions takes one scalar argument to be tested, possibly with other arguments specifying details of the test. Any scalar value is acceptable for the argument to be tested (called ARG below). Each is_ function returns a simple boolean result.

scalar_class(ARG)

Determines which of the five classes described above ARG falls into. Returns UNDEF, STRING, GLOB, REF, or BLESSED accordingly.

is_undef(ARG)

Returns true iff ARG is CWundef. This is precisely equivalent to CW!defined(ARG), and is included for completeness.

is_string(ARG)

This returns true iff ARG is defined and is an ordinary scalar value (not a reference or a typeglob). This is what one usually thinks of as a string in Perl. In fact, any scalar (including CWundef 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)

This returns true iff ARG is defined and an ordinary scalar (i.e., satisfies CWis_string above) and is an acceptable number to Perl. This is what one usually thinks of as a number. This differs from CWlooks_like_number (see looks_like_number in Scalar::Util; also looks_like_number in perlapi for a lower-level description) in excluding CWundef, typeglobs, and references. Why CWlooks_like_number returns true for CWundef 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. Note that simple (CWis_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. CW0+ARG is sufficient to collapse it to an ordinary number if you want the numeric value in string form.

is_glob(ARG)

Returns true iff ARG is a typeglob. Yes, typeglobs fit into scalar variables.

is_ref(ARG)

Returns true iff ARG is a reference to an unblessed object. If it is, then the referenced data type can be determined using CWref_type (see below), which will return a string such as HASH or SCALAR.

ref_type(ARG)

Returns CWundef 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 CWref, 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 CWref_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)

TYPE must be a string. Returns true iff ARG is a reference to an unblessed object of type TYPE, as determined by CWref_type (above). Possible TYPEs are SCALAR, ARRAY, HASH, CODE, FORMAT, and IO.

is_blessed(ARG)

Returns true iff ARG is a reference to a blessed object. If it is, then the class into which the object was blessed can be determined using CWblessed_class (see below).

is_blessed(ARG, CLASS)

CLASS must be a string. Returns true iff ARG is a reference to a blessed object that claims to be an instance of CLASS (via its CWisa method; see isa in perlobj).

blessed_class(ARG)

Returns CWundef if ARG is not a reference to a blessed object. Otherwise, returns the class into which the object is blessed. CWref (see ref in perlfunc) gives the same result on references to blessed objects, but different results on other types of value. CWblessed_class is actually identical to CWScalar::Util::blessed (see blessed in Scalar::Util).

is_strictly_blessed(ARG)

Returns true iff ARG is a reference to a blessed object, identically to CWis_blessed. This exists only for symmetry; the useful form of CWis_strictly_blessed appears below.

is_strictly_blessed(ARG, CLASS)

CLASS must be a string. Returns true iff ARG is a reference to an object blessed into class CLASS exactly. Because this excludes subclasses, this is rarely what one wants, but there are some specialised occasions where it is useful.

is_able(ARG, METHODS)

METHODS must be either a single method name or a reference to an array of method names. Each method name is a string. Returns true iff ARG is a reference to a blessed object that claims to implement the specified methods (via its CWcan method; see can in perlobj). This interface check is often more appropriate than a direct ancestry check (such as CWis_blessed performs).

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

Params::Validate, Scalar::Util

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

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

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