| 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 |
|