CWClass::Prototyped - Fast prototype-based OO programming in Perl

    use strict;
    use Class::Prototyped ':EZACCESS';

    $, = ' '; $\ = "\n";

    my $p = Class::Prototyped->new(
      field1 => 123,
      sub1   => sub { print "this is sub1 in p" },
      sub2   => sub { print "this is sub2 in p" }
    );

    $p->sub1;
    print $p->field1;
    $p->field1('something new');
    print $p->field1;

    my $p2 = Class::Prototyped::new(
      'parent*' => $p,
      field2    => 234,
      sub2      => sub { print "this is sub2 in p2" }
    );

    $p2->sub1;
    $p2->sub2;
    print ref($p2), $p2->field1, $p2->field2;
    $p2->field1('and now for something different');
    print ref($p2), $p2->field1;

    $p2->addSlots( sub1 => sub { print "this is sub1 in p2" } );
    $p2->sub1;

    print ref($p2), "has slots", $p2->reflect->slotNames;

    $p2->reflect->include( 'xx.pl' ); # includes xx.pl in $p2's package
    print ref($p2), "has slots", $p2->reflect->slotNames;
    $p2->aa();    # calls aa from included file xx.pl

    $p2->deleteSlots('sub1');
    $p2->sub1;

This package provides for efficient and simple prototype-based programming in Perl. You can provide different subroutines for each object, and also have objects inherit their behavior and state from another object.

The structure of an object is inspected and modified through mirrors, which are created by calling CWreflect on an object or class that inherits from CWClass::Prototyped.

This module requires CWModule::Build 0.24 to use the automated installation procedures. With CWModule::Build installed:

  Build.PL
  perl build test
  perl build install

It can be installed under ActivePerl for Win32 by downloading the PPM from CPAN (the file has the extension CW.ppm.zip). To install, download the CW.ppm.zip file, uncompress it, and execute:

  ppm install Class-Prototyped.ppd

The module can also be installed manually by copying CWlib/Class/Prototyped.pm to CWperl/site/lib/Class/Prototyped.pm (along with CWGraph.pm if you want it).

When I reach for CWClass::Prototyped, it's generally because I really need it. When the cleanest way of solving a problem is for the code that uses a module to subclass from it, that is generally a sign that CWClass::Prototyped would be of use. If you find yourself avoiding the problem by passing anonymous subroutines as parameters to the CWnew method, that's another good sign that you should be using prototype based programming. If you find yourself storing anonymous subroutines in databases, configuration files, or text files, and then writing infrastructure to handle calling those anonymous subroutines, that's yet another sign. When you expect the people using your module to want to change the behavior, override subroutines, and so forth, that's a sign.

