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

FreeBSD Manual Pages


home | help
User::Identity::CollecUser(Contributed Perl DocumUser::Identity::Collection(3)

       User::Identity::Collection - base class for collecting roles of a user

	  is a User::Identity::Item

	User::Identity::Collection is extended by

	use User::Identity;
	use User::Identity::Collection;
	my $me	  = User::Identity->new(...);
	my $set	  = User::Identity::Collection::Emails->new(...);

	# Simpler
	use User::Identity;
	my $me	  = User::Identity->new(...);
	my $set	  = $me->addCollection(type => 'email',	...)
	my $set	  = $me->addCollection('email',	...)

	my @roles = $me->collection('email');  # list of collected items

	my $coll  = $me->collection('email');  # a User::Identity::Collection
	my @roles = $coll->roles;
	my @roles = @$coll;		       # same, by overloading

	my $role  = $me->collection('email')->find($coderef);
	my $role  = $me->collection('location')->find('work');
	my $role  = $me->find(location => 'work');

       The "User::Identity::Collection"	object maintains a set user related
       objects.	 It helps selecting these objects, which is partially common
       to all collections (for instance, each object has a name	so you can
       search on names), and sometimes specific	to the extension of this

       Currently imlemented extensions are

       o   people is a collection of users

       o   whereabouts are locations

       o   a mailinglist is a

	   collection of email addresses

       o   a network contains

	   groups of systems

       Extends "DESCRIPTION" in	User::Identity::Item.

       overload: @{}
	   When	the reference to a collection object is	used as	array-
	   reference, it will be shown as list of roles.


	    my $locations = $ui->collection('location');
	    foreach my $loc (@$location) ...
	    print $location->[0];

       overload: stringification
	   Returns the name of the collection and a sorted list	of defined


	    print "$collection\n";  #	location: home,	work

       Extends "METHODS" in User::Identity::Item.

       Extends "Constructors" in User::Identity::Item.

       User::Identity::Collection->new(	[$name], %options )
	    -Option	--Defined in	      --Default
	     description  User::Identity::Item	undef
	     item_type				<required>
	     name	  User::Identity::Item	<required>
	     parent	  User::Identity::Item	undef
	     roles				undef

	   description => STRING
	   item_type =>	CLASS
	     The CLASS which is	used to	store the information for each of the
	     maintained	objects	within this collection.

	   name	=> STRING
	   parent => OBJECT
	   roles => ROLE|ARRAY
	     Immediately add some roles	to this	collection.  In	case of	an
	     ARRAY, each element of the	array is passed	separately to
	     addRole().	So, you	may end-up with	an ARRAY of arrays each
	     grouping a	set of options to create a role.

       Extends "Attributes" in User::Identity::Item.

	   Inherited, see "Attributes" in User::Identity::Item

	   Returns the type of the items collected.

       $obj->name( [$newname] )
	   Inherited, see "Attributes" in User::Identity::Item

	   Returns all defined roles within this collection.  Be warned: the
	   rules are returned in random	(hash) order.

       Extends "Collections" in	User::Identity::Item.

       $obj->add($collection, $role)
	   Inherited, see "Collections"	in User::Identity::Item

       $obj->addCollection( $object | <[$type],	%options> )
	   Inherited, see "Collections"	in User::Identity::Item

	   Inherited, see "Collections"	in User::Identity::Item

       $obj->parent( [$parent] )
	   Inherited, see "Collections"	in User::Identity::Item

	   Inherited, see "Collections"	in User::Identity::Item

	   Inherited, see "Collections"	in User::Identity::Item

	   Inherited, see "Collections"	in User::Identity::Item

   Maintaining roles
       $obj->addRole($role| <[$name],%options> | ARRAY)
	   Adds	a new role to this collection.	$role is an object of the
	   right type (depends on the extension	of this	module which type that
	   is) or a list of %options which are used to create such role.  The
	   options can also be passed as reference to an ARRAY.	 The added
	   role	is returned.


	    my $uicl = User::Identity::Collection::Locations->new;

	    my $uil  = User::Identity::Location->new(home => ...);

	    $uicl->addRole( home => address => 'street 32' );
	    $uicl->addRole( [home => address =>	'street	32'] );


	    $ui	     = User::Identity;
	    $ui->add(location => 'home', address => 'street 32'	);
	    $ui->add(location => [ 'home', address => 'street 32' ] );

	   The deleted role is returned	(if it existed).

       $obj->renameRole( <$role|$oldname>, $newname )
	   Give	the role a different name, and move it in the collection.

	   Returns the roles sorted by name, alphabetically and	case-

       Extends "Searching" in User::Identity::Item.

	   Find	the object with	the specified $name in this collection.	 With
	   "undef", a randomly selected	role is	returned.

	   When	a code reference is specified, all collected roles are scanned
	   one after the other (in unknown order).  For	each role,

	    CODE->($object, $collection)

	   is called.  When the	CODE returns true, the role is selected.  In
	   list	context, all selected roles are	returned.  In scalar context,
	   the first match is returned and the scan is aborted immediately.


	    my $emails = $ui->collection('emails');

	    sub	find_work($$) {
	       my ($mail, $emails) = @_;
	       $mail->location->name eq	'work';
	    my @at_work	= $emails->find(\&find_work);
	    my @at_work	= $ui->find(location =>	\&find_work);
	    my $any	= $ui->find(location =>	undef );

       Error: $object is not a collection.
	   The first argument is an object, but	not of a class which extends

       Error: Cannot create a $type to add this	to my collection.
	   Some	options	are specified to create	a $type	object,	which is
	   native to this collection.  However,	for some reason	this failed.

       Error: Cannot load collection module for	$type ($class).
	   Either the specified	$type does not exist, or that module named
	   $class returns compilation errors.  If the type as specified	in the
	   warning is not the name of a	package, you specified a nickname
	   which was not defined.  Maybe you forgot the	'require' the package
	   which defines the nickname.

       Error: Cannot rename $name into $newname: already exists
       Error: Cannot rename $name into $newname: doesn't exist
       Error: Creation of a collection via $class failed.
	   The $class did compile, but it was not possible to create an	object
	   of that class using the options you specified.

       Error: Don't know what type of collection you want to add.
	   If you add a	collection, it must either by a	collection object or a
	   list	of options which can be	used to	create a collection object.
	   In the latter case, the type	of collection must be specified.

       Warning:	No collection $name
	   The collection with $name does not exist and	can not	be created.

       Error: Wrong type of role for $collection: requires a $expect but got a
	   Each	$collection groups sets	of roles of one	specific type
	   ($expect).  You cannot add objects of a different $type.

       This module is part of User-Identity distribution version 0.98, built
       on November 08, 2017.

       Do not forget to	read Mail::Box-Overview, Mail::Box-Cookbook, and
       Mail::Box-Index.	 Examples are included in the Mail-Box distribution,
       directories 'examples' and 'scripts'.

       Browseable manuals, papers, and other released material van be found at

       The central modules (in separate	distributions) in the MailBox suite
       are: Mail::Message, Mail::Box, Mail::Box::IMAP4,	Mail::Box::POP3,
       Mail::Box::Parser::C, Mail::Box::Dbx (unpublished), Mail::Transport,
       Object::Realize::Later, and User::Identity.

       Please post questions or	ideas to the author

       Copyrights 2003-2017 by [Mark Overmeer <>]. For other
       contributors see	Changes.

       This program is free software; you can redistribute it and/or modify it
       under the Artistic license.  See

perl v5.32.0			  2017-11-08	 User::Identity::Collection(3)


Want to link to this manual page? Use this URL:

home | help