NAME

XTM::topic - Topic Map management, Topic

SYNOPSIS

  use XTM::topic;

  my $t = new XTM::topic;
  ...
  print join (",", @{$t->occurrences()});
  print "bliss and happiness" if $t->has_instanceOf ('t-billionair');

  # now this time I am providing the id myself
  my $t2 = new XTM::topic (id => '1234');

  # there is also a cheap way to populate the topic with a default
  my $t3 = new XTM::topic (id => '1234', populate => \&XTM::topic::default_populate);


  # see XTM::generic for more methods

DESCRIPTION

This package provides the primitive class Topic for Topic Maps.

INTERFACE

Constructor

The constructor expects a hash with following (optional) fields:

id:

a topic id (unique in the map in use), if not given, it will be generated

populate:

a code reference to a subroutine populating the topic. There are the following predefined subroutines:

default_populate

This routine expects as first parameter a XTM::topic-blessed object and fills in the PSI topic as 'instanceOf', global scope where appropriate. It also generates in a fairly ad-hoc manner a 'baseName' from the topic id (substituting '-' by ' ').

  $t = new XTM::topic ('id' => 'x123');

Methods

Following accessor methods are available via XTM::generic (see that package how to set/add values):

baseNames:

@{ $t->baseNames}

returns list reference of XTM::baseName nodes.

instanceOfs:

@{ $t->instanceOfs}

returns list reference of XTM::instanceOf nodes.

subjectIdentity:

$t->subjectIdentity

returns a XTM::subjectIdentity node

Other methods are:

id:

print $t->id

$t->id ("x123");

returns the id of the topic. If provided with a non-empty scalar parameter, this value will be used to change the id.

occurrences:

@{ $t->occurrences }

$t->occurrences ( $coderef )

$t->occurrences ( $arrayref )

returns the occurrences of the topic as a list reference. If provided with a CODEREF parameter, this subroutine will be used to filter the occurrences. If provided with a ARRAYREF parameter, this will be used as new value.

map:

$t->map

$t->map ( $newmap )

is an accessor method for the map component.

has_instanceOf:

$t->has_instanceOf ( $type_topic_id )

returns true if the topic is a direct subtype of a topic specified as tid for the only parameter.

Example:

   print "bliss and happiness" if $t->has_instanceOf ('t-billionair');

add_defaults

$t->add_defaults

This methods add default values according to the XTM standard. Specifically, it assures that

The topic has at least one instanceOf component and there at least one entry. If not, one will be generated (XTM clause 3.6.1).

Every occurrence must have a type (XTM clause 3.9.1).

If a scope exists (in an occurrence or a baseName), then at least one reference must be there (XTM clause 3.3.1).

canonicalize

$t->canonicalize

This method simplifies the topic by eliminating duplicates as prescribed in F.6.

connected:

@{ $t->connected }

returns a list reference of all topic references mentioned in this topic. These references might be 'internal' or 'external' ones.

Example:

   foreach (@{$t->connected}) {
     print "$t->id mentions $_\n";
   }

xml:

$t->xml ( $xmlwriter )

returns an XML representation of the topic.

Example: $xmlwriter = new XML::Writer ... ... $t->xml($xmlwriter); # outputs all onto $xmlwriter

SEE ALSO

XTM, XTM::generic

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