From: Stevan Little Date: Thu, 2 Feb 2006 21:52:53 +0000 (+0000) Subject: preping for the 0.01 release X-Git-Tag: 0_02~4 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=a2e85e6c752e6dd43555a7eb5623696a86afa858;p=gitmo%2FClass-MOP.git preping for the 0.01 release --- diff --git a/Build.PL b/Build.PL deleted file mode 100644 index 3315541..0000000 --- a/Build.PL +++ /dev/null @@ -1,31 +0,0 @@ -use Module::Build; - -use 5.6.0; - -use strict; -use warnings; - -my $build = Module::Build->new( - module_name => 'Class::MOP', - license => 'perl', - requires => { - 'perl' => '5.6.0', - 'Scalar::Util' => '1.17', - 'Sub::Name' => '0.02', - 'Carp' => '0.01', - 'B' => '0', - }, - optional => { - }, - build_requires => { - 'Test::More' => '0.47', - 'Test::Exception' => '0.21', - }, - create_makefile_pl => 'traditional', - recursive_test_files => 1, - add_to_cleanup => [ - 'META.yml', '*.bak', '*.gz', 'Makefile.PL', - ], -); - -$build->create_build_script; diff --git a/Changes b/Changes index 799c905..9be3909 100644 --- a/Changes +++ b/Changes @@ -1,4 +1,4 @@ Revision history for Perl extension Class-MOP. -0.01 +0.01 Thurs Feb. 2, 2006 - Initial release \ No newline at end of file diff --git a/MANIFEST b/MANIFEST index e69de29..c2bf67a 100644 --- a/MANIFEST +++ b/MANIFEST @@ -0,0 +1,27 @@ +Changes +Makefile.PL +MANIFEST +README +lib/Class/MOP.pm +lib/Class/MOP/Attribute.pm +lib/Class/MOP/Class.pm +lib/Class/MOP/Method.pm +t/000_load.t +t/001_basic.t +t/002_class_precedence_list.t +t/003_methods.t +t/004_advanced_methods.t +t/005_attributes.t +t/010_self_introspection.t +t/011_create_class.t +t/012_package_variables.t +t/020_attribute.t +t/030_method.t +t/100_BinaryTree_test.t +t/101_CountingClass_test.t +t/102_InsideOutClass_test.t +t/pod.t +t/pod_coverage.t +t/lib/BinaryTree.pm +t/lib/CountingClass.pm +t/lib/InsideOutClass.pm diff --git a/MANIFEST.SKIP b/MANIFEST.SKIP deleted file mode 100644 index 9b342ce..0000000 --- a/MANIFEST.SKIP +++ /dev/null @@ -1,17 +0,0 @@ -^_build -^Build$ -^blib -~$ -\.bak$ -^MANIFEST\.SKIP$ -CVS -\.svn -cover_db -\..*\.sw.?$ -^Makefile$ -^pm_to_blib$ -^MakeMaker-\d -^blibdirs$ -\.old$ -^#.*#$ -^\.# \ No newline at end of file diff --git a/Makefile.PL b/Makefile.PL new file mode 100644 index 0000000..daeed08 --- /dev/null +++ b/Makefile.PL @@ -0,0 +1,13 @@ +use ExtUtils::MakeMaker; +WriteMakefile( + NAME => 'Class::MOP', + VERSION_FROM => 'lib/Class/MOP.pm', + PREREQ_PM => { + 'Test::More' => '0.47', + 'Test::Exception' => '0.21', + 'Scalar::Util' => '1.17', + 'Sub::Name' => '0.02', + 'Carp' => '0.01', + 'B' => '0', + } +); diff --git a/lib/Class/MOP.pm b/lib/Class/MOP.pm index 4c56ef7..a401ee5 100644 --- a/lib/Class/MOP.pm +++ b/lib/Class/MOP.pm @@ -101,7 +101,8 @@ Class::MOP - A Meta Object Protocol for Perl 5 =head1 SYNOPSIS - # ... + # ... This will come later, for now see + # the other SYNOPSIS for more information =head1 DESCRIPTON @@ -156,12 +157,12 @@ This module was designed to be as unintrusive as possible. Many of it's features are accessible without B change to your existsing code at all. It is meant to be a compliment to your existing code and not an intrusion on your code base. Unlike many other B -modules, this module does require you subclass it, or even that you -C it in within your module's package. +modules, this module B require you subclass it, or even that +you C it in within your module's package. The only features which requires additions to your code are the attribute handling and instance construction features, and these are -both optional features as well. The only reason for this is because +both completely optional features. The only reason for this is because Perl 5's object system does not actually have these features built in. More information about this feature can be found below. @@ -217,16 +218,15 @@ See L for more details. =back -head1 BUGS - -All complex software has bugs lurking in it, and this module is no -exception. If you find a bug please either email me, or add the bug -to cpan-RT. - =head1 SEE ALSO =head2 Books +There are very few books out on Meta Object Protocols and Metaclasses +because it is such an esoteric topic. The following books are really +the only ones I have found. If you know of any more, B> +email me and let me know, I would love to hear about them. + =over 4 =item "The Art of the Meta Object Protocol" @@ -235,6 +235,8 @@ to cpan-RT. =item "Putting MetaClasses to Work" +=item "Smalltalk: The Language" + =back =head2 Prior Art @@ -253,11 +255,56 @@ to cpan-RT. =back -=head1 AUTHOR +=head1 SIMILAR MODULES + +As I have said above, this module is a class-builder-builder, so it is +not the same thing as modules like L and +L. That being said there are very few modules on CPAN +with similar goals to this module. The one I have found which is most +like this module is L, although it's philosophy is very +different from this module. + +To start with, it provides wrappers around common Perl data types, and even +extends those types with more specific subtypes. This module does not +go into that area at all. + +L also seems to create it's own custom meta-object protocol, +which is both more restrictive and more featureful than the vanilla +Perl 5 one. This module attempts to model the existing Perl 5 MOP as it is. + +It's introspection capabilities also seem to be heavily rooted in this +custom MOP, so that you can only introspect classes which are already +created with L. This module does not make such restictions. + +Now, all this said, L is much more featureful than B +would ever try to be. But B has some features which L +could not easily implement. It would be very possible to completely re-implement +L using B and bring some of these features to +L though. + +But in the end, this module's admitedly ambitious goals have no direct equal +on CPAN since surely no one has been crazy enough to try something as silly +as this ;) until now. -Stevan Little Estevan@iinteractive.comE +=head1 BUGS + +All complex software has bugs lurking in it, and this module is no +exception. If you find a bug please either email me, or add the bug +to cpan-RT. + +=head1 ACKNOWLEDGEMENTS + +=over 4 + +=item Rob Kinyon Erob@iinteractive.comE + +Thanks to Rob for actually getting the development of this module kick-started. + +=back + +=head1 AUTHOR -Rob Kinyon Erob@iinteractive.comE +Stevan Little Estevan@iinteractive.comE =head1 COPYRIGHT AND LICENSE diff --git a/lib/Class/MOP/Attribute.pm b/lib/Class/MOP/Attribute.pm index 440c0ad..299342c 100644 --- a/lib/Class/MOP/Attribute.pm +++ b/lib/Class/MOP/Attribute.pm @@ -212,7 +212,7 @@ object attributes. =item B An attribute must (at the very least), have a C<$name>. All other -C<%options> are contained added as key-valeue pairs. Acceptable keys +C<%options> are contained added as key-value pairs. Acceptable keys are as follows: =over 4 @@ -274,7 +274,7 @@ an exercise to the reader :). =back -This I, I, I and I keys can +The I, I, I and I keys can contain either; the name of the method and an appropriate default one will be generated for you, B a HASH ref containing exactly one key (which will be used as the name of the method) and one value, @@ -353,7 +353,7 @@ argument C<$instance> into it and return the value. =head2 Informational predicates -These are all basic predicate methodfor the values passed into C. +These are all basic predicate methods for the values passed into C. =over 4 @@ -378,13 +378,13 @@ These are all basic predicate methodfor the values passed into C. =item B This allows the attribute to generate and install code for it's own -accessor/reader/writer/predicate methods. This is called by +I methods. This is called by C. =item B This allows the attribute to remove the method for it's own -accessor/reader/writer/predicate. This is called by +I. This is called by C. =back @@ -407,7 +407,7 @@ of the MOP when subclassing it. =head1 AUTHOR -Stevan Little Estevan@iinteractive.comE +Stevan Little Estevan@iinteractive.comE =head1 COPYRIGHT AND LICENSE diff --git a/lib/Class/MOP/Class.pm b/lib/Class/MOP/Class.pm index 8f048af..d70f2c9 100644 --- a/lib/Class/MOP/Class.pm +++ b/lib/Class/MOP/Class.pm @@ -454,8 +454,9 @@ of the MOP when subclassing it. =head2 Class construction -These methods handle creating Class objects, which can be used to -both create new classes, and analyze pre-existing ones. +These methods will handle creating B objects, +which can be used to both create new classes, and analyze +pre-existing classes. This module will internally store references to all the instances you create with these methods, so that they do not need to be @@ -464,22 +465,38 @@ created any more than nessecary. Basically, they are singletons. =over 4 =item B ?@superclasses, - methods => ?%methods, - attributes => ?%attributes)> + superclasses =E ?@superclasses, + methods =E ?%methods, + attributes =E ?%attributes)> -This returns the basic Class object, bringing the specified +This returns a B 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>. +This initializes and returns returns a B object +for a given a C<$package_name>. + +=item B + +This will construct an instance of B, it is +here so that we can actually "tie the knot" for B +to use C once all the bootstrapping is done. This +method is used internally by C and should never be called +from outside of that method really. =back -=head2 Instance construction +=head2 Object instance construction + +This method is used to construct an instace structure suitable for +C-ing into your package of choice. It works in conjunction +with the Attribute protocol to collect all applicable attributes. + +This method is B, it is up to you whether you want +to use it or not. =over 4 @@ -487,18 +504,10 @@ This initializes a Class object for a given a C<$package_name>. This will construct and instance using a HASH ref as storage (currently only HASH references are supported). This will collect all -the applicable attribute meta-objects and layout out the fields in the -HASH ref, 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. - -=item B - -This will construct an instance of B, it is -here so that we can actually "tie the knot" for B -to use C once all the bootstrapping is done. This -method is used internally by C and should never be called -from outside of that method really. +the applicable attributes and layout out the fields in the HASH ref, +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 @@ -508,13 +517,13 @@ from outside of that method really. =item B -This is a read-only attribute which returns the package name that -the Class is stored in. +This is a read-only attribute which returns the package name for the +given B instance. =item B This is a read-only attribute which returns the C<$VERSION> of the -package the Class is stored in. +package for the given B instance. =back @@ -525,13 +534,14 @@ package the Class is stored in. =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. +relationships of the class the B instance is +associated with. 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. +This computes the a list of all the class's ancestors in the same order +in which method dispatch will be done. This is similair to +what B does, but we don't remove duplicate names. =back @@ -542,18 +552,19 @@ in which method dispatch will be done. =item B This will take a C<$method_name> and CODE reference to that -C<$method> and install it into the Class. +C<$method> and install it into the class's package. -B : This does absolutely nothing special to C<$method> +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 +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. +if the class inherits the method (use C for that). This will correctly handle functions defined outside of the package that use a fully qualified name (C). @@ -571,7 +582,7 @@ 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. +90% of the time, so it's a small trade off I think. =item B @@ -580,7 +591,7 @@ or return undef if that method does not exist. =item B -This will attempt to remove a given C<$method_name> from the Class. +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. @@ -593,8 +604,8 @@ 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 +This will return a list of all the methods names this class will +respond to, 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. @@ -620,22 +631,28 @@ once, and in the correct order. 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. +their own. See L for more details. =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). +This stores a C<$attribute_meta_object> in the B +instance associated with the given class, 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. +L or the L +section. + +It should be noted that any accessor, reader/writer or predicate +methods which the C<$attribute_meta_object> has will be installed +into the class at this time. =item B -Checks to see if this Class has an attribute by the name of +Checks to see if this class has an attribute by the name of C<$attribute_name> and returns a boolean. =item B @@ -648,10 +665,18 @@ if none is found, it will return undef. 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 +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. +It should be noted that any accessor, reader/writer or predicate +methods which the attribute meta-object stored at C<$attribute_name> +has will be removed from the class at this time. This B make +these attributes somewhat inaccessable in previously created +instances. But if you are crazy enough to do this at runtime, then +you are crazy enough to deal with something like this :). + =item B This returns a list of attribute names which are defined in the local @@ -703,7 +728,7 @@ This will attempt to remove the package variable at C<$variable_name>. =head1 AUTHOR -Stevan Little Estevan@iinteractive.comE +Stevan Little Estevan@iinteractive.comE =head1 COPYRIGHT AND LICENSE diff --git a/lib/Class/MOP/Method.pm b/lib/Class/MOP/Method.pm index 8db4bd3..75205b2 100644 --- a/lib/Class/MOP/Method.pm +++ b/lib/Class/MOP/Method.pm @@ -65,7 +65,7 @@ to this class. =head1 AUTHOR -Stevan Little Estevan@iinteractive.comE +Stevan Little Estevan@iinteractive.comE =head1 COPYRIGHT AND LICENSE