README
1NAME
2 Class::Data::Accessor - Inheritable, overridable class and instance data
3 accessor creation
4
5SYNOPSIS
6 package Stuff;
7 use base qw(Class::Data::Accessor);
8
9 # Set up DataFile as inheritable class data.
10 Stuff->mk_classaccessor('DataFile');
11
12 # Declare the location of the data file for this class.
13 Stuff->DataFile('/etc/stuff/data');
14
15 # Or, all in one shot:
16 Stuff->mk_classaccessor(DataFile => '/etc/stuff/data');
17
18 Stuff->DataFile; # returns /etc/stuff/data
19
20 my $stuff = Stuff->new; # your new, not ours
21
22 $stuff->DataFile; # returns /etc/stuff/data
23
24 $stuff->DataFile('/etc/morestuff'); # sets it on the object
25
26 Stuff->DataFile; # still returns /etc/stuff/data
27
28DESCRIPTION
29 Class::Data::Accessor is the marriage of Class::Accessor and
30 Class::Data::Inheritable into a single module. It is used for creating
31 accessors to class data that overridable in subclasses as well as in
32 class instances.
33
34 For example:
35
36 Pere::Ubu->mk_classaccessor('Suitcase');
37
38 will generate the method Suitcase() in the class Pere::Ubu.
39
40 This new method can be used to get and set a piece of class data.
41
42 Pere::Ubu->Suitcase('Red');
43 $suitcase = Pere::Ubu->Suitcase;
44
45 Taking this one step further, you can make a subclass that inherits from
46 Pere::Ubu:
47
48 package Raygun;
49 use base qw(Pere::Ubu);
50
51 # Raygun's suitcase is Red.
52 $suitcase = Raygun->Suitcase;
53
54 Raygun inherits its Suitcase class data from Pere::Ubu.
55
56 Inheritance of class data works analogous to method inheritance. As long
57 as Raygun does not "override" its inherited class data (by using
58 Suitcase() to set a new value) it will continue to use whatever is set
59 in Pere::Ubu and inherit further changes:
60
61 # Both Raygun's and Pere::Ubu's suitcases are now Blue
62 Pere::Ubu->Suitcase('Blue');
63
64 However, should Raygun decide to set its own Suitcase() it has now
65 "overridden" Pere::Ubu and is on its own, just like if it had overridden
66 a method:
67
68 # Raygun has an orange suitcase, Pere::Ubu's is still Blue.
69 Raygun->Suitcase('Orange');
70
71 Now that Raygun has overridden Pere::Ubu, further changes by Pere::Ubu
72 no longer effect Raygun.
73
74 # Raygun still has an orange suitcase, but Pere::Ubu is using Samsonite.
75 Pere::Ubu->Suitcase('Samsonite');
76
77 You can also override this class data on a per-object basis. If $obj isa
78 Pere::Ubu then
79
80 $obj->Suitcase; # will return Samsonite
81
82 $obj->Suitcase('Purple'); # will set Suitcase *for this object only*
83
84 And after you've done that,
85
86 $obj->Suitcase; # will return Purple
87
88 but
89
90 Pere::Ubu->Suitcase; # will still return Samsonite
91
92 If you don't want this behaviour use Class::Data::Inheritable instead.
93
94 "mk_classaccessor" will die if used as an object method instead of as a
95 class method.
96
97METHODS
98 mk_classaccessor
99 Class->mk_classaccessor($data_accessor_name);
100 Class->mk_classaccessor($data_accessor_name => $value);
101
102 This is a class method used to declare new class data accessors. A new
103 accessor will be created in the Class using the name from
104 $data_accessor_name, and optionally initially setting it to the given
105 value.
106
107 To facilitate overriding, mk_classaccessor creates an alias to the
108 accessor, _field_accessor(). So Suitcase() would have an alias
109 _Suitcase_accessor() that does the exact same thing as Suitcase(). This
110 is useful if you want to alter the behavior of a single accessor yet
111 still get the benefits of inheritable class data. For example.
112
113 sub Suitcase {
114 my($self) = shift;
115 warn "Fashion tragedy" if @_ and $_[0] eq 'Plaid';
116
117 $self->_Suitcase_accessor(@_);
118 }
119
120 Overriding accessors does not work in the same class as you declare the
121 accessor in. It only works in subclasses due to the fact that
122 subroutines are loaded at compile time and accessors are loaded at
123 runtime, thus overriding any subroutines with the same name in the same
124 class.
125
126 mk_classaccessors(@accessornames)
127 Takes a list of names and generates an accessor for each name in the
128 list using "mk_classaccessor".
129
130AUTHORS
131 Based on the creative stylings of Damian Conway, Michael G Schwern, Tony
132 Bowden (Class::Data::Inheritable) and Michael G Schwern, Marty Pauley
133 (Class::Accessor).
134
135 Coded by Matt S Trout Tweaks by Christopher H. Laco.
136
137BUGS and QUERIES
138 If your object isn't hash-based, this will currently break. My
139 modifications aren't exactly sophisticated so far.
140
141 mstrout@cpan.org or bug me on irc.perl.org, nick mst claco@cpan.org or
142 irc.perl.org, nick claco
143
144LICENSE
145 This module is free software. It may be used, redistributed and/or
146 modified under the terms of the Perl Artistic License (see
147 http://www.perl.com/perl/misc/Artistic.html)
148
149SEE ALSO
150 perltootc has a very elaborate discussion of class data in Perl.
151 Class::Accessor, Class::Data::Inheritable
152
153