Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages
Object::groups(3) User Contributed Perl Documentation Object::groups(3)

Object::groups - Pragma to implement group of properties

Included in OOTools 2.21 distribution.

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

The distribution includes:

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

    Perl version >= 5.6.1
    perl -MCPAN -e 'install OOTools'
Standard installation
From the directory where this file is located, type:

    perl Makefile.PL
    make test
    make install

    package MyClass ;

    # creates constructor method
    use Class::costr ;

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

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

    # with options
    use Object::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'
        } ;

    $object = MyClass->new ;

    $object->myGroup(\%hash) ;

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

    $hash_ref = $object->myGroup

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

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

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

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

    # copying the whole hash
    %myGroupHash = $object->myGroup

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 ;

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. $object->{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 Object::props pragma.

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

Whit the accessor method for the group you can:

  • set a group of properties by passing an hash of values to the accessor
  • retrieve (in list context) the list of the names of the (already defined) properties of the group
  • retrieve (in scalar context) the reference to the underlying hash containing the grouped properties.

Note: The underlaying hash contains:

  • all the already set properties of the class and base classes
  • all the properties with a "default" or "rt_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.

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

The name of the group accessor.

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

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 Object::groups
        { name       => 'myGroup'
        , pre_process=> sub
                         { if ( ref $_[1] eq 'ARRAY' )
                            { $_[1] = { map { $_=>$_ } @{$_[1]} }
                         ; 1

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.

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

This will add to the package package the accessors for the groups. It is useful to add properties in other packages.

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

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

If you need support or if you want just to send me some feedback or request, please use this link:

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

Thanks to Juerd Waalboer ( that with its Attribute::Property inspired the creation of this distribution.

Hey! The above document had some coding errors, which are explained below:
Around line 33:
Expected text after =item, not a bullet
Around line 37:
Expected text after =item, not a bullet
Around line 41:
Expected text after =item, not a bullet
Around line 45:
Expected text after =item, not a bullet
Around line 49:
Expected text after =item, not a bullet
Around line 53:
Expected text after =item, not a bullet
Around line 57:
Expected text after =item, not a bullet
Around line 61:
Expected text after =item, not a bullet
Around line 301:
Non-ASCII character seen before =encoding in '©'. Assuming CP1252
2017-04-19 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.