Params::Classify(3pm)

🌸 NAME 🌸

Params::Classify — argument type classification. This is the Params::Classify(3pm) page from User Contributed Perl Documentation, and bestie, it's literally all about figuring out what kind of scalar you're holding. 💅

✨ SYNOPSIS ✨

okay so here's the import vibe — copy this exactly, no cap:

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 🦋

Okay so this module provides various type-testing functions. They're intended for functions that, unlike most Perl code, actually care what type of data they're operating on. Like, some functions wish to behave differently depending on the type of their arguments (think overloaded functions in C++). Iconic behavior. 💅

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

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

💖 TYPE CLASSIFICATION 💖

This module divides up scalar values into the following classes — vibe check:

• 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.) iykyk. 🦋

🎀 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. No cap. 💀

🌟 Classification 🌟

• scalar_class(ARG) — determines which of the five classes described above ARG falls into. Returns UNDEF, STRING, GLOB, REGEXP, REF, or BLESSED accordingly. (yes, it says five and then returns six — iconic inconsistency, not me fixing it 😭)

💜 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. Fr fr.

🍓 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. Ate. 🍓
• 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. Numbers are giving main character energy. 🔥

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.) Be careful, bestie — dualvars are not here to play. 🙈

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. Math lore. ✨

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. Not the dualvar confusion again 😭

🌈 Typeglobs 🌈

• is_glob(ARG), check_glob(ARG) — check whether ARG is a typeglob. Yes bestie, typeglobs. They fit into scalar variables, which is kind of iconic. 🎀

⭐ Regexps ⭐

• is_regexp(ARG), check_regexp(ARG) — check whether ARG is a regexp object. Slay. ⭐

💖 LICENSE 💖

okay so legal stuff but make it cute: this module is free software 🫶 you can redistribute it and/or modify it under the same terms as Perl itself — that's literally it, that's the whole vibe. go off, remix it, share it, slay responsibly ✨

---

and that's a wrap bestie!! 🎀 this lil masterpiece came from perl v5.40.2, dated 2024-06-10 — go forth and classify those params like the icon you are 💅🦋 no cap, you ate 💜