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

FreeBSD Manual Pages

  
 
  

home | help
Class::groups(3)      User Contributed Perl Documentation     Class::groups(3)

NAME
       Class::groups - Pragma to implement group of properties

VERSION	2.40
       Included	in OOTools 2.21	distribution.

       The latest versions changes are reported	in the Changes file in this
       distribution.

       The distribution	includes:

       Package::props
	   Pragma to implement lvalue accessors	with options

       * Package::groups
	   Pragma to implement groups of properties accessors with options

       * Class::constr
	   Pragma to implement constructor methods

       * Class::props
	   Pragma to implement lvalue accessors	with options

       * Class::groups
	   Pragma to implement groups of properties accessors with options

       * Class::Error
	   Delayed checking of object failure

       * Class::Util
	   Class utility functions

       * Object::props
	   Pragma to implement lvalue accessors	with options

       * Object::groups
	   Pragma to implement groups of properties accessors with options

INSTALLATION
       Prerequisites
	       Perl version >= 5.6.1

       CPAN
	       perl -MCPAN -e 'install OOTools'

       Standard	installation
	   From	the directory where this file is located, type:

	       perl Makefile.PL
	       make
	       make test
	       make install

SYNOPSIS
   Class
	   package MyClass ;

	   # implement group method without options
	   use Class::groups qw(this that) ;

	   # implement group method with properties
	   use Class::groups { name  =>	'myGroup' ,
			       props =>	[qw(prop1 prop2)]
			     } ;

	   # with options
	   use Class::groups
	       { name	   => 'myOtherGroup' ,
		 no_strict => 1	,
		 default   => {	aProp => 'some value' }	,
		 pre_process=> sub
				{ if ( ref $_[1] eq 'ARRAY' )
				   { $_[1] = { map { $_=>$_ } @{$_[1]} }
				   }
				} ,
		 props	   => [	{ name	  => [qw(prop3 prop4)] ,
				  default => 'something'
				}
			      ]
	       } ;

   Usage
	   MyClass->myGroup(\%hash) ;

	   # same thing
	   MyClass->myGroup( prop1 => 1	,
			     prop2 => 2	) ;

	   $hash_ref = MyClass->myGroup

	   $value = MyClass->prop2 ;		 # $value == 2
	   $value = MyClass->myGroup('prop2') ;	 # $value == 2
	   $value = $MyClass::myGroup{prop2} ;	 # $value == 2
	   $value = $$hash_ref{prop2} ;		 # $value == 2

	   ($p1, $p2) =	MyClass->myGroup(['prop1','prop2']) ;

	   # the default will initialize the hash reference
	   $other_hash_ref = MyClass->myOtherGroup
	   $value = $other_hash_ref->{prop3}	 # $value eq 'something'

	   # adding an unknow property (see no_strict)
	   MyClass->myOtherGroup(prop5 => 5) ;

	   # copying the whole hash
	   %myGroupHash	= MyClass->myGroup

WARNING
       Don't use the group accessor in list context in order to	retrieve the
       hash keys: that way was deprecated and it doesn't work any more with
       this version.

	   # WRONG
	   @keys     = MyClass->myGroup	;

	   # change it with
	   @keys     = keys %{MyClass->myGroup}	;

	   # new behaviour in list context
	   %hash = MyClass->myGroup ;

DESCRIPTION
       This pragma easily implements accessor methods for group	of properties,
       which are very efficient	function templates that	your modules may
       import at compile time. "This technique saves on	both compile time and
       memory use, and is less error-prone as well, since syntax checks	happen
       at compile time." (quoted from "Function	Templates" in the perlref
       manpage).

       This module allows also "lazy" data computing (see the "default"
       option).

       This module creates an accessor method with a hash in the class that
       implements it (e.g. %Class::any_group) and sets/gets it using the
       options you set;	it also	creates	an accessor method for each property
       in the "props" option as	you were using the Class::props	pragma.

       Note: The grouped properties will be stored in e.g.
       $Class::any_group{any_property} instead of the usual
       $Class::any_property

       With the	accessor method	for the	group you can:

       o   set a group of properties by	passing	an hash	of values to the
	   accessor

       o   retrieve (in	list context) the list of the names of the (already
	   defined) properties of the group

       o   retrieve (in	scalar context)	the reference to the underlying	hash
	   containing the grouped properties.

       Note: The underlaying hash contains:

       o   all the already set properties of the class and base	classes

       o   all the properties with a default option (of	the class and base
	   classes, even if they have not been set yet)

       IMPORTANT NOTE: If you write any	script that rely on this module, you
       better send me an e-mail	so I will inform you in	advance	about eventual
       planned changes,	new releases, and other	relevant issues	that could
       speed-up	your work.

   Examples
       If you want to see some working example of this module, take a look at
       the source of my	other distributions.

