TM::Bulk (3pm)

  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', '*' ]);

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 \s-1TMDM\s0 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 \*(C`*\*(C' to the scoping list. If no name exist for a particular lid, then an \*(C`undef\*(C' 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 \*(C`topic-id @ scope-id\*(C' (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 \s-1NOT\s0 honored)

To control what exactly should be returned, the \*(C`what\*(C' 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 \*(C`0,19\*(C', for the next \*(C`20,39\*(C'. 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 \*(C`instances\*(C', 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 \*(C`subclasses\*(C', but creates reflexive, transitive closure

superclasses (<n,m>):

fetches all direct superclasses

superclasses* (<n,m>):

same as \*(C`superclasses\*(C', 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 \*(C`lid\*(C' does not identify a proper toplet.

TM::Overview

Copyright 200[3-57] by Robert Barta, <[email protected]>

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