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

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

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.

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.

For merging related information see XTM.

$mem = new XTM::Memory ( [ id => $id ] )

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

   $tm = new XTM::Memory ();

id

$id = $mem->id ( [ $id ] ) Returns the id of the topic map. This can be empty if it has never been provided. If a parameter is provided, that scalar will be the new value for the id.

add_topic

$mem->add_topic ( $topic ) Adds/merge a single topic to the map.

add

$mem->add ( $topic, ... ) $mem->add ( $association, ... ) $mem->add ( $tm, ... ) Adds a (list of) topic(s), associations and/or maps. There is a small overhead involved determining the kind of object to be added. See XTM for the merging rules. 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. Note: When a topic is added it may be merged with other topics according to your consistency setting of the map. This implies that topics are modified by having more CWbaseNames, CWoccurrences, ... If the calling program still maintains a reference to this topic, then it will experience these changes. On the other hand, if topics are merged, then the topic which is merged in, will NOT be stored as-is in the map. Only its components (CWbaseNames, ..._) will survive. Saying this, it means that you cannot trust the topic references you have created. You should request a new reference via a subjectIndicator or the topic id.

remove

$listref = $mem->remove ( @list_of_topic_ids ) removes particular topics and associations specified by their CWid. 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. Topic ids not identifying any topic or association in the map, are silently ignored. Examples:

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

is_topic, is_association

$boolean = $mem->is_topic ( $topic_id ) $boolean = $mem->is_association ( $association_id ) check whether a particular topic/association with a given CWid exists in the map. Returns 1 in that case, CWundef otherwise. Examples:

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

topics

$list_ref = $mem->topics ( [ $query ] ) 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                                                   |
                   'reifies'    'regexps' regexp_string                               |
                   'indicates'  'regexps' regexp_string                               |
##                 '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>

The regexps are all interpreted as //i, i.e. case-insensitive matching.

associations

$list_ref = $mem->associations ( [ $query ] ) returns the CWids 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

$topic_ref = $mem->topic ( $topic_id ) $association_ref = $mem->association ( $association_id ) return a topic/association object (reference) for a given CWid. If there is no such id, an exception will be raised.

  my $john = $tm->topic ('t-john-lennon');

baseNames

$hash_ref = $mem->baseNames ( $topic_id_list_ref, $scope_list_ref ) receives a list reference containing topic CWids. 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' ]);

XTM, XTM::base

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