NAME

TM::DM - Topic Maps, TMDM layer

SYNOPSIS

ABSTRACT

DESCRIPTION

@@@@@@@@ read-only for now

INTERFACE

topics

@topics = $tmdm->topics (@list-of-ids)

@topics = $tmdn->topics

@@@

This method expects a list containing topic identifiers and returns TM::DM::Topic references representing these topics. If any of the input identifiers do not denote a valid topic in the map, undef will be returned in its place.

If the parameter list is empty, all toplets will be returned. Have fun, I mean, use with care.

Example:

   # round tripping topic ids
   print map { $_->[ID] } $tmdm->topics ('abel', 'cain' );

   print "topic known" if $tmdm->topics ('god');

SEE ALSO

TM::PSI

COPYRIGHT AND LICENSE

Copyright 200[6] 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.

Mid-Level Interface

Toplets and Maplets

Where the classical introductions of XTM Topic Maps introduce the concept of a topic and the association, we here have a slightly different view to organize Topic Map data.

A maplet is very similar to an association in that it consists of a association type topic, topics for roles and player topics and a topic for the scope of the association. A full maplet also includes ALL information about the involved topics. In this implementation you only get the references to the topics; or rather not to the topics themselves, but to toplets.

toplets consist only of topic characteristics, like the (scoped) basename(s), (scoped) occurrence(s) and subject indicators.

Toplets and Maplets

For retrieval there are several ways: If the identifier is known, then toplets (and maplets, respectively) can be quickly extracted. This is mostly useful for toplets, though, unless you happen to know an identifier for the maplet.

To retrieve these, probably more useful is to use query specifications. These constrain parts (or all) of the information you are looking for. For example,

type    => 'isa',
aplayer => 'dog',
arole   => 'class'

would be looking for all maplets being a (direct or indirect) instance of isa which have a player dog which plays the role class there.

Most general but also the slowest method, is to query the map with a @@@@ path expression (see TM::AsTMa::Path).

Identifiers

Identifiers with TMs in general are a BIG pain. This interface adopts the approach that developers can use a local identifier as long as possible and only have to fall back to full URI (URNs or URLs) in cases this does not work.

A local identifier is a string which can identify a toplet in a map. Normally, these identifiers are maintained by the parsers when a map is read from a file, although there is no obligation to do so (neither by this package nor by the TMDM).

Internally, toplets are always identified through URIs which are built from the local identifier prefixed by the base URI. So, when you have loaded a map with a base URI http://something/ and in that map was a topic defined labelled else, then the toplet's full URI is http://something/else.

You can use either this consistently or you may use the function mids.

Global identifiers can also be used to identify toplets. In either case, these must be fully-fledged URIs. To distinguish between URIs which are a subject address and those which refer to a subject indicator we have the convention that for the latter you always have to use Perl string references.

Copy Semantics

Whenever you extract information via this interface, you will get a Perl data structure. The policy is that no underlying data structures are passed back to the calling application.

This means that it should be safe for you to alter everything you get (although you mostly will not do this), without actually changing the content of the map.

The downside of this is that every implementation of this interface has to copy the whole information and cannot simply pass on references. This certainly has an impact on the performance. If that is an issue then you might want to consider to use the underlying technology.

Identifier-related Methods

Every implementation of this class must offer a method to convert a short identifier into its long, canonical form.

mids [ ABSTRACT ]

@sids = $tm->mids (@list-of-ids)

$sids = $tm->mids ($id)

This method takes a list of identifiers (relative or absolute ones) and tries to expand all into their absolute form. undef will be mapped to undef. Identifiers which are unknown remain as they are.

maplets [ ABSTRACT ]

@maplets = $tm->maplets (%match_specification)

This method takes a match specification returns a list of maplet references which match the specification.

TBW: match specification

assert_toplets

$tm->assert_toplets (@toplet_list)

This method takes a list of toplets and puts it into the underlying store. All topic references which are relative will be automatically made absolute.

As toplets consist only of characteristics, only these are added. No further information about the topic itself is stored. If you want that that topic should be an instance of something, then this must either be done with a separate maplets.

The method returns nothing.

retract_toplets

$tm->retract_toplets (@identifier_list)

This method takes a list of (local or global) identifiers and removes all maplet information about these topics. This method does not return anything.

Note: To get completely rid of these toplets (and also all which have been orphaned by deleting the maplets), you will have to use consolidate.

assert_maplets

$tm->assert_maplets (@maplet_list)

This method takes a list of maplets and stores then into the underlying store.

The method does not return anything.

retract_maplets

$tm->retract_maplets (@identifier_list)

This method takes a list of identifiers and removes the maplets for these identifiers.

The method does not return anything.

Maplet-related Functions

While maplet components are all accessible, we provide here some useful functions to test maplets for particular role/player combinations or to extract particular players.

is_player, is_x_player

$tm->is_player ($maplet, $player_lid, [ $role_lid ])

$ms->is_x_player ($maplet, $player_id, [ $role_id ])

This function returns true (1) if the identifier specified by the second parameter plays any role in the maplet provided as first parameter. If the role id is provided as third parameter then it must be exactly this role that is played.

The 'x'-version is using equality instead of 'subclassing'.

get_players

@ps = $tm->get_players ($maplet, $role_id )

This function returns the players for the given role. As several players could play the same role this returns a list

is_role

$tm->is_role ($maplet, $role_id)

This function returns true (1) if the identifier specified by the second parameter is a role in the maplet provided as first parameter.

cpanm TM

perl -MCPAN -e shell
install TM