use strict;
use warnings;
+use Scalar::Util 'blessed';
+
our $VERSION = '0.01';
+my %METAS;
+sub UNIVERSAL::meta {
+ my $class = blessed($_[0]) || $_[0];
+ $METAS{$class} ||= Class::MOP::Class->initialize($class)
+}
+
1;
__END__
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.
+protocol for its 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
=over 4
-=item B<create ($package_name, ?@superclasses, ?%methods, ?%attributes)>
+=item B<create ($package_name, ?$package_version,
+ superclasses => ?@superclasses,
+ methods => ?%methods,
+ attributes => ?%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.
+C<$package_version>, C<@superclasses>, C<%methods> and C<%attributes>
+to it.
-=item B<load ($package_name)>
+=item B<initialize ($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_name>,
-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 initializes a Class object for a given a C<$package_name>.
=back
=over 4
-=item <create_instance ($canidate, %params)>
+=item B<construct_instance ($canidate, %params)>
This will construct and instance using the C<$canidate> as storage
-(currently on HASH references are supported). This will collect all
+(currently only HASH references are supported). This will collect all
the applicable attribute meta-objects and layout out the fields in the
C<$canidate>, it will then initialize them using either use the
corresponding key in C<%params> or any default value or initializer
=over 4
-=item C<name>
+=item B<name>
This is a read-only attribute which returns the package name that
the Class is stored in.
-=item C<version>
+=item B<version>
This is a read-only attribute which returns the C<$VERSION> of the
package the Class is stored in.
=over 4
-=item C<superclasses (?@superclasses)>
+=item B<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>
+=item B<class_precedence_list>
This computes the a list of the Class's ancestors in the same order
in which method dispatch will be done.
=head3 Methods
+B<NOTE>: These methods makes every attempt to ignore subroutines
+which have been exported by other packages into this one.
+
=over 4
-=item C<add_method ($method_name, $method)>
+=item B<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.
correct name, and therefore show up correctly in stack traces and
such.
-=item C<has_method ($method_name)>
+=item B<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)>
+=item B<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)>
+=item B<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>
+=item B<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>
+=item B<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
name, the name of the class in which the method lives and a CODE
reference for the actual method.
-=item C<find_all_methods_by_name ($method_name)>
+=item B<find_all_methods_by_name ($method_name)>
This will traverse the inheritence hierarchy and locate all methods
with a given C<$method_name>. Similar to
=back
-=head2 Attributes
+=head3 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
=over 4
-=item C<add_attribute ($attribute_name, $attribute_meta_object)>
+=item B<add_attribute ($attribute_name, $attribute_meta_object)>
This stores a C<$attribute_meta_object> in the Class object and
associates it with the C<$attribute_name>. Unlike methods, attributes
within the MOP are stored as meta-information only. They will be used
-later to construct instances from (see C<create_instance> above). More
-details about the attribute meta-objects can be found in the L<The
-Attribute protocol> section of this document.
+later to construct instances from (see C<construct_instance> above).
+More details about the attribute meta-objects can be found in the
+L<The Attribute protocol> section of this document.
-=item C<has_attribute ($attribute_name)>
+=item B<has_attribute ($attribute_name)>
Checks to see if this Class has an attribute by the name of
C<$attribute_name> and returns a boolean.
-=item C<get_attribute ($attribute_name)>
+=item B<get_attribute ($attribute_name)>
Returns the attribute meta-object associated with C<$attribute_name>,
if none is found, it will return undef.
-=item C<remove_attribute ($attribute_name)>
+=item B<remove_attribute ($attribute_name)>
This will remove the attribute meta-object stored at
C<$attribute_name>, then return the removed attribute meta-object.
the class, it will not make any attempt to remove the attribute from
any existing instances of the class.
-=item C<get_attribute_list>
+=item B<get_attribute_list>
This returns a list of attribute names which are defined in the local
class. If you want a list of all applicable attributes for a class,
use the C<compute_all_applicable_attributes> method.
-=item C<compute_all_applicable_attributes>
+=item B<compute_all_applicable_attributes>
This will traverse the inheritance heirachy and return a list of HASH
references for all the applicable attributes for this class. The HASH
the class which the attribute is associated with and the actual
attribute meta-object
+=item B<create_all_accessors>
+
+This will communicate with all of the classes attributes to create
+and install the appropriate accessors. (see L<The Attribute Protocol>
+below for more details).
+
+=back
+
+=head2 The Attribute Protocol
+
+This protocol is almost entirely an invention of this module. This is
+because Perl 5 does not have consistent notion of what is an attribute
+of a class. There are so many ways in which this is done, and very few
+(if any) are discoverable by this module.
+
+So, all that said, this module attempts to inject some order into this
+chaos, by introducing a more consistent approach.
+
+=head3 Creation
+
+=over 4
+
+=item B<new ($name, %accessor_description, $class_initialization_arg, $default_value)>
+
+ Class::MOP::Attribute->new('$foo' => (
+ accessor => 'foo', # dual purpose get/set accessor
+ init_arg => '-foo', # class->new will look for a -foo key
+ default => 'BAR IS BAZ!' # if no -foo key is provided, use this
+ ));
+
+ Class::MOP::Attribute->new('$.bar' => (
+ reader => 'bar', # getter
+ writer => 'set_bar', # setter
+ init_arg => '-bar', # class->new will look for a -bar key
+ # no default value means it is undef
+ ));
+
+=back
+
+=head3 Informational
+
+=over 4
+
+=item B<name>
+
+=item B<accessor>
+
+=item B<reader>
+
+=item B<writer>
+
+=item B<init_arg>
+
+=item B<default>
+
=back
+=head3 Informational predicates
+
+=over 4
+
+=item B<has_accessor>
+
+Returns true if this attribute uses a get/set accessor, and false
+otherwise
+
+=item B<has_reader>
+
+Returns true if this attribute has a reader, and false otherwise
+
+=item B<has_writer>
+
+Returns true if this attribute has a writer, and false otherwise
+
+=item B<has_init_arg>
+
+Returns true if this attribute has a class intialization argument, and
+false otherwise
+
+=item B<has_default>
+
+Returns true if this attribute has a default value, and false
+otherwise.
+
+=back
+
+=head3 Attribute Accessor generation
+
+=over 4
+
+=item B<generate_accessors>
+
+This allows the attribute to generate code for it's own accessor
+methods. This is mostly part of an internal protocol between the class
+and it's own attributes, see the C<create_all_accessors> method above.
+
+=back
+
+=head2 The Method Protocol
+
+This protocol is very small, since methods in Perl 5 are just
+subroutines within the particular package. Basically all we do is to
+bless the subroutine and provide some very simple introspection
+methods for it.
+
=head1 SEE ALSO
=over 4
projects / gitmo/Class-MOP.git / blobdiff