Biblio...esaurus(3pm)

💖 Biblio::Thesaurus 💖

okay bestie, sit down, hydrate, because we're about to learn the Biblio::Thesaurus perl module (that's the 3pm manpage, for the perl crowd 🫶) and honestly? it's giving classification-structure realness. it's literally a perl extension for managing ISO thesaurus files. no cap. let's go ✨

---

🌸 NAME 🌸

Biblio::Thesaurus — a Perl extension for managing ISO thesaurus. that's it, that's the name, periodt 💅

---

✨ SYNOPSIS ✨

here's the vibe check, all the ways you can call it:

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( ...)

---

🦋 ABSTRACT 🦋

so this module hands you transparent methods for keeping thesaurus files alive and thriving. it works off a subset of ISO 2788, which is the thing that defines some standard features you'd expect to find in thesaurus files. it ALSO does multilingual thesaurus, plus a few little extensions on top of what the ISO standard gives you. iconic behavior tbh 👑

---

💜 DESCRIPTION 💜

a thesaurus is a classification structure. think of it like a graph bestie — the nodes are terms, and the vertices are the relations between those terms. very graph-core of it.

this module gives you transparent methods to maintain thesaurus files, using a subset of ISO 2788 which lays out some standard features found in thesaurus files. now here's the tea: that ISO ships with a set of relations you could call standard, BUT this program lets you use your own user-defined ones too. so basically it eats with ISO thesaurus files or non-ISO thesaurus files. flexible queen 🌈

📁 File Structure 📁

thesaurus files used with this module are standard ASCII documents. a file can contain processing instructions, comments, or term definitions. the instructions area is where you define new relations and the mathematical properties between them. obsessed.

here's the whole structure, look at her:

  ______________
 |              |
 |    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 show up on any line. BUT — and this is important — the comment character # has to be the first character on the line, with no spaces before it. a comment line runs all the way to the end of the line (until the first carriage return). slay.

processing instruction lines, same energy as comments, need to start with the percent sign (%). we get into those instructions later in this doc, don't worry 🫶

term definitions cannot contain any empty line, because empty lines are literally the thing separating one definition from the next. the first line of a term definition record is where the defined term itself goes. the lines after that define relations to other terms. those lines start with an abbreviation of the relation (in upper case) followed by spaces. then comes a comma separated list of terms. periodt.

you can totally have more than one line with the same relation — the module will concatenate the lists for you 💅. and if you wanna continue a list on the next line, just repeat the relation term, or leave some spaces between the start of the line and the terms list. both work.

here's the example, no cap:

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

cat
BT Animal
SN domestic animal to be kicked when
   anything bad occurs.

there's a special term you can define: "_top_". use it when you want a top tree for thesaurus navigation. so the move is, you normally define the "_top_" term with the most interesting terms to be navigated. main character energy only 🌟

and here's the ISO subset this thing uses:

• TT — Top Term. the broadest term we can define about the current term. the ultimate ancestor, the CEO.
• NT — Narrower Term. terms that are more specific than the current term. the children, basically.
• BT — Broader Term. more generic terms than the current term. the parents.
• USE — Synonym. another chance when finding a Synonym. (iykyk)
• UF — Quasi-Synonym. terms that are not synonyms of the current term but can be used, sometimes with that meaning. close enough bestie.
• RT — Related Term. a related term that can't be slotted into any other category. it's giving miscellaneous 💀
• SN — Scope Note. text. a note on the context of the current term. use it for definitions or comments about the scope you're using that term in.

🔮 Processing Instructions 🔮

processing instructions, like we said earlier, live on a line starting with the percent sign. the current commands are:

• top — when presenting a thesaurus we need a term, so we know where to start. normally you want the thesaurus to have some kind of top level to start navigating from. this command specifies that term — the term that should be used when no term is specified. here's the example:

%top Contents

Contents
NT Biography ...
RT ...

• encoding — this one defines the encoding used in the thesaurus file. example time:

%enc utf8

• inverse — this defines the mathematical inverse of the relation. so like, if you define inverse A B and you know that "foo" is related by A with "bar", then "bar" is related by B with "foo". mutual. reciprocal. it's giving healthy relationship 💞

%inv BT NT
%inverse UF USE

