1Class::Prototyped(3) User Contributed Perl Documentation Class::Prototyped(3)
2
6 "Class::Prototyped" - Fast prototype-based OO programming in Perl
7
9 use strict;
10 use Class::Prototyped ':EZACCESS';
11 $, = ' '; $\ = "\n";
13 my $p = Class::Prototyped->new(
15 field1 => 123,
16 sub1 => sub { print "this is sub1 in p" },
17 sub2 => sub { print "this is sub2 in p" }
18 );
19 $p->sub1;
21 print $p->field1;
22 $p->field1('something new');
23 print $p->field1;
24 my $p2 = Class::Prototyped->new(
26 'parent*' => $p,
27 field2 => 234,
28 sub2 => sub { print "this is sub2 in p2" }
29 );
30 $p2->sub1;
32 $p2->sub2;
33 print ref($p2), $p2->field1, $p2->field2;
34 $p2->field1('and now for something different');
35 print ref($p2), $p2->field1;
36 $p2->addSlots( sub1 => sub { print "this is sub1 in p2" } );
38 $p2->sub1;
39 print ref($p2), "has slots", $p2->reflect->slotNames;
41 $p2->reflect->include( 'xx.pl' ); # includes xx.pl in $p2's package
43 print ref($p2), "has slots", $p2->reflect->slotNames;
44 $p2->aa(); # calls aa from included file xx.pl
45 $p2->deleteSlots('sub1');
47 $p2->sub1;
48
50 This package provides for efficient and simple prototype-based
51 programming in Perl. You can provide different subroutines for each
52 object, and also have objects inherit their behavior and state from
53 another object.
54 The structure of an object is inspected and modified through mirrors,
56 which are created by calling "reflect" on an object or class that
57 inherits from "Class::Prototyped".
58 Installation instructions
60 This module requires "Module::Build 0.24" to use the automated
61 installation procedures. With "Module::Build" installed:
62 Build.PL
64 perl build test
65 perl build install
66 It can be installed under ActivePerl for Win32 by downloading the PPM
68 from CPAN (the file has the extension ".ppm.zip"). To install,
69 download the ".ppm.zip" file, uncompress it, and execute:
70 ppm install Class-Prototyped.ppd
72 The module can also be installed manually by copying
74 "lib/Class/Prototyped.pm" to "perl/site/lib/Class/Prototyped.pm" (along
75 with "Graph.pm" if you want it).
76
78 When I reach for "Class::Prototyped", it's generally because I really
79 need it. When the cleanest way of solving a problem is for the code
80 that uses a module to subclass from it, that is generally a sign that
81 "Class::Prototyped" would be of use. If you find yourself avoiding the
82 problem by passing anonymous subroutines as parameters to the "new"
83 method, that's another good sign that you should be using prototype
84 based programming. If you find yourself storing anonymous subroutines
85 in databases, configuration files, or text files, and then writing
86 infrastructure to handle calling those anonymous subroutines, that's
87 yet another sign. When you expect the people using your module to want
88 to change the behavior, override subroutines, and so forth, that's a
89 sign.
90
92 Slots
93 "Class::Prototyped" borrows very strongly from the language Self (see
94 http://www.sun.com/research/self for more information). The core
95 concept in Self is the concept of a slot. Think of slots as being
96 entries in a hash, except that instead of just pointing to data, they
97 can point to objects, code, or parent objects.
98 So what happens when you send a message to an object (that is to say,
100 you make a method call on the object)? First, Perl looks for that slot
101 in the object. If it can't find that slot in the object, it searches
102 for that slot in one of the object's parents (which we'll come back to
103 later). Once it finds the slot, if the slot is a block of code, it
104 evaluates the code and returns the return value. If the slot
105 references data, it returns that data. If you assign to a data slot
106 (through a method call), it modifies the data.
107 Distinguishing data slots and method slots is easy - the latter are
109 references to code blocks, the former are not. Distinguishing parent
110 slots is not so easy, so instead a simple naming convention is used.
111 If the name of the slot ends in an asterisk, the slot is a parent slot.
112 If you have programmed in Self, this naming convention will feel very
113 familiar.
114 Reflecting
116 In Self, to examine the structure of an object, you use a mirror. Just
117 like using his shield as a mirror enabled Perseus to slay Medusa,
118 holding up a mirror enables us to look upon an object's structure
119 without name space collisions.
120 Once you have a mirror, you can add and delete slots like so:
122 my $cp = Class::Prototyped->new();
124 my $mirror = $cp->reflect();
125 $mirror->addSlots(
126 field1 => 'foo',
127 sub1 => sub {
128 print "this is sub1 printing field1: '".$_[0]->field1."'\n";
129 },
130 );
131 $mirror->deleteSlot('sub1');
133 In addition, there is a more verbose syntax for "addSlots" where the
135 slot name is replaced by an anonymous array - this is most commonly
136 used to control the slot attributes.
137 $cp->reflect->addSlot(
139 [qw(field1 FIELD)] => 'foo',
140 [qw(sub1 METHOD)] => sub { print "hi there.\n"; },
141 );
142 Because the mirror methods "super", "addSlot"("s"), "deleteSlot"("s"),
144 and "getSlot"("s") are called frequently on objects, there is an import
145 keyword ":EZACCESS" that adds methods to the object space that call the
146 appropriate reflected variants.
147 Slot Attributes
149 Slot attributes allow the user to specify additional information and
150 behavior relating to a specific slot in an extensible manner. For
151 instance, one might want to mark a specific field slot as constant or
152 to attach a description to a given slot.
153 Slot attributes are divided up in two ways. The first is by the type
155 of slot - "FIELD", "METHOD", or "PARENT". Some slot attributes apply
156 to all three, some to just two, and some to only one. The second
157 division is on the type of slot attribute:
158 implementor
160 These are responsible for implementing the behavior of a slot. An
161 example is a "FIELD" slot with the attribute "constant". A slot is
162 only allowed one implementor. All slot types have a default
163 implementor. For "FIELD" slots, it is a read-write scalar. For
164 "METHOD" slots, it is the passed anonymous subroutine. For
165 "PARENT" slots, "implementor" and "filter" slot attributes don't
166 really make sense.
167 filter
169 These filter access to the "implementor". The quintessential
170 example is the "profile" attribute. When set, this increments a
171 counter in $Class::Prototyped::Mirror::PROFILE::counts every time
172 the underlying "FIELD" or "METHOD" is accessed. Filter attributes
173 can be stacked, so each attribute is assigned a rank with lower
174 values being closer to the "implementor" and higher values being
175 closer to the caller.
176 advisory
178 These slot attributes serve one of two purposes. They can be used
179 to store information about the slot (i.e. "description"
180 attributes), and they can be used to pass information to the
181 "addSlots" method (i.e. the "promote" attribute, which can be used
182 to promote a new "PARENT" slot ahead of all the existing "PARENT"
183 slots).
184 There is currently no formal interface for creating your own attributes
186 - if you feel the need for new attributes, please contact the
187 maintainer first to see if it might make sense to add the new attribute
188 to "Class::Prototyped". If not, the contact might provide enough
189 impetus to define a formal interface. The attributes are currently
190 defined in $Class::Prototyped::Mirror::attributes.
191 Finally, see the "defaultAttributes" method for information about
193 setting default attributes. This can be used, for instance, to turn on
194 profiling everywhere.
195 Classes vs. Objects
197 In Self, everything is an object and there are no classes at all.
198 Perl, for better or worse, has a class system based on packages. We
199 decided that it would be better not to throw out the conventional way
200 of structuring inheritance hierarchies, so in "Class::Prototyped",
201 classes are first-class objects.
202 However, objects are not first-class classes. To understand this
204 dichotomy, we need to understand that there is a difference between the
205 way "classes" and the way "objects" are expected to behave. The
206 central difference is that "classes" are expected to persist whether or
207 not that are any references to them. If you create a class, the class
208 exists whether or not it appears in anyone's @ISA and whether or not
209 there are any objects in it. Once a class is created, it persists
210 until the program terminates.
211 Objects, on the other hand, should follow the normal behaviors of
213 reference-counted destruction - once the number of references to them
214 drops to zero, they should miraculously disappear - the memory they
215 used needs to be returned to Perl, their "DESTROY" methods need to be
216 called, and so forth.
217 Since we don't require this behavior of classes, it's easy to have a
219 way to get from a package name to an object - we simply stash the
220 object that implements the class in
221 $Class::Prototyped::Mirror::objects{$package}. But we can't do this
222 for objects, because if we do the object will persist forever because
223 that reference will always exist.
224 Weak references would solve this problem, but weak references are still
226 considered alpha and unsupported ("$WeakRef::VERSION = 0.01"), and we
227 didn't want to make "Class::Prototyped" dependent on such a module.
228 So instead, we differentiate between classes and objects. In a
230 nutshell, if an object has an explicit package name (i.e. something
231 other than the auto-generated one), it is considered to be a class,
232 which means it persists even if the object goes out of scope.
233 To create such an object, use the "newPackage" method, like so (the
235 encapsulating block exists solely to demonstrate that classes are not
236 scoped):
237 {
239 my $object = Class::Prototyped->newPackage('MyClass',
240 field => 1,
241 double => sub {$_[0]->field*2}
242 );
243 }
244 print MyClass->double,"\n";
246 Notice that the class persists even though $object goes out of scope.
248 If $object were created with an auto-generated package, that would not
249 be true. Thus, for instance, it would be a very, very, very bad idea
250 to add the package name of an object as a parent to another object -
251 when the first object goes out of scope, the package will disappear,
252 but the second object will still have it in it's @ISA.
253 Except for the crucial difference that you should never, ever, ever
255 make use of the package name for an object for any purpose other than
256 printing it to the screen, objects and classes are simply different
257 ways of inspecting the same entity.
258 To go from an object to a package, you can do one of the following:
260 $package = ref($object);
262 $package = $object->reflect->package;
263 The two are equivalent, although the first is much faster. Just
265 remember, if $object is in an auto-generated package, don't do anything
266 with that $package but print it.
267 To go from a package to an object, you do this:
269 $object = $package->reflect->object;
271 Note that $package is simple the name of the package - the following
273 code works perfectly:
274 $object = MyClass->reflect->object;
276 But keep in mind that $package has to be a class, not an auto-generated
278 package name for an object.
279 Class Manipulation
281 This lets us have tons of fun manipulating classes at run time. For
282 instance, if you wanted to add, at run-time, a new method to the
283 "MyClass" class? Assuming that the "MyClass" inherits from
284 "Class::Prototyped" or that you have specified ":REFLECT" on the "use
285 Class::Prototyped" call, you simply write:
286 MyClass->reflect->addSlot(myMethod => sub {print "Hi there\n"});
288 If you want to access a class that doesn't inherit from
290 "Class::Prototyped", and you want to avoid specifying ":REFLECT" (which
291 adds "reflect" to the "UNIVERSAL" package), you can make the call like
292 so:
293 my $mirror = Class::Prototyped::Mirror->new('MyClass');
295 $mirror->addSlot(myMethod => sub {print "Hi there\n"});
296 Just as you can "clone" objects, you can "clone" classes that are
298 derived from "Class::Prototyped". This creates a new object that has a
299 copy of all of the slots that were defined in the class. Note that if
300 you simply want to be able to use "Data::Dumper" on a class, calling
301 "MyClass->reflect->object" is the preferred approach. Even easier
302 would be to use the "dump" mirror method.
303 The code that implements reflection on classes automatically creates
305 slot names for package methods as well as parent slots for the entries
306 in @ISA. This means that you can code classes like you normally do -
307 by doing the inheritance in @ISA and writing package methods.
308 If you manually add subroutines to a package at run-time and want the
310 slot information updated properly (although this really should be done
311 via the "addSlots" mechanism, but maybe you're twisted:), you should do
312 something like:
313 $package->reflect->_vivified_methods(0);
315 $package->reflect->_autovivify_methods;
316 Parent Slots
318 Adding parent slots is no different than adding normal slots - the
319 naming scheme takes care of differentiating.
320 Thus, to add $foo as a parent to $bar, you write:
322 $bar->reflect->addSlot('fooParent*' => $foo);
324 However, keeping with our concept of classes as first class objects,
326 you can also write the following:
327 $bar->reflect->addSlot('mixIn*' => 'MyMix::Class');
329 It will automatically require the module in the namespace of $bar and
331 make the module a parent of the object. This can load a module from
332 disk if needed.
333 If you're lazy, you can add parents without names like so:
335 $bar->reflect->addSlot('*' => $foo);
337 The slots will be automatically named for the package passed in - in
339 the case of "Class::Prototyped" objects, the package is of the form
340 "PKG0x12345678". In the following example, the parent slot will be
341 named "MyMix::Class*".
342 $bar->reflect->addSlot('*' => 'MyMix::Class');
344 Parent slots are added to the inheritance hierarchy in the order that
346 they were added. Thus, in the following code, slots that don't exist
347 in $foo are looked up in $fred (and all of its parent slots) before
348 being looked up in $jill.
349 $foo->reflect->addSlots('fred*' => $fred, 'jill*' => $jill);
351 Note that "addSlot" and "addSlots" are identical - the variants exist
353 only because it looks ugly to add a single slot by calling "addSlots".
354 If you need to reorder the parent slots on an object, look at
356 "promoteParents". That said, there's a shortcut for prepending a slot
357 to the inheritance hierarchy. Simply define 'promote' as a slot
358 attribute using the extended slot syntax.
359 Finally, in keeping with our principle that classes are first-class
361 object, the inheritance hierarchy of classes can be modified through
362 "addSlots" and "deleteSlots", just like it can for objects. The
363 following code adds the $foo object as a parent of the "MyClass" class,
364 prepending it to the inheritance hierarchy:
365 MyClass->reflect->addSlots([qw(foo* promote)] => $foo);
367 Operator Overloading
369 In "Class::Prototyped", you do operator overloading by adding slots
370 with the right name. First, when you do the "use" on
371 "Class::Prototyped", make sure to pass in ":OVERLOAD" so that the
372 operator overloading support is enabled.
373 Then simply pass the desired methods in as part of the object creation
375 like so:
376 $foo = Class::Prototyped->new(
378 value => 3,
379 '""' => sub { my $self = shift; $self->value( $self->value + 1 ) },
380 );
381 This creates an object that increments its field "value" by one and
383 returns that incremented value whenever it is stringified.
384 Since there is no way to find out which operators are overloaded, if
386 you add overloading to a class through the use of "use overload", that
387 behavior will not show up as slots when reflecting on the class.
388 However, "addSlots" does work for adding operator overloading to
389 classes. Thus, the following code does what is expected:
390 Class::Prototyped->newPackage('MyClass');
392 MyClass->reflect->addSlots(
393 '""' => sub { my $self = shift; $self->value( $self->value + 1 ) },
394 );
395 $foo = MyClass->new( value => 2 );
397 print $foo, "\n";
398 Object Class
400 The special parent slot "class*" is used to indicate object class.
401 When you create "Class::Prototyped" objects by calling
402 "Class::Prototyped->new()", the "class*" slot is not set. If, however,
403 you create objects by calling "new" on a class or object that inherits
404 from "Class::Prototyped", the slot "class*" points to the package name
405 if "new" was called on a named class, or the object if "new" was called
406 on an object.
407 The value of this slot can be returned quite easily like so:
409 $foo->reflect->class;
411 Calling Inherited Methods
413 Methods (and fields) inherited from prototypes or classes are not
414 generally available using the usual Perl "$self->SUPER::something()"
415 mechanism.
416 The reason for this is that "SUPER::something" is hardcoded to the
418 package in which the subroutine (anonymous or otherwise) was defined.
419 For the vast majority of programs, this will be "main::", and thus
420 "SUPER::" will look in @main::ISA (not a very useful place to look).
421 To get around this, a very clever wrapper can be automatically placed
423 around your subroutine that will automatically stash away the package
424 to which the subroutine is attached. From within the subroutine, you
425 can use the "super" mirror method to make an inherited call. However,
426 because we'd rather not write code that attempts to guess as to whether
427 or not the subroutine uses the "super" construct, you have to tell
428 "addSlots" that the subroutine needs to have this wrapper placed around
429 it. To do this, simply use the extended "addSlots" syntax (see the
430 method description for more information) and pass in the slot attribute
431 'superable'. The following examples use the minimalist form of the
432 extended syntax.
433 For instance, the following code will work:
435 use Class::Prototyped;
437 my $p1 = Class::Prototyped->new(
439 method => sub { print "this is method in p1\n" },
440 );
441 my $p2 = Class::Prototyped->new(
443 '*' => $p1,
444 [qw(method superable)]' => sub {
445 print "this is method in p2 calling method in p1: ";
446 $_[0]->reflect->super('method');
447 },
448 );
449 To make things easier, if you specify ":EZACCESS" during the import,
451 "super" can be called directly on an object rather than through its
452 mirror.
453 The other thing of which you need to be aware is copying methods from
455 one object to another. The proper way to do this is like so:
456 $foo->reflect->addSlot($bar->reflect->getSlot('method'));
458 When the "getSlot" method is called in an array context, it returns
460 both the complete format for the slot identifier and the slot. This
461 ensures that slot attributes are passed along, including the
462 "superable" attribute.
463 Finally, to help protect the code, the "super" method is smart enough
465 to determine whether it was called within a wrapped subroutine. If it
466 wasn't, it croaks indicating that the method should have had the
467 "superable" attribute set when it was added. If you wish to disable
468 this checking (which will improve the performance of your code, of
469 course, but could result in very hard to trace bugs if you haven't been
470 careful), see the import option ":SUPER_FAST".
471
473 It is important to be aware of where the boundaries of prototyped based
474 programming lie, especially in a language like Perl that is not
475 optimized for it. For instance, it might make sense to implement every
476 field in a database as an object. Those field objects would in turn be
477 attached to a record class. All of those might be implemented using
478 "Class::Prototyped". However, it would be very inefficient if every
479 record that got read from the database was stored in a
480 "Class::Prototyped" based object (unless, of course, you are storing
481 code in the database). In that situation, it is generally good to
482 choke off the prototype-based behavior for the individual record
483 objects. For best performance, it is important to confine
484 "Class::Prototyped" to those portions of the code where behavior is
485 mutable from outside of the module. See the documentation for the
486 "new" method of "Class::Prototyped" for more information about choking
487 off "Class::Prototyped" behavior.
488 There are a number of performance hits when using "Class::Prototyped",
490 relative to using more traditional OO code. It is important to note
491 that these generally lie in the instantiation and creation of classes
492 and objects and not in the actual use of them. The scripts in the
493 "perf" directory were designed for benchmarking some of this material.
494 Class Instantiation
496 The normal way of creating a class is like this:
497 package Pack_123;
499 sub a {"hi";}
500 sub b {"hi";}
501 sub c {"hi";}
502 sub d {"hi";}
503 sub e {"hi";}
504 The most efficient way of doing that using "proper" "Class::Prototyped"
506 methodology looks like this:
507 Class::Prototyped->newPackage("Pack_123");
509 push(@P_123::slots, a => sub {"hi";});
510 push(@P_123::slots, b => sub {"hi";});
511 push(@P_123::slots, c => sub {"hi";});
512 push(@P_123::slots, d => sub {"hi";});
513 push(@P_123::slots, e => sub {"hi";});
514 Pack_123->reflect->addSlots(@P_123::slots);
515 This approach ensures that the new package gets the proper default
517 attributes and that the slots are created through "addSlots", thus
518 ensuring that default attributes are properly implemented. It avoids
519 multiple calls to "->reflect->addSlot", though, which improves
520 performance. The idea behind pushing the slots onto an array is that
521 it enables one to intersperse code with POD, since POD is not permitted
522 inside of a single Perl statement.
523 On a Pent 4 1.8GHz machine, the normal code runs in 120 usec, whereas
525 the "Class::Prototyped" code runs in around 640 usec, or over 5 times
526 slower. A straight call to "addSlots" with all five methods runs in
527 around 510 usec. Code that creates the package and the mirror without
528 adding slots runs in around 135 usec, so we're looking at an overhead
529 of less than 100 usec per slot. In a situation where the "compile"
530 time dominates the "execution" time (I'm using those terms loosely as
531 much of what happens in "Class::Prototyped" is technically execution
532 time, but it is activity that traditionally would happen at compile
533 time), "Class::Prototyped" might prove to be too much overhead. On the
534 otherhand, you may find that demand loading can cut much of that
535 overhead and can be implemented less painfully than might otherwise be
536 thought.
537 Object Instantiation
539 There is no need to even compare here. Blessing a hash into a class
540 takes less than 2 usec. Creating a new "Class::Prototyped" object
541 takes at least 60 or 70 times longer. The trick is to avoid creating
542 unnecessary "Class::Prototyped" objects. If you know that all 10,000
543 database records are going to inherit all of their behavior from the
544 parent class, there is no point in creating 10,000 packages and all the
545 attendant overhead. The "new" method for "Class::Prototyped"
546 demonstrates how to ensure that those state objects are created as
547 normal Perl objects.
548 Method Calls
550 The good news is that method calls are just as fast as normal Perl
551 method calls, inherited or not. This is because the existing Perl OO
552 machinery has been hijacked in "Class::Prototyped". The exception to
553 this is if "filter" slot attributes have been used, including
554 "wantarray", "superable", and "profile". In that situation, the added
555 overhead is that for a normal Perl subroutine call (which is faster
556 than a method call because it is a static binding)
557 Instance Variable Access
559 The hash interface is not particularly fast, and neither is it good
560 programming practice. Using the method interface to access fields is
561 just as fast, however, as using normal getter/setter methods.
562
564 ":OVERLOAD"
565 This configures the support in "Class::Prototyped" for using
566 operator overloading.
567 ":REFLECT"
569 This defines "UNIVERSAL::reflect" to return a mirror for any class.
570 With a mirror, you can manipulate the class, adding or deleting
571 methods, changing its inheritance hierarchy, etc.
572 ":EZACCESS"
574 This adds the methods "addSlot", "addSlots", "deleteSlot",
575 "deleteSlots", "getSlot", "getSlots", and "super" to
576 "Class::Prototyped".
577 This lets you write:
579 $foo->addSlot(myMethod => sub {print "Hi there\n"});
581 instead of having to write:
583 $foo->reflect->addSlot(myMethod => sub {print "Hi there\n"});
585 The other methods in "Class::Prototyped::Mirror" should be accessed
587 through a mirror (otherwise you'll end up with way too much name
588 space pollution for your objects:).
589 Note that it is bad form for published modules to use ":EZACCESS"
591 as you are polluting everyone else's namespace as well. If you
592 really want ":EZACCESS" for code you plan to publish, contact the
593 maintainer and we'll see what we can about creating a variant of
594 ":EZACCESS" that adds the shortcut methods to a single class. Note
595 that using ":EZACCESS" to do "$obj->addSlot()" is actually slower
596 than doing "$obj->reflect->addSlot()".
597 ":SUPER_FAST"
599 Switches over to the fast version of "super" that doesn't check to
600 see whether slots that use inherited calls were defined as
601 superable.
602 ":NEW_MAIN"
604 Creates a "new" function in "main::" that creates new
605 "Class::Prototyped" objects. Thus, you can write code like:
606 use Class::Prototyped qw(:NEW_MAIN :EZACCESS);
608 my $foo = new(say_hi => sub {print "Hi!\n";});
610 $foo->say_hi;
611 ":TIED_INTERFACE"
613 This is no longer supported. Sorry for the very short notice - if
614 you have a specific need, please let me know and I will discuss
615 your needs with you and determine whether they can be addressed in
616 a manner that doesn't require you to rewrite your code, but still
617 allows others to make use of less global control over the tied
618 interfaces used. See
619 "Class::Prototyped::Mirror::tiedInterfacePackage" for the preferred
620 way of doing this.
621
623 new() - Construct a new "Class::Prototyped" object.
624 A new object is created. If this is called on a class or object that
625 inherits from "Class::Prototyped", and "class*" is not being passed as
626 a slot in the argument list, the slot "class*" will be the first
627 element in the inheritance list.
628 When called on named classes, either via the package name or via the
630 object (i.e. "MyPackage->reflect->object()"), "class*" is set to the
631 package name. When called on an object, "class*" is set to the object
632 on which "new" was called.
633 The passed arguments are handed off to "addSlots".
635 Note that "new" calls "newCore", so if you want to override "new", but
637 want to ensure that your changes are applicable to "newPackage",
638 "clone", and "clonePackage", you may wish to override "newCore".
639 For instance, the following will define a new "Class::Prototyped"
641 object with two method slots and one field slot:
642 my $foo = Class::Prototyped->new(
644 field1 => 123,
645 sub1 => sub { print "this is sub1 in foo" },
646 sub2 => sub { print "this is sub2 in foo" },
647 );
648 The following will create a new "MyClass" object with one field slot
650 and with the parent object $bar at the beginning of the inheritance
651 hierarchy (just before "class*", which points to "MyClass"):
652 my $foo = MyClass->new(
654 field1 => 123,
655 [qw(bar* promote)] => $bar,
656 );
657 The following will create a new object that inherits behavior from $bar
659 with one field slot, "field1", and one parent slot, "class*", that
660 points to $bar.
661 my $foo = $bar->new(
663 field1 => 123,
664 );
665 If you want to create normal Perl objects as child objects of a
667 "Class::Prototyped" class in order to improve performance, implement
668 your own standard Perl "new" method:
669 Class::Prototyped->newPackage('MyClass');
671 MyClass->reflect->addSlot(
672 new => sub {
673 my $class = shift;
674 my $self = {};
675 bless $self, $class;
676 return $self;
677 }
678 );
679 It is still safe to use "$obj->reflect->super()" in code that runs on
681 such an object. All other reflection will automatically return the
682 same results as inspecting the class to which the object belongs.
683 newPackage() - Construct a new "Class::Prototyped" object in a specific
685 package.
686 Just like "new", but instead of creating the new object with an
687 arbitrary package name (actually, not entirely arbitrary - it's
688 generally based on the hash memory address), the first argument is used
689 as the name of the package. This creates a named class. The same
690 behavioral rules for "class*" described above for "new" apply to
691 "newPackage" (in fact, "new" calls "newPackage").
692 If the package name is already in use, this method will croak.
694 clone() - Duplicate me
696 Duplicates an existing object or class and allows you to add or
697 override slots. The slot definition is the same as in new().
698 my $p2 = $p1->clone(
700 sub1 => sub { print "this is sub1 in p2" },
701 );
702 It calls "newCore" to create the new object*, so if you have overriden
704 "new", you should contemplate overriding "clone" in order to ensure
705 that behavioral changes made to "new" that would be applicable to
706 "clone" are implemented. Or simply override "newCore".
707 clonePackage()
709 Just like "clone", but instead of creating the new object with an
710 arbitrary package name (actually, not entirely arbitrary - it's
711 generally based on the hash memory address), the first argument is used
712 as the name of the package. This creates a named class.
713 If the package name is already in use, this method will croak.
715 newCore()
717 This implements the core functionality involved in creating a new
718 object. The first passed parameter will be the name of the caller -
719 either "new", "newPackage", "clone", or "clonePackage". The second
720 parameter is the name of the package if applicable (i.e. for
721 "newPackage" and "clonePackage") calls, "undef" if inapplicable. The
722 remainder of the parameters are any slots to be added to the newly
723 created object/package.
724 If called with "new" or "newPackage", the "class*" slot will be
726 prepended to the slot list if applicable. If called with "clone" or
727 "clonePackage", all slots on the receiver will be prepended to the slot
728 list.
729 If you wish to add behavior to object instantiation that needs to be
731 present in all four of the instantiators (i.e. instance tracking), it
732 may make sense to override "newCore" so that you implement the code in
733 only one place.
734 reflect() - Return a mirror for the object or class
736 The structure of an object is modified by using a mirror. This is the
737 equivalent of calling:
738 Class::Prototyped::Mirror->new($foo);
740 destroy() - The destroy method for an object
742 You should never need to call this method. However, you may want to
743 override it. Because we had to directly specify "DESTROY" for every
744 object in order to allow safe destruction during global destruction
745 time when objects may have already destroyed packages in their @ISA, we
746 had to hook "DESTROY" for every object. To allow the "destroy"
747 behavior to be overridden, users should specify a "destroy" method for
748 their objects (by adding the slot), which will automatically be called
749 by the "Class::Prototyped::DESTROY" method after the @ISA has been
750 cleaned up.
751 This method should be defined to allow inherited method calls (i.e.
753 should use ""[qw(destroy superable)]"" to define the method) and should
754 call "$self->reflect->super('destroy');" at some point in the code.
755 Here is a quick overview of the default destruction behavior for
757 objects:
758 · "Class::Prototyped::DESTROY" is called because it is linked into
760 the package for all objects at instantiation time
761 · All no longer existent entries are stripped from @ISA
763 · The inheritance hierarchy is searched for a "DESTROY" method that
765 is not "Class::Prototyped::DESTROY". This "DESTROY" method is
766 stashed away for a later call.
767 · The inheritance hierarchy is searched for a "destroy" method and it
769 is called. Note that the "Class::Prototyped::destroy" method,
770 which will either be called directly because it shows up in the
771 inheritance hierarchy or will be called indirectly through calls to
772 "$self->reflect->super('destroy');", will delete all non-parent
773 slots from the object. It leaves parent slots alone because the
774 destructors for the parent slots should not be called until such
775 time as the destruction of the object in question is complete
776 (otherwise inherited destructors might still be executing, even
777 though the object to which they belong has already been destroyed).
778 This means that the destructors for objects referenced in non-
779 parent slots may be called, temporarily interrupting the execution
780 sequence in "Class::Prototyped::destroy".
781 · The previously stashed "DESTROY" method is called.
783 · The parent slots for the object are finally removed, thus enabling
785 the destructors for any objects referenced in those parent slots to
786 run.
787 · Final "Class::Prototyped" specific cleanup is run.
789
791 These are the methods you can call on the mirror returned from a
792 "reflect" call. If you specify ":EZACCESS" in the "use
793 Class::Prototyped" line, "addSlot", "addSlots", "deleteSlot",
794 "deleteSlots", "getSlot", "getSlots", and "super" will be callable on
795 "Class::Prototyped" objects as well.
796 new() - Creates a new "Class::Prototyped::Mirror" object
798 Normally called via the "reflect" method, this can be called directly
799 to avoid using the ":REFLECT" import option for reflecting on non
800 "Class::Prototyped" based classes.
801 autoloadCall()
803 If you add an "AUTOLOAD" slot to an object, you will need to get the
804 name of the subroutine being called. "autoloadCall()" returns the name
805 of the subroutine, with the package name stripped off.
806 package() - Returns the name of the package for the object
808 object() - Returns the object itself
809 class() - Returns the "class*" slot for the underlying object
810 dump() - Returns a Data::Dumper string representing the object
811 addSlot() - An alias for "addSlots"
812 addSlots() - Add or replace slot definitions
813 Allows you to add or replace slot definitions in the receiver.
814 $p->reflect->addSlots(
816 fred => 'this is fred',
817 doSomething => sub { print 'doing something with ' . $_[1] },
818 );
819 $p->doSomething( $p->fred );
820 In addition to the simple form, there is an extended syntax for
822 specifying the slot. In place of the slotname, pass an array reference
823 composed like so:
824 "addSlots( [$slotName, $slotType, %slotAttributes] => $slotValue );"
826 $slotName is simply the name of the slot, including the trailing "*" if
828 it is a parent slot. $slotType should be 'FIELD', 'METHOD', or
829 'PARENT'. %slotAttributes should be a list of attribute/value pairs.
830 It is common to use qw() to reduce the amount of typing:
831 $p->reflect->addSlot(
833 [qw(bar FIELD)] => "this is a field",
834 );
835 $p->reflect->addSlot(
837 [qw(bar FIELD constant 1)] => "this is a constant field",
838 );
839 $p->reflect->addSlot(
841 [qw(foo METHOD)] => sub { print "normal method.\n"; },
842 );
843 $p->reflect->addSlot(
845 [qw(foo METHOD superable 1)] => sub { print "superable method.\n"; },
846 );
847 $p->reflect->addSlot(
849 [qw(parent* PARENT)] => $parent,
850 );
851 $p->reflect->addSlot(
853 [qw(parent2* PARENT promote 1)] => $parent2,
854 );
855 To make using the extended syntax a bit less cumbersome, however, the
857 following shortcuts are allowed:
858 · $slotType can be omitted. In this case, the slot's type will be
860 determined by inspecting the slot's name (to determine if it is a
861 parent slot) and the slot's value (to determine whether it is a
862 field or method slot). The $slotType value can, however, be used
863 to supply a reference to a code object as the value for a field
864 slot. Note that this means that "FIELD", "METHOD", and "PARENT"
865 are not legal attribute names (since this would make parsing
866 difficult).
867 · If there is only one attribute and if the value is 1, then the
869 value can be omitted.
870 Using both of the above contractions, the following are valid short
872 forms for the extended syntax:
873 $p->reflect->addSlot(
875 [qw(bar constant)] => "this is a constant field",
876 );
877 $p->reflect->addSlot(
879 [qw(foo superable)] => sub { print "superable method.\n"; },
880 );
881 $p->reflect->addSlot(
883 [qw(parent2* promote)] => $parent2,
884 );
885 The currently defined slot attributes are as follows:
887 "FIELD" Slots
889 "constant" ("implementor")
890 When true, this defines the field slot as constant, disabling
891 the ability to modify it using the "$object->field($newValue)"
892 syntax. The value may still be modified using the hash syntax
893 (i.e. "$object->{field} = $newValue"). This is mostly useful
894 if you have an object method call that takes parameters, but
895 you wish to replace it on a given object with a hard-coded
896 value by using a field (which makes inspecting the value of the
897 slot through "Data::Dumper" much easier than if you use a
898 "METHOD" slot to return the constant, since code objects are
899 opaque).
900 "autoload" ("filter", rank 50)
902 The passed value for the "FIELD" slot should be a subroutine
903 that returns the desired value. Upon the first access, the
904 subroutine will be called, the return value hard-coded into the
905 object by adding the slot (including all otherwise specified
906 attributes), and the value then returned. Useful for
907 implementing constant slots that are costly to initialize,
908 especially those that return lists of "Class::Prototyped"
909 objects!
910 "profile" ("filter", rank 80)
912 If "profile" is set to 1, increments
913 "$Class::Prototyped::Mirror::PROFILE::counts->{$package}->{$slotName}"
914 everytime the slot is accessed. If "profile" is set to 2,
915 increments
916 "$Class::Prototyped::Mirror::PROFILE::counts->{$package}->{$slotName}->{$caller}"
917 everytime the slot is accessed, where $caller is "$file
918 ($line)".
919 "wantarray" ("filter", rank 90)
921 If the field specifies a reference to an array and the call is
922 in list context, dereferences the array and returns a list of
923 values.
924 "description" ("advisory")
926 Can be used to specify a description. No real support for this
927 yet beyond that!
928 "METHOD" Slots
930 "superable" ("filter", rank 10)
931 When true, this enables the "$self->reflect->super( . . . )"
932 calls for this method slot.
933 "profile" ("filter", rank 90)
935 See "FIELD" slots for explanation.
936 "overload" ("advisory")
938 Set automatically for methods that implement operator
939 overloading.
940 "description" ("advisory")
942 See "FIELD" slots for explanation.
943 "PARENT" Slots
945 "promote" ("advisory")
946 When true, this parent slot is promoted ahead of any other
947 parent slots on the object. This attribute is ephemeral - it
948 is not returned by calls to "getSlot".
949 "description" ("advisory")
951 See "FIELD" slots for explanation.
952 deleteSlot() - An alias for deleteSlots
954 deleteSlots() - Delete one or more of the receiver's slots by name
955 This will let you delete existing slots in the receiver. If those slots
956 were defined in the receiver's inheritance hierarchy, those inherited
957 definitions will now be available.
958 my $p1 = Class::Prototyped->new(
960 field1 => 123,
961 sub1 => sub { print "this is sub1 in p1" },
962 sub2 => sub { print "this is sub2 in p1" }
963 );
964 my $p2 = Class::Prototyped->new(
965 'parent*' => $p1,
966 sub1 => sub { print "this is sub1 in p2" },
967 );
968 $p2->sub1; # calls $p2.sub1
969 $p2->reflect->deleteSlots('sub1');
970 $p2->sub1; # calls $p1.sub1
971 $p2->reflect->deleteSlots('sub1');
972 $p2->sub1; # still calls $p1.sub1
973 super() - Call a method defined in a parent
975 The call to a method defined on a parent that is obscured by the
976 current one looks like so:
977 $self->reflect->super('method_name', @params);
979 slotNames() - Returns a list of all the slot names
981 This is passed an optional type parameter. If specified, it should be
982 one of 'FIELD', 'METHOD', or 'PARENT'. For instance, the following
983 will print out a list of all slots of an object:
984 print join(', ', $obj->reflect->slotNames)."\n";
986 The following would print out a list of all field slots:
988 print join(', ', $obj->reflect->slotNames('FIELD')."\n";
990 The parent slot names are returned in the same order for which
992 inheritance is done.
993 slotType() - Given a slot name, determines the type
995 This returns 'FIELD', 'METHOD', or 'PARENT'. It croaks if the slot is
996 not defined for that object.
997 parents() - Returns a list of all parents
999 Returns a list of all parent object (or package names) for this object.
1000 allParents() - Returns a list of all parents in the hierarchy
1002 Returns a list of all parent objects (or package names) in the object's
1003 hierarchy.
1004 withAllParents() - Same as above, but includes self in the list
1006 allSlotNames() - Returns a list of all slot names defined for the entire
1007 inheritance hierarchy
1008 Note that this will return duplicate slot names if inherited slots are
1009 obscured.
1010 getSlot() - Returns the requested slot
1012 When called in scalar context, this returns the thing in the slot.
1013 When called in list context, it returns both the complete form of the
1014 extended syntax for specifying a slot name and the thing in the slot.
1015 There is an optional parameter that can be used to modify the format of
1016 the return value in list context. The allowable values are:
1017 · 'default' - the extended slot syntax and the slot value are
1019 returned
1020 · 'simple' - the slot name and the slot value are returned. Note
1022 that in this mode, there is no access to any attributes the slot
1023 may have
1024 · 'rotated' - the slot name and the following hash are returned like
1026 so:
1027 $slotName => {
1029 attribs => %slotAttribs,
1030 type => $slotType,
1031 value => $slotValue
1032 },
1033 The latter two options are quite useful when used in conjunction with
1035 the "getSlots" method.
1036 getSlots() - Returns a list of all the slots
1038 This returns a list of extended syntax slot specifiers and their values
1039 ready for sending to "addSlots". It takes first the optional parameter
1040 passed to "slotNames" which specifies the type of slot ('FIELD',
1041 'METHOD', 'PARENT', or "undef") and then the optional parameter passed
1042 to "getSlot", which specifies the format for the return value. If the
1043 latter is 'simple', the returned values can be passed to "addSlots",
1044 but any non-default slot attributes (i.e. "superable" or "constant")
1045 will be lost. If the latter is 'rotated', the returned values are
1046 completely inappropriate for passing to "addSlots". Both 'simple' and
1047 'rotated' are appropriate for assigning the return values into a hash.
1048 For instance, to add all of the field slots in $bar to $foo:
1050 $foo->reflect->addSlots($bar->reflect->getSlots('FIELD'));
1052 To get a list of all of the slots in the 'simple' format:
1054 my %barSlots = $bar->reflect->getSlots(undef, 'simple');
1056 To get a list of all of the superable method slots in the 'rotated'
1058 format:
1059 my %barMethods = $bar->reflect->getSlots('METHOD', 'rotated');
1061 foreach my $slotName (%barMethods) {
1062 delete $barMethods{$slotName}
1063 unless $barMethods{$slotName}->{attribs}->{superable};
1064 }
1065 promoteParents() - This changes the ordering of the parent slots
1067 This expects a list of parent slot names. There should be no
1068 duplicates and all of the parent slot names should be already existing
1069 parent slots on the object. These parent slots will be moved forward
1070 in the hierarchy in the order that they are passed. Unspecified parent
1071 slots will retain their current positions relative to other unspecified
1072 parent slots, but as a group they will be moved to the end of the
1073 hierarchy.
1074 tiedInterfacePackage() - This specifies the tied interface package
1076 This allows you to specify the sort of tied interface you wish to offer
1077 when code accesses the object as a hash reference. If no parameter is
1078 passed, this will return the current tied interface package active for
1079 the object. If a parameter is passed, it should specify either the
1080 package name or an alias. The currently known aliases are:
1081 default
1083 This specifies "Class::Prototyped::Tied::Default" as the tie class.
1084 The default behavior is to allow access to existing fields, but
1085 attempts to create fields, access methods, or delete slots will
1086 croak. This is the tie class used by "Class::Prototyped" (unless
1087 you do something very naughty and call
1088 "Class::Prototyped->reflect->tiedInterfacePackage($not_default)"),
1089 and as such is the fallback behavior for classes and objects if
1090 they don't get a different value from their inheritance.
1091 autovivify
1093 This specifies "Class::Prototyped::Tied::AutoVivify" as the tie
1094 class. The behavior of this package allows access to existing
1095 fields, will automatically create field slots if they don't exist,
1096 and will allow deletion of field slots. Attempts to access or
1097 delete method or parent slots will croak.
1098 Calls to "new" and "clone" will use the tied interface in use on the
1100 existing object/package. When "reflect" is called for the first time
1101 on a class package, it will use the tied interface of its first parent
1102 class (i.e. $ISA[0]). If that package has not yet had "reflect"
1103 called on it, it will check its parent, and so on and so forth. If
1104 none of the packages in the primary inheritance fork have been
1105 reflected upon, the value for "Class::Prototyped" will be used, which
1106 should be "default".
1107 defaultAttributes() - get and set default attributes
1109 This isn't particularly pretty. The general syntax looks something
1110 like:
1111 my $temp = MyClass->reflect->defaultAttributes;
1113 $temp->{METHOD}->{superable} = 1;
1114 MyClass->reflect->defaultAttributes($temp);
1115 The return value from "defaultAttributes" is a hash with the keys
1117 'FIELD', 'METHOD', and 'PARENT'. The values are either "undef" or hash
1118 references consisting of the attributes and their default values.
1119 Modify the data structure as desired and pass it back to
1120 "defaultAttributes" to change the default attributes for that object or
1121 class. Note that default attributes are not inherited dynamically -
1122 the inheritance occurs when a new object is created, but from that
1123 point on changes to a parent object are not inherited by the child.
1124 Global changes can be effected by modifying the "defaultAttributes" for
1125 "Class::Prototyped" in a sufficiently early "BEGIN" block. Note that
1126 making global changes like this is "not" recommended for production
1127 modules as it may interfere with other modules that rely upon
1128 "Class::Prototyped".
1129 wrap()
1131 unwrap()
1132 delegate()
1133 delegate name => slot name can be string, regex, or array of same.
1134 slot can be slot name, or object, or 2-element array with slot name or
1135 object and method name. You can delegate to a parent.
1136 include() - include a package or external file
1138 You can "require" an arbitrary file in the namespace of an object or
1139 class without adding to the parents using "include()" :
1140 $foo->include( 'xx.pl' );
1142 will include whatever is in xx.pl. Likewise for modules:
1144 $foo->include( 'MyModule' );
1146 will search along your @INC path for "MyModule.pm" and include it.
1148 You can specify a second parameter that will be the name of a
1150 subroutine that you can use in your included code to refer to the
1151 object into which the code is being included (as long as you don't
1152 change packages in the included code). The subroutine will be removed
1153 after the include, so don't call it from any subroutines defined in the
1154 included code.
1155 If you have the following in "File.pl":
1157 sub b {'xxx.b'}
1159 sub c { return thisObject(); } # DON'T DO THIS!
1161 thisObject()->reflect->addSlots(
1163 'parent*' => 'A',
1164 d => 'added.d',
1165 e => sub {'xxx.e'},
1166 );
1167 And you include it using:
1169 $mirror->include('File.pl', 'thisObject');
1171 Then the "addSlots" will work fine, but if sub "c" is called, it won't
1173 find "thisObject()".
1174
1176 Written by Ned Konz, perl@bike-nomad.com and Toby Ovod-Everett,
1177 toby@ovod-everett.org. 5.005_03 porting by chromatic.
1178 Toby Ovod-Everett is currently maintaining the package.
1180
1182 Copyright 2001-2004 Ned Konz and Toby Ovod-Everett. All rights
1183 reserved. This program is free software; you can redistribute it and/or
1184 modify it under the same terms as Perl itself.
1185
1187 Class::SelfMethods
1188 Class::Object
1190 Class::Classless
1192perl v5.12.0 2010-04-30 Class::Prototyped(3)