local-lib5/man/man3/UNIVERSAL::can.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "UNIVERSAL::can 3"
 132 .TH UNIVERSAL::can 3 "2009-12-09" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 UNIVERSAL::can \- Hack around people calling UNIVERSAL::can() as a function
 135 .SH "VERSION"
 136 .IX Header "VERSION"
 137 Version 1.14
 138 .SH "SYNOPSIS"
 139 .IX Header "SYNOPSIS"
 140 To use this module, simply:
 141 .PP
 142 .Vb 1
 143 \&  use UNIVERSAL::can;
 144 .Ve
 145 .SH "DESCRIPTION"
 146 .IX Header "DESCRIPTION"
 147 The \s-1UNIVERSAL\s0 class provides a few default methods so that all objects can use
 148 them.  Object orientation allows programmers to override these methods in
 149 subclasses to provide more specific and appropriate behavior.
 150 .PP
 151 Some authors call methods in the \s-1UNIVERSAL\s0 class on potential invocants as
 152 functions, bypassing any possible overriding.  This is wrong and you should not
 153 do it.  Unfortunately, not everyone heeds this warning and their bad code can
 154 break your good code.
 155 .PP
 156 This module replaces \f(CW\*(C`UNIVERSAL::can()\*(C'\fR with a method that checks to see if
 157 the first argument is a valid invocant has its own \f(CW\*(C`can()\*(C'\fR method.  If so, it
 158 gives a warning and calls the overridden method, working around buggy code.
 159 Otherwise, everything works as you might expect.
 160 .PP
 161 Some people argue that you must call \f(CW\*(C`UNIVERSAL::can()\*(C'\fR as a function because
 162 you don't know if your proposed invocant is a valid invocant.  That's silly.
 163 Use \f(CW\*(C`blessed()\*(C'\fR from Scalar::Util if you want to check that the potential
 164 invocant is an object or call the method anyway in an \f(CW\*(C`eval\*(C'\fR block and check
 165 for failure (though check the exception \fIreturned\fR, as a poorly-written
 166 \&\f(CW\*(C`can()\*(C'\fR method could break Liskov and throw an exception other than \*(L"You can't
 167 call a method on this type of invocant\*(R").
 168 .PP
 169 Just don't break working code.
 170 .SH "AUTHOR"
 171 .IX Header "AUTHOR"
 172 chromatic, \f(CW\*(C`<chromatic@wgz.org>\*(C'\fR
 173 .SH "BUGS"
 174 .IX Header "BUGS"
 175 Please report any bugs or feature requests to \f(CW\*(C`bug\-universal\-can@rt.cpan.org\*(C'\fR,
 176 or through the web interface at
 177 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=UNIVERSAL\-can>.  This will
 178 contact me, hold onto patches so I don't drop them, and will notify you of
 179 progress on your request as I make changes.
 180 .SH "ACKNOWLEDGEMENTS"
 181 .IX Header "ACKNOWLEDGEMENTS"
 182 Inspired by UNIVERSAL::isa by Yuval Kogman, Autrijus Tang, and myself.
 183 .PP
 184 Adam Kennedy has tirelessly made me tired by reporting potential bugs and
 185 suggesting ideas that found actual bugs.
 186 .PP
 187 Mark Clements helped to track down an invalid invocant bug.
 188 .PP
 189 Curtis \*(L"Ovid\*(R" Poe finally provided the inspiration I needed to clean up the
 190 interface.
 191 .PP
 192 Peter du Marchie van Voorthuysen identified and fixed a problem with calling
 193 \&\f(CW\*(C`SUPER::can\*(C'\fR.
 194 .PP
 195 The Perl \s-1QA\s0 list had a huge... discussion... which inspired my realization that
 196 this module needed to do what it does now.
 197 .SH "COPYRIGHT & LICENSE"
 198 .IX Header "COPYRIGHT & LICENSE"
 199 Artistic License 2.0, copyright (c) 2005 \- 2009 chromatic. Some rights
 200 reserved.