1Class::Container(3) User Contributed Perl Documentation Class::Container(3)
2
6 Class::Container - Glues object frameworks together transparently
7
9 version 0.13
10
12 package Car;
13 use Class::Container;
14 @ISA = qw(Class::Container);
15 __PACKAGE__->valid_params
17 (
18 paint => {default => 'burgundy'},
19 style => {default => 'coupe'},
20 windshield => {isa => 'Glass'},
21 radio => {isa => 'Audio::Device'},
22 );
23 __PACKAGE__->contained_objects
25 (
26 windshield => 'Glass::Shatterproof',
27 wheel => { class => 'Vehicle::Wheel',
28 delayed => 1 },
29 radio => 'Audio::MP3',
30 );
31 sub new {
33 my $package = shift;
34 # 'windshield' and 'radio' objects are created automatically by
36 # SUPER::new()
37 my $self = $package->SUPER::new(@_);
38 $self->{right_wheel} = $self->create_delayed_object('wheel');
40 ... do any more initialization here ...
41 return $self;
42 }
43
45 This class facilitates building frameworks of several classes that
46 inter-operate. It was first designed and built for "HTML::Mason", in
47 which the Compiler, Lexer, Interpreter, Resolver, Component, Buffer,
48 and several other objects must create each other transparently, passing
49 the appropriate parameters to the right class, possibly substituting
50 other subclasses for any of these objects.
51 The main features of "Class::Container" are:
53 • Explicit declaration of containment relationships (aggregation,
55 factory creation, etc.)
56 • Declaration of constructor parameters accepted by each member in a
58 class framework
59 • Transparent passing of constructor parameters to the class that
61 needs them
62 • Ability to create one (automatic) or many (manual) contained
64 objects automatically and transparently
65 Scenario
67 Suppose you've got a class called "Parent", which contains an object of
68 the class "Child", which in turn contains an object of the class
69 "GrandChild". Each class creates the object that it contains. Each
70 class also accepts a set of named parameters in its "new()" method.
71 Without using "Class::Container", "Parent" will have to know all the
72 parameters that "Child" takes, and "Child" will have to know all the
73 parameters that "GrandChild" takes. And some of the parameters
74 accepted by "Parent" will really control aspects of "Child" or
75 "GrandChild". Likewise, some of the parameters accepted by "Child"
76 will really control aspects of "GrandChild". So, what happens when you
77 decide you want to use a "GrandDaughter" class instead of the generic
78 "GrandChild"? "Parent" and "Child" must be modified accordingly, so
79 that any additional parameters taken by "GrandDaughter" can be
80 accommodated. This is a pain - the kind of pain that object-oriented
81 programming was supposed to shield us from.
82 Now, how can "Class::Container" help? Using "Class::Container", each
84 class ("Parent", "Child", and "GrandChild") will declare what arguments
85 they take, and declare their relationships to the other classes
86 ("Parent" creates/contains a "Child", and "Child" creates/contains a
87 "GrandChild"). Then, when you create a "Parent" object, you can pass
88 "Parent->new()" all the parameters for all three classes, and they will
89 trickle down to the right places. Furthermore, "Parent" and "Child"
90 won't have to know anything about the parameters of its contained
91 objects. And finally, if you replace "GrandChild" with
92 "GrandDaughter", no changes to "Parent" or "Child" will likely be
93 necessary.
94
96 new()
97 Any class that inherits from "Class::Container" should also inherit its
98 "new()" method. You can do this simply by omitting it in your class,
99 or by calling "SUPER::new(@_)" as indicated in the SYNOPSIS. The
100 "new()" method ensures that the proper parameters and objects are
101 passed to the proper constructor methods.
102 At the moment, the only possible constructor method is "new()". If you
104 need to create other constructor methods, they should call "new()"
105 internally.
106 __PACKAGE__->contained_objects()
108 This class method is used to register what other objects, if any, a
109 given class creates. It is called with a hash whose keys are the
110 parameter names that the contained class's constructor accepts, and
111 whose values are the default class to create an object of.
112 For example, consider the "HTML::Mason::Compiler" class, which uses the
114 following code:
115 __PACKAGE__->contained_objects( lexer => 'HTML::Mason::Lexer' );
117 This defines the relationship between the "HTML::Mason::Compiler" class
119 and the class it creates to go in its "lexer" slot. The
120 "HTML::Mason::Compiler" class "has a" "lexer". The
121 "HTML::Mason::Compiler->new()" method will accept a "lexer" parameter
122 and, if no such parameter is given, an object of the
123 "HTML::Mason::Lexer" class should be constructed.
124 We implement a bit of magic here, so that if
126 "HTML::Mason::Compiler->new()" is called with a "lexer_class"
127 parameter, it will load the indicated class (presumably a subclass of
128 "HTML::Mason::Lexer"), instantiate a new object of that class, and use
129 it for the Compiler's "lexer" object. We're also smart enough to
130 notice if parameters given to "HTML::Mason::Compiler->new()" actually
131 should go to the "lexer" contained object, and it will make sure that
132 they get passed along.
133 Furthermore, an object may be declared as "delayed", which means that
135 an object won't be created when its containing class is constructed.
136 Instead, these objects will be created "on demand", potentially more
137 than once. The constructors will still enjoy the automatic passing of
138 parameters to the correct class. See the "create_delayed_object()" for
139 more.
140 To declare an object as "delayed", call this method like this:
142 __PACKAGE__->contained_objects( train => { class => 'Big::Train',
144 delayed => 1 } );
145 __PACKAGE__->valid_params(...)
147 Specifies the parameters accepted by this class's "new()" method as a
148 set of key/value pairs. Any parameters accepted by a
149 superclass/subclass will also be accepted, as well as any parameters
150 accepted by contained objects. This method is a get/set accessor
151 method, so it returns a reference to a hash of these key/value pairs.
152 As a special case, if you wish to set the valid params to an empty set
153 and you previously set it to a non-empty set, you may call
154 "__PACKAGE__->valid_params(undef)".
155 "valid_params()" is called with a hash that contains parameter names as
157 its keys and validation specifications as values. This validation
158 specification is largely the same as that used by the
159 "Params::Validate" module, because we use "Params::Validate"
160 internally.
161 As an example, consider the following situation:
163 use Class::Container;
165 use Params::Validate qw(:types);
166 __PACKAGE__->valid_params
167 (
168 allow_globals => { type => ARRAYREF, parse => 'list', default => [] },
169 default_escape_flags => { type => SCALAR, parse => 'string', default => '' },
170 lexer => { isa => 'HTML::Mason::Lexer' },
171 preprocess => { type => CODEREF, parse => 'code', optional => 1 },
172 postprocess_perl => { type => CODEREF, parse => 'code', optional => 1 },
173 postprocess_text => { type => CODEREF, parse => 'code', optional => 1 },
174 );
175 __PACKAGE__->contained_objects( lexer => 'HTML::Mason::Lexer' );
177 The "type", "default", and "optional" parameters are part of the
179 validation specification used by "Params::Validate". The various
180 constants used, "ARRAYREF", "SCALAR", etc. are all exported by
181 "Params::Validate". This means that any of these six parameter names,
182 plus the "lexer_class" parameter (because of the "contained_objects()"
183 specification given earlier), are valid arguments to the Compiler's
184 "new()" method.
185 Note that there are also some "parse" attributes declared. These have
187 nothing to do with "Class::Container" or "Params::Validate" - any extra
188 entries like this are simply ignored, so you are free to put extra
189 information in the specifications as long as it doesn't overlap with
190 what "Class::Container" or "Params::Validate" are looking for.
191 $self->create_delayed_object()
193 If a contained object was declared with "delayed => 1", use this method
194 to create an instance of the object. Note that this is an object
195 method, not a class method:
196 my $foo = $self->create_delayed_object('foo', ...); # YES!
198 my $foo = __PACKAGE__->create_delayed_object('foo', ...); # NO!
199 The first argument should be a key passed to the "contained_objects()"
201 method. Any additional arguments will be passed to the "new()" method
202 of the object being created, overriding any parameters previously
203 passed to the container class constructor. (Could I possibly be more
204 alliterative? Veni, vedi, vici.)
205 $self->delayed_object_params($name, [params])
207 Allows you to adjust the parameters that will be used to create any
208 delayed objects in the future. The first argument specifies the "name"
209 of the object, and any additional arguments are key-value pairs that
210 will become parameters to the delayed object.
211 When called with only a $name argument and no list of parameters to
213 set, returns a hash reference containing the parameters that will be
214 passed when creating objects of this type.
215 $self->delayed_object_class($name)
217 Returns the class that will be used when creating delayed objects of
218 the given name. Use this sparingly - in most situations you shouldn't
219 care what the class is.
220 __PACKAGE__->decorates()
222 Version 0.09 of Class::Container added [as yet experimental] support
223 for so-called "decorator" relationships, using the term as defined in
224 Design Patterns by Gamma, et al. (the Gang of Four book). To declare a
225 class as a decorator of another class, simply set @ISA to the class
226 which will be decorated, and call the decorator class's "decorates()"
227 method.
228 Internally, this will ensure that objects are instantiated as
230 decorators. This means that you can mix & match extra add-on
231 functionality classes much more easily.
232 In the current implementation, if only a single decoration is used on
234 an object, it will be instantiated as a simple subclass, thus avoiding
235 a layer of indirection.
236 $self->validation_spec()
238 Returns a hash reference suitable for passing to the "Params::Validate"
239 "validate" function. Does not include any arguments that can be passed
240 to contained objects.
241 $class->allowed_params(\%args)
243 Returns a hash reference of every parameter this class will accept,
244 including parameters it will pass on to its own contained objects. The
245 keys are the parameter names, and the values are their corresponding
246 specifications from their "valid_params()" definitions. If a parameter
247 is used by both the current object and one of its contained objects,
248 the specification returned will be from the container class, not the
249 contained.
250 Because the parameters accepted by "new()" can vary based on the
252 parameters passed to "new()", you can pass any parameters to the
253 "allowed_params()" method too, ensuring that the hash you get back is
254 accurate.
255 $self->container()
257 Returns the object that created you. This is remembered by storing a
258 reference to that object, so we use the "Scalar::Utils" "weakref()"
259 function to avoid persistent circular references that would cause
260 memory leaks. If you don't have "Scalar::Utils" installed, we don't
261 make these references in the first place, and calling "container()"
262 will result in a fatal error.
263 If you weren't created by another object via "Class::Container",
265 "container()" returns "undef".
266 In most cases you shouldn't care what object created you, so use this
268 method sparingly.
269 $object->show_containers
271 $package->show_containers
272 This method returns a string meant to describe the containment
273 relationships among classes. You should not depend on the specific
274 formatting of the string, because I may change things in a future
275 release to make it prettier.
276 For example, the HTML::Mason code returns the following when you do
278 "$interp->show_containers":
279 HTML::Mason::Interp=HASH(0x238944)
281 resolver -> HTML::Mason::Resolver::File
282 compiler -> HTML::Mason::Compiler::ToObject
283 lexer -> HTML::Mason::Lexer
284 request -> HTML::Mason::Request (delayed)
285 buffer -> HTML::Mason::Buffer (delayed)
286 Currently, containment is shown by indentation, so the Interp object
288 contains a resolver and a compiler, and a delayed request (or several
289 delayed requests). The compiler contains a lexer, and each request
290 contains a delayed buffer (or several delayed buffers).
291 $object->dump_parameters
293 Returns a hash reference containing a set of parameters that should be
294 sufficient to re-create the given object using its class's "new()"
295 method. This is done by fetching the current value for each declared
296 parameter (i.e. looking in $object for hash entries of the same name),
297 then recursing through all contained objects and doing the same.
298 A few words of caution here. First, the dumped parameters represent
300 the current state of the object, not the state when it was originally
301 created.
302 Second, a class's declared parameters may not correspond exactly to its
304 data members, so it might not be possible to recover the former from
305 the latter. If it's possible but requires some manual fudging, you can
306 override this method in your class, something like so:
307 sub dump_parameters {
309 my $self = shift;
310 my $dump = $self->SUPER::dump_parameters();
311 # Perform fudgery
313 $dump->{incoming} = $self->{_private};
314 delete $dump->{superfluous};
315 return $dump;
316 }
317
319 Params::Validate
320
322 Originally by Ken Williams <ken@mathforum.org> and Dave Rolsky
323 <autarch@urth.org> for the HTML::Mason project. Important feedback
324 contributed by Jonathan Swartz <swartz@pobox.com>. Extended by Ken
325 Williams for the AI::Categorizer project.
326 Currently maintained by Ken Williams.
328
330 This program is free software; you can redistribute it and/or modify it
331 under the same terms as Perl itself.
332perl v5.34.0 2021-07-22 Class::Container(3)