=head1 TITLE

Object and Class semantics for Parrot

=head1 VERSION

=head2 CURRENT

    Maintainer: Dan Sugalski
    Class: Internals
    PDD Number: 15
    Version: 1.1
    Status: Developing
    Last Modified: March 11, 2003
    PDD Format: 1
    Language: English

=head2 HISTORY

=over 4

=item Version 1.1

March 11, 2002

=item version 1

None. First version

=back

=head1 CHANGES

=over 4

=item Version 1.1

Removed attributes from the object interface and put them in the
class interface section, where they belong.

=item Version 1.0

None. First version

=back

=head1 ABSTRACT

This PDD describes the semantics of Parrot's object and class
systems. The PDD is divided into two parts, the semantics expressed
to user programs through PMCs, and the default back-end class scheme.

Note that the class system is I<not> the single mandated class
scheme, merely the one designed to express the semantics needed for
perl 6, ruby, and python. Alternate class systems are certainly
possible, and direct compatibility with the system as described here
isn't strictly necessary.

=head1 DESCRIPTION

This PDD lays out two separate things.

The first is the object semantics, as presented to user programs. This
means that code has an object PMC, and wants to do Object Things with
it. Object semantics are reasonably simple, and will be defined in a bit.

The second is class semantics. Class semantics are rather more
complex, and can't really be dealt with in a generic way, such that
all classes are compatible. As such this PDD lays out Parrot's default
class semantics, and it is assumed that languages that need different
semantics will then do whatever they need to, provided that the
objects they create are generically usable.

Please see the glossary for definitions of the various terms.

=head2 Object interfaces

Objects must present the following interface to the outside
world. Note that these are required of PMCs in general, but objects
are presumed to actually do something useful with these things rather
than just (potentially) throwing an exception.

Any PMC that meets these criteria can be considered an object. Objects
do I<not> have to have corresponding classes, though it's a fairly
common occurrence.

=over 4

=item Get and set properties

Strictly speaking, getting and setting properties is a PMC thing
rather than an object thing, as PMCs are all capable of having
properties. Nevertheless, properties are put into the object bag, as
many systems use properties to note object attributes.

Note that methods and properties may share a namespace, depending on
the language backing the PMC. Generally methods override properties,
so doing a get or set of a property on an object that has a method of
the same name will call that method in rvalue or lvalue context,
respectively.

=item Get a property hash

Returns a hash PMC with all the properties and their values in
it. This generally should have no activity associated with it, and be
a plain key/value hash. Usually used for introspective purposes.

=item Call a method

Methods are called by name. The object's method dispatch vtable entry
is responsible for doing the actual method dispatch, in whatever way
it deems necessary.

Note that it is perfectly acceptable, and common, for methods and
properties to share a namespace, with the methods overriding the
properties. That is, you may fetch property "foo", but if there is a
method "foo" as well, the return value will be the return from method
"foo" rather than property "foo". This behaviour is not required, however.

=item Get a method PMC

This returns a method PMC for the named method, which can be called
at a later time. This may return a "no method" PMC which throws an
exception if the object is unable to return a method PMC.

This PMC should be for the I<current> definition of the method. If
the method later changes, this method PMC should not be
affected. (Wrapping the method doesn't count, as wrapping methods and
subs is considered an in-place activity)

=item Check if a PMC can perform a method

Checks, by name, to see if the PMC can perform the method. 

=item Check if a PMC implements an interface

Checks to see if the PMC can implement the interface

=item Check if a PMC is a member or child of a class

Checks to see if the PMC is a member of, or child of, a
particular class.

=back

=head2 Object internals

Parrot's standard object is based around an attribute container,
essentially an array of attributes. Any object tagged with the
C<is_base_object> bit can be assumed to ultimately be derived from
this base object, and thus behave like a base object. If the bit's
not set, it's not safe to assume so.

Note that object access doesn't allow you to alter the object's
structure, just get info and get/set attributes values. Object
structure alteration has to be done via the class either directly or
via the alterations to a parent class which get delegated down.

=over 4

=item Get attribute by slot

Fetch the value for an attribute from the object's attribute catalog

=item Set attribute by slot

Set the value of an object's attribute slot

=item get attribute catalog

Get the catalog of attributes. This is a hash of classes and attribute
offsets for the fixed attributes, and a hash of fully qualified
attribute name and offset pairs. (A fully qualified attribute name is
of the form CLASS::ATTRIBUTE) Generally the class base offset is used
most often, as most attributes are created at compile time for a
class. The fully qualified form is intended mostly for attributes
added to classes at runtime.

