.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "UNIVERSAL::ref 3pm"
.TH UNIVERSAL::ref 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
UNIVERSAL::ref \- Turns ref() into a multimethod
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&  # True! Wrapper pretends to be Thing.
\&  ref( Wrapper\->new( Thing\->new ) )
\&    eq ref( Thing\->new );
\&
\&  package Thing;
\&  sub new { bless [], shift }
\&
\&  package Wrapper;
\&  sub new {
\&      my ($class,$proxy) = @_;
\&      bless \e $proxy, $class;
\&  }
\&  sub ref {
\&      my $self = shift @_;
\&      return $$self;
\&  }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module changes the behavior of the builtin function \fBref()\fR. If
\&\fBref()\fR is called on an object that has requested an overloaded ref, the
object's \f(CW\*(C`\->ref\*(C'\fR method will be called and its return value used
instead.
.SH USING
.IX Header "USING"
To enable this feature for a class, \f(CW\*(C`use UNIVERSAL::ref\*(C'\fR in your
class. Here is a sample proxy module.
.PP
.Vb 5
\&  package Pirate;
\&  # Pirate pretends to be a Privateer
\&  use UNIVERSAL::ref;
\&  sub new { bless {}, shift }
\&  sub ref { return \*(AqPrivateer\*(Aq }
.Ve
.PP
Anywhere you call \f(CWref($obj)\fR on a \f(CW\*(C`Pirate\*(C'\fR object, it will allow
\&\f(CW\*(C`Pirate\*(C'\fR to lie and pretend to be something else.
.SH METHODS
.IX Header "METHODS"
.IP import 4
.IX Item "import"
A pragma for \fBref()\fR\-enabling your class. This adds the calling class
name to a global list of \fBref()\fR\-enabled classes.
.Sp
.Vb 3
\&    package YourClass;
\&    use UNIVERSAL::ref;
\&    sub ref { ... }
.Ve
.IP unimport 4
.IX Item "unimport"
A pragma for \fBref()\fR\-disabling your class. This removes the calling
class name from a global list of \fBref()\fR\-enabled classes.
.SH TODO
.IX Header "TODO"
Currently UNIVERSAL::ref must be installed before any \fBref()\fR calls that
are to be affected.
.PP
I think \fBref()\fR always occurs in an implicit scalar context. There is no
accomodation for list context.
.PP
UNIVERSAL::ref probably shouldn't allow a module to lie to itself. Or
should it?
.SH ACKNOWLEDGEMENTS
.IX Header "ACKNOWLEDGEMENTS"
ambrus for the excellent idea to overload \fBdefined()\fR to allow Perl 5 to
have Perl 6's "interesting values of undef."
.PP
chromatic for pointing out how utterly broken \fBref()\fR is. This fix
covers its biggest hole.
.SH AUTHOR
.IX Header "AUTHOR"
Joshua ben Jore \- jjore@cpan.org
.SH LICENSE
.IX Header "LICENSE"
The standard Artistic / GPL license most other perl code is typically
using.