.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Object::Pad::MOP::Class 3pm"
.TH Object::Pad::MOP::Class 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
"Object::Pad::MOP::Class" \- meta\-object representation of a "Object::Pad" class
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Instances of this class represent a class or role implemented by
Object::Pad. Accessors provide information about the class or role, and
methods that can alter the class, typically by adding new elements to it, 
allow a program to extend existing classes.
.PP
Where possible, this API is designed to be compatible with MOP::Class.
.PP
This API should be considered \fBexperimental\fR, and will emit warnings to that
effect. They can be silenced with
.PP
.Vb 1
\&   use Object::Pad qw( :experimental(mop) );
.Ve
.PP
or
.PP
.Vb 1
\&   use Object::Pad::MOP::Class qw( :experimental(mop) );
.Ve
.SH CONSTRUCTOR
.IX Header "CONSTRUCTOR"
.SS for_class
.IX Subsection "for_class"
.Vb 1
\&   $metaclass = Object::Pad::MOP::Class\->for_class( $class );
.Ve
.PP
\&\fISince version 0.38.\fR
.PP
Returns the metaclass instance associated with the given class name. Throws an
exception if the requested class is not using \f(CW\*(C`Object::Pad\*(C'\fR.
.SS try_for_class
.IX Subsection "try_for_class"
.Vb 1
\&   $metaclass = Object::Pad::MOP::Class\->try_for_class( $class );
.Ve
.PP
\&\fISince version 0.808.\fR
.PP
If the given class name is built using \f(CW\*(C`Object::Pad\*(C'\fR then returns the
metaclass instance for it. If not, returns \f(CW\*(C`undef\*(C'\fR.
.SS for_caller
.IX Subsection "for_caller"
.Vb 1
\&   $metaclass = Object::Pad::MOP::Class\->for_caller;
.Ve
.PP
\&\fISince version 0.38.\fR
.PP
A convenient shortcut for obtaining the metaclass instance of the calling
package scope. Often handy during \f(CW\*(C`BEGIN\*(C'\fR blocks of the class itself to
perform adjustments or additions.
.PP
.Vb 6
\&   class Some::Class::Here 1.234 {
\&      BEGIN {
\&         my $meta = Object::Pad::MOP::Class\->for_caller;
\&         ...
\&      }
\&   }
.Ve
.SS create_class
.IX Subsection "create_class"
.Vb 1
\&   my $metaclass = Object::Pad::MOP::Class\->create_class( $name, %args );
.Ve
.PP
\&\fISince version 0.61.\fR
.PP
Creates a new class of the given name and yields the metaclass for it.
.PP
Takes the following additional named arguments:
.IP "extends => STRING" 4
.IX Item "extends => STRING"
.PD 0
.IP "isa => STRING" 4
.IX Item "isa => STRING"
.PD
An optional name of a superclass that this class will extend. These options
are synonyms; new code should use \f(CW\*(C`isa\*(C'\fR, as \f(CW\*(C`extends\*(C'\fR will eventually be
removed.
.PP
Once created, this metaclass must be sealed using the "seal" method before
it can be used to actually construct object instances.
.SS create_role
.IX Subsection "create_role"
.Vb 1
\&   my $metaclass = Object::Pad::MOP::Class\->create_role( $name, %args );
.Ve
.PP
\&\fISince version 0.61.\fR
.PP
As "create_class" but creates a role instead of a class.
.SS begin_class
.IX Subsection "begin_class"
.Vb 4
\&   BEGIN {
\&      my $metaclass = Object::Pad::MOP::Class\->begin_class( $name, %args );
\&      ...
\&   }
.Ve
.PP
\&\fISince version 0.46.\fR
.PP
A variant of "create_class" which sets the newly-created class as the
current complication scope of the surrounding code, allowing it to accept
\&\f(CW\*(C`Object::Pad\*(C'\fR syntax forms such as \f(CW\*(C`has\*(C'\fR and \f(CW\*(C`method\*(C'\fR.
.PP
This must be done during \f(CW\*(C`BEGIN\*(C'\fR time because of this compiletime effect.
It additionally creates a deferred code block at \f(CW\*(C`UNITCHECK\*(C'\fR time of its
surrounding scope, which is used to finalise the constructed class. In this
case you do not need to remember to call "seal" on it; this happens
automatically.
.SS begin_role
.IX Subsection "begin_role"
\&\fISince version 0.46.\fR
.PP
As "begin_class" but creates a role instead of a class.
.SH METHODS
.IX Header "METHODS"
.SS is_class
.IX Subsection "is_class"
.SS is_role
.IX Subsection "is_role"
.Vb 2
\&   $bool = $metaclass\->is_class;
\&   $bool = $metaclass\->is_role;
.Ve
.PP
Exactly one of these methods will return true, depending on whether this
metaclass instance represents a true \f(CW\*(C`class\*(C'\fR, or a \f(CW\*(C`role\*(C'\fR.
.SS name
.IX Subsection "name"
.Vb 1
\&   $name = $metaclass\->name;
.Ve
.PP
Returns the name of the class, as a plain string.
.SS superclasses
.IX Subsection "superclasses"
.Vb 1
\&   @classes = $metaclass\->superclasses;
.Ve
.PP
Returns a list of superclasses, as Object::Pad::MOP::Class instances.
.PP
Because \f(CW\*(C`Object::Pad\*(C'\fR does not support multiple superclasses, this list will
contain at most one item.
.SS direct_roles
.IX Subsection "direct_roles"
.Vb 1
\&   @roles = $metaclass\->direct_roles;
.Ve
.PP
Returns a list of the roles introduced by this class (i.e. added by `does`
declarations but not inherited from the superclass), as
Object::Pad::MOP::Class instances.
.PP
This method is also aliased as \f(CW\*(C`roles\*(C'\fR.
.SS all_roles
.IX Subsection "all_roles"
.Vb 1
\&   @roles = $metaclass\->all_roles;
.Ve
.PP
\&\fISince version 0.56.\fR
.PP
Returns a list of all the roles implemented by this class (i.e. including
those inherited from the superclass), as Object::Pad::MOP::Class instances.
.SS add_role
.IX Subsection "add_role"
.Vb 2
\&   $metaclass\->add_role( $rolename );
\&   $metaclass\->add_role( $rolemeta );
.Ve
.PP
\&\fISince version 0.56.\fR
.PP
Adds a new role to the list of those implemented by the class.
.PP
The new role can be specified either as a plain string giving its name, or as
an \f(CW\*(C`Object::Pad::MOP::Class\*(C'\fR meta instance directly.
.PP
Before version 0.56 this was called \f(CW\*(C`compose_role\*(C'\fR.
.SS add_BUILD
.IX Subsection "add_BUILD"
.Vb 1
\&   $metaclass\->add_BUILD( $code );
.Ve
.PP
Adds a new \f(CW\*(C`BUILD\*(C'\fR block to the class, as a CODE reference.
.SS add_method
.IX Subsection "add_method"
.Vb 1
\&   $metamethod = $metaclass\->add_method( $name, %args, $code );
.Ve
.PP
Adds a new named method to the class under the given name, as CODE reference.
.PP
Returns an instance of Object::Pad::MOP::Method to represent it.
.PP
Recognises the following additional named arguments:
.IP "common => BOOL" 4
.IX Item "common => BOOL"
\&\fISince version 0.62.\fR
.Sp
If true, the method is a class-common method.
.SS get_direct_method
.IX Subsection "get_direct_method"
.Vb 1
\&   $metamethod = $metaclass\->get_direct_method( $name );
.Ve
.PP
Returns an instance of Object::Pad::MOP::Method to represent the method of
the given name, if one exists. If not an exception is thrown.
.PP
This can only see directly-applied methods; that is, methods created by the
\&\f(CW\*(C`method\*(C'\fR keyword on the class itself, or added via "add_method". This will
not see other names in the package stash, even if they contain a \f(CW\*(C`CODE\*(C'\fR slot,
nor will it see methods inherited from a superclass.
.PP
This is also aliased as \f(CW\*(C`get_own_method\*(C'\fR for compatibility with the
MOP::Class interface.
.SS get_method
.IX Subsection "get_method"
.Vb 1
\&   $metamethod = $metaclass\->get_method( $name );
.Ve
.PP
\&\fISince version 0.57.\fR
.PP
Returns an instance of Object::Pad::MOP::Method to represent the method of
the given name, if one exists. If not an exception is thrown.
.PP
This will additionally search superclasses, and may return a method belonging
to a parent class.
.SS direct_methods
.IX Subsection "direct_methods"
.Vb 1
\&   @metamethods = $metaclass\->direct_methods;
.Ve
.PP
\&\fISince version 0.57.\fR
.PP
Returns a list of Object::Pad::MOP::Method instances to represent all the
direct methods of the class. This list may be empty.
.SS all_methods
.IX Subsection "all_methods"
.Vb 1
\&   @metamethods = $metaclass\->all_methods;
.Ve
.PP
\&\fISince version 0.57.\fR
.PP
Returns a list of Object::Pad::MOP::Method instances to represent all the
methods of the class, including those inherited from superclasses. This list
may be empty.
.SS add_field
.IX Subsection "add_field"
.Vb 1
\&   $metafield = $metaclass\->add_field( $name, %args );
.Ve
.PP
\&\fIsince version 0.60.\fR
.PP
Adds a new field to the class, using the given name (which must begin with the
sigil character \f(CW\*(C`$\*(C'\fR, \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR).
.PP
Recognises the following additional named arguments:
.IP "default => SCALAR" 4
.IX Item "default => SCALAR"
\&\fISince version 0.43.\fR
.Sp
Provides a default value for the field; similar to using the syntax
.Sp
.Vb 1
\&   has $field = SCALAR;
.Ve
.Sp
This value may be \f(CW\*(C`undef\*(C'\fR, to set the value as being optional if it
additionally has a parameter name.
.IP "param => STRING" 4
.IX Item "param => STRING"
\&\fISince version 0.43.\fR
.Sp
Provides a parameter name for the field; similar to setting it using the
\&\f(CW\*(C`:param\*(C'\fR attribute. This parameter will be required unless a default value is
set (such value may still be \f(CW\*(C`undef\*(C'\fR).
.IP "reader => STRING" 4
.IX Item "reader => STRING"
.PD 0
.IP "writer => STRING" 4
.IX Item "writer => STRING"
.IP "mutator => STRING" 4
.IX Item "mutator => STRING"
.PD
\&\fISince version 0.46.\fR
.IP "accessor => STRING" 4
.IX Item "accessor => STRING"
\&\fISince version 0.56.\fR
.Sp
Provides method names for generated reader, writer, lvalue-mutator or
reader+writer accessor methods, similar to setting them via the \f(CW\*(C`:reader\*(C'\fR,
\&\f(CW\*(C`:writer\*(C'\fR, \f(CW\*(C`:mutator\*(C'\fR or \f(CW\*(C`:accessor\*(C'\fR attributes.
.IP "weak => BOOL" 4
.IX Item "weak => BOOL"
\&\fISince version 0.46.\fR
.Sp
If true, reference values assigned into the field by the constructor or
accessor methods will be weakened, similar to setting the \f(CW\*(C`:weak\*(C'\fR attribute.
.PP
Returns an instance of Object::Pad::MOP::Field to represent it.
.SS add_slot
.IX Subsection "add_slot"
.Vb 1
\&   $metafield = $metaclass\->add_slot( $name, %args );
.Ve
.PP
\&\fINow deprecated.\fR
.PP
Back-compatibility alias for \f(CW\*(C`add_field\*(C'\fR.
.SS get_field
.IX Subsection "get_field"
.Vb 1
\&   $metafield = $metaclass\->get_field( $name );
.Ve
.PP
\&\fISince version 0.60.\fR
.PP
Returns an instance of Object::Pad::MOP::Field to represent the field of
the given name, if one exists. If not an exception is thrown.
.SS get_slot
.IX Subsection "get_slot"
.Vb 1
\&   $metafield = $metaclass\->get_slot( $name );
.Ve
.PP
\&\fINow deprecated.\fR
.PP
Back-compatibility alias for \f(CW\*(C`get_field\*(C'\fR.
.SS fields
.IX Subsection "fields"
.Vb 1
\&   @metafields = $metaclass\->fields;
.Ve
.PP
\&\fISince version 0.60.\fR
.PP
Returns a list of Object::Pad::MOP::Field instances to represent all the
fields of the class. This list may be empty.
.SS slots
.IX Subsection "slots"
.Vb 1
\&   @metafields = $metaclass\->slots;
.Ve
.PP
\&\fISince version 0.42; now deprecated.\fR
.PP
Back-compatibility alias for \f(CW\*(C`fields\*(C'\fR.
.SS add_required_method
.IX Subsection "add_required_method"
.Vb 1
\&   $metaclass\->add_required_method( $name );
.Ve
.PP
\&\fISince version 0.61.\fR
.PP
Adds a new required method to the role, whose name is given as a plain string.
.PP
Currently returns nothing. This should be considered temporary, as eventually
a metatype for required methods will be added, at which point this method can
return instances of it. It may also take additional parameters to define the
required method with. Currently extra parameters are not permitted.
.SS required_method_names
.IX Subsection "required_method_names"
.Vb 1
\&   @names = $metaclass\->required_method_names;
.Ve
.PP
\&\fISince version 0.61.\fR
.PP
Returns a list names of required methods for the role, as plain strings.
.PP
This should be considered a temporary method. Currently there is no metatype
for required methods, so they are represented as plain strings. Eventually a
type may be defined and a \f(CW\*(C`required_methods\*(C'\fR method will be added.
.SS seal
.IX Subsection "seal"
.Vb 1
\&   $metaclass\->seal;
.Ve
.PP
\&\fISince version 0.61.\fR
.PP
If the metaclass was created by "create_class" or "create_role", this
method must be called once everything has been added into it, as the class
will not yet be ready to construct actual object instances before this is
done.
.SH AUTHOR
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>