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

FreeBSD Manual Pages

  
 
  

home | help
Class::Accessor::GroupUser)Contributed Perl DocumenClass::Accessor::Grouped(3)

NAME
       Class::Accessor::Grouped	- Lets you build groups	of accessors

SYNOPSIS
	use base 'Class::Accessor::Grouped';

	# make basic accessors for objects
	__PACKAGE__->mk_group_accessors(simple => qw(id	name email));

	# make accessor	that works for objects and classes
	__PACKAGE__->mk_group_accessors(inherited => 'awesome_level');

	# make an accessor which calls a custom	pair of	getters/setters
	sub get_column { ... this will be called when you do $obj->name() ... }
	sub set_column { ... this will be called when you do $obj->name('foo') ... }
	__PACKAGE__->mk_group_accessors(column => 'name');

DESCRIPTION
       This class lets you build groups	of accessors that will call different
       getters and setters. The	documentation of this module still requires a
       lot of work (volunteers welcome >.>), but in the	meantime you can refer
       to this post <http://lo-
       f.at/glahn/2009/08/WritingPowerfulAccessorsForPerlClasses.html> for
       more information.

   Notes on accessor names
       In general method names in Perl are considered identifiers, and as such
       need to conform to the identifier specification of
       "qr/\A[A-Z_a-z][0-9A-Z_a-z]*\z/".  While	it is rather easy to invoke
       methods with non-standard names ("$obj->${\"anything goes"}"), it is
       not possible to properly	declare	such methods without the use of
       Sub::Name. Since	this module must be able to function identically with
       and without its optional	dependencies, starting with version 0.10008
       attempting to declare an	accessor with a	non-standard name is a fatal
       error (such operations would silently succeed since version 0.08004, as
       long as Sub::Name is present, or	otherwise would	result in a syntax
       error during a string eval).

       Unfortunately in	the years since	0.08004	a rather large body of code
       accumulated in the wild that does attempt to declare accessors with
       funny names. One	notable	perpetrator is DBIx::Class::Schema::Loader,
       which under certain conditions could create accessors of	the "column"
       group which start with numbers and/or some other	punctuation (the
       proper way would	be to declare columns with the "accessor" attribute
       set to "undef").

       Therefore an escape mechanism is	provided via the environment variable
       "CAG_ILLEGAL_ACCESSOR_NAME_OK". When set	to a true value, one warning
       is issued per class on attempts to declare an accessor with a non-
       conforming name,	and as long as Sub::Name is available all accessors
       will be properly	created. Regardless of this setting, accessor names
       containing nulls	"\0" are disallowed, due to various deficiencies in
       perl itself.

       If your code base has too many instances	of illegal accessor
       declarations, and a fix is not feasible due to time constraints,	it is
       possible	to disable the warnings	altogether by setting
       $ENV{CAG_ILLEGAL_ACCESSOR_NAME_OK} to "DO_NOT_WARN" (observe
       capitalization).

METHODS
   mk_group_accessors
	__PACKAGE__->mk_group_accessors(simple => 'hair_length', [ hair_color => 'hc' ]);

       Arguments: $group, @fieldspec
	   Returns: none

       Creates a set of	accessors in a given group.

       $group is the name of the accessor group	for the	generated accessors;
       they will call get_$group($field) on get	and set_$group($field, $value)
       on set.

       If you want to mimic Class::Accessor's mk_accessors $group has to be
       'simple'	to tell	Class::Accessor::Grouped to use	its own	get_simple and
       set_simple methods.

       @fieldspec is a list of field/accessor names; if	a fieldspec is a
       scalar this is used as both field and accessor name, if a listref it is
       expected	to be of the form [ $accessor, $field ].

   mk_group_ro_accessors
	__PACKAGE__->mk_group_ro_accessors(simple => 'birthdate', [ social_security_number => 'ssn' ]);

       Arguments: $group, @fieldspec
	   Returns: none

       Creates a set of	read only accessors in a given group. Identical	to
       "mk_group_accessors" but	accessors will throw an	error if passed	a
       value rather than setting the value.

   mk_group_wo_accessors
	__PACKAGE__->mk_group_wo_accessors(simple => 'lie', [ subject => 'subj'	]);

       Arguments: $group, @fieldspec
	   Returns: none

       Creates a set of	write only accessors in	a given	group. Identical to
       "mk_group_accessors" but	accessors will throw an	error if not passed a
       value rather than getting the value.

   get_simple
       Arguments: $field
	   Returns: $value

       Simple getter for hash-based objects which returns the value for	the
       field name passed as an argument.

   set_simple
       Arguments: $field, $new_value
	   Returns: $new_value

       Simple setter for hash-based objects which sets and then	returns	the
       value for the field name	passed as an argument.

   get_inherited
       Arguments: $field
	   Returns: $value

       Simple getter for Classes and hash-based	objects	which returns the
       value for the field name	passed as an argument. This behaves much like
       Class::Data::Accessor where the field can be set	in a base class,
       inherited and changed in	subclasses, and	inherited and changed for
       object instances.

   set_inherited
       Arguments: $field, $new_value
	   Returns: $new_value

       Simple setter for Classes and hash-based	objects	which sets and then
       returns the value for the field name passed as an argument. When	called
       on a hash-based object it will set the appropriate hash key value. When
       called on a class, it will set a	class level variable.

       Note:: This method will die if you try to set an	object variable	on a
       non hash-based object.

   get_component_class
       Arguments: $field
	   Returns: $value

       Gets the	value of the specified component class.

	__PACKAGE__->mk_group_accessors('component_class' => 'result_class');

	$self->result_class->method();

	## same	as
	$self->get_component_class('result_class')->method();

   set_component_class
       Arguments: $field, $class
	   Returns: $new_value

       Inherited accessor that automatically loads the specified class before
       setting it. This	method will die	if the specified class could not be
       loaded.

	__PACKAGE__->mk_group_accessors('component_class' => 'result_class');
	__PACKAGE__->result_class('MyClass');

	$self->result_class->method();