CWClass::Prototyped borrows very strongly from the language Self (see http://www.sun.com/research/self for more information). The core concept in Self is the concept of a slot. Think of slots as being entries in a hash, except that instead of just pointing to data, they can point to objects, code, or parent objects.

So what happens when you send a message to an object (that is to say, you make a method call on the object)? First, Perl looks for that slot in the object. If it can't find that slot in the object, it searches for that slot in one of the object's parents (which we'll come back to later). Once it finds the slot, if the slot is a block of code, it evaluates the code and returns the return value. If the slot references data, it returns that data. If you assign to a data slot (through a method call), it modifies the data.

Distinguishing data slots and method slots is easy - the latter are references to code blocks, the former are not. Distinguishing parent slots is not so easy, so instead a simple naming convention is used. If the name of the slot ends in an asterisk, the slot is a parent slot. If you have programmed in Self, this naming convention will feel very familiar.

In Self, to examine the structure of an object, you use a mirror. Just like using his shield as a mirror enabled Perseus to slay Medusa, holding up a mirror enables us to look upon an object's structure without name space collisions.

Once you have a mirror, you can add and delete slots like so:

    my $cp = Class::Prototyped->new();
    my $mirror = $cp->reflect();
    $mirror->addSlots(
      field1 => 'foo',
      sub1   => sub {
        print "this is sub1 printing field1: '".$_[0]->field1."'\n";
      },
    );

    $mirror->deleteSlot('sub1');

In addition, there is a more verbose syntax for CWaddSlots where the slot name is replaced by an anonymous array - this is most commonly used to control the slot attributes.

    $cp->reflect->addSlot(
      [qw(field1 FIELD)] => 'foo',
      [qw(sub1 METHOD)]  => sub { print "hi there.\n"; },
    );

Because the mirror methods CWsuper, CWaddSlot(CWs), CWdeleteSlot(CWs), and CWgetSlot(CWs) are called frequently on objects, there is an import keyword CW:EZACCESS that adds methods to the object space that call the appropriate reflected variants.

Slot attributes allow the user to specify additional information and behavior relating to a specific slot in an extensible manner. For instance, one might want to mark a specific field slot as constant or to attach a description to a given slot.

Slot attributes are divided up in two ways. The first is by the type of slot - CWFIELD, CWMETHOD, or CWPARENT. Some slot attributes apply to all three, some to just two, and some to only one. The second division is on the type of slot attribute:

implementor

These are responsible for implementing the behavior of a slot. An example is a CWFIELD slot with the attribute CWconstant. A slot is only allowed one implementor. All slot types have a default implementor. For CWFIELD slots, it is a read-write scalar. For CWMETHOD slots, it is the passed anonymous subroutine. For CWPARENT slots, CWimplementor and CWfilter slot attributes don't really make sense.

filter

These filter access to the CWimplementor. The quintessential example is the CWprofile attribute. When set, this increments a counter in CW$Class::Prototyped::Mirror::PROFILE::counts every time the underlying CWFIELD or CWMETHOD is accessed. Filter attributes can be stacked, so each attribute is assigned a rank with lower values being closer to the CWimplementor and higher values being closer to the caller.

advisory

These slot attributes serve one of two purposes. They can be used to store information about the slot (i.e. CWdescription attributes), and they can be used to pass information to the CWaddSlots method (i.e. the CWpromote attribute, which can be used to promote a new CWPARENT slot ahead of all the existing CWPARENT slots).

There is currently no formal interface for creating your own attributes - if you feel the need for new attributes, please contact the maintainer first to see if it might make sense to add the new attribute to CWClass::Prototyped. If not, the contact might provide enough impetus to define a formal interface. The attributes are currently defined in CW$Class::Prototyped::Mirror::attributes.

Finally, see the CWdefaultAttributes method for information about setting default attributes. This can be used, for instance, to turn on profiling everywhere.

In Self, everything is an object and there are no classes at all. Perl, for better or worse, has a class system based on packages. We decided that it would be better not to throw out the conventional way of structuring inheritance hierarchies, so in CWClass::Prototyped, classes are first-class objects.

However, objects are not first-class classes. To understand this dichotomy, we need to understand that there is a difference between the way classes and the way objects are expected to behave. The central difference is that classes are expected to persist whether or not that are any references to them. If you create a class, the class exists whether or not it appears in anyone's CW@ISA and whether or not there are any objects in it. Once a class is created, it persists until the program terminates.

Objects, on the other hand, should follow the normal behaviors of reference-counted destruction - once the number of references to them drops to zero, they should miraculously disappear - the memory they used needs to be returned to Perl, their CWDESTROY methods need to be called, and so forth.

Since we don't require this behavior of classes, it's easy to have a way to get from a package name to an object - we simply stash the object that implements the class in CW$Class::Prototyped::Mirror::objects{$package}. But we can't do this for objects, because if we do the object will persist forever because that reference will always exist.

Weak references would solve this problem, but weak references are still considered alpha and unsupported (CW$WeakRef::VERSION = 0.01), and we didn't want to make CWClass::Prototyped dependent on such a module.

So instead, we differentiate between classes and objects. In a nutshell, if an object has an explicit package name (i.e. something other than the auto-generated one), it is considered to be a class, which means it persists even if the object goes out of scope.

To create such an object, use the CWnewPackage method, like so (the encapsulating block exists solely to demonstrate that classes are not scoped):

    {
      my $object = Class::Prototyped->newPackage('MyClass',
          field => 1,
          double => sub {$_[0]->field*2}
        );
    }

    print MyClass->double,"\n";

Notice that the class persists even though CW$object goes out of scope. If CW$object were created with an auto-generated package, that would not be true. Thus, for instance, it would be a very, very, very bad idea to add the package name of an object as a parent to another object - when the first object goes out of scope, the package will disappear, but the second object will still have it in it's CW@ISA.

Except for the crucial difference that you should never, ever, ever make use of the package name for an object for any purpose other than printing it to the screen, objects and classes are simply different ways of inspecting the same entity.

To go from an object to a package, you can do one of the following:

    $package = ref($object);
    $package = $object->reflect->package;

The two are equivalent, although the first is much faster. Just remember, if CW$object is in an auto-generated package, don't do anything with that CW$package but print it.

To go from a package to an object, you do this:

    $object = $package->reflect->object;

Note that CW$package is simple the name of the package - the following code works perfectly:

    $object = MyClass->reflect->object;

But keep in mind that CW$package has to be a class, not an auto-generated package name for an object.

This lets us have tons of fun manipulating classes at run time. For instance, if you wanted to add, at run-time, a new method to the CWMyClass class? Assuming that the CWMyClass inherits from CWClass::Prototyped or that you have specified CW:REFLECT on the CWuse Class::Prototyped call, you simply write:

    MyClass->reflect->addSlot(myMethod => sub {print "Hi there\n"});

If you want to access a class that doesn't inherit from CWClass::Prototyped, and you want to avoid specifying CW:REFLECT (which adds CWreflect to the CWUNIVERSAL package), you can make the call like so:

    my $mirror = Class::Prototyped::Mirror->new('MyClass');
    $mirror->addSlot(myMethod => sub {print "Hi there\n"});

Just as you can CWclone objects, you can CWclone classes that are derived from CWClass::Prototyped. This creates a new object that has a copy of all of the slots that were defined in the class. Note that if you simply want to be able to use CWData::Dumper on a class, calling CWMyClass->reflect->object is the preferred approach. Even easier would be to use the CWdump mirror method.

The code that implements reflection on classes automatically creates slot names for package methods as well as parent slots for the entries in CW@ISA. This means that you can code classes like you normally do - by doing the inheritance in CW@ISA and writing package methods.

If you manually add subroutines to a package at run-time and want the slot information updated properly (although this really should be done via the CWaddSlots mechanism, but maybe you're twisted:), you should do something like:

    $package->reflect->_vivified_methods(0);
    $package->reflect->_autovivify_methods;

Adding parent slots is no different than adding normal slots - the naming scheme takes care of differentiating.

Thus, to add CW$foo as a parent to CW$bar, you write:

    $bar->reflect->addSlot('fooParent*' => $foo);

However, keeping with our concept of classes as first class objects, you can also write the following:

    $bar->reflect->addSlot('mixIn*' => 'MyMix::Class');

It will automatically require the module in the namespace of CW$bar and make the module a parent of the object. This can load a module from disk if needed.

If you're lazy, you can add parents without names like so:

    $bar->reflect->addSlot('*' => $foo);

The slots will be automatically named for the package passed in - in the case of CWClass::Prototyped objects, the package is of the form CWPKG0x12345678. In the following example, the parent slot will be named CWMyMix::Class*.

    $bar->reflect->addSlot('*' => 'MyMix::Class');

Parent slots are added to the inheritance hierarchy in the order that they were added. Thus, in the following code, slots that don't exist in CW$foo are looked up in CW$fred (and all of its parent slots) before being looked up in CW$jill.

    $foo->reflect->addSlots('fred*' => $fred, 'jill*' => $jill);

Note that CWaddSlot and CWaddSlots are identical - the variants exist only because it looks ugly to add a single slot by calling CWaddSlots.

If you need to reorder the parent slots on an object, look at CWpromoteParents. That said, there's a shortcut for prepending a slot to the inheritance hierarchy. Simply define CW'promote' as a slot attribute using the extended slot syntax.

Finally, in keeping with our principle that classes are first-class object, the inheritance hierarchy of classes can be modified through CWaddSlots and CWdeleteSlots, just like it can for objects. The following code adds the CW$foo object as a parent of the CWMyClass class, prepending it to the inheritance hierarchy:

    MyClass->reflect->addSlots([qw(foo* promote)] => $foo);

In CWClass::Prototyped, you do operator overloading by adding slots with the right name. First, when you do the CWuse on CWClass::Prototyped, make sure to pass in CW:OVERLOAD so that the operator overloading support is enabled.

Then simply pass the desired methods in as part of the object creation like so:

    $foo = Class::Prototyped->new(
        value => 3,
        '""'  => sub { my $self = shift; $self->value( $self->value + 1 ) },
    );

This creates an object that increments its field CWvalue by one and returns that incremented value whenever it is stringified.

Since there is no way to find out which operators are overloaded, if you add overloading to a class through the use of CWuse overload, that behavior will not show up as slots when reflecting on the class. However, CWaddSlots does work for adding operator overloading to classes. Thus, the following code does what is expected:

    Class::Prototyped->newPackage('MyClass');
    MyClass->reflect->addSlots(
        '""' => sub { my $self = shift; $self->value( $self->value + 1 ) },
    );

    $foo = MyClass->new( value => 2 );
    print $foo, "\n";

The special parent slot CWclass* is used to indicate object class. When you create CWClass::Prototyped objects by calling CWClass::Prototyped->new(), the CWclass* slot is not set. If, however, you create objects by calling CWnew on a class or object that inherits from CWClass::Prototyped, the slot CWclass* points to the package name if CWnew was called on a named class, or the object if CWnew was called on an object.

The value of this slot can be returned quite easily like so:

    $foo->reflect->class;

Methods (and fields) inherited from prototypes or classes are not generally available using the usual Perl CW$self->SUPER::something() mechanism.

The reason for this is that CWSUPER::something is hardcoded to the package in which the subroutine (anonymous or otherwise) was defined. For the vast majority of programs, this will be CWmain::, and thus CWSUPER:: will look in CW@main::ISA (not a very useful place to look).

To get around this, a very clever wrapper can be automatically placed around your subroutine that will automatically stash away the package to which the subroutine is attached. From within the subroutine, you can use the CWsuper mirror method to make an inherited call. However, because we'd rather not write code that attempts to guess as to whether or not the subroutine uses the CWsuper construct, you have to tell CWaddSlots that the subroutine needs to have this wrapper placed around it. To do this, simply use the extended CWaddSlots syntax (see the method description for more information) and pass in the slot attribute CW'superable'. The following examples use the minimalist form of the extended syntax.

For instance, the following code will work:

    use Class::Prototyped;

    my $p1 = Class::Prototyped->new(
        method => sub { print "this is method in p1\n" },
    );

    my $p2 = Class::Prototyped->new(
        '*'                     => $p1,
        [qw(method superable)]' => sub {
            print "this is method in p2 calling method in p1: ";
            $_[0]->reflect->super('method');
        },
    );

To make things easier, if you specify CW:EZACCESS during the import, CWsuper can be called directly on an object rather than through its mirror.

The other thing of which you need to be aware is copying methods from one object to another. The proper way to do this is like so:

    $foo->reflect->addSlot($bar->reflect->getSlot('method'));

When the CWgetSlot method is called in an array context, it returns both the complete format for the slot identifier and the slot. This ensures that slot attributes are passed along, including the CWsuperable attribute.

Finally, to help protect the code, the CWsuper method is smart enough to determine whether it was called within a wrapped subroutine. If it wasn't, it croaks indicating that the method should have had the CWsuperable attribute set when it was added. If you wish to disable this checking (which will improve the performance of your code, of course, but could result in very hard to trace bugs if you haven't been careful), see the import option CW:SUPER_FAST.

It is important to be aware of where the boundaries of prototyped based programming lie, especially in a language like Perl that is not optimized for it. For instance, it might make sense to implement every field in a database as an object. Those field objects would in turn be attached to a record class. All of those might be implemented using CWClass::Prototyped. However, it would be very inefficient if every record that got read from the database was stored in a CWClass::Prototyped based object (unless, of course, you are storing code in the database). In that situation, it is generally good to choke off the prototype-based behavior for the individual record objects. For best performance, it is important to confine CWClass::Prototyped to those portions of the code where behavior is mutable from outside of the module. See the documentation for the CWnew method of CWClass::Prototyped for more information about choking off CWClass::Prototyped behavior.

There are a number of performance hits when using CWClass::Prototyped, relative to using more traditional OO code. It is important to note that these generally lie in the instantiation and creation of classes and objects and not in the actual use of them. The scripts in the CWperf directory were designed for benchmarking some of this material.

The normal way of creating a class is like this:

    package Pack_123;
    sub a {"hi";}
    sub b {"hi";}
    sub c {"hi";}
    sub d {"hi";}
    sub e {"hi";}

The most efficient way of doing that using proper CWClass::Prototyped methodology looks like this:

    Class::Prototyped->newPackage("Pack_123");
    push(@P_123::slots, a => sub {"hi";});
    push(@P_123::slots, b => sub {"hi";});
    push(@P_123::slots, c => sub {"hi";});
    push(@P_123::slots, d => sub {"hi";});
    push(@P_123::slots, e => sub {"hi";});
    Pack_123->reflect->addSlots(@P_123::slots);

This approach ensures that the new package gets the proper default attributes and that the slots are created through CWaddSlots, thus ensuring that default attributes are properly implemented. It avoids multiple calls to CW ->reflect->addSlot, though, which improves performance. The idea behind pushing the slots onto an array is that it enables one to intersperse code with POD, since POD is not permitted inside of a single Perl statement.

On a Pent 4 1.8GHz machine, the normal code runs in 120 usec, whereas the CWClass::Prototyped code runs in around 640 usec, or over 5 times slower. A straight call to CWaddSlots with all five methods runs in around 510 usec. Code that creates the package and the mirror without adding slots runs in around 135 usec, so we're looking at an overhead of less than 100 usec per slot. In a situation where the compile time dominates the execution time (I'm using those terms loosely as much of what happens in CWClass::Prototyped is technically execution time, but it is activity that traditionally would happen at compile time), CWClass::Prototyped might prove to be too much overhead. On the otherhand, you may find that demand loading can cut much of that overhead and can be implemented less painfully than might otherwise be thought.

