phpman > perldoc > Moose::Meta::Attribute(3pm)

NAME
    Moose::Meta::Attribute - The Moose attribute metaclass

VERSION
    version 2.2200

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 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 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 Moose::Meta::Attribute::Native 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 Moose::Meta::Role::Attribute 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 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->role_attribute
        Returns the Moose::Meta::Role::Attribute 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.

BUGS
    See "BUGS" in Moose for details on reporting bugs.

AUTHORS
    *   Stevan Little <stevan AT cpan.org>

    *   Dave Rolsky <autarch AT urth.org>

    *   Jesse Luehrs <doy AT cpan.org>

    *   Shawn M Moore <sartak AT cpan.org>

    *   יובל קוג'מן (Yuval Kogman) <nothingmuch AT woobling.org>

    *   Karen Etheridge <ether AT cpan.org>

    *   Florian Ragwitz <rafl AT debian.org>

    *   Hans Dieter Pearcey <hdp AT cpan.org>

    *   Chris Prather <chris AT prather.org>

    *   Matt S Trout <mstrout AT cpan.org>

COPYRIGHT AND LICENSE
    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.