/ 
XTM-0.20
/ XTM::Memory

NAME

XTM - Topic Map management, in-memory data structure.

SYNOPSIS

   use XTM::Memory;
   $tm = new XTM::Memory ();

   # adding something
   $tm->add (new XTM::topic (id => "t-beatles", ...));
   $tm->add (new XTM::association (....));

   # removing something
   $tm->remove ('t-beatles');

   # checking something
   print "Hurray" if 
    $tm->is_topic ('t-john-lennon') ||
    $tm->is_association ('a-played-in');

   # finding something
   @rumstis = @{$tm->topics ( "baseName regexps /rumsti.*/" )};

   # fetching names for a scope
   @names = @{$tm->baseNames ([ 't-paul-mccartney', 't-john-lennon' ], 
			      [ 'http://www.topicmaps.org/xtm/language.xtm#en' ]);}

DESCRIPTION

This package provides an in-memory data structure for topic maps. Basically, the object maintains a hash of topics and a hash of associations. The interface provides for basic operations to add/delete topics/associations and to query the map via a query language.

INTERFACE

The interface offers basic access function but also some sophisticated filters to create sub maps. More convenient functions to retrieve topic and association information can be found in the XTM::Server package distributed seperately.

Constructor

The constructor expects only one optional parameter, id. If not provided, the id will remain undefined.

$tm = new XTM::Memory ();

Methods

add

Adds a (list of) topics, associations and/or maps to the map object with the following rules:

  1. If a particular topic/association id does already exist in the map object, the corresponding topic will simply be overwritten. This also happens when another map with such a topic/association is merged.

  2. No topic merging will (yet) occur.

Examples:

$t = new XTM::topic (id => "t-portishead", ...);
$a = new XTM::association (....);
$tm->add ($t);
$tm->add ($t1, $t2);
$a = new XTM::association (....);
$tm->add ($a);
$tm->add ($a, $t);
$tm2 = new XTM::Memory;
...
$tm->add ($tm2);

If a parameter is neither a topic nor an association nor a topic map, an exception will be raised.

remove

removes particular topics and associations specified by their id. You can provide a list here. The method will return a list references of object (references), which were removed from the map during this operation. ids not identifying any topic or association in the map, are ignored.

Examples:

# get rid of a particular topic
$tm->remove ('t-portishead');
is_topic, is_association

check whether a particular topic/association with a given id exists in the map. Returns 1 in that case, undef otherwise.

Examples:

print "Hurray" if $tm->is_topic ('t-john-lennon') || 
                  $tm->is_association ('a-played-in');
topics

returns a list reference of topic ids for this given map. An optional filter specification can filter only relevant topics:

Example:

# get all of them (or at least what the implementation is willing to give)
$tm->topics ();
# only with some name
$tm->topics ( "baseName regexps /rumsti.*/" );

The filter specifications follow the syntax:

filter        -> clause { 'AND' clause } 
clause        -> 'baseName'   'regexps' regexp_string                               |
                 'occurrence' 'regexps' regexp_string                               |
                 'text'       'regexps' regexp_string                               | # any text within the topic
                 'id'         'regexps' regexp_string                               |
                 'id'         'eq'      ''' string '''                              |
                 'assocs' [ 'via' topic_id ] [ 'with' topic_id ] [ 'transitively' ] |
                 'is-a'  topic_id                                                   |
##                 'instanceOfs' ( '<=' | '==' | '>=' )  set_of_topic_ids | NOT IMPLEMENTED
##                 'scoped_by' topic_id   ## NOT IMPLEMENTED
regexp_string -> '/' regexp '/'
regexp        -> <a perl pattern>
topic_id      -> <id of a topic>
string        -> <any string with no \' in it>
associations

returns the ids of associations. An optional filter specification can filter only relevant associations:

Examples:

# get _all_  from the map
@assocs = @{$tm->associations()};
# get only these matching a specific regexp for the id
@assocs = @{$tm->associations ('id  regexps /^#a-some-assoc/')};
# get only these containing a particular topic as a role player
@assocs = @{$tm->associations ('has_role t-some-role')};
# get only these containing a particular topic as a member
@assocs = @{$tm->associations ('has_member t-some-topic AND has_role t-some-role')};
# with a specific type
@assocs = @{$tm->associations ('is-a at-relation')};

The filter specifications follow the syntax:

filter        -> clause { 'AND' clause } 
clause        -> 'id'    'regexps' regexp_string      |
                 'id'    'eq'      ''' string '''     |
                 'has-role'        topic_id           |
                 'has-member'      topic_id           |
                 'is-a'            topic_id           |
regexp_string -> '/' regexp '/'
regexp        -> <a perl pattern>
topic_id      -> <id of a topic>
topic, association

return a topic/association object (reference) for a given id. If there is no such id, an exception will be raised.

my $john = $tm->topic ('t-john-lennon');
topic_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->topic_tree (topic      => $start_node,
			       assoc_type => 'at-relation',
			       a_role     => 'tt-parent',
			       b_role     => 'tt-child' );
  $yhcareih = $tm->topic_tree (topic      => $start_node,
			       assoc_type => 'at-relation',
			       b_role     => 'tt-parent',
			       a_role     => 'tt-child',
			       depth      => 42 );
baseNames

receives a list reference containing topic ids. It returns a hash reference containing the baseName for each topic as a value with the topic id the key. The additional parameter is interpreted as list reference to scoping topics. If this list is undef, then any basename may be returned. If the list is empty ([]), then NO basename will ever be returned. If it is non-empty, then - according to the order in this list - the first basename matching will be selected.

Example:

   $names_ref = $tm->baseNames ([ 't-topic1', 't-topic-2' ], 
				[ 'http://www.topicmaps.org/xtm/language.xtm#en' ]);

SEE ALSO

XTM

AUTHOR INFORMATION

Copyright 2001, 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.