There is no need to even compare here. Blessing a hash into a class takes less than 2 usec. Creating a new CWClass::Prototyped object takes at least 60 or 70 times longer. The trick is to avoid creating unnecessary CWClass::Prototyped objects. If you know that all 10,000 database records are going to inherit all of their behavior from the parent class, there is no point in creating 10,000 packages and all the attendant overhead. The CWnew method for CWClass::Prototyped demonstrates how to ensure that those state objects are created as normal Perl objects.

The good news is that method calls are just as fast as normal Perl method calls, inherited or not. This is because the existing Perl OO machinery has been hijacked in CWClass::Prototyped. The exception to this is if CWfilter slot attributes have been used, including CWwantarray, CWsuperable, and CWprofile. In that situation, the added overhead is that for a normal Perl subroutine call (which is faster than a method call because it is a static binding)

The hash interface is not particularly fast, and neither is it good programming practice. Using the method interface to access fields is just as fast, however, as using normal getter/setter methods.

This configures the support in CWClass::Prototyped for using operator overloading. This defines CWUNIVERSAL::reflect to return a mirror for any class. With a mirror, you can manipulate the class, adding or deleting methods, changing its inheritance hierarchy, etc. This adds the methods CWaddSlot, CWaddSlots, CWdeleteSlot, CWdeleteSlots, CWgetSlot, CWgetSlots, and CWsuper to CWClass::Prototyped. This lets you write:

  $foo->addSlot(myMethod => sub {print "Hi there\n"});

  $foo->reflect->addSlot(myMethod => sub {print "Hi there\n"});

  use Class::Prototyped qw(:NEW_MAIN :EZACCESS);

  my $foo = new(say_hi => sub {print "Hi!\n";});
  $foo->say_hi;

