Moose::Meta::AttributeUser Contributed Perl DocumentaMoose::Meta::Attribute(3)NAMEMoose::Meta::Attribute - The Moose attribute metaclass
VERSION
version 2.1005
DESCRIPTION
This class is a subclass of Class::MOP::Attribute that provides
additional Moose-specific functionality.
To really understand this class, you will need to start with the
Class::MOP::Attribute documentation. This class can be understood as a
set of additional features on top of the basic feature provided by that
parent class.
INHERITANCE
"Moose::Meta::Attribute" is a subclass of Class::MOP::Attribute.
METHODS
Many of the documented below override methods in Class::MOP::Attribute
and add Moose specific features.
Creation
Moose::Meta::Attribute->new($name, %options)
This method overrides the Class::MOP::Attribute constructor.
Many of the options below are described in more detail in the
Moose::Manual::Attributes document.
It adds the following options to the constructor:
· is => 'ro', 'rw', 'bare'
This provides a shorthand for specifying the "reader",
"writer", or "accessor" names. If the attribute is read-
only ('ro') then it will have a "reader" method with the
same attribute as the name.
If it is read-write ('rw') then it will have an "accessor"
method with the same name. If you provide an explicit
"writer" for a read-write attribute, then you will have a
"reader" with the same name as the attribute, and a
"writer" with the name you provided.
Use 'bare' when you are deliberately not installing any
methods (accessor, reader, etc.) associated with this
attribute; otherwise, Moose will issue a deprecation
warning when this attribute is added to a metaclass.
· isa => $type
This option accepts a type. The type can be a string, which
should be a type name. If the type name is unknown, it is
assumed to be a class name.
This option can also accept a Moose::Meta::TypeConstraint
object.
If you also provide a "does" option, then your "isa" option
must be a class name, and that class must do the role
specified with "does".
· does => $role
This is short-hand for saying that the attribute's type
must be an object which does the named role.
· coerce => $bool
This option is only valid for objects with a type
constraint ("isa") that defined a coercion. If this is
true, then coercions will be applied whenever this
attribute is set.
You can make both this and the "weak_ref" option true.
· trigger => $sub
This option accepts a subroutine reference, which will be
called after the attribute is set.
· required => $bool
An attribute which is required must be provided to the
constructor. An attribute which is required can also have a
"default" or "builder", which will satisfy its required-
ness.
A required attribute must have a "default", "builder" or a
non-"undef" "init_arg"
· lazy => $bool
A lazy attribute must have a "default" or "builder". When
an attribute is lazy, the default value will not be
calculated until the attribute is read.
· weak_ref => $bool
If this is true, the attribute's value will be stored as a
weak reference.
· auto_deref => $bool
If this is true, then the reader will dereference the value
when it is called. The attribute must have a type
constraint which defines the attribute as an array or hash
reference.
· lazy_build => $bool
Setting this to true makes the attribute lazy and provides
a number of default methods.
has 'size' => (
is => 'ro',
lazy_build => 1,
);
is equivalent to this:
has 'size' => (
is => 'ro',
lazy => 1,
builder => '_build_size',
clearer => 'clear_size',
predicate => 'has_size',
);
If your attribute name starts with an underscore ("_"),
then the clearer and predicate will as well:
has '_size' => (
is => 'ro',
lazy_build => 1,
);
becomes:
has '_size' => (
is => 'ro',
lazy => 1,
builder => '_build__size',
clearer => '_clear_size',
predicate => '_has_size',
);
Note the doubled underscore in the builder name.
Internally, Moose simply prepends the attribute name with
"_build_" to come up with the builder name.
· documentation
An arbitrary string that can be retrieved later by calling
"$attr->documentation".
$attr->clone(%options)
This creates a new attribute based on attribute being cloned. You
must supply a "name" option to provide a new name for the
attribute.
The %options can only specify options handled by
Class::MOP::Attribute.
Value management
$attr->initialize_instance_slot($meta_instance, $instance, $params)
This method is used internally to initialize the attribute's slot
in the object $instance.
This overrides the Class::MOP::Attribute method to handle lazy
attributes, weak references, and type constraints.
get_value
set_value
eval { $point->meta->get_attribute('x')->set_value($point, 'forty-two') };
if($@) {
print "Oops: $@\n";
}
Attribute (x) does not pass the type constraint (Int) with
'forty-two'
Before setting the value, a check is made on the type constraint of
the attribute, if it has one, to see if the value passes it. If the
value fails to pass, the set operation dies.
Any coercion to convert values is done before checking the type
constraint.
To check a value against a type constraint before setting it, fetch
the attribute instance using "find_attribute_by_name" in
Class::MOP::Class, fetch the type_constraint from the attribute
using "type_constraint" in Moose::Meta::Attribute and call "check"
in Moose::Meta::TypeConstraint. See
Moose::Cookbook::Basics::Company_Subtypes for an example.
Attribute Accessor generation
$attr->install_accessors
This method overrides the parent to also install delegation
methods.
If, after installing all methods, the attribute object has no
associated methods, it throws an error unless "is => 'bare'" was
passed to the attribute constructor. (Trying to add an attribute
that has no associated methods is almost always an error.)
$attr->remove_accessors
This method overrides the parent to also remove delegation methods.
$attr->inline_set($instance_var, $value_var)
This method return a code snippet suitable for inlining the
relevant operation. It expect strings containing variable names to
be used in the inlining, like '$self' or '$_[1]'.
$attr->install_delegation
This method adds its delegation methods to the attribute's
associated class, if it has any to add.
$attr->remove_delegation
This method remove its delegation methods from the attribute's
associated class.
$attr->accessor_metaclass
Returns the accessor metaclass name, which defaults to
Moose::Meta::Method::Accessor.
$attr->delegation_metaclass
Returns the delegation metaclass name, which defaults to
Moose::Meta::Method::Delegation.
Additional Moose features
These methods are not found in the superclass. They support features
provided by Moose.
$attr->does($role)
This indicates whether the attribute itself does the given role.
The role can be given as a full class name, or as a resolvable
trait name.
Note that this checks the attribute itself, not its type
constraint, so it is checking the attribute's metaclass and any
traits applied to the attribute.
Moose::Meta::Class->interpolate_class_and_new($name, %options)
This is an alternate constructor that handles the "metaclass" and
"traits" options.
Effectively, this method is a factory that finds or creates the
appropriate class for the given "metaclass" and/or "traits".
Once it has the appropriate class, it will call "$class->new($name,
%options)" on that class.
$attr->clone_and_inherit_options(%options)
This method supports the "has '+foo'" feature. It does various bits
of processing on the supplied %options before ultimately calling
the "clone" method.
One of its main tasks is to make sure that the %options provided
does not include the options returned by the
"illegal_options_for_inheritance" method.
$attr->illegal_options_for_inheritance
This returns a blacklist of options that can not be overridden in a
subclass's attribute definition.
This exists to allow a custom metaclass to change or add to the
list of options which can not be changed.
$attr->type_constraint
Returns the Moose::Meta::TypeConstraint object for this attribute,
if it has one.
$attr->has_type_constraint
Returns true if this attribute has a type constraint.
$attr->verify_against_type_constraint($value)
Given a value, this method returns true if the value is valid for
the attribute's type constraint. If the value is not valid, it
throws an error.
$attr->handles
This returns the value of the "handles" option passed to the
constructor.
$attr->has_handles
Returns true if this attribute performs delegation.
$attr->is_weak_ref
Returns true if this attribute stores its value as a weak
reference.
$attr->is_required
Returns true if this attribute is required to have a value.
$attr->is_lazy
Returns true if this attribute is lazy.
$attr->is_lazy_build
Returns true if the "lazy_build" option was true when passed to the
constructor.
$attr->should_coerce
Returns true if the "coerce" option passed to the constructor was
true.
$attr->should_auto_deref
Returns true if the "auto_deref" option passed to the constructor
was true.
$attr->trigger
This is the subroutine reference that was in the "trigger" option
passed to the constructor, if any.
$attr->has_trigger
Returns true if this attribute has a trigger set.
$attr->documentation
Returns the value that was in the "documentation" option passed to
the constructor, if any.
$attr->has_documentation
Returns true if this attribute has any documentation.
$attr->applied_traits
This returns an array reference of all the traits which were
applied to this attribute. If none were applied, this returns
"undef".
$attr->has_applied_traits
Returns true if this attribute has any traits applied.
BUGS
See "BUGS" in Moose for details on reporting bugs.
AUTHOR
Moose is maintained by the Moose Cabal, along with the help of many
contributors. See "CABAL" in Moose and "CONTRIBUTORS" in Moose for
details.
COPYRIGHT AND LICENSE
This software is copyright (c) 2013 by Infinity Interactive, Inc..
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
perl v5.18.1 2013-08-07 Moose::Meta::Attribute(3)
