Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Class::MOP::Attribute(User Contributed Perl DocumentatClass::MOP::Attribute(3)

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

VERSION
       version 2.2013

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.

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

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

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

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

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

	   o	   reader

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

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

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

	   o	   clearer

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

	   o	   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
       o   Stevan Little <stevan.little@iinteractive.com>

       o   Dave	Rolsky <autarch@urth.org>

       o   Jesse Luehrs	<doy@tozt.net>

       o   Shawn M Moore <code@sartak.org>

       o   xxxx	x<section>xx'xx	(Yuval Kogman) <nothingmuch@woobling.org>

       o   Karen Etheridge <ether@cpan.org>

       o   Florian Ragwitz <rafl@debian.org>

       o   Hans	Dieter Pearcey <hdp@weftsoar.net>

       o   Chris Prather <chris@prather.org>

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

perl v5.32.0			  2020-07-21	      Class::MOP::Attribute(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | AUTHORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Class::MOP::Attribute&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help