Revision history for Perl extension Class-MOP.
0.53
+ ~~~ some misc. doc. fixes ~~~
+
* Class::MOP::Instance
- added get_all_slot_values method (Sartak)
- added tests for this (Sartak)
=head1 DESCRIPTON
-This module is an attempt to create a meta object protocol for the
+This module is a fully functioning 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 its manipulation and introspection.
=head1 PROTOCOLS
-The protocol is divided into 3 main sub-protocols:
+The protocol is divided into 4 main sub-protocols:
=over 4
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
+attributes 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<Class::MOP::Method> for more details.
+=item The Instance protocol
+
+This provides a layer of abstraction for creating object instances.
+Since the other layers use this protocol, it is relatively easy to
+change the type of your instances from the default HASH ref to other
+types of references. Several examples are provided in the F<examples/>
+directory included in this distribution.
+
+See L<Class::MOP::Instance> for more details.
+
=back
=head1 FUNCTIONS
This will load a given C<$class_name> and if it does not have an
already initialized metaclass, then it will intialize one for it.
+This function can be used in place of tricks like
+C<eval "use $module"> or using C<require>.
=item B<is_class_loaded ($class_name)>
=item B<check_package_cache_flag ($pkg)>
+This will return an integer that is managed by C<Class::MOP::Class>
+to determine if a module's symbol table has been altered.
+
+In Perl 5.10 or greater, this flag is package specific. However in
+versions prior to 5.10, this will use the C<PL_sub_generation> variable
+which is not package specific.
+
=item B<get_code_info ($code)>
+This function returns two values, the name of the package the C<$code>
+is from and the name of the C<$code> itself. This is used by several
+elements of the MOP to detemine where a given C<$code> reference is from.
+
=back
=head2 Metaclass cache functions
=item B<get_metaclass_by_name ($name)>
+This will return a cached B<Class::MOP::Class> instance of nothing
+if no metaclass exist by that C<$name>.
+
=item B<store_metaclass_by_name ($name, $meta)>
+This will store a metaclass in the cache at the supplied C<$key>.
+
=item B<weaken_metaclass ($name)>
+In rare cases it is desireable to store a weakened reference in
+the metaclass cache. This function will weaken the reference to
+the metaclass stored in C<$name>.
+
=item B<does_metaclass_exist ($name)>
+This will return true of there exists a metaclass stored in the
+C<$name> key and return false otherwise.
+
=item B<remove_metaclass_by_name ($name)>
+This will remove a the metaclass stored in the C<$name> key.
+
=back
=head1 SEE ALSO
And lastly, if the value of your attribute is dependent upon
some other aspect of the instance structure, then you can take
advantage of the fact that when the I<default> value is a CODE
-reference, it is passed the raw (unblessed) instance structure
+reference, it is passed the (as yet unfinished) instance structure
as it's only argument. So you can do things like this:
Class::MOP::Attribute->new('$object_identity' => (
is provided to make it easy to set the (possibly altered) value on the instance
without going through several more method calls.
-If no initializer is given (as is the common case) initial attribute values are
-set directly, bypassing the writer.
-
This contrived example shows an initializer that sets the attribute to twice
the given value.
initializer => 'some_attr',
));
+Your writer will simply need to examine it's C<@_> and determine under
+which context it is being called.
+
=back
The I<accessor>, I<reader>, I<writer>, I<predicate> and I<clearer> keys can
=item B<clone (%options)>
+This will return a clone of the attribute instance, allowing the overriding
+of various attributes through the C<%options> supplied.
+
=item B<initialize_instance_slot ($instance, $params)>
+This method is used internally to initialize the approriate slot for this
+attribute in a given C<$instance>, the C<$params> passed are those that were
+passed to the constructor.
+
=back
=head2 Value management
value of the attribute in the associated class. Suitable for use whether
C<reader> and C<writer> or C<accessor> was specified or not.
-NOTE: If not reader/writer/accessor was specified, this will use the
+NOTE: If no reader/writer/accessor was specified, this will use the
attribute get_value/set_value methods, which can be very inefficient.
=back
=item B<associated_methods>
This will return the list of methods which have been associated with
-the C<associate_method> methods.
+the C<associate_method> methods. This is a good way of seeing what
+methods are used to manage a given attribute.
=item B<install_accessors>
It should also be noted that B<Class::MOP> will actually bootstrap
this module by installing a number of attribute meta-objects into
-it's metaclass. This will allow this class to reap all the benifits
+it's metaclass. This will allow this class to reap all the benefits
of the MOP when subclassing it.
=back
}
}
-sub get_attribute_values {
- my ($self, $instance) = @_;
-
- return +{
- map { $_->name => $_->get_value($instance) }
- grep { $_->has_value($instance) }
- $self->compute_all_applicable_attributes
- };
-}
-
-sub get_init_args {
- my ($self, $instance) = @_;
-
- return +{
- map { $_->init_arg => $_->get_value($instance) }
- grep { $_->has_value($instance) }
- grep { defined($_->init_arg) }
- $self->compute_all_applicable_attributes
- };
-}
-
# Inheritance
sub superclasses {
=item B<reset_package_cache_flag>
-Clear this flag, used in Moose.
+Clears the package cache flag to announce to the internals that we need
+to rebuild the method map.
=back
=item B<instance_metaclass>
+Returns the class name of the instance metaclass, see L<Class::MOP::Instance>
+for more information on the instance metaclasses.
+
=item B<get_meta_instance>
+Returns an instance of L<Class::MOP::Instance> to be used in the construction
+of a new instance of the class.
+
=item B<new_object (%params)>
This is a convience method for creating a new object of the class, and
$class->meta->new_object(%params);
}
-Of course the ideal place for this would actually be in C<UNIVERSAL::>
-but that is considered bad style, so we do not do that.
-
=item B<construct_instance (%params)>
-This method is used to construct an instace structure suitable for
+This method is used to construct an instance structure suitable for
C<bless>-ing into your package of choice. It works in conjunction
with the Attribute protocol to collect all applicable attributes.
$self->meta->clone_object($self, %params);
}
-Of course the ideal place for this would actually be in C<UNIVERSAL::>
-but that is considered bad style, so we do not do that.
-
=item B<clone_instance($instance, %params)>
This method is a compliment of C<construct_instance> (which means if
think Yuval "nothingmuch" Kogman put it best when he said that cloning
is too I<context-specific> to be part of the MOP.
-=item B<get_attribute_values($instance)>
-
-Returns the values of the C<$instance>'s fields keyed by the attribute names.
-
-=item B<get_init_args($instance)>
-
-Returns a hash reference where the keys are all the attributes' C<init_arg>s
-and the values are the instance's fields. Attributes without an C<init_arg>
-will be skipped.
-
=item B<rebless_instance($instance)>
This will change the class of C<$instance> to the class of the invoking
C<Class::MOP::Class>. You may only rebless the instance to a subclass of
-itself. This limitation may be relaxed in the future.
-
-This can be useful in a number of situations, such as when you are writing
-a program that doesn't know everything at object construction time.
+itself.
=back
relationships of the class the B<Class::MOP::Class> instance is
associated with. Basically, it can get and set the C<@ISA> for you.
-B<NOTE:>
-Perl will occasionally perform some C<@ISA> and method caching, if
-you decide to change your superclass relationship at runtime (which
-is quite insane and very much not recommened), then you should be
-aware of this and the fact that this module does not make any
-attempt to address this issue.
-
=item B<class_precedence_list>
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<Class::ISA::super_path> does, but we don't remove duplicate names.
+in which method dispatch will be done. This is similair to what
+B<Class::ISA::super_path> does, but we don't remove duplicate names.
=item B<linearized_isa>
=item B<subclasses>
-This returns a list of subclasses for this class.
+This returns a list of subclasses for this class.
=back
=item B<get_method_map>
+Returns a HASH ref of name to CODE reference mapping for this class.
+
=item B<method_metaclass>
+Returns the class name of the method metaclass, see L<Class::MOP::Method>
+for more information on the method metaclasses.
+
=item B<add_method ($method_name, $method)>
This will take a C<$method_name> and CODE reference to that
=item B<attribute_metaclass>
+Returns the class name of the attribute metaclass, see L<Class::MOP::Attribute>
+for more information on the attribute metaclasses.
+
=item B<get_attribute_map>
-=item B<add_attribute ($attribute_meta_object | $attribute_name, %attribute_spec)>
+This returns a HASH ref of name to attribute meta-object mapping.
+
+=item B<add_attribute ($attribute_meta_object | ($attribute_name, %attribute_spec))>
This stores the C<$attribute_meta_object> (or creates one from the
C<$attribute_name> and C<%attribute_spec>) in the B<Class::MOP::Class>
meta => sub {
my $self = shift;
# if it is not blessed, then someone is asking
- # for the meta of Class::MOP::Class::Immutable
+ # for the meta of Class::MOP::Immutable
return Class::MOP::Class->initialize($self) unless blessed($self);
# otherwise, they are asking for the metaclass
# which has been made immutable, which is itself
making methods un-callable and memoizing methods (in a type specific
way too).
-This module is fairly new to the MOP, and quite possibly will be
-expanded and further generalized as the need arises.
+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.
=head1 METHODS
Class::MOP::Instance - Instance Meta Object
-=head1 SYNOPSIS
-
- # This API is largely internal
- # you shouldn't need it unless you are writing meta attributes or meta
- # instances
-
=head1 DESCRIPTION
The meta instance is used by attributes for low level storage.
=item B<clone_instance ($instance_structure)>
+This too does just exactly what it says it does.
+
=back
=head2 Instrospection
=item B<associated_metaclass>
+This returns the metaclass associated with this instance.
+
=item B<get_all_slots>
This will return the current list of slots based on what was
=item B<is_valid_slot ($slot_name)>
+This will return true if C<$slot_name> is a valid slot name.
+
=back
=head2 Operations on Instance Structures
instance it creates. For this reason, any actions on slots
require that the C<$instance_structure> is passed into them.
+The names of these methods pretty much explain exactly
+what they do, if that is not enough then I suggest reading
+the source, it is very straightfoward.
+
=over 4
=item B<get_slot_value ($instance_structure, $slot_name)>
=head2 Inlineable Instance Operations
-This part of the API is currently un-used. It is there for use
-in future experiments in class finailization mostly. Best to
-ignore this for now.
-
=over 4
=item B<is_inlinable>
Each meta-instance should override this method to tell Class::MOP if it's
-possible to inline the slot access.
-
-This is currently only used by Class::MOP::Class::Immutable when performing
-optimizations.
+possible to inline the slot access. This is currently only used by
+L<Class::MOP::Immutable> when performing optimizations.
=item B<inline_create_instance>
Class::MOP::Method - Method Meta Object
-=head1 SYNOPSIS
-
- # ... more to come later maybe
-
=head1 DESCRIPTION
The Method Protocol is very small, since methods in Perl 5 are just
=over 4
-=item B<wrap (&code)>
+=item B<wrap ($code)>
+
+This is the basic constructor, it returns a B<Class::MOP::Method>
+instance which wraps the given C<$code> reference.
=back
=item B<body>
+This returns the actual CODE reference of the particular instance.
+
=item B<name>
+This returns the name of the CODE reference.
+
=item B<package_name>
+This returns the package name that the CODE reference is attached to.
+
=item B<fully_qualified_name>
+This returns the fully qualified name of the CODE reference.
+
=back
=head1 AUTHORS
=head1 DESCRIPTION
This is a subclass of C<Class::MOP::Method> which deals with
-class constructors.
+class constructors. This is used when making a class immutable
+to generate an optimized constructor.
=head1 METHODS
=back
-=head2 Method Generators
+=head2 Method Generators
=over 4
Class::MOP::Method::Wrapped - Method Meta Object to handle before/around/after modifiers
-=head1 SYNOPSIS
-
- # ... more to come later maybe
-
=head1 DESCRIPTION
+This is a L<Class::MOP::Method> subclass which provides the funtionality
+to wrap a given CODE reference with before, after and around method modifiers.
+
=head1 METHODS
=head2 Construction
=over 4
-=item B<wrap (&code)>
+=item B<wrap ($code)>
+
+This is the constructor, it will return a B<Class::MOP::Method::Wrapped>
+instance that can be used to add before, after and around modifiers to.
=item B<get_original_method>
+This returns the original CODE reference that was provided to the
+constructor.
+
=back
=head2 Modifiers
+These three methods will add the method modifiers to the wrapped
+CODE reference. For more information on how method modifiers work,
+see the section in L<Class::MOP::Class>.
+
=over 4
=item B<add_before_modifier ($code)>
Class::MOP::Module - Module Meta Object
-=head1 SYNOPSIS
-
=head1 DESCRIPTION
+This is an abstraction of a Perl 5 module, it is a superclass of
+L<Class::MOP::Class>. A module essentially a package with metadata,
+in our case the version and authority.
+
=head1 METHODS
=over 4
=item B<meta>
+Returns a metaclass for this package.
+
+=item B<initialize ($package_name)>
+
+This will initialize a Class::MOP::Module instance which represents
+the module of C<$package_name>.
+
=item B<version>
This is a read-only attribute which returns the C<$VERSION> of the
Class::MOP::Package - Package Meta Object
-=head1 SYNOPSIS
-
=head1 DESCRIPTION
+This is an abstraction of a Perl 5 package, it is a superclass of
+L<Class::MOP::Class> and provides all of the symbol table
+introspection methods.
+
=head1 METHODS
=over 4
=item B<meta>
+Returns a metaclass for this package.
+
=item B<initialize ($package_name)>
+This will initialize a Class::MOP::Package instance which represents
+the package of C<$package_name>.
+
=item B<name>
This is a read-only attribute which returns the package name for the
projects / gitmo/Class-MOP.git / commitdiff