From: Stevan Little <stevan.little@iinteractive.com>
Date: Fri, 20 Jan 2006 20:04:34 +0000 (+0000)
Subject: Class-MOP : first hacks at the documentation
X-Git-Tag: 0_02~31
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=94b190693902e4be4f4f180065ce25b982829630;p=gitmo%2FClass-MOP.git

Class-MOP : first hacks at the documentation
---

94b190693902e4be4f4f180065ce25b982829630
diff --git a/Changes b/Changes
new file mode 100644
index 0000000..d7acd8e
--- /dev/null
+++ b/Changes
@@ -0,0 +1 @@
+Changes for Class::MOP
\ No newline at end of file
diff --git a/MANIFEST b/MANIFEST
new file mode 100644
index 0000000..e69de29
diff --git a/README b/README
new file mode 100644
index 0000000..e68d341
--- /dev/null
+++ b/README
@@ -0,0 +1 @@
+READ ME for Class::MOP
\ No newline at end of file
diff --git a/lib/Class/MOP.pm b/lib/Class/MOP.pm
new file mode 100644
index 0000000..d49e67d
--- /dev/null
+++ b/lib/Class/MOP.pm
@@ -0,0 +1,252 @@
+
+package Class::MOP;
+
+use strict;
+use warnings;
+
+our $VERSION = '0.01';
+
+1;
+
+__END__
+
+=pod
+
+=head1 NAME 
+
+Class::MOP - A Meta Object Protocol for Perl 5
+
+=head1 SYNOPSIS
+
+  # ... coming soon
+
+=head1 DESCRIPTON
+
+This module is an attempt to create a meta object protocol for the 
+Perl 5 object system. It makes no attempt to change the behavior or 
+characteristics of the Perl 5 object system, only to create a 
+protocol for it's manipulation and introspection.
+
+That said, it does attempt to create the tools for building a rich 
+set of extensions to the Perl 5 object system. Every attempt has been 
+made for these tools to keep to the spirit of the Perl 5 object 
+system that we all know and love.
+
+=head2 Who is this module for?
+
+This module is specifically for anyone who has ever created or 
+wanted to create a module for the Class:: namespace. The tools which 
+this module will provide will hopefully make it easier to do more 
+complex things with Perl 5 classes by removing such barriers as 
+the need to hack the symbol tables, or understand the fine details 
+of method dispatch. 
+
+=head1 PROTOCOLS
+
+The protocol is divided into 3 main sub-protocols:
+
+=over 4
+
+=item The Class protocol
+
+This provides a means of manipulating and introspecting a Perl 5 
+class. It handles all of symbol table hacking for you, and provides 
+a rich set of methods that go beyond simple package introspection.
+
+=item The Attribute protocol
+
+This provides a consistent represenation for an attribute of a 
+Perl 5 class. Since there are so many ways to create and handle 
+atttributes in Perl 5 OO, this attempts to provide as much of a 
+unified approach as possible, while giving the freedom and 
+flexibility to subclass for specialization.
+
+=item The Method protocol
+
+This provides a means of manipulating and introspecting methods in 
+the Perl 5 object system. As with attributes, there are many ways to 
+approach this topic, so we try to keep it pretty basic, while still 
+making it possible to extend the system in many ways.
+
+=back
+
+What follows is a more detailed documentation on each specific sub 
+protocol.
+
+=head2 The Class protocol
+
+=head3 Creation
+
+These methods handle creating Class objects, which can be used to 
+both create new classes, and analyze pre-existing ones. 
+
+Class::MOP will internally store weakened references to all the 
+instances you create with these methods, so that they do not need 
+to be created any more than nessecary. 
+
+=over 4
+
+=item B<create ($package_name, ?@superclasses, ?%methods, ?%attributes)>
+
+This returns the basic Class object, bringing the specified 
+C<$package_name> into existence and adding any of the 
+C<@superclasses>, C<%methods> and C<%attributes> to it.
+
+=item B<load ($package_name)>
+
+This returns the basic Class object, after examining the given 
+C<$package_name> and attempting to discover it's components (the 
+methods, attributes and superclasses). 
+
+B<NOTE>: This method makes every attempt to ignore subroutines
+which have been exported by other packages into this one.
+
+=item B<initialize ($package_name, @superclasses, %methods, %attributes)>
+
+This creates the actual Class object given a C<$package_nam>, 
+an array of C<@superclasses>, a hash of C<%methods> and a hash 
+of C<%attributes>. This method is used by both C<load> and 
+C<create>.
+
+This method also stores the Class object for you inside Class::MOP.
+
+=back
+
+=head3 Informational 
+
+=over 4
+
+=item C<name>
+
+This is a read-only attribute which returns the package name that 
+the Class is stored in.
+
+=item C<version>
+
+This is a read-only attribute which returns the C<$VERSION> of the 
+package the Class is stored in.
+
+=back
+
+=head3 Inheritance Relationships
+
+=over 4
+
+=item C<superclasses (?@superclasses)>
+
+This is a read-write attribute which represents the superclass 
+relationships of this Class. Basically, it can get and set the 
+C<@ISA> for you.
+
+=item C<class_precendence_list>
+
+This computes the a list of the Class's ancestors in the same order 
+in which method dispatch will be done. 
+
+=back
+
+=head3 Methods
+
+=over 4
+
+=item C<add_method ($method_name, $method)>
+
+This will take a C<$method_name> and CODE reference to that 
+C<$method> and install it into the Class. 
+
+B<NOTE> : This does absolutely nothing special to C<$method> 
+other than use B<Sub::Name> to make sure it is tagged with the 
+correct name, and therefore show up correctly in stack traces and 
+such.
+
+=item C<has_method ($method_name)>
+
+This just provides a simple way to check if the Class implements 
+a specific C<$method_name>. It will I<not> however, attempt to check 
+if the class inherits the method.
+
+=item C<get_method ($method_name)>
+
+This will return a CODE reference of the specified C<$method_name>, 
+or return undef if that method does not exist.
+
+=item C<remove_method ($method_name)>
+
+This will attempt to remove a given C<$method_name> from the Class. 
+It will return the CODE reference that it has removed, and will 
+attempt to use B<Sub::Name> to clear the methods associated name.
+
+=item C<get_method_list>
+
+This will return a list of method names for all I<locally> defined 
+methods. It does B<not> provide a list of all applicable methods, 
+including any inherited ones. If you want a list of all applicable 
+methods, use the C<compute_all_applicable_methods> method.
+
+=item C<compute_all_applicable_methods>
+
+This will return a list of all the methods names this Class will 
+support, taking into account inheritance. The list will be a list of 
+HASH references, each one containing the following information; method 
+name, the name of the class in which the method lives and a CODE reference 
+for the actual method.
+
+=item C<find_methods_by_name ($method_name)>
+
+This will traverse the inheritence hierarchy and locate all methods 
+with a given C<$method_name>. Similar to C<compute_all_applicable_methods>
+it returns a list of HASH references with the following information; 
+method name (which will always be the same as C<$method_name), the name of 
+the class in which the method lives and a CODE reference for the actual method.
+
+=back
+
+=head2 Attributes
+
+It should be noted that since there is no one consistent way to define the 
+attributes of a class in Perl 5. These methods can only work with the 
+information given, and can not easily discover information on their own.
+
+=over 4
+
+=item C<>
+
+=item C<>
+
+=item C<>
+
+=item C<>
+
+=item C<>
+
+=item C<>
+
+=back
+
+=head1 SEE ALSO
+
+=over 4
+
+=item "The Art of the Meta Object Protocol"
+
+=item CLOS
+
+=back
+
+=head1 AUTHOR
+
+Stevan Little E<gt>stevan@iinteractive.comE<lt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2006 by Infinity Interactive, Inc.
+
+L<http://www.iinteractive.com>
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself. 
+
+=cut
+
+
+