When called on named classes, either via the package name or via the object (i.e. CWMyPackage->reflect->object()), CWclass* is set to the package name. When called on an object, CWclass* is set to the object on which CWnew was called.

The passed arguments are handed off to CWaddSlots.

Note that CWnew calls CWnewCore, so if you want to override CWnew, but want to ensure that your changes are applicable to CWnewPackage, CWclone, and CWclonePackage, you may wish to override CWnewCore.

For instance, the following will define a new CWClass::Prototyped object with two method slots and one field slot:

    my $foo = Class::Prototyped->new(
        field1 => 123,
        sub1   => sub { print "this is sub1 in foo" },
        sub2   => sub { print "this is sub2 in foo" },
    );

The following will create a new CWMyClass object with one field slot and with the parent object CW$bar at the beginning of the inheritance hierarchy (just before CWclass*, which points to CWMyClass):

    my $foo = MyClass->new(
        field1  => 123,
        [qw(bar* promote)] => $bar,
    );

The following will create a new object that inherits behavior from CW$bar with one field slot, CWfield1, and one parent slot, CWclass*, that points to CW$bar.

    my $foo = $bar->new(
        field1  => 123,
    );

If you want to create normal Perl objects as child objects of a CWClass::Prototyped class in order to improve performance, implement your own standard Perl CWnew method:

    Class::Prototyped->newPackage('MyClass');
    MyClass->reflect->addSlot(
        new => sub {
            my $class = shift;
            my $self = {};
            bless $self, $class;
            return $self;
        }
    );

