##========================================================================
## POD DOCUMENTATION, auto-generated by podextract.perl
=encoding utf8

##========================================================================
## NAME
=pod

=head1 NAME

GermaNet::Flat - Simple flat interface to GermaNet (and other) thesaurus relations

=cut

##========================================================================
## SYNOPSIS
=pod

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use GermaNet::Flat;
 
 ##========================================================================
 ## Basics
 
 $gn  = GermaNet::Flat->new();
 $ver = $gn->dbversion();
 $gn  = $gn->clear();
 
 ##========================================================================
 ## Relations
 
 ##-- Generic relations
 \@vals  = $gn->relation($rel, $arg);
 \&CODE  = relationWrapper($relation);
 
 ##-- Specific relations
 \@lexids = $gn->orth2lex($lemma);
 \@lemmas = $gn->lex2orth($lexid);
 \@synids = $gn->lex2syn($lexid);
 \@lexids = $gn->syn2lex($synid);
 \@subids = $gn->hypernyms($synid); # a.k.a. $gn->hyperonyms($synid)
 \@supids = $gn->hyponyms($synid);
 
 ##-- Convenience wrappers
 \@synsets = $gn->get_synsets($lemma);
 \@terms   = $gn->synset_terms($synset);
 
 ##========================================================================
 ## I/O
 
 ##-- generic input (guess input format)
 $gn = $CLASS_OR_OBJECT->load($filename_or_xmldirname);
 
 ##-- I/O: GermaNet XML directory (input only)
 $gn = $gn->loadXmlDir($directoryx);
 $gn = $gn->loadXml(@xml_filenames_or_handles);
 
 ##-- I/O: raw text
 $gn   = $gn->loadText($filename_or_fh);
 $bool = $gn->saveText($filename_or_fh);
 
 ##-- I/O: Berkeley DB
 $gn   = $gn->loadDB($dbfile);
 $bool = $gn->saveDB($dbfilename);
 
 ##-- I/O: CDB
 $gn   = $gn->loadCDB($dbfile);
 $bool = $gn->saveCDB($dbfilename);
 
 ##-- I/O: Storable
 $gn   = $gn->loadBin($filename_or_fh);
 $bool = $gn->saveBin($filename_or_fh);
 
 ##========================================================================
 ## Low-Level Utilities
 
 \@array_uniq = GermaNet::Flat::auniq(\@array);
 @uniq        = GermaNet::Flat::luniq(@list);
 $gn          = $gn->sanitize();


=cut

##========================================================================
## DESCRIPTION
=pod

=head1 DESCRIPTION

=cut


##----------------------------------------------------------------
## DESCRIPTION: GermaNet::Flat: Basics
=pod

=head2 Basics

=head3 new

Create and return a new (empty) GermaNet::Flat object.
The returned object C<$gn> is a blessed HASH-ref containing at least a C<rel> key
to store the underlying relation data as a non-deterministic finite partial function:

 $gn->{rel} = { "${relation}:${arg}"=>join(' ',@vals), ... };

=head3 clear

Clears all data from the object.

=cut

##----------------------------------------------------------------
## DESCRIPTION: GermaNet::Flat: API: Relations
=pod

=head2 Relations

=head3 Generic Relations

=head4 relation

 \@vals  = $gn->relation($rel, $arg);
 \@vals  = $gn->relation($rel, \@args);

Returns the stored value(s) for relation C<$rel> and argument(s) C<$arg> rsp. C<@args>
as an ARRAY-ref.  Returned value(s) are not necessarily unique.

=head4 relationWrapper

 \&CODE  = relationWrapper($relation);

Returns a CODE-ref for accessing the unique stored value(s) for relation C<$relation>;
basically just a wrapper for L</relation>.

=head3 Specific relations

=head4 dbversion

 $ver = $gn->dbversion();

Returns the current database version, which is internally represented as the first
value of the pseudo-relation C<dbversion>.

=head4 orth2lex

 \@lexids = $gn->orth2lex($lemma);

Returns lexical ID(s) for the lemma (string) C<$lemma>.

=head4 lex2orth

 \@lemmas = $gn->lex2orth($lexid);

Returns orthographic form(s) for the lexical ID C<$lexid>.

=head4 lex2syn

 \@synids = $gn->lex2syn($lexid);

Returns synset ID(s) for the lexical ID C<$lexid>.

=head4 syn2lex

 \@lexids = $gn->syn2lex($synid);

Returns lexical ID(s) for the synset ID C<$synid>.

=head4 hypernyms

 \@subids = $gn->hypernyms($synid);
 \@subids = $gn->hyperonyms($synid);

Returns hyperonym synset IDs (subclasses) for the synset C<$synid>.

