-
-
03 Nov 2017 04:56:06 UTC
- Distribution: Class-Container
- Module version: 0.13
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Repository
- Issues
- Testers (2323 / 0 / 0)
- Kwalitee
Bus factor: 1- 73.24% Coverage
- License: perl_5
- Activity
24 month- Tools
- Download (25.16KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
- NAME
- VERSION
- SYNOPSIS
- DESCRIPTION
- METHODS
- new()
- __PACKAGE__->contained_objects()
- __PACKAGE__->valid_params(...)
- $self->create_delayed_object()
- $self->delayed_object_params($name, [params])
- $self->delayed_object_class($name)
- __PACKAGE__->decorates()
- $self->validation_spec()
- $class->allowed_params(\%args)
- $self->container()
- $object->show_containers
- $package->show_containers
- $object->dump_parameters
- SEE ALSO
- AUTHOR
- COPYRIGHT
NAME
Class::Container - Glues object frameworks together transparently
VERSION
version 0.13
SYNOPSIS
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
This class facilitates building frameworks of several classes that inter-operate. It was first designed and built for
HTML::Mason
, in which the Compiler, Lexer, Interpreter, Resolver, Component, Buffer, and several other objects must create each other transparently, passing the appropriate parameters to the right class, possibly substituting other subclasses for any of these objects.The main features of
Class::Container
are: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
Suppose you've got a class called
Parent
, which contains an object of the classChild
, which in turn contains an object of the classGrandChild
. Each class creates the object that it contains. Each class also accepts a set of named parameters in itsnew()
method. Without usingClass::Container
,Parent
will have to know all the parameters thatChild
takes, andChild
will have to know all the parameters thatGrandChild
takes. And some of the parameters accepted byParent
will really control aspects ofChild
orGrandChild
. Likewise, some of the parameters accepted byChild
will really control aspects ofGrandChild
. So, what happens when you decide you want to use aGrandDaughter
class instead of the genericGrandChild
?Parent
andChild
must be modified accordingly, so that any additional parameters taken byGrandDaughter
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? UsingClass::Container
, each class (Parent
,Child
, andGrandChild
) will declare what arguments they take, and declare their relationships to the other classes (Parent
creates/contains aChild
, andChild
creates/contains aGrandChild
). Then, when you create aParent
object, you can passParent->new()
all the parameters for all three classes, and they will trickle down to the right places. Furthermore,Parent
andChild
won't have to know anything about the parameters of its contained objects. And finally, if you replaceGrandChild
withGrandDaughter
, no changes toParent
orChild
will likely be necessary.METHODS
new()
Any class that inherits from
Class::Container
should also inherit itsnew()
method. You can do this simply by omitting it in your class, or by callingSUPER::new(@_)
as indicated in the SYNOPSIS. Thenew()
method ensures that the proper parameters and objects are passed to the proper constructor methods.At the moment, the only possible constructor method is
new()
. If you need to create other constructor methods, they should callnew()
internally.__PACKAGE__->contained_objects()
This class method is used to register what other objects, if any, a given class creates. It is called with a hash whose keys are the parameter names that the contained class's constructor accepts, and whose values are the default class to create an object of.
For example, consider the
HTML::Mason::Compiler
class, which uses the following code:__PACKAGE__->contained_objects( lexer => 'HTML::Mason::Lexer' );
This defines the relationship between the
HTML::Mason::Compiler
class and the class it creates to go in itslexer
slot. TheHTML::Mason::Compiler
class "has a"lexer
. TheHTML::Mason::Compiler->new()
method will accept alexer
parameter and, if no such parameter is given, an object of theHTML::Mason::Lexer
class should be constructed.We implement a bit of magic here, so that if
HTML::Mason::Compiler->new()
is called with alexer_class
parameter, it will load the indicated class (presumably a subclass ofHTML::Mason::Lexer
), instantiate a new object of that class, and use it for the Compiler'slexer
object. We're also smart enough to notice if parameters given toHTML::Mason::Compiler->new()
actually should go to thelexer
contained object, and it will make sure that they get passed along.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 theParams::Validate
module, because we useParams::Validate
internally.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
, andoptional
parameters are part of the validation specification used byParams::Validate
. The various constants used,ARRAYREF
,SCALAR
, etc. are all exported byParams::Validate
. This means that any of these six parameter names, plus thelexer_class
parameter (because of thecontained_objects()
specification given earlier), are valid arguments to the Compiler'snew()
method.Note that there are also some
parse
attributes declared. These have nothing to do withClass::Container
orParams::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 whatClass::Container
orParams::Validate
are looking for.$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 thenew()
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.
__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'sdecorates()
method.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.
$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 tonew()
, you can pass any parameters to theallowed_params()
method too, ensuring that the hash you get back is accurate.$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 haveScalar::Utils
installed, we don't make these references in the first place, and callingcontainer()
will result in a fatal error.If you weren't created by another object via
Class::Container
,container()
returnsundef
.In most cases you shouldn't care what object created you, so use this method sparingly.
$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).
$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. 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
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.
Module Install Instructions
To install Class::Container, copy and paste the appropriate command in to your terminal.
cpanm Class::Container
perl -MCPAN -e shell install Class::Container
For more information on module installation, please visit the detailed CPAN module installation guide.