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

FreeBSD Manual Pages

  
 
  

home | help
Class::Accessor::ComplUser)Contributed Perl DocumenClass::Accessor::Complex(3)

NAME
       Class::Accessor::Complex	- Arrays, hashes, booleans, integers, sets and
       more

VERSION
       version 1.100880

SYNOPSIS
	 package MyClass;
	 use base 'Class::Accessor::Complex';
	 __PACKAGE__
	     ->mk_new
	     ->mk_array_accessors(qw(an_array))
	     ->mk_hash_accessors(qw(a_hash))
	     ->mk_integer_accessors(qw(an_integer))
	     ->mk_class_hash_accessors(qw(a_hash))
	     ->mk_set_accessors(qw(testset))
	     ->mk_object_accessors('Some::Foo' => {
		 slot => 'an_object',
		 comp_mthds => [ qw(do_this do_that) ]
	     });

DESCRIPTION
       This module generates accessors for your	class in the same spirit as
       Class::Accessor does. While the latter deals with accessors for scalar
       values, this module provides accessor makers for	arrays,	hashes,
       integers, booleans, sets	and more.

       As seen in the synopsis,	you can	chain calls to the accessor makers.
       Also, because this module inherits from Class::Accessor,	you can	put a
       call to one of its accessor makers at the end of	the chain.

       The accessor generators also generate documentation ready to be used
       with Sub::Documentation.

