This queue is for tickets about the Class-Data-Inheritable CPAN distribution.

Report information
The Basics
Id:
70844
Status:
new
Priority:
Low/Low

People
Owner:
Nobody in particular
Requestors:
AlanHamilton [...] pobox.com
Cc:
AdminCc:

BugTracker
Severity:
(no value)
Broken in:
(no value)
Fixed in:
(no value)



Subject: CPAN documentation does not clearly specify inheritance
Date: Fri, 9 Sep 2011 08:48:38 -0400
To: "bug-Class-Data-Inheritable@rt.cpan.org" <bug-Class-Data-Inheritable@rt.cpan.org>
From: Alan Hamilton <alanhamilton@pobox.com>
The Class::Data perldoc seems to leave out a lot of details.
Please consider the following elaboration for your consideration. 

--Alan



__END__

=head1 NAME

Class::Data::Inheritable - Inheritable, overridable class data

=head1 SYNOPSIS

  package Stuff;
  use base qw(Class::Data::Inheritable);

  # Set up DataFile as inheritable class data.
  Stuff->mk_classdata('DataFile');

  # Declare the location of the data file for this class.
  Stuff->DataFile('/etc/stuff/data');

  # Or, all in one shot:
  Stuff->mk_classdata(DataFile => '/etc/stuff/data');

=head1 DESCRIPTION

Class::Data::Inheritable is for creating accessor/mutators to inherited class data.  That is, if you want to store something about your class as a whole (instead of about a single object).  That class's data are then inherited by its subclasses and can be individually overridden by any subclass, just like inherited methods. 

For example, if you want to keep count of how many objects are created in Pere::Ubu:

  Pere::Ubu->mk_classdata('Object_count');

You can define other class variables as well:

  Pere::Ubu->mk_classdata('Trunk');
  Pere::Ubu->mk_classdata('Suitcase');

Each of these will generate a get/set method in the class Pere::Ubu. Object_count(), Trunk() and Suitcase().

Each of the new methods can be used to get and set a piece of class data.

  Pere::Ubu->Object_count(0);
  $object_count = Pere::Ubu->Object_count;

  Pere::Ubu->Trunk('Black');
  $trunk = Pere::Ubu->Trunk;
  
  Pere::Ubu->Suitcase('Red');
  $suitcase = Pere::Ubu->Suitcase;

Inheritance of class data works analogous to method inheritance. It gets interesting when a class inherits from Pere::Ubu:

  package Raygun;
  use base qw(Pere::Ubu);
  
  # Raygun wants to keep its own count of Raygun objects, 
  # so it overrides Object_count:
  Raygun->Object_count(0);

As long as Raygun does not "override" its inherited class data (by using
Suitcase() to set a new value) it will continue to use whatever is set
in Pere::Ubu and inherit further changes:

  Pere::Ubu->Suitcase('Blue');
  # Both Raygun's and Pere::Ubu's suitcases are now Blue

However, should Raygun decide to set its own Suitcase() it has now
"overridden" Pere::Ubu's Suitcase. From here on, Raygun's Suitcase is separate from Pere::Ubu's Suitcase, just like if it had overriden a method:

  Raygun->Suitcase('Orange');
  # Raygun now has an orange suitcase, and Pere::Ubu's is still Blue.

Now that Raygun has overridden Pere::Ubu::Suitcase() futher changes by Pere::Ubu::Suitcase() no longer effect Raygun.

  Pere::Ubu->Suitcase('Samsonite');
  # Raygun still has an orange suitcase, but Pere::Ubu is using Samsonite.
  
  # But Raygun still uses Pere::Ubu->Trunk
  $trunk = Raygun::Trunk();

Subclasses of Raygun inherit class data from Raygun and any class data from Pere::Ubu that has not been overridden by Raygun.

  package Laser_pistol;
  use base qw(Raygun);

  # Laser_pistol also wants to count its objects
  Laser_pistol->Object_count(0);

Unless class Laser_pistol overrides them, it inherits Suitcase() from Raygun and Trunk() from Pere::Ubu. Changes made by Raygun->Suitcase() will change the value of Suitcase for classes Raygun and Laser_pistol. Changes made by Pere::Ubu->Trunk() will change the value of Trunk for Pere::Ubu, Raygun and Laser_pistol. Changes made by Raygun->Suitcase() will change the value of Suitcase for Raygun and Laser_pistol. Changes made by Pere::Ubu->Suitcase() will change the value of Suitcase for Pere::Ubu only.

Note that if Laser_pistol did not override Object_count it would continue to see the Object_count of Raygun. 


=head1 Methods

=head2 mk_classdata

  Class->mk_classdata($data_accessor_name);
  Class->mk_classdata($data_accessor_name => $value);

This is a class method used to declare new class data get/set accessors.
A new accessor will be created in the Class using the name from
$data_accessor_name, and optionally initially setting it to the given
value.

To facilitate overriding, mk_classdata creates an alias to the
accessor, _field_accessor().  So Suitcase() would have an alias
_Suitcase_accessor() that does the exact same thing as Suitcase().
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.

  sub Suitcase {
      my($self) = shift;
      warn "Fashion tragedy" if @_ and $_[0] eq 'Plaid';

      $self->_Suitcase_accessor(@_);
  }

=head1 AUTHOR

Original code by Damian Conway.

Maintained by Michael G Schwern until September 2005.

Now maintained by Tony Bowden.

=head1 BUGS and QUERIES

Please direct all correspondence regarding this module to:
  bug-Class-Data-Inheritable@rt.cpan.org

=head1 COPYRIGHT and LICENSE

Copyright (c) 2000-2005, Damian Conway and Michael G Schwern. 
All Rights Reserved.  

This module is free software. It may be used, redistributed and/or
modified under the same terms as Perl itself.

=head1 SEE ALSO

L<perltooc> has a very elaborate discussion of class data in Perl.


--
.


This service runs on Request Tracker, is sponsored by The Perl Foundation, and maintained by Best Practical Solutions.

Please report any issues with rt.cpan.org to rt-cpan-admin@bestpractical.com.