NAME

XTM - Topic Map management, single thread class

SYNOPSIS

use XTM;

$tm = new XTM; # creating an empty map

# reading a topic map description from an XML file
use XTM::XML;
$xml = new XTM::XML (file => 'mymap.tm'); # create an XML channel, see XTM::XML
$tm  = new XTM (tie => $xml); # binds variable to channel

# primitive accessor to fetch/set the memory representation of the map
print Dumper $tm->memory;
# basic statistics about a map
print Dumper $tm->info;
# analyze the 'clusters' of a map, see below
print Dumper $tm->cluster;

DESCRIPTION

This class can be used to

• construct/manipulate topic maps and to

• tie a particular persistent manifestation of a topic map to an in-memory object

INTERFACE

Constructor

The constructor expects no mandatory parameters but you can provide a hash with the following fields:

tie:

If you provide a tieable object (XTM::XML, ...), then this object is bound to the topic map.

$tm = new XTM ();
$tm = new XTM (tie => new XTM::XML (file => 'map.xtm'));

Methods

All, except the methods below, are handed over to the corresponding memory component.

memory

returns/sets the XTM::Memory component. Setting will NOT check the consistency with the other components.

info

returns some meta/statistical information about the map in form of a hash reference containing one or more of the following components (you might want to discover the return values with Data::Dumper):

(a)

informational: this hash reference contains the number of topics, the number of associations, the UNIX date of the last modification and synchronisation with the external tied object and a list reference to other topic maps on which this particular map depends.

(b)

warnings

This hash reference contains a list (reference) of topic ids of topics not_used anywhere in the map. There is also a list (no_baseName) of topics which do not contain any baseName (yes this is allowed in section 3.6.1 of the standard).

(c)

errors

This component contains a list reference undefined_topics containing a list of topic identifiers of topics not defined in the map.

(d)

statistics

This component contains a hash reference to various statistics information, as the number of clusters, maximum and minimum size of clusters, number of topics defined and topics mentioned.

TODOs:

• there is a cyclic dependency of topic types

You can control via a parameter which information you are interested in:

Example:

$my_info = $tm->info ('informational', 'warning', 'errors', 'statistics');

clusters

computes the 'islands' of topics. It figures out which topics are connected via is-a, scoping or other associations and - in case they are - will collate them into clusters. The result is a hash reference to a hash containing list references of topic ids organized in a cluster.

Example:

my $clusters = $tm->clusters();
foreach (keys %$clusters) {
   print "we are connnected: ", join (",", @{$clusters->{$_}});
}

induced_assoc_tree

computes a tree of topics based on a starting topic, an association type and two roles. Whenever an association of the given type is found and the given topic appears in the role given in this very association, then all topics appearing in the other given role are regarded to be children in the result tree. There is also an optional depth parameter. If it is not defined, no limit applies. If there are loops implied by this relation, so be it.

Examples:

  $hierachy = $tm->induced_assoc_tree (topic      => $start_node,
				       assoc_type => 'at-relation',
				       a_role     => 'tt-parent',
				       b_role     => 'tt-child' );
  $yhcareih = $tm->induced_assoc_tree (topic      => $start_node,
				       assoc_type => 'at-relation',
				       b_role     => 'tt-parent',
				       a_role     => 'tt-child',
				       depth      => 42 );

induced_vortex

returns _a lot_ of information about a particular topic. The function expects the following parameters:

topic_id:

the tid of the topic 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:

t_instances:

fetches all topics which are instances of the vortex

t_types:

fetches all (direct) types of the vortex

a_instances:

fetches all associations which are instances of the vortex, additional integers define the from and to value (say to ask for the first twenty, use 0, 20)

topic:

fetches the complete topic itself

roles:

fetches all associations where the vortex _is_ a role, additional integers define the from and to value (say to ask for the first twenty, use 0, 20)

members:

fetches all associations where the vortex _plays_ a role, additional integers define the from and to value (say to ask for the first twenty, use 0, 20)

tree:

tries to build a 'tree-view' from the map induced by particular associations. These associations are characterized via a type (instanceOf) and the relevant roles. There is also an optional level which allows you to control the depth of the tree. If the map contains cycles, they will NOT YET be detected. In other words, the function may loop.

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->induced_vortex ('some-topic-id',
                                 {
				  't_types'     => [ 't_types' ],
				  't_instances' => [ 't_instances' ],
				  'a_instances' => [ 'a_instances', 0, 20 ],
				  'topic'       => [ 'topic' ],
				  'roles'       => [ 'role', 0, 10 ],
				  'members'     => [ 'member' ],
				  'treeup'      => [ 'tree', {assoc_type => '#at-content-relation',
							      a_role     => '#tt-content-parent',
							      b_role     => '#tt-content-child',
							      depth      => 2} ],
				  'treedown'    => [ 'tree', {assoc_type => '#at-content-relation',
							      b_role     => '#tt-content-parent',
							      a_role     => '#tt-content-child',
							      depth      => 2} ] 
				 },
				 [ 'scope1', 'scope2', .... ]
				);

SEE ALSO

XTM

AUTHOR INFORMATION

Copyright 2001, 2002, Robert Barta <rho@telecoma.net>, All rights reserved.

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