Provided by: libmoose-perl_2.2009-1_amd64 bug

NAME

       Class::MOP::Attribute - Attribute Meta Object

VERSION

       version 2.2009

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 the attributes various 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.little@iinteractive.com>

       •   Dave Rolsky <autarch@urth.org>

       •   Jesse Luehrs <doy@tozt.net>

       •   Shawn M Moore <code@sartak.org>

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

       •   Karen Etheridge <ether@cpan.org>

       •   Florian Ragwitz <rafl@debian.org>

       •   Hans Dieter Pearcey <hdp@weftsoar.net>

       •   Chris Prather <chris@prather.org>

       •   Matt S Trout <mst@shadowcat.co.uk>

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.