OPTIONS
   name	=> $name
       The name	of the group accessor.

   no_strict =>	0 | 1
       With "no_strict"	option set to a	true value, the	accessor accepts and
       sets also unknown properties (i.e. not predeclared). You	have to	access
       the unknown properties without any accessor method. All the other
       options will work as expected. Without this option the method will
       croak if	any property does not have an accessor method.

       Note: This option is on by default if you define	an accessor group
       without any "props" option (i.e.	in this	case you can omit the
       'no_strict' option).

   pre_process => \&code
       You can set a code reference to preprocess @_.

       The original @_ is passed to the	referenced pre_process CODE. Modify @_
       in the CODE to change the actual	input value.

	   # This code will transform the @_ on	input
	   # if	it's passed a ref to an	ARRAY
	   # [ qw|a b c| ] will	become
	   # ( a=>'a', b=>'b', c=>'c')

	   use Class::groups
	       { name	    => 'myGroup' ,
		 pre_process=> sub
				{ if ( ref $_[1] eq 'ARRAY' )
				   { $_[1] = { map { $_=>$_ } @{$_[1]} }
				   }
				}
	       }

   default => \%props |	\&$method
       Use this	option to set a	default	value. The default value must be a
       HASH reference or a CODE	reference.

       If you pass a CODE reference as the default it will be evaluated	only
       when the	group will be accessed,	and only if the	group has no defined
       (HASH) value (this allows "lazy"	data computing and may save some CPU);
       the group will be set to	the HASH reference that	the referenced CODE
       must return.

       You can reset a property	to its default value by	assigning an empty
       HASH reference ({}) to it.

   props => \@props
       This option creates the same properties accessor	methods	as you would
       use directly the	Class::props pragma. It	accepts	a reference to an
       array, containing the same structured parameters	as such	accepted by
       the Class::props	pragma.

METHODS
   add_to( package, groups )
       This will add to	the package package the	accessors for the groups. It
       is useful to add	properties in other packages.

	  package Any::Package;
	  Class::groups->('My::Package', { name	=> 'any_name', ... });

	  # which has the same effect of
	  package My::Package;
	  use Class::groups { name => 'any_name', ... }

SUPPORT	and FEEDBACK
       If you need support or if you want just to send me some feedback	or
       request,	please use this	link: http://perl.4pro.net/?Class::groups.

AUTHOR and COPYRIGHT
       A(C) 2004-2005 by Domizio Demichelis.

       All Rights Reserved. This module	is free	software. It may be used,
       redistributed and/or modified under the same terms as perl itself.

CREDITS
       Thanks to Juerd Waalboer	(http://search.cpan.org/author/JUERD) that
       with its	Attribute::Property inspired the creation of this
       distribution.

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 158:
	   Expected text after =item, not a bullet

       Around line 162:
	   Expected text after =item, not a bullet

       Around line 166:
	   Expected text after =item, not a bullet

       Around line 170:
	   Expected text after =item, not a bullet

       Around line 174:
	   Expected text after =item, not a bullet

       Around line 178:
	   Expected text after =item, not a bullet

       Around line 182:
	   Expected text after =item, not a bullet

       Around line 186:
	   Expected text after =item, not a bullet

       Around line 396:
	   Non-ASCII character seen before =encoding in	'A(C)'.	Assuming
	   CP1252

perl v5.32.0			  2017-04-19		      Class::groups(3)

NAME | VERSION 2.40 | INSTALLATION | SYNOPSIS | WARNING | DESCRIPTION | OPTIONS | METHODS | SUPPORT and FEEDBACK | AUTHOR and COPYRIGHT | CREDITS | POD ERRORS

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

home | help