Moose::Meta::Attribute - The Moose attribute metaclass
version 2.2201
This class is a subclass of the Class::MOP::Attribute manpage that provides
additional Moose-specific functionality.
To really understand this class, you will need to start with the
the Class::MOP::Attribute manpage documentation. This class can be understood
as a set of additional features on top of the basic feature provided
by that parent class.
Moose::Meta::Attribute is a subclass of the Class::MOP::Attribute manpage.
Many of the documented below override methods in
the Class::MOP::Attribute manpage and add Moose specific features.
- Moose::Meta::Attribute->new($name, %options)
-
This method overrides the the Class::MOP::Attribute manpage constructor.
Many of the options below are described in more detail in the
the Moose::Manual::Attributes manpage 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 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 the Moose::Meta::TypeConstraint manpage 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 cannot 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.
- documentation
An arbitrary string that can be retrieved later by calling <
$attr-documentation >>.
- auto_deref => $bool
Note that in cases where you want this feature you are often better served
by using a the Moose::Meta::Attribute::Native manpage trait instead.
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
Note that use of this feature is strongly discouraged. Some documentation
used to encourage use of this feature as a best practice, but we have changed
our minds.
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.
- role_attribute => $role_attribute
If provided, this should be a the Moose::Meta::Role::Attribute manpage object.
- $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
the Class::MOP::Attribute manpage.
- $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 the Class::MOP::Attribute manpage 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 the Class::MOP::Class manpage,
fetch the type_constraint from the attribute using type_constraint in the Moose::Meta::Attribute manpage
and call check in the Moose::Meta::TypeConstraint manpage. See the Moose::Cookbook::Basics::Company_Subtypes manpage
for an example.
- $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
the Moose::Meta::Method::Accessor manpage.
- $attr->delegation_metaclass
-
Returns the delegation metaclass name, which defaults to
the Moose::Meta::Method::Delegation manpage.
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 the Moose::Meta::TypeConstraint manpage 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 >>$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->role_attribute
-
Returns the the Moose::Meta::Role::Attribute manpage object from which this attribute
was created, if any. This may return
undef.
- $attr->has_role_attribute
-
Returns true if this attribute has an associated role attribute.
- $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.
See Moose/BUGS for details on reporting bugs.
This software is copyright (c) 2006 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.
|