From: Stevan Little Date: Sat, 28 Jan 2006 17:01:35 +0000 (+0000) Subject: Class-MOP = bunch of moving stuff around X-Git-Tag: 0_02~20 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=552e3d24bc4b3f3f524be6f4bed4720485eb6cf2;p=gitmo%2FClass-MOP.git Class-MOP = bunch of moving stuff around --- diff --git a/lib/Class/MOP.pm b/lib/Class/MOP.pm index 2b86f1a..b828d8d 100644 --- a/lib/Class/MOP.pm +++ b/lib/Class/MOP.pm @@ -110,6 +110,8 @@ 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. +See L for more details. + =item The Attribute protocol This provides a consistent represenation for an attribute of a @@ -118,6 +120,8 @@ 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. +See L for more details. + =item The Method protocol This provides a means of manipulating and introspecting methods in @@ -125,338 +129,44 @@ 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 Class construction - -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 ?@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<$package_version>, C<@superclasses>, C<%methods> and C<%attributes> -to it. - -=item B - -This initializes a Class object for a given a C<$package_name>. - -=back - -=head3 Instance construction - -=over 4 - -=item B - -This will construct and instance using the C<$canidate> as storage -(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 -found in the attribute meta-object. - -=back - -=head3 Informational - -=over 4 - -=item B - -This is a read-only attribute which returns the package name that -the Class is stored in. - -=item B - -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 B - -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 B - -This computes the a list of the Class's ancestors in the same order -in which method dispatch will be done. +See L for more details. =back -=head3 Methods - -=over 4 - -=item B - -This will take a C<$method_name> and CODE reference to that -C<$method> and install it into the Class. - -B : This does absolutely nothing special to C<$method> -other than use B to make sure it is tagged with the -correct name, and therefore show up correctly in stack traces and -such. - -=item B - -This just provides a simple way to check if the Class implements -a specific C<$method_name>. It will I however, attempt to check -if the class inherits the method. - -This will correctly handle functions defined outside of the package -that use a fully qualified name (C). - -This will correctly handle functions renamed with B and -installed using the symbol tables. However, if you are naming the -subroutine outside of the package scope, you must use the fully -qualified name, including the package name, for C to -correctly identify it. - -This will attempt to correctly ignore functions imported from other -packages using B. It breaks down if the function imported -is an C<__ANON__> sub (such as with C), which very well -may be a valid method being applied to the class. - -In short, this method cannot always be trusted to determine if the -C<$method_name> is actually a method. However, it will DWIM about -90% of the time, so it's a small trade off IMO. - -=item B - -This will return a CODE reference of the specified C<$method_name>, -or return undef if that method does not exist. - -=item B - -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 to clear the methods associated name. - -=item B - -This will return a list of method names for all I defined -methods. It does B provide a list of all applicable methods, -including any inherited ones. If you want a list of all applicable -methods, use the C method. - -=item B - -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 B - -This will traverse the inheritence hierarchy and locate all methods -with a given C<$method_name>. Similar to -C 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. - -The list of methods produced is a distinct list, meaning there are no -duplicates in it. This is especially useful for things like object -initialization and destruction where you only want the method called -once, and in the correct order. - -=back - -=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 -the information given, and can not easily discover information on -their own. - -=over 4 - -=item B - -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 above). -More details about the attribute meta-objects can be found in the -L section of this document. - -=item B - -Checks to see if this Class has an attribute by the name of -C<$attribute_name> and returns a boolean. - -=item B - -Returns the attribute meta-object associated with C<$attribute_name>, -if none is found, it will return undef. - -=item B - -This will remove the attribute meta-object stored at -C<$attribute_name>, then return the removed attribute meta-object. - -B Removing an attribute will only affect future instances of -the class, it will not make any attempt to remove the attribute from -any existing instances of the class. - -=item B - -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 method. - -=item B - -This will traverse the inheritance heirachy and return a list of HASH -references for all the applicable attributes for this class. The HASH -references will contain the following information; the attribute name, -the class which the attribute is associated with and the actual -attribute meta-object - -=item B - -This will communicate with all of the classes attributes to create -and install the appropriate accessors. (see L -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 - - 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 +=head1 SEE ALSO -=head3 Informational +=head2 Books =over 4 -=item B - -=item B - -=item B - -=item B - -=item B +=item "The Art of the Meta Object Protocol" -=item B +=item "Advances in Object-Oriented Metalevel Architecture and Reflection" =back -=head3 Informational predicates +=head2 Prior Art =over 4 -=item B - -Returns true if this attribute uses a get/set accessor, and false -otherwise - -=item B - -Returns true if this attribute has a reader, and false otherwise - -=item B - -Returns true if this attribute has a writer, and false otherwise - -=item B - -Returns true if this attribute has a class intialization argument, and -false otherwise - -=item B - -Returns true if this attribute has a default value, and false -otherwise. - -=back - -=head3 Attribute Accessor generation +=item The Perl 6 MetaModel work =over 4 -=item B +=item L -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 method above. +=item L =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 - -=item "The Art of the Meta Object Protocol" - -=item "Advances in Object-Oriented Metalevel Architecture and Reflection" - =back =head1 AUTHOR Stevan Little Estevan@iinteractive.comE +Rob Kinyon Erob@iinteractive.comE + =head1 COPYRIGHT AND LICENSE Copyright 2006 by Infinity Interactive, Inc. diff --git a/lib/Class/MOP/Attribute.pm b/lib/Class/MOP/Attribute.pm index 491e1c2..3ed1f23 100644 --- a/lib/Class/MOP/Attribute.pm +++ b/lib/Class/MOP/Attribute.pm @@ -75,6 +75,83 @@ Class::MOP::Attribute - Attribute Meta Object =head1 DESCRIPTION +The Attribute 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. + +=head1 METHODS + +=head2 Creation + +=over 4 + +=item B + +=back + +=head2 Informational + +=over 4 + +=item B + +=item B + +=item B + +=item B + +=item B + +=item B + +=back + +=head2 Informational predicates + +=over 4 + +=item B + +Returns true if this attribute uses a get/set accessor, and false +otherwise + +=item B + +Returns true if this attribute has a reader, and false otherwise + +=item B + +Returns true if this attribute has a writer, and false otherwise + +=item B + +Returns true if this attribute has a class intialization argument, and +false otherwise + +=item B + +Returns true if this attribute has a default value, and false +otherwise. + +=back + +=head2 Attribute Accessor generation + +=over 4 + +=item B + +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 method above. + +=back + =head1 AUTHOR Stevan Little Estevan@iinteractive.comE diff --git a/lib/Class/MOP/Class.pm b/lib/Class/MOP/Class.pm index 2f600dc..a2bc46d 100644 --- a/lib/Class/MOP/Class.pm +++ b/lib/Class/MOP/Class.pm @@ -230,6 +230,16 @@ sub find_all_methods_by_name { } +## Attributes + +sub has_attribute {} +sub get_attribute {} +sub add_attribute {} +sub remove_attribute {} +sub get_attribute_list {} +sub compute_all_applicable_attributes {} +sub create_all_accessors {} + 1; __END__ @@ -244,6 +254,222 @@ Class::MOP::Class - Class Meta Object =head1 DESCRIPTION +=head1 METHODS + +=head2 Class construction + +These methods handle creating Class objects, which can be used to +both create new classes, and analyze pre-existing ones. + +This module will internally store references to all the instances +you create with these methods, so that they do not need to be +created any more than nessecary. Basically, they are singletons. + +=over 4 + +=item B ?@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<$package_version>, C<@superclasses>, C<%methods> and C<%attributes> +to it. + +=item B + +This initializes a Class object for a given a C<$package_name>. + +=back + +=head2 Instance construction + +=over 4 + +=item B + +This will construct and instance using the C<$canidate> as storage +(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 +found in the attribute meta-object. + +=back + +=head2 Informational + +=over 4 + +=item B + +This is a read-only attribute which returns the package name that +the Class is stored in. + +=item B + +This is a read-only attribute which returns the C<$VERSION> of the +package the Class is stored in. + +=back + +=head2 Inheritance Relationships + +=over 4 + +=item B + +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 B + +This computes the a list of the Class's ancestors in the same order +in which method dispatch will be done. + +=back + +=head2 Methods + +=over 4 + +=item B + +This will take a C<$method_name> and CODE reference to that +C<$method> and install it into the Class. + +B : This does absolutely nothing special to C<$method> +other than use B to make sure it is tagged with the +correct name, and therefore show up correctly in stack traces and +such. + +=item B + +This just provides a simple way to check if the Class implements +a specific C<$method_name>. It will I however, attempt to check +if the class inherits the method. + +This will correctly handle functions defined outside of the package +that use a fully qualified name (C). + +This will correctly handle functions renamed with B and +installed using the symbol tables. However, if you are naming the +subroutine outside of the package scope, you must use the fully +qualified name, including the package name, for C to +correctly identify it. + +This will attempt to correctly ignore functions imported from other +packages using B. It breaks down if the function imported +is an C<__ANON__> sub (such as with C), which very well +may be a valid method being applied to the class. + +In short, this method cannot always be trusted to determine if the +C<$method_name> is actually a method. However, it will DWIM about +90% of the time, so it's a small trade off IMO. + +=item B + +This will return a CODE reference of the specified C<$method_name>, +or return undef if that method does not exist. + +=item B + +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 to clear the methods associated name. + +=item B + +This will return a list of method names for all I defined +methods. It does B provide a list of all applicable methods, +including any inherited ones. If you want a list of all applicable +methods, use the C method. + +=item B + +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 B + +This will traverse the inheritence hierarchy and locate all methods +with a given C<$method_name>. Similar to +C 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. + +The list of methods produced is a distinct list, meaning there are no +duplicates in it. This is especially useful for things like object +initialization and destruction where you only want the method called +once, and in the correct order. + +=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 B + +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 above). +More details about the attribute meta-objects can be found in the +L section of this document. + +=item B + +Checks to see if this Class has an attribute by the name of +C<$attribute_name> and returns a boolean. + +=item B + +Returns the attribute meta-object associated with C<$attribute_name>, +if none is found, it will return undef. + +=item B + +This will remove the attribute meta-object stored at +C<$attribute_name>, then return the removed attribute meta-object. + +B Removing an attribute will only affect future instances of +the class, it will not make any attempt to remove the attribute from +any existing instances of the class. + +=item B + +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 method. + +=item B + +This will traverse the inheritance heirachy and return a list of HASH +references for all the applicable attributes for this class. The HASH +references will contain the following information; the attribute name, +the class which the attribute is associated with and the actual +attribute meta-object + +=item B + +This will communicate with all of the classes attributes to create +and install the appropriate accessors. (see L +below for more details). + +=back + =head1 AUTHOR Stevan Little Estevan@iinteractive.comE diff --git a/lib/Class/MOP/Method.pm b/lib/Class/MOP/Method.pm index a15bd0f..56772f7 100644 --- a/lib/Class/MOP/Method.pm +++ b/lib/Class/MOP/Method.pm @@ -20,6 +20,11 @@ Class::MOP::Method - Method Meta Object =head1 DESCRIPTION +The Method 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 AUTHOR Stevan Little Estevan@iinteractive.comE diff --git a/t/010_self_introspection.t b/t/010_self_introspection.t index 03037d5..f73e89d 100644 --- a/t/010_self_introspection.t +++ b/t/010_self_introspection.t @@ -10,16 +10,21 @@ BEGIN { use_ok('Class::MOP::Class'); } - my $meta = Class::MOP::Class->initialize('Class::MOP::Class'); isa_ok($meta, 'Class::MOP::Class'); foreach my $method_name (qw( initialize create + name version + superclasses class_precedence_list + has_method get_method add_method remove_method get_method_list compute_all_applicable_methods find_all_methods_by_name + + has_attribute get_attribute add_attribute remove_attribute + get_attribute_list compute_all_applicable_attributes create_all_accessors )) { ok($meta->has_method($method_name), '... Class::MOP::Class->has_method(' . $method_name . ')'); { diff --git a/t/pod.t b/t/pod.t new file mode 100644 index 0000000..4ae1af3 --- /dev/null +++ b/t/pod.t @@ -0,0 +1,11 @@ +#!/usr/bin/perl + +use strict; +use warnings; + +use Test::More; + +eval "use Test::Pod 1.14"; +plan skip_all => "Test::Pod 1.14 required for testing POD" if $@; + +all_pod_files_ok(); diff --git a/t/pod_coverage.t b/t/pod_coverage.t new file mode 100644 index 0000000..7569358 --- /dev/null +++ b/t/pod_coverage.t @@ -0,0 +1,11 @@ +#!/usr/bin/perl + +use strict; +use warnings; + +use Test::More; + +eval "use Test::Pod::Coverage 1.04"; +plan skip_all => "Test::Pod::Coverage 1.04 required for testing POD coverage" if $@; + +all_pod_coverage_ok();