The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
XTM-0.37
++
/ XTM

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

  • to construct/manipulate topic maps and

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

  • to compute statistical information about a map.

It can be used as a top-level class to do all topic map related operations.

INTERFACE

Constructor

$tm = new XTM ([ tie => some source ], [ consistency => consistency ]);

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.

consistency:

A consistent map is one which has gone through processing detailled in Annex F of the XTM specification. By default an XTM object has consistency set to 'standard' which means that all of the above mentioned processing will occur at every modification of that with following exception(s):

external maps will not be followed automatically (implicit topic map merge, F.5.5). This is to protect applications from unintentionally pulling in HUGE ontologies from external maps only because of some topicRefs pointing to these topics. So this is turned off by default.

Alternatively, the user can control the extent of 'consistency' by providing a hash reference with the following components:

merge: The value is a list reference containing some of the following constants:
Topic_Naming_Constraint: see F.5.3
Subject_based_Merging: see F.5.2
Id_based_Merging: If set, then then two topics with the same id are merged. If not set, then one topic will substitute the other. This was the old behaviour.
Application_based_Merging: not implemented yet.
all: includes all above, default

To achieve backward compatibility, you should set

  merge => $XTM::backward_consistency
duplicate_suppression: The value is a list reference containing some of the following constants:
Subject_Indicator: see F.6.1
Topic_Name: see F.6.2
Association: see F.6.3
Role_Player: see F.6.4
all: includes all above, default
follow_maps: The value is a list reference containing some of the following constants:
explicit: see F.5.4,
implicit: see F.5.5
all: includes all above, default

The use of any other constant will raise an exception whenever the map is modified for the first time (either by reading it from a tied resource or when programmatically changing it).

The package provides the following constants

default_consistency: all but implicit follow-up of topic references to other maps
max_consistency: all
backward_consistency: backward compatible behavior

Examples:

  # empty map
  $tm = new XTM ();

  # map loaded and bound to a particular XTM file, see XTM::XML
  $tm = new XTM (tie         => new XTM::XML (file => 'map.xtm'));

  # fine tuning merging
  $tm = new XTM (tie         => new XTM::XML (file => 'map.xtm'),
                                # TNC is EVIL, EVIL :-)
                 consistency => { merge => [ 'Subject_based_Merging' ],
                                # but I do not fear external maps
                                  follow_maps => ['all']
                                 });

TODO:

  - allow CODEREFs to give total control to the application

Methods

All, except the methods below, are handed over to the corresponding memory component (XTM::Memory).

memory

$tm->memory

returns/sets the XTM::Memory component. Changing this value will cause big, big harm as there will NOT be a consistency check with the other internal components.

consistency

$hashref = $tm->consistency

returns the consistency component as hash reference as described in the constructor above. Currently, this is a read-only method.

info

$hashref = $tm->info (list of info items)

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:

  • detect cyclic dependency of topic types

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

Example:

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

$hashref = $tm->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

$treeref = $tm->induced_assoc_tree ( [ topic => $start_topic, ] [ assoc_type => $type_topic, ] [ a_role => $role_topic, ] [ b_role => $role_topic, ] [ depth => integer ])

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. Starting from XTM::base version 0.34 loops are detected and are handled gracefully. The returned tree might contain loops then.

Examples:

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

Note

Starting from XTM::base version 0.34 you can also use the predefined association type http://www.topicmaps.org/xtm/core.xtm#class-instance:

  $types     = $tm->induced_assoc_tree (topic      => $start_node,
                                        assoc_type => $XTM::PSI::xtm{'class-instance'},
                                        a_role     => $XTM::PSI::xtm{'instance'},
                                        b_role     => $XTM::PSI::xtm{'class'},
                                        depth      => undef );

or

  $instances = $tm->induced_assoc_tree (topic      => $start_node,
                                        assoc_type => $XTM::PSI::xtm{'class-instance'},
                                        b_role     => $XTM::PSI::xtm{'instance'},
                                        a_role     => $XTM::PSI::xtm{'class'},
                                        depth      => undef );

Every output tree node contains following fields:

tid:

the topic id of the node

children:

a list reference of child nodes, there is no specific sort order

children*:

for convenience this list reference contains all children, grand-children, grand-grand children.... of this node (this list is neither sorted nor unique out of performance considerations).

induced_vortex

$vortex = $tm->induced_vortex ($some_topic, $what_hashref, $scope_list_ref )

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

topic_id:

the tid of the topic in question (vortex)

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::Memory, XTM::base

AUTHOR INFORMATION

Copyright 200[1-2], 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. http://www.perl.com/perl/misc/Artistic.html