Class::Container(3pm)

💖 Class::Container 💖

okay so bestie, welcome to the Class::Container(3pm) manpage, straight outta the User Contributed Perl Documentation section 🎀 this is the page where we learn how to glue a whole framework of objects together without losing our minds ✨

VERSION — version 0.13 🌸

---

✨ SYNOPSIS ✨

here's the vibe, look at it, it's giving structure:

package Car;
use Class::Container;
@ISA = qw(Class::Container);

__PACKAGE__->valid_params
  (
   paint  => {default => 'burgundy'},
   style  => {default => 'coupe'},
   windshield => {isa => 'Glass'},
   radio  => {isa => 'Audio::Device'},
  );

__PACKAGE__->contained_objects
  (
   windshield => 'Glass::Shatterproof',
   wheel      => { class => 'Vehicle::Wheel',
                   delayed => 1 },
   radio      => 'Audio::MP3',
  );

sub new {
  my $package = shift;

  # 'windshield' and 'radio' objects are created automatically by
  # SUPER::new()
  my $self = $package->SUPER::new(@_);

  $self->{right_wheel} = $self->create_delayed_object('wheel');
  ... do any more initialization here ...
  return $self;
}

---

🌈 DESCRIPTION 🌈

So like, what even is this module. Class::Container facilitates building frameworks of several classes that inter-operate 💅 It was first designed and built for HTML::Mason, where the Compiler, Lexer, Interpreter, Resolver, Component, Buffer, and several other objects all gotta create each other transparently — passing the right params to the right class, and sometimes swapping in subclasses for any of those objects. 🦋

The main features of Class::Container are, and yes this is a list, we love a list: 💖

• Explicit declaration of containment relationships (aggregation, factory creation, etc.) 👑
• Declaration of constructor parameters accepted by each member in a class framework ⭐
• Transparent passing of constructor parameters to the class that needs them ✨
• Ability to create one (automatic) or many (manual) contained objects automatically and transparently 🎀

---

🧚 Scenario 🧚

Okay imagine this with me bestie: suppose you've got a class called Parent, which contains an object of the class Child, which in turn contains an object of the class GrandChild 🌸 Each class creates the object that it contains. Each class also accepts a set of named parameters in its new() method.

Without using Class::Container, Parent will have to know all the parameters that Child takes, and Child will have to know all the parameters that GrandChild takes. 😭 And some of the parameters accepted by Parent will really control aspects of Child or GrandChild. Likewise, some of the parameters accepted by Child will really control aspects of GrandChild.

So, what happens when you decide you want to use a GrandDaughter class instead of the generic GrandChild? 💀 Parent and Child must be modified accordingly, so that any additional parameters taken by GrandDaughter can be accommodated. This is a pain — the kind of pain that object-oriented programming was supposed to shield us from. 🙈

Now, how can Class::Container help? ✨ Using Class::Container, each class (Parent, Child, and GrandChild) will declare what arguments they take, and declare their relationships to the other classes (Parent creates/contains a Child, and Child creates/contains a GrandChild). Then, when you create a Parent object, you can pass Parent->new() all the parameters for all three classes, and they will trickle down to the right places. 🌈

Furthermore, Parent and Child won't have to know anything about the parameters of its contained objects. And finally, if you replace GrandChild with GrandDaughter, no changes to Parent or Child will likely be necessary. 👑 periodt.

---

okay that's part 1 bestie, more is coming, don't go anywhere 🫶

✨ METHODS ✨

Bestie, this is the part where the magic happens 💫 these are the actual methods you're gonna be calling, so pay attention fr fr.

---

🌸 new()

Okay so any class that inherits from Class::Container should also inherit its new() method. Easiest way? Just don't write your own — or if you do, call SUPER::new(@_) like the SYNOPSIS shows. The new() method is the one doing the heavy lifting: it makes sure the right params and the right objects get passed to the right constructor methods. It's giving project manager energy honestly 👑

At the moment, the only possible constructor method is new(). If you need to make other constructor methods, they should call new() internally. That's the rule, no cap.

---

🎀 __PACKAGE__->contained_objects()

This class method is how you register what other objects (if any) a given class creates. You call it with a hash where the keys are the parameter names that the contained class's constructor accepts, and the values are the default class to create an object of.