INTERNAL METHODS
       These methods are documented for	clarity, but are never meant to	be
       called directly,	and are	not really meant for overriding	either.

   get_super_paths
       Returns a list of 'parent' or 'super' class names that the current
       class inherited from. This is what drives the traversal done by
       "get_inherited".

   make_group_accessor
	__PACKAGE__->make_group_accessor('simple', 'hair_length', 'hair_length');
	__PACKAGE__->make_group_accessor('simple', 'hc', 'hair_color');

       Arguments: $group, $field, $accessor
	   Returns: \&accessor_coderef ?

       Called by mk_group_accessors for	each entry in @fieldspec. Either
       returns a coderef which will be installed at "&__PACKAGE__::$accessor",
       or returns "undef" if it	elects to install the coderef on its own.

   make_group_ro_accessor
	__PACKAGE__->make_group_ro_accessor('simple', 'birthdate', 'birthdate');
	__PACKAGE__->make_group_ro_accessor('simple', 'ssn', 'social_security_number');

       Arguments: $group, $field, $accessor
	   Returns: \&accessor_coderef ?

       Called by mk_group_ro_accessors for each	entry in @fieldspec. Either
       returns a coderef which will be installed at "&__PACKAGE__::$accessor",
       or returns "undef" if it	elects to install the coderef on its own.

   make_group_wo_accessor
	__PACKAGE__->make_group_wo_accessor('simple', 'lie', 'lie');
	__PACKAGE__->make_group_wo_accessor('simple', 'subj', 'subject');

       Arguments: $group, $field, $accessor
	   Returns: \&accessor_coderef ?

       Called by mk_group_wo_accessors for each	entry in @fieldspec. Either
       returns a coderef which will be installed at "&__PACKAGE__::$accessor",
       or returns "undef" if it	elects to install the coderef on its own.

