local-lib5/man/man3/parent.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "parent 3"
 127 .TH parent 3 "2009-09-01" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 parent \- Establish an ISA relationship with base classes at compile time
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 2
 137 \&    package Baz;
 138 \&    use parent qw(Foo Bar);
 139 .Ve
 140 .SH "DESCRIPTION"
 141 .IX Header "DESCRIPTION"
 142 Allows you to both load one or more modules, while setting up inheritance from
 143 those modules at the same time.  Mostly similar in effect to
 144 .PP
 145 .Vb 6
 146 \&    package Baz;
 147 \&    BEGIN {
 148 \&        require Foo;
 149 \&        require Bar;
 150 \&        push @ISA, qw(Foo Bar);
 151 \&    }
 152 .Ve
 153 .PP
 154 By default, every base class needs to live in a file of its own.
 155 If you want to have a subclass and its parent class in the same file, you
 156 can tell \f(CW\*(C`parent\*(C'\fR not to load any modules by using the \f(CW\*(C`\-norequire\*(C'\fR switch:
 157 .PP
 158 .Vb 2
 159 \&  package Foo;
 160 \&  sub exclaim { "I CAN HAS PERL" }
 161 \&
 162 \&  package DoesNotLoadFooBar;
 163 \&  use parent \-norequire, \*(AqFoo\*(Aq, \*(AqBar\*(Aq;
 164 \&  # will not go looking for Foo.pm or Bar.pm
 165 .Ve
 166 .PP
 167 This is equivalent to the following code:
 168 .PP
 169 .Vb 2
 170 \&  package Foo;
 171 \&  sub exclaim { "I CAN HAS PERL" }
 172 \&
 173 \&  package DoesNotLoadFooBar;
 174 \&  push @DoesNotLoadFooBar::ISA, \*(AqFoo\*(Aq, \*(AqBar\*(Aq;
 175 .Ve
 176 .PP
 177 This is also helpful for the case where a package lives within
 178 a differently named file:
 179 .PP
 180 .Vb 3
 181 \&  package MyHash;
 182 \&  use Tie::Hash;
 183 \&  use parent \-norequire, \*(AqTie::StdHash\*(Aq;
 184 .Ve
 185 .PP
 186 This is equivalent to the following code:
 187 .PP
 188 .Vb 3
 189 \&  package MyHash;
 190 \&  require Tie::Hash;
 191 \&  push @ISA, \*(AqTie::StdHash\*(Aq;
 192 .Ve
 193 .PP
 194 If you want to load a subclass from a file that \f(CW\*(C`require\*(C'\fR would
 195 not consider an eligible filename (that is, it does not end in
 196 either \f(CW\*(C`.pm\*(C'\fR or \f(CW\*(C`.pmc\*(C'\fR), use the following code:
 197 .PP
 198 .Vb 3
 199 \&  package MySecondPlugin;
 200 \&  require \*(Aq./plugins/custom.plugin\*(Aq; # contains Plugin::Custom
 201 \&  use parent \-norequire, \*(AqPlugin::Custom\*(Aq;
 202 .Ve
 203 .SH "DIAGNOSTICS"
 204 .IX Header "DIAGNOSTICS"
 205 .IP "Class 'Foo' tried to inherit from itself" 4
 206 .IX Item "Class 'Foo' tried to inherit from itself"
 207 Attempting to inherit from yourself generates a warning.
 208 .Sp
 209 .Vb 2
 210 \&    use Foo;
 211 \&    use parent \*(AqFoo\*(Aq;
 212 .Ve
 213 .SH "HISTORY"
 214 .IX Header "HISTORY"
 215 This module was forked from base to remove the cruft
 216 that had accumulated in it.
 217 .SH "CAVEATS"
 218 .IX Header "CAVEATS"
 219 .SH "SEE ALSO"
 220 .IX Header "SEE ALSO"
 221 base
 222 .SH "AUTHORS AND CONTRIBUTORS"
 223 .IX Header "AUTHORS AND CONTRIBUTORS"
 224 Rafae\*:l Garcia-Suarez, Bart Lateur, Max Maischein, Anno Siegel, Michael Schwern
 225 .SH "MAINTAINER"
 226 .IX Header "MAINTAINER"
 227 Max Maischein \f(CW\*(C` corion@cpan.org \*(C'\fR
 228 .PP
 229 Copyright (c) 2007 Max Maischein \f(CW\*(C`<corion@cpan.org>\*(C'\fR
 230 Based on the idea of \f(CW\*(C`base.pm\*(C'\fR, which was introduced with Perl 5.004_04.
 231 .SH "LICENSE"
 232 .IX Header "LICENSE"
 233 This module is released under the same terms as Perl itself.