NAME

       TM::Bulk - Topic Maps, Bulk Retrieval Trait

SYNOPSIS

         my $tm = .....                          # get a map from anywhere

         use TM::Bulk;
         use Class::Trait;
         Class::Trait->apply ($tm, 'TM::Bulk');  # give the map the trait

         # find out environment of topic
         my $vortex = $tm->vortex ('some-lid',
                                  {
                                   'types'       => [ 'types' ],
                                   'instances'   => [ 'instances*', 0, 20 ],
                                   'topic'       => [ 'topic' ],
                                   'roles'       => [ 'roles',     0, 10 ],
                                   'members'     => [ 'players' ],
                                  },
                                  );
         # find names of topics (optionally using a scope preference list)
         my $names = $tm->names ([ 'ccc', 'bbb', 'aaa' ], [ 's1', 's3', '*' ]);

DESCRIPTION

       Especially when you build user interfaces, you might need access to a lot of topic-related
       information. Instead of collecting this 'by foot' the following methods help you achieve
       this more effectively.

       names
           $name_hash_ref = $tm->names ($lid_list_ref, [ $scope_list_ref ] )

           This method takes a list (reference) of topic ids and an optional list of scoping
           topic ids.  For the former it will try to find the names (topic names for TMDM
           acolytes).

           If the list of scopes is empty then the preference is on the unconstrained scope. If
           no name for a topic is in that scope, some other will be used.

           If the list of scopes is non-empty, it directs to look first for a name in the first
           scoping topic, then second, and so on. If you want to have one name in any case,
           append "*" to the scoping list.

           If no name exist for a particular lid, then an "undef" is returned in the result hash.
           References to non-existing topics are ignored.

           The overall result is a hash (reference). The keys are of the form "topic-id @
           scope-id" (without the blanks) and the name strings are the values.

       vortex
           $info = $tm->vortex (,
                          $vortex_lid,
                          $what_hashref,
                          $scope_list_ref )

           This method returns a lot of information about a particular toplet (vortex). The
           function expects the following parameters:

           lid:
               the lid of the toplet in question

           what:
               a hash reference describing the extent of the information (see below)

           scopes:
               a list (reference) to scopes (currently NOT honored)

           To control what exactly should be returned, the "what" hash reference can contain
           following components. All of them being tagged with <n,m> accept an additional pair of
           integer specify the range which should be returned.  To ask for the first twenty, use
           "0,19", for the next "20,39". The order in which the identifiers is returned is
           undefined but stable over subsequent read-only calls.

           topic:
               fetches the toplet (which is only the subject locator, subject indicators
               information).

           names (<n,m>):
               fetches all names (as array reference triple [ type, scope, string value ])

           occurrences (<n,m>):
               fetches all occurrences (as array reference triple [ type, scope, value ])

           instances (<n,m>):
               fetches all toplets which are direct instances of the vortex (that is regarded as
               class here);

           instances* (<n,m>):
               same as "instances", but including all instances of subclasses of the vortex

           types (<n,m>):
               fetches all (direct) types of the vortex (that is regarded as instance here)

           types* (<n,m>):
               fetches all (direct and indirect) types of the vortex (that is regarded as
               instance here)

           subclasses  (<n,m>):
               fetches all direct subclasses

           subclasses* (<n,m>):
               same as "subclasses", but creates reflexive, transitive closure

           superclasses (<n,m>):
               fetches all direct superclasses

           superclasses* (<n,m>):
               same as "superclasses", but creates reflexive, transitive closure

           roles (<n,m>):
               fetches all assertion ids where the vortex plays a role

           peers (<n,m>):
               fetches all topics which are also a direct instance of any of the (direct) types
               of this topic

           peers* (<n,m>):
               fetches all topics which are also a (direct or indirect) instances of any of the
               (direct) types of this topic

           peers** (<n,m>):
               fetches all topics which are also a (direct or indirect) instances of any of the
               (direct or indirect) types of this topic

           The function will determine all of the requested information and will prepare a hash
           reference storing each information into a hash component. Under which name this
           information is stored, the caller can determine with the hash above as the example
           shows:

           Example:

             $vortex = $tm->vortex ('some-lid',
                                    {
                                     'types'       => [ 'types' ],
                                     'instances'   => [ 'instances*', 0, 20 ],
                                     'topic'       => [ 'topic' ],
                                     'roles'       => [ 'roles',     0, 10 ],
                                    },
                                   );

           The method dies if "lid" does not identify a proper toplet.

SEE ALSO

       TM::Overview

COPYRIGHT AND LICENSE

       Copyright 200[3-57] by Robert Barta, <drrho@cpan.org>

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.