Class::MOP::Attribute(3pm)

NAME

Class::MOP::Attribute - Attribute Meta Object

SYNOPSIS

Class::MOP::Attribute->new(
    foo => (
        accessor  => 'foo',           # dual purpose get/set accessor
        predicate => 'has_foo',       # predicate check for defined-ness
        init_arg  => '-foo',          # class->new will look for a -foo key
        default   => 'BAR IS BAZ!'    # if no -foo key is provided, use this
    )
);

Class::MOP::Attribute->new(
    bar => (
        reader    => 'bar',           # getter
        writer    => 'set_bar',       # setter
        predicate => 'has_bar',       # predicate check for defined-ness
        init_arg  => ':bar',          # class->new will look for a :bar key
                                      # no default value means it is undef
    )
);

DESCRIPTION

The Attribute Protocol is almost entirely an invention of "Class::MOP". Perl 5 does not have a consistent notion of attributes. There are so
many ways in which this is done, and very few (if any) are easily
discoverable by this module.

With that said, this module attempts to inject some order into this
chaos, by introducing a consistent API which can be used to create
object attributes.

METHODS

Creation: Class::MOP::Attribute->new($name, ?%options)
An attribute must (at the very least), have a $name. All other
%options are added as key-value pairs.

o init_arg

This is a string value representing the expected key in an initialization hash. For instance, if we have an "init_arg" value of "-foo", then the following code will Just Work.

MyClass->meta->new_object( -foo => 'Hello There' );

If an init_arg is not assigned, it will automatically use
the attribute's name. If "init_arg" is explicitly set to
"undef", the attribute cannot be specified during
initialization.
o builder: This provides the name of a method that will be called to
initialize the attribute. This method will be called on the object after it is constructed. It is expected to return a valid value for the attribute.
o default: This can be used to provide an explicit default for
initializing the attribute. If the default you provide is a subroutine reference, then this reference will be called as a method on the object.; If the value is a simple scalar (string or number), then it can be just passed as is. However, if you wish to
initialize it with a HASH or ARRAY ref, then you need to
wrap that inside a subroutine reference:

Class::MOP::Attribute->new(
'foo' => (
default => sub { [] },

)

);

# or ...

Class::MOP::Attribute->new(

'foo' => (

default => sub { {} },

)

);; If you wish to initialize an attribute with a subroutine
reference itself, then you need to wrap that in a
subroutine as well:

Class::MOP::Attribute->new(
'foo' => (
default => sub {
sub { print "Hello World" }

},

)

);; 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 "default"
value is called as a method:

Class::MOP::Attribute->new(
'object_identity' => (
default => sub { Scalar::Util::refaddr( $_[0] ) },

)

);; Note that there is no guarantee that attributes are
initialized in any particular order, so you cannot rely on the value of some other attribute when generating the
default.
o initializer: This option can be either a method name or a subroutine
reference. This method will be called when setting the
attribute's value in the constructor. Unlike "default" and "builder", the initializer is only called when a value is
provided to the constructor. The initializer allows you to munge this value during object construction.; The initializer is called as a method with three arguments. The first is the value that was passed to the constructor. The second is a subroutine reference that can be called to actually set the attribute's value, and the last is the
associated "Class::MOP::Attribute" object.; This contrived example shows an initializer that sets the
attribute to twice the given value.

Class::MOP::Attribute->new(
'doubled' => (
initializer => sub {
my ( $self, $value, $set, $attr ) = @_;
$set->( $value * 2 );

},

)

);; Since an initializer can be a method name, you can easily
make attribute initialization use the writer:

Class::MOP::Attribute->new(
'some_attr' => (
writer => 'some_attr',
initializer => 'some_attr',

)

);; Your writer will need to examine @_ and determine under
which context it is being called.
The "accessor", "reader", "writer", "predicate" and "clearer" options all accept the same parameters. You can provide the name of the method, in which case an appropriate default method will be generated for you. Or instead you can also provide hash reference containing exactly one key (the method name) and one value. The value should be a subroutine reference, which will be installed as the method itself.
o accessor: An "accessor" is a standard Perl-style read/write accessor. It will return the value of the attribute, and if a value
is passed as an argument, it will assign that value to the attribute.; Note that "undef" is a legitimate value, so this will work:

$object->set_something(undef);
o reader: This is a basic read-only accessor. It returns the value of the attribute.
o writer: This is a basic write accessor, it accepts a single
argument, and assigns that value to the attribute.; Note that "undef" is a legitimate value, so this will work:

$object->set_something(undef);
o predicate: The predicate method returns a boolean indicating whether
or not the attribute has been explicitly set.; Note that the predicate returns true even if the attribute was set to a false value (0 or "undef").
o clearer: This method will uninitialize the attribute. After an
attribute is cleared, its "predicate" will return false.
o definition_context: Mostly, this exists as a hook for the benefit of Moose.; This option should be a hash reference containing several
keys which will be used when inlining the attribute's
accessors. The keys should include "line", the line number where the attribute was created, and either "file" or
"description".; This information will ultimately be used when eval'ing
inlined accessor code so that error messages report a
useful line and file name.
$attr->clone(%options): This clones the attribute. Any options you provide will override
the settings of the original attribute. You can change the name of the new attribute by passing a "name" key in %options.
Informational: These are all basic read-only accessors for the values passed into the constructor.; $attr->name
Returns the attribute's name.; $attr->accessor
$attr->reader
$attr->writer
$attr->predicate
$attr->clearer
The "accessor", "reader", "writer", "predicate", and "clearer"
methods all return exactly what was passed to the constructor, so
it can be either a string containing a method name, or a hash
reference.; $attr->initializer
Returns the initializer as passed to the constructor, so this may
be either a method name or a subroutine reference.; $attr->init_arg
$attr->is_default_a_coderef $attr->default($instance)
The $instance argument is optional. If you don't pass it, the
return value for this method is exactly what was passed to the
constructor, either a simple scalar or a subroutine reference.

