phpMan > perldoc > Class::MOP::Attribute

NAME
    Class::MOP::Attribute - Attribute Meta Object

VERSION
    version 2.2200

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.

        *       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.

        *       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.

        *       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.

        *       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 (actually, a wrapper around the writer, using method modifications) will
                need to examine @_ and determine under which context it is being called:

                  around 'some_attr' => sub {
                      my $orig = shift;
                      my $self = shift;
                      # $value is not defined if being called as a reader
                      # $setter and $attr are only defined if being called as an initializer
                      my ($value, $setter, $attr) = @_;

                      # the reader behaves normally
                      return $self->$orig if not @_;

                      # mutate $value as desired
                      # $value = <something($value);

                      # if called as an initializer, set the value and we're done
                      return $setter->($row) if $setter;

                      # otherwise, call the real writer with the new value
                      $self->$orig($row);
                  };

        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.

        *       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);

        *       reader

                This is a basic read-only accessor. It returns the value of the attribute.

        *       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);

        *       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").

        *       clearer

                This method will uninitialize the attribute. After an attribute is cleared, its
                "predicate" will return false.

        *       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->builder
    $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, $instance, $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, $value)
        Sets the value without going through the accessor. Note that this works even with read-only
        attributes.

    $attr->set_raw_value($instance, $value)
        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, $value)
        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 for the attribute's 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".

    $attr->inline_get
    $attr->inline_set
    $attr->inline_has
    $attr->inline_clear
        These methods return a code snippet suitable for inlining the relevant operation. They
        expect strings containing variable names to be used in the inlining, like '$self' or
        '$_[1]'.

  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 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.