=item get class base offset

This gets the base attribute offset for a class. 

=back

=head2 Classes

Default classes are objects of class Class. Like the object
internals, classes aren't required as such by parrot.

Classes all have the following attributes:

=over 4

=item ISA

=back

=head1 IMPLEMENTATION

Note that because this describes the "blessed" parrot object system,
we snag flag bits. Nyah. [Note to self: Remove this when the PDD goes final]


=head2 Flag bits

=over 4

=item is_delegate

If the is_delegate bit is set in the PMC's header, the object is a
delegate of a parent object, and the method call should be made on
the parent instead.

Generally this bit will only be used if the method dispatch vtable
entry doesn't already know whether the PMC it's part of is a delegate
object or not.

The correct behaviour is, when doing a method call on this PMC, to
find its __PARENT property, which has the PMC for the parent PMC, and
dispatch to that instead.

=item is_base_object

If set, the PMC is ultimately derived from Parrot's base object type,
the attribute container class.

=back

=head2 Properties

The following are 'reserved' object properties. In general the
interpreter reserves anything with a leading double-underscore, but
that's a matter for another PDD.

=over 4

=item __PARENT

Object property. The value is the PMC for the parent object, the one
encapsulating this one.

=item __IS

Class property. An array of the immediate superclasses.

=item __GRANDS

Class property. An array of I<all> the super classes, flattened, in
search order.

=item __HAS

Class property. An array of the interfaces this class implements.

=back

=head2 Object Interface

=head2 Object guts

=head2 Classes

=head1 TRANSLATION AND GLOSSARY

Since every object system on the planet shares a common set of terms
but uses them completely differently, this section defines

=head2 Glossary

=over 4

=item Property

A name and value pair attached to a PMC. Properties may be attached to
the PMC in its role as a container or the PMC in its role as a value.

Properties are global to the PMC. That is there can only be one
property named "FOO" attached to a PMC, and it is globally visible to
all inspectors of the PMCs properties. They are I<not> restricted by
class.

Properties are generally assigned at runtime, and a particular
property may or may not exist on a PMC at any particular
time. Properties are not restricted to objects as such, and any PMC
may have a property attached to it.

=item Attribute

An attribute is a slot in an object that contains a value, generally a
PMC. (Containing non-PMCs leads to interesting garbage collection
issues at the moment) Attributes are referenced either
by slot number or by class name/attribute name pairs. (At least
conceptually)

Attributes are set on a class-wide basis, and all the objects of a
class will have the same set of attributes. Generally attributes
aren't added or removed from classes at runtime, as this would require
resizing and moving the elements of the attribute arrays of existing
objects, and potentially recompiling code with fixed attribute offsets
embedded in it. Most OO languages don't allow attribute changes to
existing classes, though parrot's base attribute system does allow
this.

=item Method

In its strictest sense, a method is a chunk of code that you call with
an object in the object slot of the calling conventions.

More generally, a method is some piece of code that you invoke by name
through an object. You call the object's "Invoke a method" vtable
entry, passing in the method name (Assuming we don't just get it from
the sub name register, per calling conventions). The object is then
responsible for doing something with the method being
requested. Presumably it calls the method, though this isn't strictly
required.

=item Delegate

An object that is transparently (to the user) embedded in another
object. Delegate objects are used in those cases where we can't
inherit from a class because the class is from a different object
universe.

As an example, assume you have a class A, which inherits from class
B. The classes are incompatible, so Parrot can't automatically meld B
into A, as it might if they were. When instantiating an object of
class A, Parrot will automatically instantiate an object of class B
and embed it in the object of class A. The object of class B is class
A's delegate--when a method call comes in that A can't handle, that
method call is delegated to B.

=item Parent class

Also called the super-class. The parent class is, in an inheritance
situation, the class being derived from. If A derives from B, B is the
parent class of A.

=item Child class

Also called the sub-class. The child class is, in an inheritance
situation, the class doing the deriving. If A derives from B, A is the
child class.

=back

=head2 Translation

The following list a set of languages, then within each language what
the parrot term translates to.

=over 4

=item Python

=over 4

=item Attribute

A Python attribute maps to a parrot property

=back

=item .NET

=over 4

=item Attribute

What .NET calls an attribute parrot calls a property

=item Property

What .NET calls a property we call an attribute

=back

=item Generic Terminology

=over 4

=item Instance Variable

Instance Variables map to what we call attributes

=back

=back

=head1 ATTACHMENTS

None

=head1 FOOTNOTES

=head1 REFERENCES