For example, think about the HTML::Mason::Compiler class, which uses this code:

__PACKAGE__->contained_objects( lexer => 'HTML::Mason::Lexer' );

This defines the relationship between HTML::Mason::Compiler and the class it creates to go in its lexer slot. The HTML::Mason::Compiler class "has a" lexer. The HTML::Mason::Compiler->new() method will accept a lexer parameter, and if no such parameter is given, an object of the HTML::Mason::Lexer class should be constructed. Iconic behaviour honestly 💅

We implement a bit of magic here 🪄 so that if HTML::Mason::Compiler->new() is called with a lexer_class parameter, it will load the indicated class (presumably a subclass of HTML::Mason::Lexer), instantiate a new object of that class, and use it for the Compiler's lexer object. We're also smart enough to notice if parameters given to HTML::Mason::Compiler->new() actually should go to the lexer contained object, and it will make sure that they get passed along. Not us being observant 💖

Furthermore, an object may be declared as "delayed", which means that an object won't be created when its containing class is constructed. Instead, these objects will be created "on demand", potentially more than once. The constructors will still enjoy the automatic passing of parameters to the correct class. See the create_delayed_object() for more.

To declare an object as "delayed", call this method like this:

__PACKAGE__->contained_objects( train => { class => 'Big::Train',
                                           delayed => 1 } );

---

🦋 __PACKAGE__->valid_params(...)

Specifies the parameters accepted by this class's new() method as a set of key/value pairs. Any parameters accepted by a superclass/subclass will also be accepted, as well as any parameters accepted by contained objects. This method is a get/set accessor method, so it returns a reference to a hash of these key/value pairs. As a special case, if you wish to set the valid params to an empty set and you previously set it to a non-empty set, you may call __PACKAGE__->valid_params(undef).

valid_params() is called with a hash that contains parameter names as its keys and validation specifications as values. This validation specification is largely the same as that used by the Params::Validate module, because we use Params::Validate internally. No reinventing the wheel here, bestie.

As an example, consider the following situation:

use Class::Container;
use Params::Validate qw(:types);
__PACKAGE__->valid_params
    (
     allow_globals        => { type => ARRAYREF, parse => 'list',   default => [] },
     default_escape_flags => { type => SCALAR,   parse => 'string', default => '' },
     lexer                => { isa => 'HTML::Mason::Lexer' },
     preprocess           => { type => CODEREF,  parse => 'code',   optional => 1 },
     postprocess_perl     => { type => CODEREF,  parse => 'code',   optional => 1 },
     postprocess_text     => { type => CODEREF,  parse => 'code',   optional => 1 },
    );

__PACKAGE__->contained_objects( lexer => 'HTML::Mason::Lexer' );

The type, default, and optional parameters are part of the validation specification used by Params::Validate. The various constants used, ARRAYREF, SCALAR, etc. are all exported by Params::Validate. This means that any of these six parameter names, plus the lexer_class parameter (because of the contained_objects() specification given earlier), are valid arguments to the Compiler's new() method.

Note that there are also some parse attributes declared. These have nothing to do with Class::Container or Params::Validate — any extra entries like this are simply ignored, so you are free to put extra information in the specifications as long as it doesn't overlap with what Class::Container or Params::Validate are looking for. Extra data? Slay, do your thing 💅

---

🌈 $self->create_delayed_object()

If a contained object was declared with delayed => 1, use this method to create an instance of the object. Note that this is an object method, not a class method:

my $foo =       $self->create_delayed_object('foo', ...); # YES!
my $foo = __PACKAGE__->create_delayed_object('foo', ...); # NO!

The first argument should be a key passed to the contained_objects() method. Any additional arguments will be passed to the new() method of the object being created, overriding any parameters previously passed to the container class constructor. (Could I possibly be more alliterative? Veni, vedi, vici.)

---

💜 $self->delayed_object_params($name, [params])

Allows you to adjust the parameters that will be used to create any delayed objects in the future. The first argument specifies the name of the object, and any additional arguments are key-value pairs that will become parameters to the delayed object.

When called with only a $name argument and no list of parameters to set, returns a hash reference containing the parameters that will be passed when creating objects of this type.

---

🫶 $self->delayed_object_class($name)