It is still safe to use CW$obj->reflect->super() in code that runs on such an object. All other reflection will automatically return the same results as inspecting the class to which the object belongs. Just like CWnew, but instead of creating the new object with an arbitrary package name (actually, not entirely arbitrary - it's generally based on the hash memory address), the first argument is used as the name of the package. This creates a named class. The same behavioral rules for CWclass* described above for CWnew apply to CWnewPackage (in fact, CWnew calls CWnewPackage).

If the package name is already in use, this method will croak.

Duplicates an existing object or class and allows you to add or override slots. The slot definition is the same as in BInew().

  my $p2 = $p1->clone(
      sub1 => sub { print "this is sub1 in p2" },
  );

It calls CWnewCore to create the new object*, so if you have overriden CWnew, you should contemplate overriding CWclone in order to ensure that behavioral changes made to CWnew that would be applicable to CWclone are implemented. Or simply override CWnewCore.

Just like CWclone, but instead of creating the new object with an arbitrary package name (actually, not entirely arbitrary - it's generally based on the hash memory address), the first argument is used as the name of the package. This creates a named class.

If the package name is already in use, this method will croak.

This implements the core functionality involved in creating a new object. The first passed parameter will be the name of the caller - either CWnew, CWnewPackage, CWclone, or CWclonePackage. The second parameter is the name of the package if applicable (i.e. for CWnewPackage and CWclonePackage) calls, CWundef if inapplicable. The remainder of the parameters are any slots to be added to the newly created object/package.

If called with CWnew or CWnewPackage, the CWclass* slot will be prepended to the slot list if applicable. If called with CWclone or CWclonePackage, all slots on the receiver will be prepended to the slot list.

If you wish to add behavior to object instantiation that needs to be present in all four of the instantiators (i.e. instance tracking), it may make sense to override CWnewCore so that you implement the code in only one place.

The structure of an object is modified by using a mirror. This is the equivalent of calling:

  Class::Prototyped::Mirror->new($foo);

You should never need to call this method. However, you may want to override it. Because we had to directly specify CWDESTROY for every object in order to allow safe destruction during global destruction time when objects may have already destroyed packages in their CW@ISA, we had to hook CWDESTROY for every object. To allow the CWdestroy behavior to be overridden, users should specify a CWdestroy method for their objects (by adding the slot), which will automatically be called by the CWClass::Prototyped::DESTROY method after the CW@ISA has been cleaned up.

This method should be defined to allow inherited method calls (i.e. should use "CW[qw(destroy superable)]" to define the method) and should call CW$self->reflect->super('destroy'); at some point in the code.

Here is a quick overview of the default destruction behavior for objects:

•

CWClass::Prototyped::DESTROY is called because it is linked into the package for all objects at instantiation time

•

All no longer existent entries are stripped from CW@ISA

•

The inheritance hierarchy is searched for a CWDESTROY method that is not CWClass::Prototyped::DESTROY. This CWDESTROY method is stashed away for a later call.

•

The inheritance hierarchy is searched for a CWdestroy method and it is called. Note that the CWClass::Prototyped::destroy method, which will either be called directly because it shows up in the inheritance hierarchy or will be called indirectly through calls to CW$self->reflect->super('destroy');, will delete all non-parent slots from the object. It leaves parent slots alone because the destructors for the parent slots should not be called until such time as the destruction of the object in question is complete (otherwise inherited destructors might still be executing, even though the object to which they belong has already been destroyed). This means that the destructors for objects referenced in non-parent slots may be called, temporarily interrupting the execution sequence in CWClass::Prototyped::destroy.

•

The previously stashed CWDESTROY method is called.

•

The parent slots for the object are finally removed, thus enabling the destructors for any objects referenced in those parent slots to run.

•

Final CWClass::Prototyped specific cleanup is run. These are the methods you can call on the mirror returned from a CWreflect call. If you specify CW:EZACCESS in the CWuse Class::Prototyped line, CWaddSlot, CWaddSlots, CWdeleteSlot, CWdeleteSlots, CWgetSlot, CWgetSlots, and CWsuper will be callable on CWClass::Prototyped objects as well. Normally called via the CWreflect method, this can be called directly to avoid using the CW:REFLECT import option for reflecting on non CWClass::Prototyped based classes.

If you add an CWAUTOLOAD slot to an object, you will need to get the name of the subroutine being called. CWautoloadCall() returns the name of the subroutine, with the package name stripped off.

Allows you to add or replace slot definitions in the receiver.

    $p->reflect->addSlots(
        fred        => 'this is fred',
        doSomething => sub { print 'doing something with ' . $_[1] },
    );
    $p->doSomething( $p->fred );

In addition to the simple form, there is an extended syntax for specifying the slot. In place of the slotname, pass an array reference composed like so:

CWaddSlots( [$slotName, $slotType, %slotAttributes] => $slotValue );

CW$slotName is simply the name of the slot, including the trailing CW* if it is a parent slot. CW$slotType should be CW'FIELD', CW'METHOD', or CW'PARENT'. CW%slotAttributes should be a list of attribute/value pairs. It is common to use qw() to reduce the amount of typing:

    $p->reflect->addSlot(
        [qw(bar FIELD)] => "this is a field",
    );

    $p->reflect->addSlot(
        [qw(bar FIELD constant 1)] => "this is a constant field",
    );

    $p->reflect->addSlot(
        [qw(foo METHOD)] => sub { print "normal method.\n"; },
    );

    $p->reflect->addSlot(
        [qw(foo METHOD superable 1)] => sub { print "superable method.\n"; },
    );

    $p->reflect->addSlot(
        [qw(parent* PARENT)] => $parent,
    );

    $p->reflect->addSlot(
        [qw(parent2* PARENT promote 1)] => $parent2,
    );

To make using the extended syntax a bit less cumbersome, however, the following shortcuts are allowed:

•

CW$slotType can be omitted. In this case, the slot's type will be determined by inspecting the slot's name (to determine if it is a parent slot) and the slot's value (to determine whether it is a field or method slot). The CW$slotType value can, however, be used to supply a reference to a code object as the value for a field slot. Note that this means that CWFIELD, CWMETHOD, and CWPARENT are not legal attribute names (since this would make parsing difficult).

•

If there is only one attribute and if the value is CW1, then the value can be omitted.

Using both of the above contractions, the following are valid short forms for the extended syntax:

    $p->reflect->addSlot(
        [qw(bar constant)] => "this is a constant field",
    );

    $p->reflect->addSlot(
        [qw(foo superable)] => sub { print "superable method.\n"; },
    );

    $p->reflect->addSlot(
        [qw(parent2* promote)] => $parent2,
    );

The currently defined slot attributes are as follows: When true, this defines the field slot as constant, disabling the ability to modify it using the CW$object->field($newValue) syntax. The value may still be modified using the hash syntax (i.e. CW$object->{field} = $newValue). This is mostly useful if you have an object method call that takes parameters, but you wish to replace it on a given object with a hard-coded value by using a field (which makes inspecting the value of the slot through CWData::Dumper much easier than if you use a CWMETHOD slot to return the constant, since code objects are opaque). The passed value for the CWFIELD slot should be a subroutine that returns the desired value. Upon the first access, the subroutine will be called, the return value hard-coded into the object by adding the slot (including all otherwise specified attributes), and the value then returned. Useful for implementing constant slots that are costly to initialize, especially those that return lists of CWClass::Prototyped objects! If CWprofile is set to 1, increments CW $Class::Prototyped::Mirror::PROFILE::counts->{$package}->{$slotName} everytime the slot is accessed. If CWprofile is set to 2, increments CW $Class::Prototyped::Mirror::PROFILE::counts->{$package}->{$slotName}->{$caller} everytime the slot is accessed, where CW$caller is CW"$file ($line)". If the field specifies a reference to an array and the call is in list context, dereferences the array and returns a list of values. Can be used to specify a description. No real support for this yet beyond that! When true, this enables the CW$self->reflect->super( . . . ) calls for this method slot. See CWFIELD slots for explanation. Set automatically for methods that implement operator overloading. See CWFIELD slots for explanation. When true, this parent slot is promoted ahead of any other parent slots on the object. This attribute is ephemeral - it is not returned by calls to CWgetSlot. See CWFIELD slots for explanation.

This will let you delete existing slots in the receiver. If those slots were defined in the receiver's inheritance hierarchy, those inherited definitions will now be available.

    my $p1 = Class::Prototyped->new(
        field1 => 123,
        sub1   => sub { print "this is sub1 in p1" },
        sub2   => sub { print "this is sub2 in p1" }
    );
    my $p2 = Class::Prototyped->new(
        'parent*' => $p1,
        sub1      => sub { print "this is sub1 in p2" },
    );
    $p2->sub1;    # calls $p2.sub1
    $p2->reflect->deleteSlots('sub1');
    $p2->sub1;    # calls $p1.sub1
    $p2->reflect->deleteSlots('sub1');
    $p2->sub1;    # still calls $p1.sub1

The call to a method defined on a parent that is obscured by the current one looks like so:

    $self->reflect->super('method_name', @params);

This is passed an optional type parameter. If specified, it should be one of CW'FIELD', CW'METHOD', or CW'PARENT'. For instance, the following will print out a list of all slots of an object:

  print join(', ', $obj->reflect->slotNames)."\n";

The following would print out a list of all field slots:

  print join(', ', $obj->reflect->slotNames('FIELD')."\n";

The parent slot names are returned in the same order for which inheritance is done.

This returns CW'FIELD', CW'METHOD', or CW'PARENT'. It croaks if the slot is not defined for that object.

Returns a list of all parent object (or package names) for this object.

Returns a list of all parent objects (or package names) in the object's hierarchy.

Note that this will return duplicate slot names if inherited slots are obscured.

When called in scalar context, this returns the thing in the slot. When called in list context, it returns both the complete form of the extended syntax for specifying a slot name and the thing in the slot. There is an optional parameter that can be used to modify the format of the return value in list context. The allowable values are:

•

CW'default' - the extended slot syntax and the slot value are returned

•

CW'simple' - the slot name and the slot value are returned. Note that in this mode, there is no access to any attributes the slot may have

•

CW'rotated' - the slot name and the following hash are returned like so:

  $slotName => {
    attribs => %slotAttribs,
    type => $slotType,
    value => $slotValue
  },

The latter two options are quite useful when used in conjunction with the CWgetSlots method.

This returns a list of extended syntax slot specifiers and their values ready for sending to CWaddSlots. It takes first the optional parameter passed to CWslotNames which specifies the type of slot (CW'FIELD', CW'METHOD', CW'PARENT', or CWundef) and then the optional parameter passed to CWgetSlot, which specifies the format for the return value. If the latter is CW'simple', the returned values can be passed to CWaddSlots, but any non-default slot attributes (i.e. CWsuperable or CWconstant) will be lost. If the latter is CW'rotated', the returned values are completely inappropriate for passing to CWaddSlots. Both CW'simple' and CW'rotated' are appropriate for assigning the return values into a hash.

For instance, to add all of the field slots in CW$bar to CW$foo:

  $foo->reflect->addSlots($bar->reflect->getSlots('FIELD'));

To get a list of all of the slots in the CW'simple' format:

  my %barSlots = $bar->reflect->getSlots(undef, 'simple');

To get a list of all of the superable method slots in the CW'rotated' format:

  my %barMethods = $bar->reflect->getSlots('METHOD', 'rotated');
  foreach my $slotName (%barMethods) {
    delete $barMethods{$slotName}
      unless $barMethods{$slotName}->{attribs}->{superable};
  }

This expects a list of parent slot names. There should be no duplicates and all of the parent slot names should be already existing parent slots on the object. These parent slots will be moved forward in the hierarchy in the order that they are passed. Unspecified parent slots will retain their current positions relative to other unspecified parent slots, but as a group they will be moved to the end of the hierarchy.

This allows you to specify the sort of tied interface you wish to offer when code accesses the object as a hash reference. If no parameter is passed, this will return the current tied interface package active for the object. If a parameter is passed, it should specify either the package name or an alias. The currently known aliases are:

default

This specifies CWClass::Prototyped::Tied::Default as the tie class. The default behavior is to allow access to existing fields, but attempts to create fields, access methods, or delete slots will croak. This is the tie class used by CWClass::Prototyped (unless you do something very naughty and call CWClass::Prototyped->reflect->tiedInterfacePackage($not_default)), and as such is the fallback behavior for classes and objects if they don't get a different value from their inheritance.

autovivify

This specifies CWClass::Prototyped::Tied::AutoVivify as the tie class. The behavior of this package allows access to existing fields, will automatically create field slots if they don't exist, and will allow deletion of field slots. Attempts to access or delete method or parent slots will croak.

Calls to CWnew and CWclone will use the tied interface in use on the existing object/package. When CWreflect is called for the first time on a class package, it will use the tied interface of its first parent class (i.e. CW$ISA[0]). If that package has not yet had CWreflect called on it, it will check its parent, and so on and so forth. If none of the packages in the primary inheritance fork have been reflected upon, the value for CWClass::Prototyped will be used, which should be CWdefault.

This isn't particularly pretty. The general syntax looks something like:

    my $temp = MyClass->reflect->defaultAttributes;
    $temp->{METHOD}->{superable} = 1;
    MyClass->reflect->defaultAttributes($temp);

The return value from CWdefaultAttributes is a hash with the keys CW'FIELD', CW'METHOD', and CW'PARENT'. The values are either CWundef or hash references consisting of the attributes and their default values. Modify the data structure as desired and pass it back to CWdefaultAttributes to change the default attributes for that object or class. Note that default attributes are not inherited dynamically - the inheritance occurs when a new object is created, but from that point on changes to a parent object are not inherited by the child. Global changes can be effected by modifying the CWdefaultAttributes for CWClass::Prototyped in a sufficiently early CWBEGIN block. Note that making global changes like this is CWnot recommended for production modules as it may interfere with other modules that rely upon CWClass::Prototyped.

delegate name => slot name can be string, regex, or array of same. slot can be slot name, or object, or 2-element array with slot name or object and method name. You can delegate to a parent.

You can CWrequire an arbitrary file in the namespace of an object or class without adding to the parents using CWinclude() :

  $foo->include( 'xx.pl' );

will include whatever is in xx.pl. Likewise for modules:

  $foo->include( 'MyModule' );

will search along your CW@INC path for CWMyModule.pm and include it.

You can specify a second parameter that will be the name of a subroutine that you can use in your included code to refer to the object into which the code is being included (as long as you don't change packages in the included code). The subroutine will be removed after the include, so don't call it from any subroutines defined in the included code.

If you have the following in CWFile.pl:

    sub b {'xxx.b'}

    sub c { return thisObject(); }    # DON'T DO THIS!

    thisObject()->reflect->addSlots(
        'parent*' => 'A',
        d         => 'added.d',
        e         => sub {'xxx.e'},
    );

And you include it using:

    $mirror->include('File.pl', 'thisObject');

Then the CWaddSlots will work fine, but if sub CWc is called, it won't find CWthisObject().

Written by Ned Konz, perl@bike-nomad.com and Toby Ovod-Everett, toby@ovod-everett.org. 5.005_03 porting by chromatic.

Toby Ovod-Everett is currently maintaining the package.

Copyright 2001-2004 Ned Konz and Toby Ovod-Everett. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Class::SelfMethods

Class::Object

Class::Classless