local-lib5/man/man3/Class::Data::Inheritable.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 "Class::Data::Inheritable 3"
 132 .TH Class::Data::Inheritable 3 "2008-01-25" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Class::Data::Inheritable \- Inheritable, overridable class data
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 2
 138 \&  package Stuff;
 139 \&  use base qw(Class::Data::Inheritable);
 140 .Ve
 141 .PP
 142 .Vb 2
 143 \&  # Set up DataFile as inheritable class data.
 144 \&  Stuff\->mk_classdata('DataFile');
 145 .Ve
 146 .PP
 147 .Vb 2
 148 \&  # Declare the location of the data file for this class.
 149 \&  Stuff\->DataFile('/etc/stuff/data');
 150 .Ve
 151 .PP
 152 .Vb 2
 153 \&  # Or, all in one shot:
 154 \&  Stuff\->mk_classdata(DataFile => '/etc/stuff/data');
 155 .Ve
 156 .SH "DESCRIPTION"
 157 .IX Header "DESCRIPTION"
 158 Class::Data::Inheritable is for creating accessor/mutators to class
 159 data.  That is, if you want to store something about your class as a
 160 whole (instead of about a single object).  This data is then inherited
 161 by your subclasses and can be overriden.
 162 .PP
 163 For example:
 164 .PP
 165 .Vb 1
 166 \&  Pere::Ubu\->mk_classdata('Suitcase');
 167 .Ve
 168 .PP
 169 will generate the method \fISuitcase()\fR in the class Pere::Ubu.
 170 .PP
 171 This new method can be used to get and set a piece of class data.
 172 .PP
 173 .Vb 2
 174 \&  Pere::Ubu\->Suitcase('Red');
 175 \&  $suitcase = Pere::Ubu\->Suitcase;
 176 .Ve
 177 .PP
 178 The interesting part happens when a class inherits from Pere::Ubu:
 179 .PP
 180 .Vb 2
 181 \&  package Raygun;
 182 \&  use base qw(Pere::Ubu);
 183 .Ve
 184 .PP
 185 .Vb 2
 186 \&  # Raygun's suitcase is Red.
 187 \&  $suitcase = Raygun\->Suitcase;
 188 .Ve
 189 .PP
 190 Raygun inherits its Suitcase class data from Pere::Ubu.
 191 .PP
 192 Inheritance of class data works analogous to method inheritance.  As
 193 long as Raygun does not \*(L"override\*(R" its inherited class data (by using
 194 \&\fISuitcase()\fR to set a new value) it will continue to use whatever is set
 195 in Pere::Ubu and inherit further changes:
 196 .PP
 197 .Vb 2
 198 \&  # Both Raygun's and Pere::Ubu's suitcases are now Blue
 199 \&  Pere::Ubu\->Suitcase('Blue');
 200 .Ve
 201 .PP
 202 However, should Raygun decide to set its own \fISuitcase()\fR it has now
 203 \&\*(L"overridden\*(R" Pere::Ubu and is on its own, just like if it had
 204 overriden a method:
 205 .PP
 206 .Vb 2
 207 \&  # Raygun has an orange suitcase, Pere::Ubu's is still Blue.
 208 \&  Raygun\->Suitcase('Orange');
 209 .Ve
 210 .PP
 211 Now that Raygun has overridden Pere::Ubu futher changes by Pere::Ubu
 212 no longer effect Raygun.
 213 .PP
 214 .Vb 2
 215 \&  # Raygun still has an orange suitcase, but Pere::Ubu is using Samsonite.
 216 \&  Pere::Ubu\->Suitcase('Samsonite');
 217 .Ve
 218 .SH "Methods"
 219 .IX Header "Methods"
 220 .Sh "mk_classdata"
 221 .IX Subsection "mk_classdata"
 222 .Vb 2
 223 \&  Class\->mk_classdata($data_accessor_name);
 224 \&  Class\->mk_classdata($data_accessor_name => $value);
 225 .Ve
 226 .PP
 227 This is a class method used to declare new class data accessors.
 228 A new accessor will be created in the Class using the name from
 229 \&\f(CW$data_accessor_name\fR, and optionally initially setting it to the given
 230 value.
 231 .PP
 232 To facilitate overriding, mk_classdata creates an alias to the
 233 accessor, \fI_field_accessor()\fR.  So \fISuitcase()\fR would have an alias
 234 \&\fI_Suitcase_accessor()\fR that does the exact same thing as \fISuitcase()\fR.
 235 This is useful if you want to alter the behavior of a single accessor
 236 yet still get the benefits of inheritable class data.  For example.
 237 .PP
 238 .Vb 3
 239 \&  sub Suitcase {
 240 \&      my($self) = shift;
 241 \&      warn "Fashion tragedy" if @_ and $_[0] eq 'Plaid';
 242 .Ve
 243 .PP
 244 .Vb 2
 245 \&      $self\->_Suitcase_accessor(@_);
 246 \&  }
 247 .Ve
 248 .SH "AUTHOR"
 249 .IX Header "AUTHOR"
 250 Original code by Damian Conway.
 251 .PP
 252 Maintained by Michael G Schwern until September 2005.
 253 .PP
 254 Now maintained by Tony Bowden.
 255 .SH "BUGS and QUERIES"
 256 .IX Header "BUGS and QUERIES"
 257 Please direct all correspondence regarding this module to:
 258   bug\-Class\-Data\-Inheritable@rt.cpan.org
 259 .SH "COPYRIGHT and LICENSE"
 260 .IX Header "COPYRIGHT and LICENSE"
 261 Copyright (c) 2000\-2005, Damian Conway and Michael G Schwern.
 262 All Rights Reserved.
 263 .PP
 264 This module is free software. It may be used, redistributed and/or
 265 modified under the same terms as Perl itself.
 266 .SH "SEE ALSO"
 267 .IX Header "SEE ALSO"
 268 perltooc has a very elaborate discussion of class data in Perl.