Installation instructions

  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 ".ppm.zip"). To install, download the ".ppm.zip" file, uncompress it, and execute:

  ppm install Class-Prototyped.ppd

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

Slots

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.

Reflecting

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 "addSlots" 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 "super", "addSlot"("s"), "deleteSlot"("s"), and "getSlot"("s") are called frequently on objects, there is an import keyword ":EZACCESS" that adds methods to the object space that call the appropriate reflected variants.

Slot Attributes

Slot attributes are divided up in two ways. The first is by the type of slot - "FIELD", "METHOD", or "PARENT". 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 "FIELD" slot with the attribute "constant". A slot is only allowed one implementor. All slot types have a default implementor. For "FIELD" slots, it is a read-write scalar. For "METHOD" slots, it is the passed anonymous subroutine. For "PARENT" slots, "implementor" and "filter" slot attributes don't really make sense.

filter

These filter access to the "implementor". The quintessential example is the "profile" attribute. When set, this increments a counter in $Class::Prototyped::Mirror::PROFILE::counts every time the underlying "FIELD" or "METHOD" is accessed. Filter attributes can be stacked, so each attribute is assigned a rank with lower values being closer to the "implementor" 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. "description" attributes), and they can be used to pass information to the "addSlots" method (i.e. the "promote" attribute, which can be used to promote a new "PARENT" slot ahead of all the existing "PARENT" 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 "Class::Prototyped". If not, the contact might provide enough impetus to define a formal interface. The attributes are currently defined in $Class::Prototyped::Mirror::attributes.

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

Classes vs. 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 @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 "DESTROY" 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 $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 ("$WeakRef::VERSION = 0.01"), and we didn't want to make "Class::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 "newPackage" 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 $object goes out of scope. If $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 @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 $object is in an auto-generated package, don't do anything with that $package but print it.

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

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

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

    $object = MyClass->reflect->object;

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

Class Manipulation

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

If you want to access a class that doesn't inherit from "Class::Prototyped", and you want to avoid specifying ":REFLECT" (which adds "reflect" to the "UNIVERSAL" 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 "clone" objects, you can "clone" classes that are derived from "Class::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 "Data::Dumper" on a class, calling "MyClass->reflect->object" is the preferred approach. Even easier would be to use the "dump" 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 @ISA. This means that you can code classes like you normally do - by doing the inheritance in @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 "addSlots" mechanism, but maybe you're twisted:), you should do something like:

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

Parent Slots

Thus, to add $foo as a parent to $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 $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 "Class::Prototyped" objects, the package is of the form "PKG0x12345678". In the following example, the parent slot will be named "MyMix::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 $foo are looked up in $fred (and all of its parent slots) before being looked up in $jill.

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

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

If you need to reorder the parent slots on an object, look at "promoteParents". That said, there's a shortcut for prepending a slot to the inheritance hierarchy. Simply define '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 "addSlots" and "deleteSlots", just like it can for objects. The following code adds the $foo object as a parent of the "MyClass" class, prepending it to the inheritance hierarchy:

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

Operator Overloading

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 "value" 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 "use overload", that behavior will not show up as slots when reflecting on the class. However, "addSlots" 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";

Object Class

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

    $foo->reflect->class;

Calling Inherited Methods

The reason for this is that "SUPER::something" is hardcoded to the package in which the subroutine (anonymous or otherwise) was defined. For the vast majority of programs, this will be "main::", and thus "SUPER::" will look in @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 "super" 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 "super" construct, you have to tell "addSlots" that the subroutine needs to have this wrapper placed around it. To do this, simply use the extended "addSlots" syntax (see the method description for more information) and pass in the slot attribute '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 ":EZACCESS" during the import, "super" 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 "getSlot" 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 "superable" attribute.

Finally, to help protect the code, the "super" 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 "superable" 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 ":SUPER_FAST".

Class Instantiation

    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" "Class::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 "addSlots", thus ensuring that default attributes are properly implemented. It avoids multiple calls to "->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 "Class::Prototyped" code runs in around 640 usec, or over 5 times slower. A straight call to "addSlots" 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 "Class::Prototyped" is technically execution time, but it is activity that traditionally would happen at compile time), "Class::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.

Object Instantiation

