NAME

       "Object::Pad::MOP::Class" - meta-object representation of a "Object::Pad" class

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.

       Where possible, this API is designed to be compatible with MOP::Class.

       This API should be considered experimental, and will emit warnings to that effect. They
       can be silenced with

          use Object::Pad qw( :experimental(mop) );

       or

          use Object::Pad::MOP::Class qw( :experimental(mop) );

CONSTRUCTOR

   for_class
          $metaclass = Object::Pad::MOP::Class->for_class( $class )

       Since version 0.38.

       Returns the metaclass instance associated with the given class name.

   for_caller
          $metaclass = Object::Pad::MOP::Class->for_caller;

       Since version 0.38.

       A convenient shortcut for obtaining the metaclass instance of the calling package scope.
       Often handy during "BEGIN" blocks of the class itself to perform adjustments or additions.

          class Some::Class::Here 1.234 {
             BEGIN {
                my $meta = Object::Pad::MOP::Class->for_caller;
                ...
             }
          }

   create_class
          my $metaclass = Object::Pad::MOP::Class->create_class( $name, %args )

       Since version 0.61.

       Creates a new class of the given name and yields the metaclass for it.

       Takes the following additional named arguments:

       extends => STRING
       isa => STRING
           An optional name of a superclass that this class will extend. These options are
           synonyms; new code should use "isa", as "extends" will eventually be removed.

       Once created, this metaclass must be sealed using the "seal" method before it can be used
       to actually construct object instances.

   create_role
          my $metaclass = Object::Pad::MOP::Class->create_role( $name, %args )

       Since version 0.61.

       As "create_class" but creates a role instead of a class.

   begin_class
          BEGIN {
             my $metaclass = Object::Pad::MOP::Class->begin_class( $name, %args )
             ...
          }

       Since version 0.46.

       A variant of "create_class" which sets the newly-created class as the current complication
       scope of the surrounding code, allowing it to accept "Object::Pad" syntax forms such as
       "has" and "method".

       This must be done during "BEGIN" time because of this compiletime effect.  It additionally
       creates a deferred code block at "UNITCHECK" 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.

   begin_role
       Since version 0.46.

       As "begin_class" but creates a role instead of a class.

METHODS

   is_class
   is_role
          $bool = $metaclass->is_class
          $bool = $metaclass->is_role

       Exactly one of these methods will return true, depending on whether this metaclass
       instance represents a true "class", or a "role".

   name
          $name = $metaclass->name

       Returns the name of the class, as a plain string.

   superclasses
          @classes = $metaclass->superclasses

       Returns a list of superclasses, as Object::Pad::MOP::Class instances.

       Because "Object::Pad" does not support multiple superclasses, this list will contain at
       most one item.

   direct_roles
          @roles = $metaclass->direct_roles

       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.

       This method is also aliased as "roles".

   all_roles
          @roles = $metaclass->all_roles

       Since version 0.56.

       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.

   add_role
          $metaclass->add_role( $rolename )
          $metaclass->add_role( $rolemeta )

       Since version 0.56.

       Adds a new role to the list of those implemented by the class.

       The new role can be specified either as a plain string giving its name, or as an
       "Object::Pad::MOP::Class" meta instance directly.

       Before version 0.56 this was called "compose_role".

   add_BUILD
          $metaclass->add_BUILD( $code )

       Adds a new "BUILD" block to the class, as a CODE reference.

   add_method
          $metamethod = $metaclass->add_method( $name, %args, $code )

       Adds a new named method to the class under the given name, as CODE reference.

       Returns an instance of Object::Pad::MOP::Method to represent it.

       Recognises the following additional named arguments:

       common => BOOL
           Since version 0.62.

           If true, the method is a class-common method.

   get_direct_method
          $metamethod = $metaclass->get_direct_method( $name )

       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.

       This can only see directly-applied methods; that is, methods created by the "method"
       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 "CODE" slot, nor will it see methods inherited
       from a superclass.

       This is also aliased as "get_own_method" for compatibility with the MOP::Class interface.

   get_method
          $metamethod = $metaclass->get_method( $name )

       Since version 0.57.

       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.

       This will additionally search superclasses, and may return a method belonging to a parent
       class.

   direct_methods
          @metamethods = $metaclass->direct_methods

       Since version 0.57.

       Returns a list of Object::Pad::MOP::Method instances to represent all the direct methods
       of the class. This list may be empty.

   all_methods
          @metamethods = $metaclass->all_methods

       Since version 0.57.

       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.

   add_field
          $metafield = $metaclass->add_field( $name, %args )

       since version 0.60.

       Adds a new field to the class, using the given name (which must begin with the sigil
       character "$", "@" or "%").

       Recognises the following additional named arguments:

       default => SCALAR
           Since version 0.43.

           Provides a default value for the field; similar to using the syntax

              has $field = SCALAR;

           This value may be "undef", to set the value as being optional if it additionally has a
           parameter name.

       param => STRING
           Since version 0.43.

           Provides a parameter name for the field; similar to setting it using the ":param"
           attribute. This parameter will be required unless a default value is set (such value
           may still be "undef").

       reader => STRING
       writer => STRING
       mutator => STRING
           Since version 0.46.

       accessor => STRING
           Since version 0.56.

           Provides method names for generated reader, writer, lvalue-mutator or reader+writer
           accessor methods, similar to setting them via the ":reader", ":writer", ":mutator" or
           ":accessor" attributes.

       weak => BOOL
           Since version 0.46.

           If true, reference values assigned into the field by the constructor or accessor
           methods will be weakened, similar to setting the ":weak" attribute.

       Returns an instance of Object::Pad::MOP::Field to represent it.

   add_slot
          $metafield = $metaclass->add_slot( $name, %args )

       Now deprecated.

       Back-compatibility alias for "add_field".

   get_field
          $metafield = $metaclass->get_field( $name )

       Since version 0.60.

       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.

   get_slot
          $metafield = $metaclass->get_slot( $name )

       Now deprecated.

       Back-compatibility alias for "get_field".

   fields
          @metafields = $metaclass->fields

       Since version 0.60.

       Returns a list of Object::Pad::MOP::Field instances to represent all the fields of the
       class. This list may be empty.

   slots
          @metafields = $metaclass->slots

       Since version 0.42; now deprecated.

       Back-compatibility alias for "fields".

   add_required_method
          $metaclass->add_required_method( $name )

       Since version 0.61.

       Adds a new required method to the role, whose name is given as a plain string.

       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.

   required_method_names
          @names = $metaclass->required_method_names

       Since version 0.61.

       Returns a list names of required methods for the role, as plain strings.

       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
       "required_methods" method will be added.

   seal
          $metaclass->seal

       Since version 0.61.

       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.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>