• description — this defines a description for some relation class. these descriptions get used when you output the thesaurus as HTML. example:

%desc SN Note of Scope
%description IOF Instance of

and ooh, if you're building a multilingual thesaurus, you're gonna want to translate the relation class description. to do that, use the "description" command with the language in front of it:

%desc[PT] SN Nota de Contexto
%description[PT] IOF Instancia de

• externals — this defines classes that don't relate terms but instead relate a term with some text (a scope note, a url, etc.). used like this:

%ext SN URL
%externals SN URL

heads up bestie: you can specify more than one relation type per line.

• languages — this other command permits the construction of a multilingual thesaurus. to specify language classifiers (like PT, EN, FR, and so on) you can use one of these lines:

%lang PT EN FR
%languages PT EN FR

and to describe (legend) the language names, you should use the description command. so you could append:

%description PT Portuguese
%description EN English
%description FR French

• baselanguage — this one makes it possible to explicitly name the base language for the thesaurus. this command should be used together with the "description" one, to describe the language name. simple example:

%baselang PT
%languages EN FR

%description PT Portuguese
%description EN English
%description FR French

🌍 I18N 🌍

internationalization functions — "languages" and "setLanguage" — should be used before any other function or constructor. and note this: when loading a saved thesaurus, descriptions defined in that file will not be translated. that's important! don't skip that part 🚨

• interfaceLanguages() — this function returns a list of languages that can be used on the current Thesaurus version.
• interfaceSetLanguage( <lang-name> ) — this function turns on the language you specify. so it's the first function you should call when using this module. by default it uses Portuguese. future versions can change this, so you should call it anyway. don't be lazy bestie, call it.

---

👑 API 👑

this module uses a perl object oriented model programming approach, so you gotta create an object first, using one of thesaurusNew, thesaurusLoad or thesaurusRetrieve. everything after that gets called in the OO fashion. periodt.

🎀 Constructors 🎀

thesaurusNew

makes an empty thesaurus object. the newly created object that comes back to you already contains the inversion properties from the ISO classes, plus some stub descriptions for those same classes. starter pack included ✨

thesaurusLoad

to use thesaurusLoad, you must supply a file name. that file name should correspond to the ISO ASCII file as defined in the earlier sections. it returns the object with the contents of the file. and if the file doesn't define relations and descriptions for the ISO classes, they get added for you. generous queen 💅

also:

$obj = thesaurusLoad({ completed => 1}, 'iso-file');

this can be used to say that the thesaurus needs not to be complete after load. okay noted.

thesaurusMultiLoad

you can join different thesaurus ISO files together with this function:

$obj = thesaurusMultiLoad('iso-file1','iso-file2',...);

appendThesaurus

you can also append a thesaurus ISO (or another thesaurus object) to a loaded thesaurus. for that, use one of:

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

thesaurusLoadM

this method is used to load a thesaurus in the meta-thesaurus format. > this is still under development, so don't come for her, she's growing 🌱

thesaurusRetrieve

everybody knows that text access and parsing of files is not efficient. so this module can save and load thesaurus from Storable files. this function should receive a file name from a file which was saved using the storeOn function. speed demon behavior 🔥

---

