Debian Codegraph @

README

raw
1 NAME
2 Class::Tiny - Minimalist class construction
3
4 VERSION
5 version 1.008
6
7 SYNOPSIS
8 In Person.pm:
9
10 package Person;
11
12 use Class::Tiny qw( name );
13
14 1;
15
16 In Employee.pm:
17
18 package Employee;
19 use parent 'Person';
20
21 use Class::Tiny qw( ssn ), {
22 timestamp => sub { time } # attribute with default
23 };
24
25 1;
26
27 In example.pl:
28
29 use Employee;
30
31 my $obj = Employee->new( name => "Larry", ssn => "111-22-3333" );
32
33 # unknown attributes are ignored
34 my $obj = Employee->new( name => "Larry", OS => "Linux" );
35 # $obj->{OS} does not exist
36
37 DESCRIPTION
38 This module offers a minimalist class construction kit in around 120
39 lines of code. Here is a list of features:
40
41 * defines attributes via import arguments
42
43 * generates read-write accessors
44
45 * supports lazy attribute defaults
46
47 * supports custom accessors
48
49 * superclass provides a standard "new" constructor
50
51 * "new" takes a hash reference or list of key/value pairs
52
53 * "new" supports providing "BUILDARGS" to customize constructor
54 options
55
56 * "new" calls "BUILD" for each class from parent to child
57
58 * superclass provides a "DESTROY" method
59
60 * "DESTROY" calls "DEMOLISH" for each class from child to parent
61
62 Multiple-inheritance is possible, with superclass order determined via
63 mro::get_linear_isa.
64
65 It uses no non-core modules for any recent Perl. On Perls older than
66 v5.10 it requires MRO::Compat. On Perls older than v5.14, it requires
67 Devel::GlobalDestruction.
68
69 USAGE
70 Defining attributes
71 Define attributes as a list of import arguments:
72
73 package Foo::Bar;
74
75 use Class::Tiny qw(
76 name
77 id
78 height
79 weight
80 );
81
82 For each attribute, a read-write accessor is created unless a subroutine
83 of that name already exists:
84
85 $obj->name; # getter
86 $obj->name( "John Doe" ); # setter
87
88 Attribute names must be valid subroutine identifiers or an exception
89 will be thrown.
90
91 You can specify lazy defaults by defining attributes with a hash
92 reference. Keys define attribute names and values are constants or code
93 references that will be evaluated when the attribute is first accessed
94 if no value has been set. The object is passed as an argument to a code
95 reference.
96
97 package Foo::WithDefaults;
98
99 use Class::Tiny qw/name id/, {
100 title => 'Peon',
101 skills => sub { [] },
102 hire_date => sub { $_[0]->_build_hire_date },
103 };
104
105 When subclassing, if multiple accessors of the same name exist in
106 different classes, any default (or lack of default) is determined by
107 standard method resolution order.
108
109 To make your own custom accessors, just pre-declare the method name
110 before loading Class::Tiny:
111
112 package Foo::Bar;
113
114 use subs 'id';
115
116 use Class::Tiny qw( name id );
117
118 sub id { ... }
119
120 Even if you pre-declare a method name, you must include it in the
121 attribute list for Class::Tiny to register it as a valid attribute.
122
123 If you set a default for a custom accessor, your accessor will need to
124 retrieve the default and do something with it:
125
126 package Foo::Bar;
127
128 use subs 'id';
129
130 use Class::Tiny qw( name ), { id => sub { int(rand(2*31)) } };
131
132 sub id {
133 my $self = shift;
134 if (@_) {
135 return $self->{id} = shift;
136 }
137 elsif ( exists $self->{id} ) {
138 return $self->{id};
139 }
140 else {
141 my $defaults =
142 Class::Tiny->get_all_attribute_defaults_for( ref $self );
143 return $self->{id} = $defaults->{id}->();
144 }
145 }
146
147 Class::Tiny::Object is your base class
148 If your class does not already inherit from some class, then
149 Class::Tiny::Object will be added to your @ISA to provide "new" and
150 "DESTROY".
151
152 If your class does inherit from something, then no additional
153 inheritance is set up. If the parent subclasses Class::Tiny::Object,
154 then all is well. If not, then you'll get accessors set up but no
155 constructor or destructor. Don't do that unless you really have a
156 special need for it.
157
158 Define subclasses as normal. It's best to define them with base, parent
159 or superclass before defining attributes with Class::Tiny so the @ISA
160 array is already populated at compile-time:
161
162 package Foo::Bar::More;
163
164 use parent 'Foo::Bar';
165
166 use Class::Tiny qw( shoe_size );
167
168 Object construction
169 If your class inherits from Class::Tiny::Object (as it should if you
170 followed the advice above), it provides the "new" constructor for you.
171
172 Objects can be created with attributes given as a hash reference or as a
173 list of key/value pairs:
174
175 $obj = Foo::Bar->new( name => "David" );
176
177 $obj = Foo::Bar->new( { name => "David" } );
178
179 If a reference is passed as a single argument, it must be able to be
180 dereferenced as a hash or an exception is thrown.
181
182 Unknown attributes in the constructor arguments will be ignored. Prior
183 to version 1.000, unknown attributes were an error, but this made it
184 harder for people to cleanly subclass Class::Tiny classes so this
185 feature was removed.
186
187 You can define a "BUILDARGS" method to change how arguments to new are
188 handled. It will receive the constructor arguments as they were provided
189 and must return a hash reference of key/value pairs (or else throw an
190 exception).
191
192 sub BUILDARGS {
193 my $class = shift;
194 my $name = shift || "John Doe";
195 return { name => $name };
196 };
197
198 Foo::Bar->new( "David" );
199 Foo::Bar->new(); # "John Doe"
200
201 Unknown attributes returned from "BUILDARGS" will be ignored.
202
203 BUILD
204 If your class or any superclass defines a "BUILD" method, it will be
205 called by the constructor from the furthest parent class down to the
206 child class after the object has been created.
207
208 It is passed the constructor arguments as a hash reference. The return
209 value is ignored. Use "BUILD" for validation, checking required
210 attributes or setting default values that depend on other attributes.
211
212 sub BUILD {
213 my ($self, $args) = @_;
214
215 for my $req ( qw/name age/ ) {
216 croak "$req attribute required" unless defined $self->$req;
217 }
218
219 croak "Age must be non-negative" if $self->age < 0;
220
221 $self->msg( "Hello " . $self->name );
222 }
223
224 The argument reference is a copy, so deleting elements won't affect data
225 in the original (but changes will be passed to other BUILD methods in
226 @ISA).
227
228 DEMOLISH
229 Class::Tiny provides a "DESTROY" method. If your class or any superclass
230 defines a "DEMOLISH" method, they will be called from the child class to
231 the furthest parent class during object destruction. It is provided a
232 single boolean argument indicating whether Perl is in global
233 destruction. Return values are ignored. Errors are caught and rethrown.
234
235 sub DEMOLISH {
236 my ($self, $global_destruct) = @_;
237 $self->cleanup();
238 }
239
240 Introspection and internals
241 You can retrieve an unsorted list of valid attributes known to
242 Class::Tiny for a class and its superclasses with the
243 "get_all_attributes_for" class method.
244
245 my @attrs = Class::Tiny->get_all_attributes_for("Employee");
246 # returns qw/name ssn timestamp/
247
248 Likewise, a hash reference of all valid attributes and default values
249 (or code references) may be retrieved with the
250 "get_all_attribute_defaults_for" class method. Any attributes without a
251 default will be "undef".
252
253 my $def = Class::Tiny->get_all_attribute_defaults_for("Employee");
254 # returns {
255 # name => undef,
256 # ssn => undef
257 # timestamp => $coderef
258 # }
259
260 The "import" method uses two class methods, "prepare_class" and
261 "create_attributes" to set up the @ISA array and attributes. Anyone
262 attempting to extend Class::Tiny itself should use these instead of
263 mocking up a call to "import".
264
265 When the first object is created, linearized @ISA, the valid attribute
266 list and various subroutine references are cached for speed. Ensure that
267 all inheritance and methods are in place before creating objects. (You
268 don't want to be changing that once you create objects anyway, right?)
269
270 RATIONALE
271 Why this instead of Object::Tiny or Class::Accessor or something else?
272 I wanted something so simple that it could potentially be used by core
273 Perl modules I help maintain (or hope to write), most of which either
274 use Class::Struct or roll-their-own OO framework each time.
275
276 Object::Tiny and Object::Tiny::RW were close to what I wanted, but
277 lacking some features I deemed necessary, and their maintainers have an
278 even more strict philosophy against feature creep than I have.
279
280 I also considered Class::Accessor, which has been around a long time and
281 is heavily used, but it, too, lacked features I wanted and did things in
282 ways I considered poor design.
283
284 I looked for something else on CPAN, but after checking a dozen class
285 creators I realized I could implement exactly what I wanted faster than
286 I could search CPAN for something merely sufficient.
287
288 In general, compared to most things on CPAN (other than Object::Tiny),
289 Class::Tiny is smaller in implementation and simpler in API.
290
291 Specifically, here is how Class::Tiny ("C::T") compares to Object::Tiny
292 ("O::T") and Class::Accessor ("C::A"):
293
294 FEATURE C::T O::T C::A
295 --------------------------------------------------------------
296 attributes defined via import yes yes no
297 read/write accessors yes no yes
298 lazy attribute defaults yes no no
299 provides new yes yes yes
300 provides DESTROY yes no no
301 new takes either hashref or list yes no (list) no (hash)
302 Moo(se)-like BUILD/DEMOLISH yes no no
303 Moo(se)-like BUILDARGS yes no no
304 no extraneous methods via @ISA yes yes no
305
306 Why this instead of Moose or Moo?
307 Moose and Moo are both excellent OO frameworks. Moose offers a powerful
308 meta-object protocol (MOP), but is slow to start up and has about 30
309 non-core dependencies including XS modules. Moo is faster to start up
310 and has about 10 pure Perl dependencies but provides no true MOP,
311 relying instead on its ability to transparently upgrade Moo to Moose
312 when Moose's full feature set is required.
313
314 By contrast, Class::Tiny has no MOP and has zero non-core dependencies
315 for Perls in the support window. It has far less code, less complexity
316 and no learning curve. If you don't need or can't afford what Moo or
317 Moose offer, this is intended to be a reasonable fallback.
318
319 That said, Class::Tiny offers Moose-like conventions for things like
320 "BUILD" and "DEMOLISH" for some minimal interoperability and an easier
321 upgrade path.
322
323 AUTHOR
324 David Golden <[email protected]>
325
326 CONTRIBUTORS
327 * Dagfinn Ilmari MannsĂ„ker <[email protected]>
328
329 * David Golden <[email protected]>
330
331 * Gelu Lupas <[email protected]>
332
333 * Karen Etheridge <[email protected]>
334
335 * Matt S Trout <[email protected]>
336
337 * Olivier MenguĂ© <[email protected]>
338
339 * Toby Inkster <[email protected]>
340
341 COPYRIGHT AND LICENSE
342 This software is Copyright (c) 2013 by David Golden.
343
344 This is free software, licensed under:
345
346 The Apache License, Version 2.0, January 2004
347