From: Dave Rolsky Date: Mon, 16 Mar 2009 16:48:46 +0000 (-0500) Subject: proper API docs for CMOP::Immutable X-Git-Tag: 0.80_01~48 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=2ca3697e2414c1450af329c5e00503849f257df5;p=gitmo%2FClass-MOP.git proper API docs for CMOP::Immutable removed docs on some methods which are not really useful for "outside" users as-is.I will do some more refactoring in a branch. --- diff --git a/lib/Class/MOP/Immutable.pm b/lib/Class/MOP/Immutable.pm index 7dcbed9..7c83fc4 100644 --- a/lib/Class/MOP/Immutable.pm +++ b/lib/Class/MOP/Immutable.pm @@ -406,63 +406,108 @@ Class::MOP::Immutable - A class to transform Class::MOP::Class metaclasses =head1 DESCRIPTION -This is basically a module for applying a transformation on a given -metaclass. Current features include making methods read-only, -making methods un-callable and memoizing methods (in a type specific -way too). +This class encapsulates the logic behind immutabilization. -This module is not for the feint of heart, it does some whacky things -to the metaclass in order to make it immutable. If you are just curious, -I suggest you turn back now, there is nothing to see here. +This class provides generic immutabilization logic. Decisions about +I gets transformed are up to the caller. + +Immutabilization allows for a number of transformations. It can ask +the calling metaclass to inline methods such as the constructor, +destructor, or accessors. It can memoize metaclass accessors +themselves. It can also turn read-write accessors in the metaclass +into read-only methods, and make attempting to set these values an +error. Finally, it can make some methods throw an exception when they +are called. This is used to disable methods that can alter the class. =head1 METHODS =over 4 -=item B +=item B<< Class::MOP::Immutable->new($metaclass, %options) >> -Given a C<$metaclass> and a set of C<%options> this module will -prepare an immutable version of the C<$metaclass>, which can then -be applied to the C<$metaclass> using the C -method. +This method takes a metaclass object (typically a L +object) and a hash of options. -=item B +It returns a new transformer, but does not actually do any +transforming yet. -Returns the options HASH set in C. +This method accepts the following options: -=item B +=over 8 -Returns the metaclass set in C. +=item * inline_accessors -=item B +=item * inline_constructor -Returns the immutable metaclass created within C. +=item * inline_destructor -=back +These are all booleans indicating whether the specified method(s) +should be inlined. -=over 4 +By default, accessors and the constructor are inlined, but not the +destructor. + +=item * replace_constructor + +This is a boolean indicating whether an existing constructor should be +replaced when inlining a constructor. This defaults to false. + +=item * constructor_name + +This is the constructor method name. This defaults to "new". + +=item * constructor_class + +The name of the method metaclass for constructors. It will be used to +generate the inlined constructor. This defaults to +"Class::MOP::Method::Constructor". + +=item * destructor_class -=item B +The name of the method metaclass for destructors. It will be used to +generate the inlined destructor. This defaults to +"Class::MOP::Method::Denstructor". -This will create the immutable version of the C<$metaclass>, but will -not actually change the original metaclass. +=item * memoize + +This option takes a hash reference. They keys are method names to be +memoized, and the values are the type of data the method returns. This +can be one of "SCALAR", "ARRAY", or "HASH". + +=item * read_only + +This option takes an array reference of read-write methods which will +be made read-only. After they are transformed, attempting to set them +will throw an error. + +=item * cannot_call + +This option takes an array reference of methods which cannot be called +after immutabilization. Attempting to call these methods will throw an +error. + +=item * wrapped + +This option takes a hash reference. The keys are method names and the +body is a subroutine reference which will wrap the named method. This +allows you to do some sort of custom transformation to a method. + +=back -=item B +=item B<< $transformer->options >> -This will create all the methods for the immutable metaclass based -on the C<%options> passed into C. +Returns a hash reference of the options passed to C. -=item B +=item B<< $transformer->metaclass >> -This will actually change the C<$metaclass> into the immutable version. +Returns the metaclass object passed to C. -=item B +=item B<< $transformer->immutable_metaclass >> -This will change the C<$metaclass> into the mutable version by reversing -the immutable process. C<%options> should be the same options that were -given to make_metaclass_immutable. +Returns the immutable metaclass object that is created by the +transformation process. -=item B +=item B<< $transformer->inlined_constructor >> If the constructor was inlined, this returns the constructor method object that was created to do this. diff --git a/xt/pod_coverage.t b/xt/pod_coverage.t index 70e6585..fb79eb1 100644 --- a/xt/pod_coverage.t +++ b/xt/pod_coverage.t @@ -45,6 +45,13 @@ my %trustme = ( 'compute_all_applicable_attributes', ], + + 'Class::MOP::Immutable' => [ + qw( create_immutable_metaclass + create_methods_for_immutable_metaclass + make_metaclass_immutable + make_metaclass_mutable ) + ], ); for my $module ( sort @modules ) {