Class::Tiny(3)

🎀 NAME 🎀

Class::Tiny — Minimalist class construction. This is the Class::Tiny(3) man page, bestie — User Contributed Perl Documentation and everything. 💖

---

✨ VERSION ✨

version 1.008 — that's the version, no cap. 💅

---

🦋 SYNOPSIS 🦋

Okay so first up, in Person.pm:

package Person;

use Class::Tiny qw( name );

1;

Then in Employee.pm:

package Employee;
use parent 'Person';

use Class::Tiny qw( ssn ), {
  timestamp => sub { time }   # attribute with default
};

1;

And in example.pl:

use Employee;

my $obj = Employee->new( name => "Larry", ssn => "111-22-3333" );

# unknown attributes are ignored
my $obj = Employee->new( name => "Larry", OS => "Linux" );
# $obj->{OS} does not exist

---

🌸 DESCRIPTION 🌸

Okay so Class::Tiny is a whole minimalist class-construction kit that fits in around 120 lines of code. Iconic. Here's the feature haul:

• 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 supports providing BUILDARGS to customize constructor options 💖
• 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. Yup, that's the vibe. 💜

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. Important little compatibility note, bestie. 🧚

---

💅 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. So like, don't get cute with the names. 😭

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. MRO said what it said. 💅

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 { ... }

Even if you pre-declare a method name, you must include it in the attribute list for Class::Tiny to register it as a valid attribute. No skipping that part, bestie. 🫶

If you set a default for a custom accessor, your accessor will need to retrieve the default and do something with it:

package Foo::Bar;

use subs 'id';

use Class::Tiny qw( name ), { id => sub { int(rand(2*31)) } };

sub id {
    my $self = shift;
    if (@_) {
        return $self->{id} = shift;
    }
    elsif ( exists $self->{id} ) {
        return $self->{id};
    }
    else {
        my $defaults =
            Class::Tiny->get_all_attribute_defaults_for( ref $self );
        return $self->{id} = $defaults->{id}->();
    }
}

🧚 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. Free constructor and destructor, slay. ✨

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. Like, seriously. 💀

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. Main character energy. 👑

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. Don't try to hand it some random arrayref and expect magic. 🫶

Unknown attributes in the constructor arguments will be ignored. Prior to version 1.000, unknown attributes were an error, but this made it harder for people to cleanly subclass Class::Tiny classes so this feature was removed. Character development. 💅

You can define a BUILDARGS method to change how arguments to new are handled. It will receive the constructor arguments as they were provided and must return a hash reference of key/value pairs (or else throw an exception).

sub BUILDARGS {
   my $class = shift;
   my $name = shift || "John Doe";
   return { name => $name };
 };

 Foo::Bar->new( "David" );
 Foo::Bar->new(); # "John Doe"

Unknown attributes returned from BUILDARGS will be ignored. Noted. 📝

🌈 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. Parent first, then down to child — that's the order. 💖

It is passed the constructor arguments as a hash reference. The return value is ignored. Use BUILD for validation, checking required attributes or setting default values that depend on other attributes.

sub BUILD {
    my ($self, $args) = @_;

    for my $req ( qw/name age/ ) {
        croak "$req attribute required" unless defined $self->$req;
    }

    croak "Age must be non-negative" if $self->age < 0;

    $self->msg( "Hello " . $self->name );
}

The argument reference is a copy, so deleting elements won't affect data in the original (but changes will be passed to other BUILD methods in @ISA). Little copy-pasta, but make it intentional. 🍓

💀 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 are ignored. Errors are caught and rethrown.

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. Respect the internals, bestie. 👑

When the first object is created, linearized @ISA, the valid attribute list and various subroutine 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? 🧐

okay so the whole tea here: the author wanted something so simple that it could potentially get used by core Perl modules he helps maintain (or hopes to write), and like… most of those either use Class::Struct or just roll-their-own OO framework every single time. 💀

Object::Tiny and Object::Tiny::RW were close to what he wanted, but lowkey lacking some features he deemed necessary, and ngl their maintainers have an even stricter philosophy against feature creep than he does. 🙈

He also considered Class::Accessor, which has been around forever and is heavily used, but it, too, lacked the features he wanted and did things in ways he considered poor design. 🫠

Then he went looking for something else on CPAN, but after checking a dozen class creators he realized he could implement exactly what he wanted faster than he could search CPAN for something merely sufficient. main character energy, honestly. 👑

In general, compared to most things on CPAN (other than Object::Tiny), Class::Tiny is smaller in implementation and simpler in API. periodt. ✨

Specifically, here's how Class::Tiny (C::T) compares to Object::Tiny (O::T) and Class::Accessor (C::A) — vibe check, feature by feature:

• attributes defined via import — C::T: yes · O::T: yes · C::A: no
• read/write accessors — C::T: yes · O::T: no · C::A: yes
• lazy attribute defaults — C::T: yes · O::T: no · C::A: no
• provides new — C::T: yes · O::T: yes · C::A: yes
• provides DESTROY — C::T: yes · O::T: no · C::A: no
• new takes either hashref or list — C::T: yes · O::T: no (list) · C::A: no (hash)
• Moo(se)-like BUILD/DEMOLISH — C::T: yes · O::T: no · C::A: no
• Moo(se)-like BUILDARGS — C::T: yes · O::T: no · C::A: no
• no extraneous methods via @ISA — C::T: yes · O::T: yes · C::A: no

---

Why this instead of Moose or Moo? 🦋

Moose and Moo are both excellent OO frameworks, no cap. Moose offers a powerful meta-object protocol (MOP), but it's 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 — it relies instead on its ability to transparently upgrade Moo to Moose when Moose's full feature set is required. slay for them, honestly.

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. So if you don't need or can't afford what Moo or Moose offer, this is intended to be a reasonable fallback. 🫶

That said, Class::Tiny does offer Moose-like conventions for things like BUILD and DEMOLISH for some minimal interoperability and an easier upgrade path. little sprinkle of compatibility, we love to see it. 🌸

---

💖 AUTHOR 💖

David Golden <dagolden@cpan.org>

---

🫶 CONTRIBUTORS 🫶

• Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
• David Golden <xdg@xdg.me>
• Gelu Lupas <gelu@devnull.ro>
• Karen Etheridge <ether@cpan.org>
• Matt S Trout <mstrout@cpan.org>
• Olivier Mengué <dolmen@cpan.org>
• Toby Inkster <tobyink@cpan.org>

the whole squad showed up, iconic. 👑

---

📜 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

---

okay bestie that's the whole page, you're officially a Class::Tiny girlie now 💅 this was Class::Tiny(3) as shipped with perl v5.42.0, dated 2020-09-05 — go forth and make tiny little classes, mwah 🎀✨