From 1c349098c10d1963ec68ea92771d3646869bb20e Mon Sep 17 00:00:00 2001 From: Dan Book Date: Mon, 10 Jun 2024 21:36:05 -0400 Subject: [PATCH] perlfunc - defang warning about ref() and add warning about using reftype() on objects Also, move the pointer to "isa" up to the paragraph discussing blessed references, and point to "builtin" instead of "Scalar::Util". --- pod/perlfunc.pod | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 11c902bb6a74..0dc5e3ef1fb1 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -6811,6 +6811,11 @@ results against a class name doesn't perform a class membership test: a class's members also include objects blessed into subclasses, for which C will return the name of the subclass. Also beware that class names can clash with the built-in type names (described below). +Use L method|UNIVERSAL/C<< $obj->isa( TYPE ) >>> to test +class membership of a class name or blessed object, after ensuring it +is one of these things. Alternatively, the +L operator|perlop/"Class Instance Operator"> can test class +membership without checking blessedness first. If the operand is a reference to an unblessed object, then the return value indicates the type of object. If the unblessed referent is not @@ -6825,15 +6830,15 @@ these built-in type names can also be used as class names, so C returning one of these names doesn't unambiguously indicate that the referent is of the kind to which the name refers. -The ambiguity between built-in type names and class names significantly -limits the utility of C. For unambiguous information, use -L|Scalar::Util/blessed> for information about -blessing, and L|Scalar::Util/reftype> for -information about physical types. Use L method|UNIVERSAL/C<< -$obj->isa( TYPE ) >>> for class membership tests, though one must be -sure of blessedness before attempting a method call. Alternatively, the -L operator|perlop/"Class Instance Operator"> can test class -membership without checking blessedness first. +The ambiguity between built-in type names and class names may limit the +utility of C, but in practice, such clashes rarely occur unless +intentionally engineered. For unambiguous information, use +L for information about blessing, and L +for information about physical types. But beware that the physical type +returned by C does not indicate how a blessed object is meant to +be used, and the appropriate dereference operations for an object +(whether to access the blessed structure directly, or via an L) +will be described by the documentation for the object class. See also L and L.