Class:...Builder(3pm)

💖 Class::Adapter::Builder 💖

okay so bestie, quick vibe check: this page lives in the User Contributed Perl Documentation and it's filed under Class:...Builder(3pm) — yes the title is lowkey truncated, we don't ask questions, we just roll with it 💅

---

🌸 NAME 🌸

Class::Adapter::Builder — Generate Class::Adapter classes ✨

⭐ VERSION ⭐

version 1.09

🎀 SYNOPSIS 🎀

package My::Adapter;

use strict;
use Class::Adapter::Builder
    ISA     => 'Specific::API',
    METHODS => [ qw{foo bar baz} ],
    method  => 'different_method';

1;

🦋 DESCRIPTION 🦋

So Class::Adapter::Builder is, like, another way to let you cook up your own Adapter classes. It's not here to do the job for you, bestie — it's here to be a whole toolkit for generating the guts of tons of different, varied kinds of Adapter classes. It's giving ✨workshop✨.

And if what you actually want is a simple base class you can inherit from and then just change one specific method? Then go look at Class::Adapter::Clear instead, that's its whole thing.

🌈 The Pragma Interface 🌈

The most common way to define Adapter classes — literally the one in the synopsis, the classic, the icon — is the pragma interface.

It's just a set of key/value pairs you hand over when you load the module. No cap.

# The format for building Adapter classes
use Class::Adapter::Builder PARAM => VALUE, ...

💜 ISA

The ISA param comes as either one single value, or a reference to an ARRAY that holds the list of classes.

Normally it's just a straight-up list of classes. But — plot twist — if you set ISA to '_OBJECT_', then the object will identify itself as whatever is actually contained in it when ->isa and ->can get called on it. Sneaky. Iconic. Slay.

💙 NEW

Normally you have to build your Class::Adapter objects separately, in two whole steps:

# Create the object
my $query = CGI->new( 'param1', 'param2' );

# Create the Decorator
my $object = My::Adapter->new( $query );

But if you pass a class name as the NEW param, the Decorator does that whole first step for you and passes along any constructor arguments. Two steps become one, we love efficiency:

# Assume we provided the following
# NEW => 'CGI',

# We can now do the above in one step
my $object = My::Adapter->new( 'param1', 'param2' );

💚 AUTOLOAD

By default, a Class::Adapter does not pass on any methods — nope, zero, none. The methods that do get passed on have to be spelled out explicitly with the METHODS param.

But if you set AUTOLOAD to true, the Adapter gets handed the standard AUTOLOAD function so it can pass through all the unspecified methods to the parent object. Main character behaviour fr fr.

By default, that AUTOLOAD passes through any and all calls — including calls to private methods. Yeah. All of them.

If instead you specifically set AUTOLOAD to 'PUBLIC', then the AUTOLOAD setting will ONLY apply to public methods, and private methods will not be passed through at all. Boundaries! We stan a boundary.

💛 METHODS

The METHODS param comes as a reference to an array of all the methods that are to be passed through to the parent object as-is. Simple as that.

---

Any params other than the ones listed above are taken as translated methods. 👀

# If you provide the following
# foo => bar

# It the following are equivalent
$decorator->foo;
$decorator->_OBJECT_->bar;

This whole capability exists primarily because in Perl, one of the main situations where you smack face-first into the limits of Perl's inheritance model is when your class needs to inherit from multiple different classes that contain clashing methods. It's giving chaos. 😭

For example:

# If your class is like this
package Foo;

use base 'This', 'That';

1;

If both This->method exists and That->method exists, and the two of them mean different things, then Foo->method becomes ambiguous. 💀

A Class::Adapter could be used to wrap your Foo object, with the Class::Adapter becoming the That sub-class, and passing $decorator->method through to $object->that_method. Problem solved, vibe restored. 🫶

✨ METHODS ✨

Yes, Class::Adapter::Builder has public methods, and later on you'll be able to access them directly — but for now they're staying undocumented, so that I can shuffle things around for another few versions. 🙈

Just stick to the pragma interface for now, bestie. Trust.

👀 SEE ALSO 👀

Class::Adapter, Class::Adapter::Clear

🛟 SUPPORT 🛟

Bugs may be submitted through the RT bug tracker <https://rt.cpan.org/Public/Dist/Display.html?Name=Class-Adapter> (or bug-Class-Adapter@rt.cpan.org <mailto:bug-Class-Adapter@rt.cpan.org>).

👑 AUTHOR 👑

Adam Kennedy <adamk@cpan.org>

📜 COPYRIGHT AND LICENSE 📜

This software is copyright (c) 2005 by Adam Kennedy.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page, bestie 💖 this one shipped as part of perl v5.36.0, dated 2022-12-04 — go forth and build your adapters, periodt 🌸🦋✨