NAME
    "Class::Prototyped" - Fast prototype-based OO programming in Perl

SYNOPSIS
        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;

DESCRIPTION
    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 "reflect" on an object or class that
    inherits from "Class::Prototyped".

  Installation instructions
    This module requires "Module::Build 0.24" to use the automated
    installation procedures. With "Module::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 ".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).

WHEN TO USE THIS MODULE
    When I reach for "Class::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
    "Class::Prototyped" would be of use. If you find yourself avoiding the
    problem by passing anonymous subroutines as parameters to the "new"
    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.

CONCEPTS
  Slots
    "Class::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.

  Reflecting
    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 "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 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 - "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
    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 "Class::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 @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
    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
    "MyClass" class? Assuming that the "MyClass" inherits from
    "Class::Prototyped" or that you have specified ":REFLECT" on the "use
    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
    "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
    Adding parent slots is no different than adding normal slots - the
    naming scheme takes care of differentiating.

    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
    In "Class::Prototyped", you do operator overloading by adding slots with
    the right name. First, when you do the "use" on "Class::Prototyped",
    make sure to pass in ":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 "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 special parent slot "class*" is used to indicate object class. When
    you create "Class::Prototyped" objects by calling
    "Class::Prototyped->new()", the "class*" slot is not set. If, however,
    you create objects by calling "new" on a class or object that inherits
    from "Class::Prototyped", the slot "class*" points to the package name
    if "new" was called on a named class, or the object if "new" was called
    on an object.

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

        $foo->reflect->class;

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

    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".

PERFORMANCE NOTES
    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
    "Class::Prototyped". However, it would be very inefficient if every
    record that got read from the database was stored in a
    "Class::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 "Class::Prototyped" to
    those portions of the code where behavior is mutable from outside of the
    module. See the documentation for the "new" method of
    "Class::Prototyped" for more information about choking off
    "Class::Prototyped" behavior.

    There are a number of performance hits when using "Class::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 "perf"
    directory were designed for benchmarking some of this material.

  Class Instantiation
    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" "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
    There is no need to even compare here. Blessing a hash into a class
    takes less than 2 usec. Creating a new "Class::Prototyped" object takes
    at least 60 or 70 times longer. The trick is to avoid creating
    unnecessary "Class::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 "new" method for "Class::Prototyped"
    demonstrates how to ensure that those state objects are created as
    normal Perl objects.

  Method Calls
    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 "Class::Prototyped". The exception to
    this is if "filter" slot attributes have been used, including
    "wantarray", "superable", and "profile". 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)

  Instance Variable Access
    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.

IMPORT OPTIONS
    ":OVERLOAD"
        This configures the support in "Class::Prototyped" for using
        operator overloading.

    ":REFLECT"
        This defines "UNIVERSAL::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.

    ":EZACCESS"
        This adds the methods "addSlot", "addSlots", "deleteSlot",
        "deleteSlots", "getSlot", "getSlots", and "super" to
        "Class::Prototyped".

        This lets you write:

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

        instead of having to write:

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

        The other methods in "Class::Prototyped::Mirror" should be accessed
        through a mirror (otherwise you'll end up with way too much name
        space pollution for your objects:).

        Note that it is bad form for published modules to use ":EZACCESS" as
        you are polluting everyone else's namespace as well. If you really
        want ":EZACCESS" for code you plan to publish, contact the
        maintainer and we'll see what we can about creating a variant of
        ":EZACCESS" that adds the shortcut methods to a single class. Note
        that using ":EZACCESS" to do "$obj->addSlot()" is actually slower
        than doing "$obj->reflect->addSlot()".

    ":SUPER_FAST"
        Switches over to the fast version of "super" that doesn't check to
        see whether slots that use inherited calls were defined as
        superable.

    ":NEW_MAIN"
        Creates a "new" function in "main::" that creates new
        "Class::Prototyped" objects. Thus, you can write code like:

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

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

    ":TIED_INTERFACE"
        This is no longer supported. Sorry for the very short notice - if
        you have a specific need, please let me know and I will discuss your
        needs with you and determine whether they can be addressed in a
        manner that doesn't require you to rewrite your code, but still
        allows others to make use of less global control over the tied
        interfaces used. See
        "Class::Prototyped::Mirror::tiedInterfacePackage" for the preferred
        way of doing this.