If you do pass an $instance and the default is a subroutine
reference, then the reference is called as a method on the
$instance and the generated value is returned.; $attr->slots
Return a list of slots required by the attribute. This is usually
just one, the name of the attribute.

A slot is the name of the hash key used to store the attribute in
an object instance.; $attr->get_read_method
$attr->get_write_method
Returns the name of a method suitable for reading or writing the
value of the attribute in the associated class.

If an attribute is read- or write-only, then these methods can
return "undef" as appropriate.; $attr->has_read_method
$attr->has_write_method
This returns a boolean indicating whether the attribute has a named read or write method.; $attr->get_read_method_ref $attr->get_write_method_ref
Returns the subroutine reference of a method suitable for reading
or writing the attribute's value in the associated class. These
methods always return a subroutine reference, regardless of whether or not the attribute is read- or write-only.; $attr->insertion_order
If this attribute has been inserted into a class, this returns a
zero based index regarding the order of insertion.
Informational predicates: These are all basic predicate methods for the values passed into "new".; $attr->has_accessor
$attr->has_reader
$attr->has_writer
$attr->has_predicate
$attr->has_clearer
$attr->has_initializer
$attr->has_init_arg
This will be false if the "init_arg" was set to "undef".; $attr->has_default
This will be false if the "default" was set to "undef", since "undef" is the default "default" anyway.; $attr->has_builder
$attr->has_insertion_order
This will be false if this attribute has not be inserted into a class
Value management: These methods are basically "back doors" to the instance, and can be
used to bypass the regular accessors, but still stay within the MOP.; These methods are not for general use, and should only be used if you
really know what you are doing.; $attr->initialize_instance_slot($meta_instance, $$iinnssttaannccee, $params)
This method is used internally to initialize the attribute's slot
in the object $instance.

The $params is a hash reference of the values passed to the object constructor.

It's unlikely that you'll need to call this method yourself.; $attr->set_value($instance, $$vvaalluuee)
Sets the value without going through the accessor. Note that this
works even with read-only attributes.; $attr->set_raw_value($instance, $$vvaalluuee)
Sets the value with no side effects such as a trigger.

This doesn't actually apply to Class::MOP attributes, only to
subclasses.; $attr->set_initial_value($instance, $$vvaalluuee)
Sets the value without going through the accessor. This method is
only called when the instance is first being initialized.; $attr->get_value($instance)
Returns the value without going through the accessor. Note that
this works even with write-only accessors.; $attr->get_raw_value($instance)
Returns the value without any side effects such as lazy attributes.

Doesn't actually apply to Class::MOP attributes, only to
subclasses.; $attr->has_value($instance)
Return a boolean indicating whether the attribute has been set in
$instance. This how the default "predicate" method works.; $attr->clear_value($instance)
This will clear the attribute's value in $instance. This is what
the default "clearer" calls.

Note that this works even if the attribute does not have any
associated read, write or clear methods.
Class association: These methods allow you to manage the attributes association with the
class that contains it. These methods should not be used lightly, nor
are they very magical, they are mostly used internally and by metaclass instances.; $attr->associated_class
This returns the "Class::MOP::Class" with which this attribute is
associated, if any.; $attr->attach_to_class($metaclass)
This method stores a weakened reference to the $metaclass object
internally.

This method does not remove the attribute from its old class, nor
does it create any accessors in the new class.

It is probably best to use the Class::MOP::Class "add_attribute"
method instead.; $attr->detach_from_class
This method removes the associate metaclass object from the
attribute it has one.

This method does not remove the attribute itself from the class, or remove its accessors.

It is probably best to use the Class::MOP::Class "remove_attribute" method instead.
Attribute Accessor generation: $attr->accessor_metaclass
Accessor methods are generated using an accessor metaclass. By
default, this is Class::MOP::Method::Accessor. This method returns the name of the accessor metaclass that this attribute uses.; $attr->associate_method($method)
This associates a Class::MOP::Method object with the attribute.
Typically, this is called internally when an attribute generates
its accessors.; $attr->associated_methods
This returns the list of methods which have been associated with
the attribute.; $attr->install_accessors
This method generates and installs code the attributes various
accessors. It is typically called from the Class::MOP::Class
"add_attribute" method.; $attr->remove_accessors
This method removes all of the accessors associated with the
attribute.

This does not currently remove methods from the list returned by
"associated_methods".
Introspection: Class::MOP::Attribute->meta
This will return a Class::MOP::Class instance for this class.

It should also be noted that Class::MOP will actually bootstrap
this module by installing a number of attribute meta-objects into
its metaclass.

AUTHORS

Stevan Little <stevan@iinteractive.com>

COPYRIGHT AND LICENSE

<http://www.iinteractive.com>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

docs.sk

komplexný repozitár dokumentácie