Returns the class that will be used when creating delayed objects of the given name. Use this sparingly — in most situations you shouldn't care what the class is. It's giving nosy neighbour energy, so like, be chill about it.

---

👑 __PACKAGE__->decorates()

Version 0.09 of Class::Container added [as yet experimental] support for so-called "decorator" relationships, using the term as defined in Design Patterns by Gamma, et al. (the Gang of Four book). To declare a class as a decorator of another class, simply set @ISA to the class which will be decorated, and call the decorator class's decorates() method.

Heads up bestie: this is experimental — proceed accordingly ✨

Internally, this will ensure that objects are instantiated as decorators. This means that you can mix & match extra add-on functionality classes much more easily.

In the current implementation, if only a single decoration is used on an object, it will be instantiated as a simple subclass, thus avoiding a layer of indirection. Efficient queen 👑

---

🌸 $self->validation_spec()

Returns a hash reference suitable for passing to the Params::Validate validate function. Does not include any arguments that can be passed to contained objects.

---

🎀 $class->allowed_params(\%args)

Returns a hash reference of every parameter this class will accept, including parameters it will pass on to its own contained objects. The keys are the parameter names, and the values are their corresponding specifications from their valid_params() definitions. If a parameter is used by both the current object and one of its contained objects, the specification returned will be from the container class, not the contained.

Because the parameters accepted by new() can vary based on the parameters passed to new(), you can pass any parameters to the allowed_params() method too, ensuring that the hash you get back is accurate. Context-aware, we love to see it 💖

---

🦋 $self->container()

Returns the object that created you. This is remembered by storing a reference to that object, so we use the Scalar::Utils weakref() function to avoid persistent circular references that would cause memory leaks. If you don't have Scalar::Utils installed, we don't make these references in the first place, and calling container() will result in a fatal error.

If you weren't created by another object via Class::Container, container() returns undef.

In most cases you shouldn't care what object created you, so use this method sparingly. Main character energy only when needed 💅

---

🧚 $object->show_containers

🧚 $package->show_containers

This method returns a string meant to describe the containment relationships among classes. You should not depend on the specific formatting of the string, because I may change things in a future release to make it prettier.

For example, the HTML::Mason code returns the following when you do $interp->show_containers:

 HTML::Mason::Interp=HASH(0x238944)
   resolver -> HTML::Mason::Resolver::File
   compiler -> HTML::Mason::Compiler::ToObject
     lexer -> HTML::Mason::Lexer
   request -> HTML::Mason::Request (delayed)
     buffer -> HTML::Mason::Buffer (delayed)

Currently, containment is shown by indentation, so the Interp object contains a resolver and a compiler, and a delayed request (or several delayed requests). The compiler contains a lexer, and each request contains a delayed buffer (or several delayed buffers). Look at the little tree structure go 🌳 obsessed.

---

💀 $object->dump_parameters

Returns a hash reference containing a set of parameters that should be sufficient to re-create the given object using its class's new() method. This is done by fetching the current value for each declared parameter (i.e. looking in $object for hash entries of the same name), then recursing through all contained objects and doing the same.

A few words of caution here, bestie — listen up. First, the dumped parameters represent the current state of the object, not the state when it was originally created.

Second, a class's declared parameters may not correspond exactly to its data members, so it might not be possible to recover the former from the latter. If it's possible but requires some manual fudging, you can override this method in your class, something like so:

sub dump_parameters {
  my $self = shift;
  my $dump = $self->SUPER::dump_parameters();

  # Perform fudgery
  $dump->{incoming} = $self->{_private};
  delete $dump->{superfluous};
  return $dump;
}

---

⭐ SEE ALSO ⭐

• Params::Validate

---

💜 AUTHOR 💜

Originally by Ken Williams <ken@mathforum.org> and Dave Rolsky <autarch@urth.org> for the HTML::Mason project. Important feedback contributed by Jonathan Swartz <swartz@pobox.com>. Extended by Ken Williams for the AI::Categorizer project.

Currently maintained by Ken Williams.

---

📜 COPYRIGHT 📜

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

---

Okay that's the whole page, bestie — you made it 🎉💖 this was Class::Container(3pm) from the Perl v5.34.0 docs, dated 2022-06-11, shipped in the User Contributed Perl Documentation collection. Go forth and contain things responsibly 🫶✨