=pod

=head1 NAME

Synopsis 12.5 - The Perl 6 Meta Object Protocol

=head1 SYNOPSIS

This is an unofficial amendment to Synopsis 12, which describes the design
and implementation of the Perl 6 Meta Object Protocol. 

It expands upon the section entitled "Introspection" in Synopsis 12, which only 
describes the meta-"data" available from the metaclasses. In this document I will
describe how that meta-data can be manipulated as well.

NOTE: 
For a quick overview of the MetaModel itself please see the F<10_000_ft-view.pod>
in this same directory.

=head1 What is a Meta Object Protocol?

A meta object protocol is basically an API for the elements of the meta-level classes
and objects which are exposed to user level code. Basically this describes all the things
you can do with the object returned by C<$obj.meta>.

=head2 The Perl 6 Meta Object Protocol.

The following protocol defines the behavior of I<all> classes in the Perl 6 object model. 
This is not meant to be documentation for one particular class, but for classes in general.

=head3 Basic Introspection

These methods are very basic introspection methods, some of which are described already in 
Synopsis 12.

=over 4

=item C<name (Str ?$name) returns Str>

This is a read-write accessor method which determines the name of the class it is associated 
with. Its default value is C<undef>, which is essentially an anonymous class.

NOTE: Changing the name of a class at runtime is possible, however it is likely that doing so
could have many unforseen consequences, and so it is generally discouraged.

=item C<version (T ?$version) returns T>

Also a read-write accessor method, this is the version number of the class it is associated 
with. Its default value is C<0.0.0>.

=begin NOTE

I am not sure what "Type" a version number would be. 

=end

=item C<authority (Str ?$authority) returns Str>

This is also a read-write accessor method; it is the certifying authority for the class 
it is associated with. This will likely be a string in one of the following formats:

  cpan:JRANDOM
  email:jrandom@cpan.org
  url:http://www.random-inc.com/~jrandom/
  
=item C<identifier returns Str>
 
This is a read-only method which takes the C<name>, C<version> and C<identifier> and concatenates
them into a single string separated by '-' characters. This is the format found in the class 
defintions:

  class Foo-0.0.5-cpan:BARBAZ { ... }

=back

=head3 Superclasses and MROs

The following are methods which can be used to determine superclass relationships as well as the 
MRO (Method Resolution Order) of a given class. 

=over 4 

=item C<superclasses (Array of Class ?@superclasses) returns Array of Class>

This is a read-write accessor for a class's superclass list. Passing a C<@superclasses> list will 
overwrite the list, it will not attempt to push or shift elements onto the list.

Changing the superclass list will result in a recalculation of the classes MRO, and possible other
"cache clearing" actions as yet to be determined.

=item C<is_a (Class $class) returns Bool>

This is a predicate function which is used to determine of one Class instance inherits from another.
It is similar in function to C<isa>, however, it requires a Class instance, and not a Str for it's 
argument.

=item C<MRO returns Array of Class>

=item C<dispatcher (+$preorder, +$breadth, +$descendant, +$ascendant) returns Dispatcher>

The named arguments here are used as a means of determining the order in which the dispatcher will 
dispense the class precendence list. 

=begin NOTE

I am not sure the return value should be of type Dispatcher or not. Maybe it should just be of 
type Code. This will need some thought.

=end

=back

=head3 Methods, Submethods, etc.

Let me first begin this by saying that there are a number of assumptions made in the MetaModel design 
regarding methods, they are as follows:

=over 4

=item *

There will be a C<method> primative, and that it will properly bind and unbind the C<$?SELF> and 
C<$?CLASS> values.

=item *

There will be a C<multi method> primative, and it will do all the same things as C<method> and it will 
be possible to store all variants of the multi-method into a single slot in the class.

=item *

There will be a C<submethod> primative, and that it will properly perform the following check prior to 
executing the underlying body of code:

  next METHOD unless $?SELF.class =:= $?CLASS;

The C<submethod> primative will also properly bind and unbind the C<$?SELF> and C<$?CLASS> values.

=item *

There is a C<private method> primative which makes the assumption that the value in C<$?CLASS> will be 
the same as the class the method is associated with. The result of this is that the private method can
only be called from within that class. It is also important to note that when dispatching on a private
method the value in $?CLASS should be used to find the methods in. This allows for subclasses to be
the invocant, while still retaining the privacy of the method during internal calls.

=back

=over 4

=item C<has_method (Str $label) returns Bool>

=item C<get_method (Str $label) returns Method>

=item C<remove_method (Str $label) returns Void>

=item C<add_method (Str $label, Method $method) returns Void>

This method can be used to associate a C<$method> with a class. It's usage is simple enough:

  Foo.meta.add_method('bar', method (Foo $self:) { ... });

=item C<get_method_list returns Array of Str>

This method returns a list of the method labels for a given class.

=back

=head1 SEE ALSO

=head2 Books

=over 4

=item The Art of the Meta Object Protocol

An excellent book, I cannot recommend it highly enough.

=back

=head2 Research Papers

=over 4

=item A Core Calculus for MetaClasses

L<http://research.sun.com/projects/plrg/core-calculus.pdf>

=item Any of these papers on Traits

L<http://www.iam.unibe.ch/~scg/Research/Traits/>

(Note: Traits are what inspired the Perl 6 concept of Roles)

=back 

=head2 Other Perl Modules

=over 4

=item L<Class::Role>, L<Class::Roles> & L<Class::Trait>

The first two are early attempts to prototype role behavior, and the last is an
implementation of the Trait system based on the paper which originally inspired
Roles.

=item L<MiniMetaModel.pl>

This is found in this directory, and is a very minimal and readable Meta-Model 
implementation. The current 2.0 implementation of the metamodel is based on this.

=back

=head2 Other Languages

=over 4

=item Smalltalk

I prefer the Brown book by Adele Goldberg and David Robinson, but any book that
talks about the Smalltalk metaclasses is a good reference.

=item CLOS

The Common Lisp Object System has a very nice metamodel, and there's plenty of
reference on it. In particular there is a small implementation of CLOS called
TinyCLOS which is very readable (if you know enough Scheme, that is :).

=item Objective C

There is a good amount of documentation about the Objective C Runtime which
explains the class and object structures. Here are some relevant links:

=over 4

=item L<http://developer.apple.com/documentation/Cocoa/Reference/ObjCRuntimeRef/index.html>

=item ... add more links

=back

=item Ruby

I found some interesting Object Model discussions regarding Ruby here:

L<http://lazaridis.com/case/lang/ruby/>

=back

=head1 AUTHORS

Stevan Little E<lt>stevan@iinteractive.comE<gt>

=cut