{
    "mode": "perldoc",
    "parameter": "User::Identity::Collection",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/User%3A%3AIdentity%3A%3ACollection/json",
    "generated": "2026-06-12T11:53:33Z",
    "synopsis": "use User::Identity;\nuse User::Identity::Collection;\nmy $me    = User::Identity->new(...);\nmy $set   = User::Identity::Collection::Emails->new(...);\n$me->addCollection($set);\n# Simpler\nuse User::Identity;\nmy $me    = User::Identity->new(...);\nmy $set   = $me->addCollection(type => 'email', ...)\nmy $set   = $me->addCollection('email', ...)\nmy @roles = $me->collection('email');  # list of collected items\nmy $coll  = $me->collection('email');  # a User::Identity::Collection\nmy @roles = $coll->roles;\nmy @roles = @$coll;                    # same, by overloading\nmy $role  = $me->collection('email')->find($coderef);\nmy $role  = $me->collection('location')->find('work');\nmy $role  = $me->find(location => 'work');",
    "sections": {
        "NAME": {
            "content": "User::Identity::Collection - base class for collecting roles of a user\n",
            "subsections": []
        },
        "INHERITANCE": {
            "content": "User::Identity::Collection\nis a User::Identity::Item\n\nUser::Identity::Collection is extended by\nUser::Identity::Collection::Emails\nUser::Identity::Collection::Locations\nUser::Identity::Collection::Systems\nUser::Identity::Collection::Users\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use User::Identity;\nuse User::Identity::Collection;\nmy $me    = User::Identity->new(...);\nmy $set   = User::Identity::Collection::Emails->new(...);\n$me->addCollection($set);\n\n# Simpler\nuse User::Identity;\nmy $me    = User::Identity->new(...);\nmy $set   = $me->addCollection(type => 'email', ...)\nmy $set   = $me->addCollection('email', ...)\n\nmy @roles = $me->collection('email');  # list of collected items\n\nmy $coll  = $me->collection('email');  # a User::Identity::Collection\nmy @roles = $coll->roles;\nmy @roles = @$coll;                    # same, by overloading\n\nmy $role  = $me->collection('email')->find($coderef);\nmy $role  = $me->collection('location')->find('work');\nmy $role  = $me->find(location => 'work');\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "The \"User::Identity::Collection\" object maintains a set user related objects. It helps selecting\nthese objects, which is partially common to all collections (for instance, each object has a\nname so you can search on names), and sometimes specific to the extension of this collection.\n\nCurrently imlemented extensions are\n\n*   *people* is a collection of users\n\n*   *whereabouts* are locations\n\n*   a *mailinglist* is a\n\ncollection of email addresses\n\n*   a *network* contains\n\ngroups of systems\n\nExtends \"DESCRIPTION\" in User::Identity::Item.\n",
            "subsections": []
        },
        "OVERLOADED": {
            "content": "overload: @{}\nWhen the reference to a collection object is used as array-reference, it will be shown as\nlist of roles.\n\nexample:\n\nmy $locations = $ui->collection('location');\nforeach my $loc (@$location) ...\nprint $location->[0];\n\noverload: stringification\nReturns the name of the collection and a sorted list of defined items.\n\nexample:\n\nprint \"$collection\\n\";  #   location: home, work\n",
            "subsections": []
        },
        "METHODS": {
            "content": "Extends \"METHODS\" in User::Identity::Item.\n",
            "subsections": [
                {
                    "name": "Constructors",
                    "content": "Extends \"Constructors\" in User::Identity::Item.\n\nUser::Identity::Collection->new( [$name], %options )\n-Option     --Defined in          --Default\ndescription  User::Identity::Item  undef\nitemtype                          <required>\nname         User::Identity::Item  <required>\nparent       User::Identity::Item  undef\nroles                              undef\n\ndescription => STRING\nitemtype => CLASS\nThe CLASS which is used to store the information for each of the maintained objects within\nthis collection.\n\nname => STRING\nparent => OBJECT\nroles => ROLE|ARRAY\nImmediately add some roles to this collection. In case of an ARRAY, each element of the\narray is passed separately to addRole(). So, you may end-up with an ARRAY of arrays each\ngrouping a set of options to create a role.\n"
                },
                {
                    "name": "Attributes",
                    "content": "Extends \"Attributes\" in User::Identity::Item.\n\n$obj->description()\nInherited, see \"Attributes\" in User::Identity::Item\n\n$obj->itemType()\nReturns the type of the items collected.\n\n$obj->name( [$newname] )\nInherited, see \"Attributes\" in User::Identity::Item\n\n$obj->roles()\nReturns all defined roles within this collection. Be warned: the rules are returned in\nrandom (hash) order.\n"
                },
                {
                    "name": "Collections",
                    "content": "Extends \"Collections\" in User::Identity::Item.\n\n$obj->add($collection, $role)\nInherited, see \"Collections\" in User::Identity::Item\n\n$obj->addCollection( $object | <[$type], %options> )\nInherited, see \"Collections\" in User::Identity::Item\n\n$obj->collection($name)\nInherited, see \"Collections\" in User::Identity::Item\n\n$obj->parent( [$parent] )\nInherited, see \"Collections\" in User::Identity::Item\n\n$obj->removeCollection($object|$name)\nInherited, see \"Collections\" in User::Identity::Item\n\n$obj->type()\nUser::Identity::Collection->type()\nInherited, see \"Collections\" in User::Identity::Item\n\n$obj->user()\nInherited, see \"Collections\" in User::Identity::Item\n"
                },
                {
                    "name": "Maintaining roles",
                    "content": "$obj->addRole($role| <[$name],%options> | ARRAY)\nAdds a new role to this collection. $role is an object of the right type (depends on the\nextension of this module which type that is) or a list of %options which are used to create\nsuch role. The options can also be passed as reference to an ARRAY. The added role is\nreturned.\n\nexample:\n\nmy $uicl = User::Identity::Collection::Locations->new;\n\nmy $uil  = User::Identity::Location->new(home => ...);\n$uicl->addRole($uil);\n\n$uicl->addRole( home => address => 'street 32' );\n$uicl->addRole( [home => address => 'street 32'] );\n\nEasier\n\n$ui      = User::Identity;\n$ui->add(location => 'home', address => 'street 32' );\n$ui->add(location => [ 'home', address => 'street 32' ] );\n\n$obj->removeRole($role|$name)\nThe deleted role is returned (if it existed).\n\n$obj->renameRole( <$role|$oldname>, $newname )\nGive the role a different name, and move it in the collection.\n\n$obj->sorted()\nReturns the roles sorted by name, alphabetically and case-sensitive.\n"
                },
                {
                    "name": "Searching",
                    "content": "Extends \"Searching\" in User::Identity::Item.\n\n$obj->find($name|CODE|undef)\nFind the object with the specified $name in this collection. With \"undef\", a randomly\nselected role is returned.\n\nWhen a code reference is specified, all collected roles are scanned one after the other (in\nunknown order). For each role,\n\nCODE->($object, $collection)\n\nis called. When the CODE returns true, the role is selected. In list context, all selected\nroles are returned. In scalar context, the first match is returned and the scan is aborted\nimmediately.\n\nexample:\n\nmy $emails = $ui->collection('emails');\n$emails->find('work');\n\nsub findwork($$) {\nmy ($mail, $emails) = @;\n$mail->location->name eq 'work';\n}\nmy @atwork = $emails->find(\\&findwork);\nmy @atwork = $ui->find(location => \\&findwork);\nmy $any     = $ui->find(location => undef );\n"
                }
            ]
        },
        "DIAGNOSTICS": {
            "content": "Error: $object is not a collection.\nThe first argument is an object, but not of a class which extends\nUser::Identity::Collection.\n\nError: Cannot create a $type to add this to my collection.\nSome options are specified to create a $type object, which is native to this collection.\nHowever, for some reason this failed.\n\nError: Cannot load collection module for $type ($class).\nEither the specified $type does not exist, or that module named $class returns compilation\nerrors. If the type as specified in the warning is not the name of a package, you specified\na nickname which was not defined. Maybe you forgot the 'require' the package which defines\nthe nickname.\n\nError: Cannot rename $name into $newname: already exists\nError: Cannot rename $name into $newname: doesn't exist\nError: Creation of a collection via $class failed.\nThe $class did compile, but it was not possible to create an object of that class using the\noptions you specified.\n\nError: Don't know what type of collection you want to add.\nIf you add a collection, it must either by a collection object or a list of options which\ncan be used to create a collection object. In the latter case, the type of collection must\nbe specified.\n\nWarning: No collection $name\nThe collection with $name does not exist and can not be created.\n\nError: Wrong type of role for $collection: requires a $expect but got a $type\nEach $collection groups sets of roles of one specific type ($expect). You cannot add objects\nof a different $type.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "This module is part of User-Identity distribution version 1.01, built on February 11, 2022.\nWebsite: http://perl.overmeer.net/CPAN/\n",
            "subsections": []
        },
        "LICENSE": {
            "content": "Copyrights 2003-2022 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.\n\nThis program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself. See http://dev.perl.org/licenses/\n",
            "subsections": []
        }
    },
    "summary": "User::Identity::Collection - base class for collecting roles of a user",
    "flags": [],
    "examples": [],
    "see_also": []
}