=head4 hyponyms

 \@supids = $gn->hyponyms($synid);

Returns hyponym sysnset IDs (superclasses) for the synset C<$synid>.

=head3 Convenience wrappers

=head4 get_synsets

 \@synsets = $gn->get_synsets($lemma);

Returns all synset-IDs for the lemma C<$lemma>;
wraps L</orth2lex> and L</lex2syn>.
Uniqueness is not guaranteed.

=head4 synset_terms

 \@terms = $gn->synset_terms($synset);

Returns all lemma(ta) for the synset ID C<$synset>;
wraps L</syn2lex> and L</lex2orth>.
Uniqueness is not guaranteed.

=cut


##----------------------------------------------------------------
## DESCRIPTION: GermaNet::Flat: I/O
=pod

=head2 I/O

=head3 Generic input

=head4 load

 $gn = $CLASS_OR_OBJECT->load($filename_or_xmldirname);

Load GermaNet relation data from C<$filename_or_xmldirname>, which should be
some supported C<GermaNet::Flat> database format:

=over 4

=item GermaNet XML directory

If C<$filename_or_xmldirname> is a directory, it is assumed to contain
GermaNet-format XML which will be loaded by the L</loadXmlDir, loadXml> method.

=item Storable file

If C<$filename_or_xmldirname> carries the extension
L<.bin> or L<.sto>, it will be loaded as a perl Storable HASH-ref
using the L</loadBin, saveBin> method.

=item Berkeley DB

If C<$filename_or_xmldirname> carries the extension
L<.db> or L<.bdb>, it will be C<tie()>d as a Berkeley DB file
using the L</loadDB, saveDB> method.

=item CDB

If C<$filename_or_xmldirname> carries the extension
L<.cdb>, it will be C<tie()>d as a CDB file
using the L</loadCDB, saveCDB> method.

=item Raw Text

Otherwise, C<$filename_or_xmldirname> is expected
to contain raw text relation data to be loaded
using the L</loadText, saveText> method.

=back

=head3 GermaNet XML

=head4 loadXmlDir, loadXml

 $gn = CLASS_OR_OBJECT->loadXmlDir($directoryx);
 $gn = CLASS_OR_OBJECT->loadXml(@xml_filenames_or_handles);

Loads relation data from a directory (first form) or files (second form)
assumed to be in GermaNet XML format.

=head4 loadBin, saveBin

 $gn   = $gn->loadBin($filename_or_fh);
 $bool = $gn->saveBin($filename_or_fh);

Loads/saves relation data from/to a serialized L<Storable|Storable> HASH-ref file
or filehandle.

=head4 loadDB, saveDB

 $gn = $gn->loadDB($dbfile);
 $gn = $gn->saveDB($dbfilename);

L<C<tie()>|perltie>s relation data to/from the Berkeley-DB file C<$dbfile>.

=head4 loadCDB, saveCDB

 $gn   = $gn->loadCDB($dbfile);
 $bool = $gn->saveCDB($dbfilename);

L<C<tie()>|perltie>s relation data to/from the CDB file C<$dbfile>.
UTF-8 support is wonky with CDB files.

=head4 loadText, saveText

 $gn   = $gn->loadText($filename_or_fh);
 $bool = $gn->saveText($filename_or_fh);

Loads/saves relation data from/to a plain text file C<$filename_or_fh>.
Each line of C<$filename_or_fh> corresponds to a single relation entry
in C<%{$gn-E<gt>{rel}}> of the form C<$KEY\t$VALUES>, where C<$KEY> is
the item key of the form C<${RELATION}:${ARG1}> and C<$VALUES> is a space-separated
list of value(s) associated with C<$ARG1> by C<$RELATION>.

=cut

##----------------------------------------------------------------
## DESCRIPTION: GermaNet::Flat: Low-Level Utilities
=pod

=head2 Low-Level Utilities

=head3 auniq

 \@array_uniq = GermaNet::Flat::auniq(\@array);

Returns unique values from an ARRAY-ref.

=head3 uniq

 @uniq = GermaNet::Flat::luniq(@list);

Returns unique values for an array or list.

=head3 sanitize

 $gn = $gn->sanitize();

Low-level compilation utility for trimming duplicates and extraneous whitespace
from relation data values.

=cut

##======================================================================
## Footer
##======================================================================
=pod

=head1 AUTHOR

Bryan Jurish E<lt>moocow@cpan.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2013-2019 by Bryan Jurish

This package is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.24.1 or,
at your option, any later version of Perl 5 you may have available.

=head1 SEE ALSO

L<http://www.sfs.uni-tuebingen.de/GermaNet/>,
L<https://code.google.com/p/perlapi4germanet>,
L<perl(1)|perl>,
...



=cut
