NAME¶
Moose::Meta::Attribute - The Moose attribute metaclass
VERSION¶
version 2.0603
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(%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) 2012 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.