Provided by: libclass-tiny-perl_0.012-1_all 
NAME
Class::Tiny - Minimalist class construction
VERSION
version 0.012
SYNOPSIS
In Person.pm:
package Person;
use Class::Tiny qw( name );
1;
In Employee.pm:
package Employee;
use parent 'Person';
use Class::Tiny qw( ssn ), {
timestamp => sub { time } # attribute with default
};
1;
In example.pl:
use Employee;
my $obj = Employee->new( name => "Larry", ssn => "111-22-3333" );
# unknown attributes are fatal:
eval { Employee->new( name => "Larry", OS => "Linux" ) };
die "Error creating Employee: $@" if $@;
DESCRIPTION
This module offers a minimalist class construction kit in around 120 lines of code. Here
is a list of features:
· defines attributes via import arguments
· generates read-write accessors
· supports lazy attribute defaults
· supports custom accessors
· superclass provides a standard "new" constructor
· "new" takes a hash reference or list of key/value pairs
· "new" has heuristics to catch constructor attribute typos
· "new" calls "BUILD" for each class from parent to child
· superclass provides a "DESTROY" method
· "DESTROY" calls "DEMOLISH" for each class from child to parent
Multiple-inheritance is possible, with superclass order determined via
mro::get_linear_isa.
It uses no non-core modules for any recent Perl. On Perls older than v5.10 it requires
MRO::Compat. On Perls older than v5.14, it requires Devel::GlobalDestruction.
USAGE
Defining attributes
Define attributes as a list of import arguments:
package Foo::Bar;
use Class::Tiny qw(
name
id
height
weight
);
For each attribute, a read-write accessor is created unless a subroutine of that name
already exists:
$obj->name; # getter
$obj->name( "John Doe" ); # setter
Attribute names must be valid subroutine identifiers or an exception will be thrown.
You can specify lazy defaults by defining attributes with a hash reference. Keys define
attribute names and values are constants or code references that will be evaluated when
the attribute is first accessed if no value has been set. The object is passed as an
argument to a code reference.
package Foo::WithDefaults;
use Class::Tiny qw/name id/, {
title => 'Peon',
skills => sub { [] },
hire_date => sub { $_[0]->_build_hire_date },
};
When subclassing, if multiple accessors of the same name exist in different classes, any
default (or lack of default) is determined by standard method resolution order.
To make your own custom accessors, just pre-declare the method name before loading
Class::Tiny:
package Foo::Bar;
use subs 'id';
use Class::Tiny qw( name id );
sub id { ... }
By declaring "id" also with Class::Tiny, you include it in the list of known attributes
for introspection. Default values will not be set for custom accessors unless you handle
that yourself.
Class::Tiny::Object is your base class
If your class does not already inherit from some class, then Class::Tiny::Object will be
added to your @ISA to provide "new" and "DESTROY".
If your class does inherit from something, then no additional inheritance is set up. If
the parent subclasses Class::Tiny::Object, then all is well. If not, then you'll get
accessors set up but no constructor or destructor. Don't do that unless you really have a
special need for it.
Define subclasses as normal. It's best to define them with base, parent or superclass
before defining attributes with Class::Tiny so the @ISA array is already populated at
compile-time:
package Foo::Bar::More;
use parent 'Foo::Bar';
use Class::Tiny qw( shoe_size );
Object construction
If your class inherits from Class::Tiny::Object (as it should if you followed the advice
above), it provides the "new" constructor for you.
Objects can be created with attributes given as a hash reference or as a list of key/value
pairs:
$obj = Foo::Bar->new( name => "David" );
$obj = Foo::Bar->new( { name => "David" } );
If a reference is passed as a single argument, it must be able to be dereferenced as a
hash or an exception is thrown. A shallow copy is made of the reference provided.
In order to help catch typos in constructor arguments, any argument that it is not also a
valid method (e.g. an accessor or other method) will result in a fatal exception. This is
not perfect, but should catch typical transposition typos. Also see "BUILD" for how to
explicitly hide non-attribute, non-method arguments if desired.
BUILD
If your class or any superclass defines a "BUILD" method, it will be called by the
constructor from the furthest parent class down to the child class after the object has
been created.
It is passed the constructor arguments as a hash reference. The return value is ignored.
Use "BUILD" for validation or setting default values.
sub BUILD {
my ($self, $args) = @_;
$self->foo(42) unless defined $self->foo;
croak "Foo must be non-negative" if $self->foo < 0;
}
If you want to hide a non-attribute constructor argument from validation, delete it from
the passed-in argument hash reference.
sub BUILD {
my ($self, $args) = @_;
if ( delete $args->{do_something_special} ) {
...
}
}
The argument reference is a copy, so deleting elements won't affect data in the object.
You have to delete it from both if that's what you want.
sub BUILD {
my ($self, $args) = @_;
if ( delete $args->{do_something_special} ) {
delete $self->{do_something_special};
...
}
}
DEMOLISH
Class::Tiny provides a "DESTROY" method. If your class or any superclass defines a
"DEMOLISH" method, they will be called from the child class to the furthest parent class
during object destruction. It is provided a single boolean argument indicating whether
Perl is in global destruction. Return values and errors are ignored.
sub DEMOLISH {
my ($self, $global_destruct) = @_;
$self->cleanup();
}
Introspection and internals
You can retrieve an unsorted list of valid attributes known to Class::Tiny for a class and
its superclasses with the "get_all_attributes_for" class method.
my @attrs = Class::Tiny->get_all_attributes_for("Employee");
# returns qw/name ssn timestamp/
Likewise, a hash reference of all valid attributes and default values (or code references)
may be retrieved with the "get_all_attribute_defaults_for" class method. Any attributes
without a default will be "undef".
my $def = Class::Tiny->get_all_attribute_defaults_for("Employee");
# returns {
# name => undef,
# ssn => undef
# timestamp => $coderef
# }
The "import" method uses two class methods, "prepare_class" and "create_attributes" to set
up the @ISA array and attributes. Anyone attempting to extend Class::Tiny itself should
use these instead of mocking up a call to "import".
When the first object is created, linearized @ISA and various subroutines references are
cached for speed. Ensure that all inheritance and methods are in place before creating
objects. (You don't want to be changing that once you create objects anyway, right?)
RATIONALE
Why this instead of Object::Tiny or Class::Accessor or something else?
I wanted something so simple that it could potentially be used by core Perl modules I help
maintain (or hope to write), most of which either use Class::Struct or roll-their-own OO
framework each time.
Object::Tiny and Object::Tiny::RW were close to what I wanted, but lacking some features I
deemed necessary, and their maintainers have an even more strict philosophy against
feature creep than I have.
I looked for something like it on CPAN, but after checking a dozen class creators I
realized I could implement it exactly how I wanted faster than I could search CPAN for
something merely sufficient. Compared to everything else, this is smaller in
implementation and simpler in API.
Why this instead of Moose or Moo?
Moose and Moo are both excellent OO frameworks. Moose offers a powerful meta-object
protocol (MOP), but is slow to start up and has about 30 non-core dependencies including
XS modules. Moo is faster to start up and has about 10 pure Perl dependencies but
provides no true MOP, relying instead on its ability to transparently upgrade Moo to Moose
when Moose's full feature set is required.
By contrast, Class::Tiny has no MOP and has zero non-core dependencies for Perls in the
support window. It has far less code, less complexity and no learning curve. If you don't
need or can't afford what Moo or Moose offer, this is a intended to be a reasonable
fallback.
That said, Class::Tiny offers Moose-like conventions for things like "BUILD" and
"DEMOLISH" for some minimal interoperability and an easier upgrade path.
SUPPORT
Bugs / Feature Requests
Please report any bugs or feature requests through the issue tracker at
<https://github.com/dagolden/Class-Tiny/issues>. You will be notified automatically of
any progress on your issue.
Source Code
This is open source software. The code repository is available for public review and
contribution under the terms of the license.
<https://github.com/dagolden/Class-Tiny>
git clone https://github.com/dagolden/Class-Tiny.git
AUTHOR
David Golden <dagolden@cpan.org>
CONTRIBUTORS
· Gelu Lupas <gelu@devnull.ro>
· Karen Etheridge <ether@cpan.org>
· Matt S Trout <mstrout@cpan.org>
· Olivier Mengue <dolmen@cpan.org>
· Toby Inkster <tobyink@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2013 by David Golden.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004