.\" -*- 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 "Class::Data::Inheritable 3"
.TH Class::Data::Inheritable 3 2023-07-25 "perl v5.38.0" "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
Class::Data::Inheritable \- Inheritable, overridable class data
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&  package Stuff;
\&  use base qw(Class::Data::Inheritable);
\&
\&  # Set up DataFile as inheritable class data.
\&  Stuff\->mk_classdata(\*(AqDataFile\*(Aq);
\&
\&  # Declare the location of the data file for this class.
\&  Stuff\->DataFile(\*(Aq/etc/stuff/data\*(Aq);
\&
\&  # Or, all in one shot:
\&  Stuff\->mk_classdata(DataFile => \*(Aq/etc/stuff/data\*(Aq);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Class::Data::Inheritable is for creating accessor/mutators to class
data.  That is, if you want to store something about your class as a
whole (instead of about a single object).  This data is then inherited
by your subclasses and can be overridden.
.PP
For example:
.PP
.Vb 1
\&  Pere::Ubu\->mk_classdata(\*(AqSuitcase\*(Aq);
.Ve
.PP
will generate the method \fBSuitcase()\fR in the class Pere::Ubu.
.PP
This new method can be used to get and set a piece of class data.
.PP
.Vb 2
\&  Pere::Ubu\->Suitcase(\*(AqRed\*(Aq);
\&  $suitcase = Pere::Ubu\->Suitcase;
.Ve
.PP
The interesting part happens when a class inherits from Pere::Ubu:
.PP
.Vb 2
\&  package Raygun;
\&  use base qw(Pere::Ubu);
\&  
\&  # Raygun\*(Aqs suitcase is Red.
\&  $suitcase = Raygun\->Suitcase;
.Ve
.PP
Raygun inherits its Suitcase class data from Pere::Ubu.
.PP
Inheritance of class data works analogous to method inheritance.  As
long as Raygun does not "override" its inherited class data (by using
\&\fBSuitcase()\fR to set a new value) it will continue to use whatever is set
in Pere::Ubu and inherit further changes:
.PP
.Vb 2
\&  # Both Raygun\*(Aqs and Pere::Ubu\*(Aqs suitcases are now Blue
\&  Pere::Ubu\->Suitcase(\*(AqBlue\*(Aq);
.Ve
.PP
However, should Raygun decide to set its own \fBSuitcase()\fR it has now
"overridden" Pere::Ubu and is on its own, just like if it had
overridden a method:
.PP
.Vb 2
\&  # Raygun has an orange suitcase, Pere::Ubu\*(Aqs is still Blue.
\&  Raygun\->Suitcase(\*(AqOrange\*(Aq);
.Ve
.PP
Now that Raygun has overridden Pere::Ubu further changes by Pere::Ubu
no longer effect Raygun.
.PP
.Vb 2
\&  # Raygun still has an orange suitcase, but Pere::Ubu is using Samsonite.
\&  Pere::Ubu\->Suitcase(\*(AqSamsonite\*(Aq);
.Ve
.SH Methods
.IX Header "Methods"
.SS mk_classdata
.IX Subsection "mk_classdata"
.Vb 2
\&  Class\->mk_classdata($data_accessor_name);
\&  Class\->mk_classdata($data_accessor_name => $value);
.Ve
.PP
This is a class method used to declare new class data accessors.
A new accessor will be created in the Class using the name from
\&\f(CW$data_accessor_name\fR, and optionally initially setting it to the given
value.
.PP
To facilitate overriding, mk_classdata creates an alias to the
accessor, \fB_field_accessor()\fR.  So \fBSuitcase()\fR would have an alias
\&\fB_Suitcase_accessor()\fR that does the exact same thing as \fBSuitcase()\fR.
This is useful if you want to alter the behavior of a single accessor
yet still get the benefits of inheritable class data.  For example.
.PP
.Vb 3
\&  sub Suitcase {
\&      my($self) = shift;
\&      warn "Fashion tragedy" if @_ and $_[0] eq \*(AqPlaid\*(Aq;
\&
\&      $self\->_Suitcase_accessor(@_);
\&  }
.Ve
.SH AUTHOR
.IX Header "AUTHOR"
Original code by Damian Conway.
.PP
Maintained by Michael G Schwern until September 2005.
.PP
Now maintained by Tony Bowden.
.SH "BUGS and QUERIES"
.IX Header "BUGS and QUERIES"
Please direct all correspondence regarding this module to:
  bug\-Class\-Data\-Inheritable@rt.cpan.org
.SH "COPYRIGHT and LICENSE"
.IX Header "COPYRIGHT and LICENSE"
Copyright (c) 2000\-2005, Damian Conway and Michael G Schwern. 
All Rights Reserved.
.PP
This module is free software. It may be used, redistributed and/or
modified under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
perltooc has a very elaborate discussion of class data in Perl.