Method Calls

Instance Variable Access

new() - Construct a new "Class::Prototyped" object.

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

The passed arguments are handed off to "addSlots".

Note that "new" calls "newCore", so if you want to override "new", but want to ensure that your changes are applicable to "newPackage", "clone", and "clonePackage", you may wish to override "newCore".

For instance, the following will define a new "Class::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 "MyClass" object with one field slot and with the parent object $bar at the beginning of the inheritance hierarchy (just before "class*", which points to "MyClass"):

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

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

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

If you want to create normal Perl objects as child objects of a "Class::Prototyped" class in order to improve performance, implement your own standard Perl "new" 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 "$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.

newPackage() - Construct a new "Class::Prototyped" object in a specific package.

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

clone() - Duplicate me

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

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

clonePackage()

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

newCore()

If called with "new" or "newPackage", the "class*" slot will be prepended to the slot list if applicable. If called with "clone" or "clonePackage", 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 "newCore" so that you implement the code in only one place.

reflect() - Return a mirror for the object or class

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

destroy() - The destroy method for an object

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

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

• "Class::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 @ISA
• The inheritance hierarchy is searched for a "DESTROY" method that is not "Class::Prototyped::DESTROY". This "DESTROY" method is stashed away for a later call.
• The inheritance hierarchy is searched for a "destroy" method and it is called. Note that the "Class::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 "$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 "Class::Prototyped::destroy".
• The previously stashed "DESTROY" 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 "Class::Prototyped" specific cleanup is run.

new() - Creates a new "Class::Prototyped::Mirror" object

autoloadCall()

package() - Returns the name of the package for the object

object() - Returns the object itself

class() - Returns the "class*" slot for the underlying object

dump() - Returns a Data::Dumper string representing the object

addSlot() - An alias for "addSlots"

addSlots() - Add or replace slot definitions

    $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:

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

$slotName is simply the name of the slot, including the trailing "*" if it is a parent slot. $slotType should be 'FIELD', 'METHOD', or 'PARENT'. %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:

• $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 $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 "FIELD", "METHOD", and "PARENT" are not legal attribute names (since this would make parsing difficult).
• If there is only one attribute and if the value is 1, 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:

"FIELD" Slots

"METHOD" Slots

"PARENT" Slots

deleteSlot() - An alias for deleteSlots

deleteSlots() - Delete one or more of the receiver's slots by name

    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

super() - Call a method defined in a parent

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

slotNames() - Returns a list of all the slot names

  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.

slotType() - Given a slot name, determines the type

parents() - Returns a list of all parents

allParents() - Returns a list of all parents in the hierarchy

withAllParents() - Same as above, but includes self in the list

allSlotNames() - Returns a list of all slot names defined for the entire inheritance hierarchy

getSlot() - Returns the requested slot

• 'default' - the extended slot syntax and the slot value are returned
• '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
• '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 "getSlots" method.

getSlots() - Returns a list of all the slots

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

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

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

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

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

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

promoteParents() - This changes the ordering of the parent slots

tiedInterfacePackage() - This specifies the tied interface package

default

This specifies "Class::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 "Class::Prototyped" (unless you do something very naughty and call "Class::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 "Class::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 "new" and "clone" will use the tied interface in use on the existing object/package. When "reflect" is called for the first time on a class package, it will use the tied interface of its first parent class (i.e. $ISA[0]). If that package has not yet had "reflect" 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 "Class::Prototyped" will be used, which should be "default".

defaultAttributes() - get and set default attributes

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

The return value from "defaultAttributes" is a hash with the keys 'FIELD', 'METHOD', and 'PARENT'. The values are either "undef" or hash references consisting of the attributes and their default values. Modify the data structure as desired and pass it back to "defaultAttributes" 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 "defaultAttributes" for "Class::Prototyped" in a sufficiently early "BEGIN" block. Note that making global changes like this is "not" recommended for production modules as it may interfere with other modules that rely upon "Class::Prototyped".

wrap()

unwrap()

delegate()

include() - include a package or external file

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

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

  $foo->include( 'MyModule' );

will search along your @INC path for "MyModule.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 "File.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 "addSlots" will work fine, but if sub "c" is called, it won't find "thisObject()".