(okay bestie, that's part one — there's more coming, don't go anywhere 🫶)

💖 Methods 💖

okay bestie this is the big one, the main character section, the whole reason we're here 💅 every method you can call on your thesaurus object, no skips, no shortcuts, we're doing ALL of them.

---

save

This one dumps the object onto an ISO ASCII file 🎀 heads up though, the sequence thesaurusLoad then save is not the identity function — it's giving "changed", not "same", fr fr. Comments get removed, and processing instructions can be added. To use it, you gotta supply a file name.

⚠️ note bestie: if the process fails, this method returns 0. Every other method just straight up dies when it fails to save on a file. so like, save is the forgiving one and everyone else is dramatic 💀

meta2str

Returns the ISO ascii description of the metadata ✨ that's it, that's the whole vibe.

storeOn

Saves the thesaurus object in Storable format. Use this one when you wanna load with the thesaurusRetrieve function 🫶

addTerm

You can add term definitions using the perl API, slay. This method adds a term onto the thesaurus. But note — if that term already exists, all its relations will be deleted 😭 so like, be careful, it's not a merge, it's a replace, no cap.

all_terms

Returns an array with all terms for the thesaurus base language.

🚨 NOTE: this function is deprecated. Use allTerms instead. we don't do deprecated here, bestie, upgrade.

allTerms

Returns an array with all terms for the thesaurus base language. (yes it's the same sentence as its deprecated cousin, but this one is the one you actually want 💖)

topName

Returns the term in the top of the thesaurus — or defines a new one if you call it with an argument 👑

top_name

Deprecated. See "<topName">; — yeah the original really does have that quote situation, we keep it exactly as-is, character for character 💀

addRelation

To add relations to a term, use this method. It can be called again and again and again. Previous inserted relations will not be deleted. It can be used with a list of terms for the relation, like:

$obj->addRelation('Animal','NT','cat','dog','cow','camel');

🫶 Note: after you add a big amount of relations, autocomplete the thesaurus using the $obj->complete() method. Completing after each relation addiction is time and cpu consuming. (yes the original says "addiction" and honestly? relatable, we keep it.)

hasRelation

Checks if a specific relation exists in the Thesaurus:

if ($obj->hasRelation('Animal','NT','cat')) { ... }

You can also check if a term has a relation "X" with literally anything:

if ($obj->hasRelation('Animal','SN')) { ... }

deleteRelation

$obj->deleteRelation('Animal','NT','cat','dog','cow','camel');

that's the whole method, it's giving minimalism 🎀

deleteTerm

Use this method to remove all references of the term supplied. Note that all references will be deleted — like, all of them, gone, periodt.

describe

You can use this method to describe some relation class. Use it to change the description of an existing class (like the ISO ones) or to define a brand new class ✨

isDefined

Use this method to check if a term exists in the thesaurus.

setExternal

Use this method to define that a relation is "extern".

isExternal

Use this method to check if a relation is "extern".

isLanguage

Use this method to check if a relation is a Language 🌈

getdefinition

Deprecated. Use "<getDefinition — again with the mystery quote, we don't fix it, we preserve it 💅

getDefinition

Returns the definition for a term. The definition is a feature structure containing the term information.

getDescription

Given a relation name and a language (or the default will be used), it returns the description for that relation.

relations

Call this method with a term, and it returns a list of the relations defined for that term.

addInverse

This method should be used to describe the inversion property to relation classes.

⚠️ Note that if there is some previous property about any of the relations, it will de deleted. (yes, "de deleted", we keep it exactly, iykyk.) If any of the relations does not exist, it will be added.

order

With this method you can define (and access) the order of classes. This order is used whenever you call a dump function, or the navigation CGI 👑

navigate

This function is a some what type of CGI included on a object method. You must supply an associative array of CGI parameters. This method prints an HTML thesaurus for Web Navigation 🌐

The typical thesaurus navigation CGI is:

#!/usr/bin/perl -w

use CGI qw/:standard/;
use Biblio::Thesaurus;

print header;
for (param()) { $arg{$_} = param($_) }
$thesaurus = thesaurusLoad("thesaurus_file");
print $thesaurus->navigate(%arg);

This method can receive, as first argument, a reference to an associative array with some configuration variables like what relations to be expanded and what language to be used by default ✨

So, in the last example we could write

$thesaurus->navigate(+{expand=>['NT', 'USE'],
                       lang  =>'EN'})

meaning that the structure should show two levels of 'NT' and 'USE' relations, and that it should use the English language 🇬🇧

These options include:

• capitalize — try to capitalize terms when they are the title of the page.
• expand — a reference to a list of relations that should be expanded at first level; Defaults to the empty list.
• title — can be "yes" or "no". If it is "no", the current term will not be shown as a title; Defaults to "yes".
• scriptname — the name of the script the links should point on. Defaults to current page name.
• level1hide — a reference to a list of relations to do not show on the first level. Defaults to the empty list. Useful to hide the 'LEN' relation when using Library::Simple.
• level2size — the number of terms to be shown on each second level relation; Defaults to 0 (all terms).
• level2hide — a reference to a list of relations to do not show on the second level. Defaults to the empty list.
• topic_name — the name of the topic CGI parameter (default: "t")

dumpHTML

This method returns a big string containing all the thesaurus in HTML. It is mainly used for debug 🐛

getHTMLTop

This method returns the HTML needed for the top level of the browsing thesaurus. It can be useful when putting a top level on the first page of a portal 🌸

complete

This function completes the thesaurus based on the invertibility properties. This operation is only needed when adding terms and relations by this API. Whenever the system loads a thesaurus ISO file, it is completed ✨

baselang

Use this method to set or retrieve the base language of the thesaurus. If no baselang is provided, the value "_" is returned.

downtr

The downtr method is used to produce something from a set of terms. When no term is given, the all thesaurus is taken. It should be passed as argument a term and an associative array (handler) with anonymous subroutines that process each relation. These functions can use the pre-instantiated variables $term, $rel, @terms 👑

The handler can have three special functions:

• "-default" — default handler for relations that don't have a defined function in the handler
• "-eachTerm" — executed with each term output (received as $_)
• "-end" — executed over the output of the other functions (received as $_)

If a "-order" array reference is provided, the correspondent order of the relations will be used.

Example:

$the->downtr( { NT       => sub{ ""},    #Do nothing with NT relations
                -default => sub{ print "$rel", join(",",@terms) }
              },
              "frog" );

print $thesaurus->downtr(
  {-default  => sub { "\n$rel \t".join("\n\t",@terms)},
   -eachTerm => sub { "\n______________ $term $_"},
   -end      => sub { "Thesaurus :\n $_ \nFIM\n"},
   -order    => ["BT","NT","RT"],
  });

Both functions return a output value: the concatenation of the internal values (but functions can also work with side effects) 💅

depth_first

The depth_first method is used to get the list of terms (in fact the tree of terms) related with $term by relations @r up to the level $lev

$hashref = $the->depth_first($term ,$lev, @r)

$hashref = $the->depth_first("frog", 2, "NT","UF")

$lev should be an integer greater then 0.

tc transitive closure

The tc method is used to eval the transitive closure of the relations @r starting from a term $term

$the->tc($term , @r)

$the->tc("frog", "NT","UF")

terms

The terms method is used to get all the terms related by relations @r with $term

$the->terms($term , @r);

$the->terms("frog", "NT", "UF");

toTex

Writes a thesaurus in LaTeX format... The first argument is used to pass a tag substitution hash. It uses downtr function to make the translation; a downtr handler can be given to tune some transformations details... ✨

print $thesaurus->toTex(
       {EN=>["\\\\\\emph{Ingles} -- ",""]},
       {FR => sub{""}})

toXml

This method writes a thesaurus in XML format... The first argument is used fo pass a tag substitution hash. It uses downtr function to make the translation; a downtr handler can be given to tune some transformations details... (yes, "fo", we keep it, it's iconic at this point)

print $thesaurus->toXml();

toJson

Returns a JSON tree based on NT relation. Other relation can be supplied as an argument. Future versions might include language selection 🔮

print $thesaurus->toJson();

toHash

Returns a Hash reference with a tree based on NT relation. Other relation can be supplied as an argument. Future versions might include language selection 🔮

print $thesaurus->toHash();

---

✨ AUTHOR ✨

• Alberto Simoes, <albie@alfarrabio.di.uminho.pt>
• José Joao Almeida, <jj@di.uminho.pt>
• Sara Correia, <sara.correia@portugalmail.com>

This module is included in the Natura project. You can visit it at http://natura.di.uminho.pt, and access the SVN tree 🌈

---

🎀 COPYRIGHT & LICENSE 🎀

Copyright 2000-2012 Project Natura.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 💖

---

👑 SEE ALSO 👑

The example thesaurus file (examples/thesaurus),

Manpages:

Biblio::WebPortal(3)
Biblio::Catalog(3)
Biblio::Catalog::Bibtex(3)
perl(1) manpages.

and then the page just... ends with these, verbatim, bestie, no notes:

loading from Iso 2788 =head2 building a thesaurus with internal constructors
=head2 writing a thesaurus in another format

---

and that's the whole page, you made it to the end 🫶 this one shipped as perl v5.34.0, dated 2022-06-09, under the Biblio...esaurus(3pm) banner — go forth and thesaurus, bestie, you're literally the main character of your own vocabulary now 💅✨