PERFORMANCE
       To provide total	flexibility Class::Accessor::Grouped calls methods
       internally while	performing get/set actions, which makes	it noticeably
       slower than similar modules. To compensate, this	module will
       automatically use the insanely fast Class::XSAccessor to	generate the
       "simple"-group accessors	if this	module is available on your system.

   Benchmark
       This is the benchmark of	200 get/get/set/get/set	cycles on perl 5.16.2
       with thread support, showcasing how this	modules	simple (CAG_S),
       inherited (CAG_INH) and inherited with parent-class data	(CAG_INHP)
       accessors stack up against most popular accessor	builders:  Moose, Moo,
       Mo, Mouse (both pure-perl and XS	variant), Object::Tiny::RW (OTRW),
       Class::Accessor (CA), Class::Accessor::Lite (CAL),
       Class::Accessor::Fast (CAF), Class::Accessor::Fast::XS (CAF_XS) and
       Class::XSAccessor (XSA)

			     Rate CAG_INHP CAG_INH     CA  CAG_S    CAF	 moOse	 OTRW	 CAL	 mo  moUse HANDMADE    moo CAF_XS moUse_XS    XSA

	CAG_INHP  287.021+-0.02/s	--   -0.3% -10.0% -37.1% -53.1%	-53.6% -53.7% -54.1% -56.9% -59.0%   -59.6% -59.8% -78.7%   -81.9% -83.5%

	CAG_INH	 288.025+-0.031/s     0.3%	--  -9.7% -36.9% -52.9%	-53.5% -53.5% -53.9% -56.7% -58.8%   -59.5% -59.7% -78.6%   -81.9% -83.5%

	CA	 318.967+-0.047/s    11.1%   10.7%     -- -30.1% -47.9%	-48.5% -48.5% -49.0% -52.1% -54.4%   -55.1% -55.3% -76.3%   -79.9% -81.7%

	CAG_S	 456.107+-0.054/s    58.9%   58.4%  43.0%     -- -25.4%	-26.3% -26.4% -27.0% -31.5% -34.8%   -35.8% -36.1% -66.1%   -71.3% -73.9%

	CAF	 611.745+-0.099/s   113.1%  112.4%  91.8%  34.1%     --	 -1.2%	-1.2%  -2.1%  -8.1% -12.6%   -14.0% -14.3% -54.5%   -61.5% -64.9%

	moOse	 619.051+-0.059/s   115.7%  114.9%  94.1%  35.7%   1.2%	    --	-0.1%  -1.0%  -7.0% -11.6%   -12.9% -13.3% -54.0%   -61.0% -64.5%

	OTRW	   619.475+-0.1/s   115.8%  115.1%  94.2%  35.8%   1.3%	  0.1%	   --  -0.9%  -6.9% -11.5%   -12.9% -13.2% -54.0%   -61.0% -64.5%

	CAL	 625.106+-0.085/s   117.8%  117.0%  96.0%  37.1%   2.2%	  1.0%	 0.9%	  --  -6.1% -10.7%   -12.1% -12.5% -53.5%   -60.6% -64.2%

	mo	   665.44+-0.12/s   131.8%  131.0% 108.6%  45.9%   8.8%	  7.5%	 7.4%	6.5%	 --  -4.9%    -6.4%  -6.8% -50.5%   -58.1% -61.9%

	moUse	    699.9+-0.15/s   143.9%  143.0% 119.4%  53.5%  14.4%	 13.1%	13.0%  12.0%   5.2%	--    -1.6%  -2.0% -48.0%   -55.9% -59.9%

	HANDMADE   710.98+-0.16/s   147.7%  146.8% 122.9%  55.9%  16.2%	 14.9%	14.8%  13.7%   6.8%   1.6%	 --  -0.4% -47.2%   -55.2% -59.2%

	moo	   714.04+-0.13/s   148.8%  147.9% 123.9%  56.6%  16.7%	 15.3%	15.3%  14.2%   7.3%   2.0%     0.4%	-- -46.9%   -55.0% -59.1%

	CAF_XS	 1345.55+-0.051/s   368.8%  367.2% 321.8% 195.0% 120.0%	117.4% 117.2% 115.3% 102.2%  92.2%    89.3%  88.4%     --   -15.3% -22.9%

	moUse_XS    1588+-0.036/s   453.3%  451.3% 397.9% 248.2% 159.6%	156.5% 156.3% 154.0% 138.6% 126.9%   123.4% 122.4%  18.0%	--  -9.0%

	XSA	 1744.67+-0.052/s   507.9%  505.7% 447.0% 282.5% 185.2%	181.8% 181.6% 179.1% 162.2% 149.3%   145.4% 144.3%  29.7%     9.9%     --

       Benchmarking program is available in the	root of	the repository
       <http://search.cpan.org/dist/Class-Accessor-Grouped/>:

   Notes on Class::XSAccessor
       You can force (or disable) the use of Class::XSAccessor before creating
       a particular "simple" accessor by either	manipulating the global
       variable	$Class::Accessor::Grouped::USE_XS to true or false (preferably
       with localization, or you can do	so before runtime via the "CAG_USE_XS"
       environment variable.

       Since Class::XSAccessor has no knowledge	of "get_simple"	and
       "set_simple" this module	does its best to detect	if you are overriding
       one of these methods and	will fall back to using	the perl version of
       the accessor in order to	maintain consistency. However be aware that if
       you enable use of "Class::XSAccessor" (automatically or explicitly),
       create an object, invoke	a simple accessor on that object, and then
       manipulate the symbol table to install a	"get/set_simple" override -
       you get to keep all the pieces.

AUTHORS
       Matt S. Trout <mst@shadowcatsystems.co.uk>

       Christopher H. Laco <claco@chrislaco.com>

CONTRIBUTORS
       Caelum: Rafael Kitover <rkitover@cpan.org>

       frew: Arthur Axel "fREW"	Schmidt	<frioux@gmail.com>

       groditi:	Guillermo Roditi <groditi@cpan.org>

       Jason Plum <jason.plum@bmmsi.com>

       ribasushi: Peter	Rabbitson <ribasushi@cpan.org>

COPYRIGHT & LICENSE
       Copyright (c) 2006-2010 Matt S. Trout <mst@shadowcatsystems.co.uk>

       This program is free software; you can redistribute it and/or modify it
       under the same terms as perl itself.

perl v5.24.1			  2014-10-05	   Class::Accessor::Grouped(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | INTERNAL METHODS | PERFORMANCE | AUTHORS | CONTRIBUTORS | COPYRIGHT & LICENSE

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

home | help