NAME

TM::Bulk - Topic Maps, Bulk Retrieval Trait

SYNOPSIS

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

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

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

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.

basenames

$name_hash_ref = $tm->basenames ($lid_list_ref, $scope_list_ref )

This method takes a list (reference) of topic ids and a list of scoping topic ids. For the former it will try to find the basenames (topic names for TMDM acolytes). The list of scopes directs the method to look first for a basename in the first scoping topic, then second, and so on. If no such basenames exist for a particular lid, then an undef is returned.

If the list of scoping topics is empty, then it will be interpreted as dont care. In that case any basename may be returned (if such exists). You can make this explicit by adding a * at the end (or as sole entry) in the list. Otherwise the result is undefined.

The overall result is a hash (reference) having the lids as keys and the basename strings as 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.

instances (<n,m>):

fetches all toplets (and maplets) 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 maplet ids where the vortex is a role,

players (<n,m>):

fetches all maplets where the vortex plays a role

toplet:

fetches the complete toplet itself (all characteristics, but no maplets)

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 ],
			  'members'     => [ 'players' ],
			 },
			 [ 'scope1', 'scope2', .... ]
			);

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.