"Class::Prototyped" Methods
  new() - Construct a new "Class::Prototyped" object.
    A new object is created. If this is called on a class or object that
    inherits from "Class::Prototyped", and "class*" is not being passed as a
    slot in the argument list, the slot "class*" will be the first element
    in the inheritance list.

    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.
    Just like "new", 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 "class*" described above for "new" apply to
    "newPackage" (in fact, "new" calls "newPackage").

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

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

      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()
    Just like "clone", 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.

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

    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
    The structure of an object is modified by using a mirror. This is the
    equivalent of calling:

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

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

    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.

"Class::Prototyped::Mirror" Methods
    These are the methods you can call on the mirror returned from a
    "reflect" call. If you specify ":EZACCESS" in the "use
    Class::Prototyped" line, "addSlot", "addSlots", "deleteSlot",
    "deleteSlots", "getSlot", "getSlots", and "super" will be callable on
    "Class::Prototyped" objects as well.

  new() - Creates a new "Class::Prototyped::Mirror" object
    Normally called via the "reflect" method, this can be called directly to
    avoid using the ":REFLECT" import option for reflecting on non
    "Class::Prototyped" based classes.

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

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

    "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

        "constant" ("implementor")
            When true, this defines the field slot as constant, disabling
            the ability to modify it using the "$object->field($newValue)"
            syntax. The value may still be modified using the hash syntax
            (i.e. "$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 "Data::Dumper" much easier than if you use a "METHOD"
            slot to return the constant, since code objects are opaque).

        "autoload" ("filter", rank 50)
            The passed value for the "FIELD" 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 "Class::Prototyped"
            objects!

        "profile" ("filter", rank 80)
            If "profile" is set to 1, increments
            "$Class::Prototyped::Mirror::PROFILE::counts->{$package}->{$slot
            Name}" everytime the slot is accessed. If "profile" is set to 2,
            increments
            "$Class::Prototyped::Mirror::PROFILE::counts->{$package}->{$slot
            Name}->{$caller}" everytime the slot is accessed, where $caller
            is "$file ($line)".

        "wantarray" ("filter", rank 90)
            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.

        "description" ("advisory")
            Can be used to specify a description. No real support for this
            yet beyond that!

    "METHOD" Slots

        "superable" ("filter", rank 10)
            When true, this enables the "$self->reflect->super( . . . )"
            calls for this method slot.

        "profile" ("filter", rank 90)
            See "FIELD" slots for explanation.

        "overload" ("advisory")
            Set automatically for methods that implement operator
            overloading.

        "description" ("advisory")
            See "FIELD" slots for explanation.

    "PARENT" Slots

        "promote" ("advisory")
            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 "getSlot".

        "description" ("advisory")
            See "FIELD" slots for explanation.

  deleteSlot() - An alias for deleteSlots
  deleteSlots() - Delete one or more of the receiver's slots by name
    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

  super() - Call a method defined in a parent
    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);

  slotNames() - Returns a list of all the slot names
    This is passed an optional type parameter. If specified, it should be
    one of 'FIELD', 'METHOD', or '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.

  slotType() - Given a slot name, determines the type
    This returns 'FIELD', 'METHOD', or 'PARENT'. It croaks if the slot is
    not defined for that object.

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

  allParents() - Returns a list of all parents in the hierarchy
    Returns a list of all parent objects (or package names) in the object's
    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
    Note that this will return duplicate slot names if inherited slots are
    obscured.

  getSlot() - Returns the requested slot
    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:

    *   '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
    This returns a list of extended syntax slot specifiers and their values
    ready for sending to "addSlots". It takes first the optional parameter
    passed to "slotNames" which specifies the type of slot ('FIELD',
    'METHOD', 'PARENT', or "undef") and then the optional parameter passed
    to "getSlot", which specifies the format for the return value. If the
    latter is 'simple', the returned values can be passed to "addSlots", but
    any non-default slot attributes (i.e. "superable" or "constant") will be
    lost. If the latter is 'rotated', the returned values are completely
    inappropriate for passing to "addSlots". Both 'simple' and 'rotated' are
    appropriate for assigning the return values into a hash.

    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
    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.

  tiedInterfacePackage() - This specifies the tied interface package
    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 "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
    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 "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()
    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.

  include() - include a package or external file
    You can "require" an arbitrary file in the namespace of an object or
    class without adding to the parents using "include()" :

      $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()".

AUTHOR
    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.

LICENSE
    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.

SEE ALSO
    Class::SelfMethods

    Class::Object

    Class::Classless