METHODS
   mk_new
       Takes an	array of strings as its	argument. If no	argument is given, it
       uses "new" as the default. For each string it creates a constructor of
       that name.  The constructor accepts named arguments - that is, a	hash -
       and will	set the	hash values on the accessor methods denoted by the
       keys. For example,

	   package MyClass;
	   use base 'Class::Accessor::Complex';
	   __PACKAGE__->mk_new;

	   package main;
	   use MyClass;

	   my $o = MyClass->new(foo => 12, bar => [ 1..5 ]);

       is the same as

	   my $o = MyClass->new;
	   $o->foo(12);
	   $o->bar([1..5]);

       The constructor will also call an "init()" method, if there is one.

   mk_singleton
       Takes an	array of strings as its	argument. If no	argument is given, it
       uses "new" as the default. For each string it creates a constructor of
       that name.

       This constructor	only ever returns a single instance of the class. That
       is, after the first call, repeated calls	to this	constructor return the
       same instance.  Note that the instance is instantiated at the time of
       the first call, not before. Any arguments are treated as	for
       "mk_new()".  Naturally, "init()"	and any	initializer methods are	called
       only by the first invocation of this method.

   mk_scalar_accessors
       Takes an	array of strings as its	argument. For each string it creates
       methods as described below, where "*" denotes the slot name.

       "*" This	method can store a value in a slot and retrieve	that value. If
	   it receives an argument, it sets the	value. Only the	first argument
	   is used, subsequent arguments are ignored. If called	without	a
	   value, the method retrieves the value from the slot.

       *_clear,	"clear_*"
	   Clears the value by setting it to undef.

   mk_class_scalar_accessors
       Takes an	array of strings as its	argument. For each string it creates
       methods like those generated with "mk_scalar_accessors()", except that
       it is a class scalar, i.e. shared by all	instances of the class.

   mk_concat_accessors
       Takes an	array of strings as its	argument. For each string it creates
       methods as described below, where "*" denotes the slot name.

       "*" Like	"mk_scalar_accessors()", but passing a value to	the accessor
	   doesn't clear out the original value, but instead concatenates the
	   new value to	the existing one. Thus,	this kind of accessor is only
	   good	for plain scalars.

       *_clear,	"clear_*"
	   Clears the value by setting it to undef.

   mk_array_accessors
       Takes an	array of strings as its	argument. For each string it creates
       methods as described below, where "*" denotes the slot name.

       "*" This	method returns the list	of values stored in the	slot. If any
	   arguments are provided to this method, they replace the current
	   list	contents. In an	array context it returns the values as an
	   array and in	a scalar context as a reference	to the array. Note
	   that	this reference is currently a direct reference to the storage;
	   changes to the storage will affect the contents of the reference,
	   and vice-versa. This	behaviour is not guaranteed; caveat emptor.

       *_push, "push_*"
	   Pushes the given elements onto the end of the array.	Like perl's
	   "push()".

       *_pop, "pop_*"
	   Pops	one element off	the end	of the array. Like perl's "pop()".

       *_shift,	"shift_*"
	   Shifts one element off the beginning	of the array. Like perl's
	   "shift()".

       *_unshift, "unshift_*"
	   Unshifts the	given elements onto the	beginning of the array.	Like
	   perl's "unshift()".

       *_splice, "splice_*"
	   Takes an offset, a length and a replacement list. The arguments and
	   behaviour are exactly like perl's "splice()".

       *_clear,	"clear_*"
	   Deletes all elements	of the array.

       *_count,	"count_*"
	   Returns the number of elements in the array.

       *_set, "set_*"
	   Takes a list, treated as pairs of index => value; each given	index
	   is set to the corresponding value. No return.

       *_index,	"index_*"
	   Takes a list	of indices and returns a list of the corresponding
	   values. This	is like	an array slice.

   mk_class_array_accessors
       Takes an	array of strings as its	argument. For each string it creates
       methods like those generated with "mk_array_accessors()", except	that
       it is a class hash, i.e.	shared by all instances	of the class.

   mk_hash_accessors
       Takes an	array of strings as its	argument. For each string it creates
       methods as described below, where "*" denotes the slot name.

       "*" Called with no arguments returns the	hash stored in the slot, as a
	   hash	in a list context or as	a reference in a scalar	context.

	   Called with one simple scalar argument it treats the	argument as a
	   key and returns the value stored under that key.

	   Called with one array (list)	reference argument, the	array elements
	   are considered to be	be keys	of the hash. x returns the list	of
	   values stored under those keys (also	known as a hash	slice.)

	   Called with one hash	reference argument, the	keys and values	of the
	   hash	are added to the hash.

	   Called with more than one argument, treats them as a	series of
	   key/value pairs and adds them to the	hash.

       *_keys, "keys_*"
	   Returns the keys of the hash.

       *_count,	"count_*"
	   Returns the number of keys in the hash.

       *_values, "values_*"
	   Returns the list of values.

       *_exists, "exists_*"
	   Takes a single key and returns whether that key exists in the hash.

       *_delete, "delete_*"
	   Takes a list	and deletes each key from the hash.

       *_clear,	"clear_*"
	   Resets the hash to empty.

   mk_class_hash_accessors
       Takes an	array of strings as its	argument. For each string it creates
       methods like those generated with "mk_hash_accessors()",	except that it
       is a class hash,	i.e. shared by all instances of	the class.

   mk_abstract_accessors
       Takes an	array of strings as its	argument. For each string it creates
       methods as described below, where "*" denotes the slot name.

       "*" When	called,	it either dies (if Error::Hierarchy is not installed)
	   or throws an	exception of type
	   Error::Hierarchy::Internal::AbstractMethod (if it is	installed).

   mk_boolean_accessors
       Takes an	array of strings as its	argument. For each string it creates
       methods as described below, where "*" denotes the slot name.

       "*" If given a true value - in the Perl sense, i.e. anything except
	   "undef", 0 or the empty string - it sets the	slot's value to	1,
	   otherwise to	0. If no argument is given, it returns the slot's
	   value.

       *_set, "set_*"
	   Sets	the slot's value to 1.

       *_clear,	"clear_*"
	   Sets	the slot's value to 0.

   mk_integer_accessors
	   __PACKAGE__->mk_integer_accessors(qw(some_counter other_index));

       Takes a list of accessor	base names (simple strings). For each string
       it creates methods as described below, where "*"	denotes	the accessor
       base name.

       "*" A basic getter/setter that stores an	integer	value. Actually, it
	   can store any value,	but when read back, it returns 0 if the	value
	   is undef.

       *_reset,	"reset_*"
	   Resets the slot's value to 0.

       *_inc, "inc_*"
	   Increments the value, then returns it.

       *_dec, "dec_*"
	   Decrements the value, then returns it.

       Example:

	 package Foo;

	 use base 'Class::Accessor::Complex';
	 __PACKAGE__->mk_integer_accessors(qw(score));

       Then:

	 my $obj = Foo->new(score => 150);
	 my $x = $obj->score_inc;   # is now 151
	 $obj->score_reset;	    # is now 0

   mk_set_accessors
       Takes an	array of strings as its	argument. For each string it creates
       methods as described below, where "*" denotes the slot name.

       A set is	different from a list in that it can contain every value only
       once and	there is no order on the elements (similar to hash keys, for
       example).

       "*" If called without arguments,	it returns the elements	in the set. If
	   called with arguments, it puts those	elements into the set. As
	   such, it is a wrapper over "*_insert()" and "*_elements()".

       *_insert, "insert_*"
	   Inserts the given elements (arguments) into the set.	If you pass an
	   array reference as the first	argument, it is	being dereferenced and
	   used	instead.

       *_elements, "elements_*"
	   Returns the elements	in the set.

       *_delete, "delete_*"
	   Removes the given elements from the list. The order in which	the
	   elements are	returned is not	guaranteed.

       *_clear,	"clear_*"
	   Empties the set.

       *_contains, "contains_*"
	   Given an element, it	returns	whether	the set	contains the element.

       *_is_empty, "is_empty_*"
	   Returns whether or not the set is empty.

       *_size, "size_*"
	   Returns the number of elements in the set.

   mk_object_accessors
	   MyClass->mk_object_accessors(
	       'Foo' =>	'phooey',
	       'Bar' =>	[ qw(bar1 bar2 bar3) ],
	       'Baz' =>	{
		   slot	=> 'foo',
		   comp_mthds => [ qw(bar baz) ]
	       },
	       'Fob' =>	[
		   {
		       slot	  => 'dog',
		       comp_mthds => 'bark',
		   },
		   {
		       slot	  => 'cat',
		       comp_mthds => 'miaow',
		   },
	       ],
	   );

       The main	argument should	be a reference to an array. The	array should
       contain pairs of	class => sub-argument pairs. The sub-arguments parsed
       thus:

       Hash Reference
	   See "Baz" above. The	hash should contain the	following keys:

	   "slot"
	       The name	of the instance	attribute (slot).

	   "comp_mthds"
	       A string	or array reference, naming the methods that will be
	       forwarded directly to the object	in the slot.

       Array Reference
	   As for "String", for	each member of the array. Also works if	each
	   member is a hash reference (see "Fob" above).

       String
	   The name of the instance attribute (slot).

       For each	slot "x", with forwarding methods "y()"	and "z()", the
       following methods are created:

       "x" A get/set method, see "*" below.

       "y" Forwarded onto the object in	slot "x", which	is auto-created	via
	   "new()" if necessary. The "new()", if called, is called without
	   arguments.

       "z" As for "y".

       So, using the example above, a method, "foo()", is created, which can
       get and set the value of	those objects in slot "foo", which will
       generally contain an object of class "Baz". Two additional methods are
       created named "bar()" and "baz()" which result in a call	to the "bar()"
       and "baz()" methods on the "Baz"	object stored in slot "foo".

       Apart from the forwarding methods described above,
       "mk_object_accessors()" creates methods as described below, where "*"
       denotes the slot	name.

       "*" If the accessor is supplied with an object of an appropriate	type,
	   will	set set	the slot to that value.	Else, if the slot has no
	   value, then an object is created by calling "new()" on the
	   appropriate class, passing in any supplied arguments.

	   The stored object is	then returned.

       *_clear,	"clear_*"
	   Removes the object from the accessor.

   mk_forward_accessors
	   __PACKAGE__->mk_forward_accessors(
	       comp1 =>	'method1',
	       comp2 =>	[ qw(method2 method3) ],
	   );

       Takes a hash of mappings	as its arguments. Each hash value is expected
       to be either a string or	an array reference. For	each hash value	an
       accessor	is created and forwarded to the	accessor denoted by its
       associated hash key.

       In the example above, a call to "method1()" will	be forwarded onto
       "comp1()", and calls to "method2()" and "method3()" will	be forwarded
       onto "comp2()".

INSTALLATION
       See perlmodinstall for information and options on installing Perl
       modules.

BUGS AND LIMITATIONS
       No bugs have been reported.

       Please report any bugs or feature requests through the web interface at
       <http://rt.cpan.org/Public/Dist/Display.html?Name=Class-Accessor-Complex>.

AVAILABILITY
       The latest version of this module is available from the Comprehensive
       Perl Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find
       a CPAN site near	you, or	see
       <http://search.cpan.org/dist/Class-Accessor-Complex/>.

       The development version lives at
       <http://github.com/hanekomu/Class-Accessor-Complex/>.  Instead of
       sending patches,	please fork this project using the standard git	and
       github infrastructure.

AUTHOR
	 Marcel	Gruenauer <marcel@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2007 by Marcel Gruenauer.

       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			  2010-03-29	   Class::Accessor::Complex(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | INSTALLATION | BUGS AND LIMITATIONS | AVAILABILITY | AUTHOR | COPYRIGHT AND LICENSE

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

home | help