.\" -*- 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 "Damn 3pm"
.TH Damn 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
Acme::Damn \- 'Unbless' Perl objects.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Acme::Damn;
\&
\&  my $ref = ... some reference ...
\&  my $obj = bless $ref , \*(AqSome::Class\*(Aq;
\&  
\&  ... do something with your object ...
\&
\&     $ref = damn $obj;   # recover the original reference (unblessed)
\&
\&  ... neither $ref nor $obj are Some::Class objects ...
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBAcme::Damn\fR provides a single routine, \fBdamn()\fR, which takes a blessed
reference (a Perl object), and \fIunblesses\fR it, to return the original
reference.
.SS EXPORT
.IX Subsection "EXPORT"
By default, \fBAcme::Damn\fR exports the method \fBdamn()\fR into the current
namespace. Aliases for \fBdamn()\fR (see below) may be imported upon request.
.SS Methods
.IX Subsection "Methods"
.IP "\fBdamn\fR \fIobject\fR" 4
.IX Item "damn object"
\&\fBdamn()\fR accepts a single blessed reference as its argument, and returns
that reference unblessed. If \fIobject\fR is not a blessed reference, then
\&\fBdamn()\fR will \f(CW\*(C`die\*(C'\fR with an error.
.IP "\fBbless\fR \fIreference\fR" 4
.IX Item "bless reference"
.PD 0
.IP "\fBbless\fR \fIreference\fR [ , \fIpackage\fR ]" 4
.IX Item "bless reference [ , package ]"
.IP "\fBbless\fR \fIreference\fR [ , undef ]" 4
.IX Item "bless reference [ , undef ]"
.PD
Optionally, \fBAcme::Damn\fR will modify the behaviour of \f(CW\*(C`bless\*(C'\fR to
allow the passing of an explicit \f(CW\*(C`undef\*(C'\fR as the target package to invoke
\&\fBdamn()\fR:
.Sp
.Vb 1
\&    use Acme::Damn  qw( bless );
\&
\&    my  $obj = ... some blessed reference ...;
\&
\&    # the following statements are equivalent
\&    my  $ref = bless $obj , undef;
\&    my  $ref = damn $obj;
.Ve
.Sp
\&\fBNOTE:\fR The modification of \f(CW\*(C`bless\*(C'\fR is lexically scoped to the current
package, and is \fInot\fR global.
.SS "Method Aliases"
.IX Subsection "Method Aliases"
Not everyone likes to damn the same way or in the same language, so
\&\fBAcme::Damn\fR offers the ability to specify any alias on import, provided
that alias is a valid Perl subroutine name (i.e. all characters match \f(CW\*(C`\ew\*(C'\fR).
.PP
.Vb 4
\&  use Acme::Damn qw( unbless );
\&  use Acme::Damn qw( foo );
\&  use Acme::Damn qw( unblessthyself );
\&  use Acme::Damn qw( recant );
.Ve
.PP
Version 0.02 supported a defined list of aliases, and this has been replaced
in v0.03 by the ability to import any alias for \f(CWdamn()\fR.
.SH WARNING
.IX Header "WARNING"
Just as \f(CW\*(C`bless\*(C'\fR doesn't call an object's initialisation code, \f(CW\*(C`damn\*(C'\fR doesn't
invoke an object's \f(CW\*(C`DESTROY\*(C'\fR method. For objects that need to be \f(CW\*(C`DESTROY\*(C'\fRed,
either don't \f(CW\*(C`damn\*(C'\fR them, or call \f(CW\*(C`DESTROY\*(C'\fR before judgement is passed.
.SH ACKNOWLEDGEMENTS
.IX Header "ACKNOWLEDGEMENTS"
Thanks to Claes Jacobsson <claes@surfar.nu> for suggesting the use of
aliases, and Bo Lindbergh <blgl@cpan.org> for the suggested
modification of \f(CW\*(C`bless\*(C'\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
bless, perlboot, perltoot, perltooc, perlbot,
perlobj.
.SH AUTHOR
.IX Header "AUTHOR"
Ian Brayshaw, <ibb@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2003\-2016 Ian Brayshaw
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.