view release on metacpan or  search on metacpan

lib/Biblio/Thesaurus.pm  view on Meta::CPAN

__END__

=encoding UTF-8

=head1 NAME

Biblio::Thesaurus - Perl extension for managing ISO thesaurus

=head1 SYNOPSIS

  use Biblio::Thesaurus;

  $obj = thesaurusNew();
  $obj = thesaurusLoad('iso-file');
  $obj = thesaurusRetrieve('storable-file');
  $obj = thesaurusMultiLoad('iso-file1','iso-file2',...);

  $obj->save('iso-file');
  $obj->storeOn('storable-file');

  $obj->addTerm('term');
  $obj->addRelation('term','relation','term1',...,'termn');
  $obj->deleteTerm('term');

  $obj->isDefined('term');

  $obj->describe( { rel='NT', desc="Narrow Term", lang=>"UK" } );

  $obj->addInverse('Relation1','Relation2');

  $obj->order('rela1', 'rel2', ....);
  @order = $obj->order();

  $obj->languages('l1', 'l2', ....);
  @langs = $obj->languages();

  $obj->baselang('l');
  $lang = $obj->baselang();

  $obj->topName('term');
  $term = $obj->topName();

  $html = $obj->navigate(+{configuration},%parameters);

  $html = $obj->getHTMLTop();

  $output = $obj->downtr(\%handler);
  $output = $obj->downtr(\%handler,'term', ... );

  $obj->appendThesaurus("iso-file");
  $obj->appendThesaurus($tobj);

  $obj->tc('term', 'relation1', 'relation2');
  $obj->depth_first('term', 2, "NT", "UF")

  $latex = $obj->toTex( ...)
  $xml   = $obj->toXml( ...)

=head1 ABSTRACT

This module provides transparent methods to maintain Thesaurus files.
The module uses a subset from ISO 2788 which defines some standard
features to be found on thesaurus files. The module also supports
multilingual thesaurus and some extensions to the ISOs standard.

=head1 DESCRIPTION

A Thesaurus is a classification structure. We can see it as a graph
where nodes are terms and the vertices are relations between terms.

This module provides transparent methods to maintain Thesaurus files.
The module uses a subset from ISO 2788 which defines some standard
features to be found on thesaurus files. This ISO includes a set of
relations that can be seen as standard but, this program can use user
defined ones.  So, it can be used on ISO or not ISO thesaurus files.

=head1 File Structure

Thesaurus used with this module are standard ASCII documents. This
file can contain processing instructions, comments or term
definitions. The instructions area is used to define new relations and
mathematical properties between them.

We can see the file with this structure:

   ______________
  |              |
  |    HEADER    | --> Can contain, only, processing instructions,
  |______________|     comment or empty lines.
  |              |
  |  Def Term 1  | --> Each term definition should be separated
  |              |     from each other with an empty line.
  |  Def Term 2  |
  |              |
  |     .....    |
  |              |
  |  Def Term n  |
  |______________|

Comments can appear on any line. Meanwhile, the comment character
(B<#>) should be the first character on the line (with no spaces
before).  Comments line span to the end of the line (until the first
carriage return).

Processing instructions lines, like comments, should start with the
percent sign (B<%>). We describe these instructions later on this
document.

Terms definitions can't contain any empty line because they are used
to separate definitions from each other. On the first line of term
definition record should appear the defined term. Next lines defines
relations with other terms. The first characters should be an
abbreviation of the relation (on upper case) and spaces. Then, should
appear a comma separated list of terms.

There can be more than one line with the same relation. Thesaurus module will
concatenate the lists. If you want to continue a list on the next line you
can repeat the relation term of leave some spaces between the start of the line
and the terms list.

Here is an example:

  Animal
  NT cat, dog, cow
     fish, ant
  NT camel
  BT Life being

  cat
  BT Animal
  SN domestic animal to be kicked when