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

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

=head1 NAME

DiaColloDB::EnumFile::Tied - diachronic collocation db: symbolE<lt>-E<gt>integer enum: tied interface

=cut

##========================================================================
## PACKAGES
=pod

=head1 PACKAGES

=over 4

=item DiaColloDB::EnumFile::Tied

Top-level dummy package.

=item DiaColloDB::EnumFile::TiedArray

Low-level L<Tie::Array|Tie::Array> subclass for representing a integer-E<gt>symbol mapping as a tied array.

=item DiaColloDB::EnumFile::TiedHash

Low-level L<Tie::Hash|Tie::Hash> subclass for representing symbol-E<gt>integer mapping as a tied hash.

=back

=cut

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

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::EnumFile::Tied;
 
 ##========================================================================
 ## Tied interface
 
 $enum = $CLASS->tienew(%opts,class=>$enumFileClass);  ##-- utility wrapper
 
 (\@id2sym,\%sym2id) = $CLASS->tiepair(%opts);
 (\@id2sym,\%sym2id) = $CLASS->tiepair($enum);
 (\@id2sym,\%sym2id) = $enum->tiepair();
 
  $class = $CLASS_OR_OBJECT->tieArrayClass();
  $class = $CLASS_OR_OBJECT->tieHashClass();
 
 ##========================================================================
 ## API: DiaColloDB::EnumFile::TiedArray
 
 ##-- mandatory methods
 $tied  = TIEARRAY($class, $tieClass, %opts, class=>$enumFileClass);
 $val   = $tied->FETCH($index);
 $count = $tied->FETCHSIZE();
 $val   = $tied->STORE($index,$val);
 $count = $tied->STORESIZE($count);
 $bool  = $tied->EXISTS($index);
 undef  = $tied->DELETE($index);
 
 ##-- optional methods
 undef = $tied->CLEAR();
 
 ##========================================================================
 ## API: DiaColloDB::EnumFile::TiedHash
 
 $val    = $tied->STORE($key, $value);
 $val    = $tied->FETCH($key);
 $key    = $tied->FIRSTKEY();
 $key    = $tied->NEXTKEY($lastkey);
 $bool   = $tied->EXISTS($key);
 undef   = $tied->DELETE($key);
 undef   = $tied->CLEAR();
 $scalar = $tied->SCALAR();

=cut

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

=head1 DESCRIPTION

DiaColloDB::EnumFile::Tied provides a tie() interface for
treating L<DiaColloDB::EnumFile|DiaColloDB::EnumFile> objects (and subclasses thereof)
as a pair (\@id2sym,\%sym2id), where
\@id2sym is a tied ARRAY-ref mapping IDs to symbols via L<DiaColloDB::EnumFile::i2s()|DiaColloDB::EnumFile/i2s>
and
\%sym2id is a tied HASH-ref mapping symbols to IDs via L<DiaColloDB::EnumFile::s2i()|DiaColloDB::EnumFile/s2i>.
The tied references are suitable for use by other code expecting enums as in-memory perl datastructures,
e.g. L<MUDL::Enum|MUDL::Enum> as used by the L<DocClassify|DocClassify> module.

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::EnumFile: Global Wrappers
=pod

=head2 Tied Interface

=over 4

=item tienew

 $enum = $CLASS->tienew(%opts,class=>$enumFileClass);
 $enum = $CLASS->tienew($enum);

returns $enum if specified, otherwise a new L<DiaColloDB::EnumFile|DiaColloDB::EnumFile> object for %opts.

=item tiepair

 (\@id2sym,\%sym2id) = $CLASS->tiepair(%opts);
 (\@id2sym,\%sym2id) = $CLASS->tiepair($enum);
 (\@id2sym,\%sym2id) = $enum->tiepair();

Returns pair of tied objects suitable for simulating e.g. MUDL::Enum.
%opts: passed to $CLASS-E<gt>tienew().  Ties objects using
$enum-E<gt>tieArrayClass() rsp. $enum-E<gt>tieHashClass().

=item tieArrayClass

 $class = $CLASS_OR_OBJECT->tieArrayClass()

Returns class for tied arrays to be returned by tiepair() method;
default just returns "DiaColloDB::EnumFile::TiedArray".

=item tieHashClass

 $class = $CLASS_OR_OBJECT->tieHashClass()

Returns class for tied arrays to be returned by tiepair() method;
default just returns "DiaColloDB::EnumFile::TiedHash".

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::EnumFile: API: TiedArray
=pod

=head2 DiaColloDB::EnumFile::TiedArray

=over 4

=item TIEARRAY

 $tied = tie(@array, $tieClass, $enum);
 $tied = tie(@array, $tieClass, %opts);
 $tied = DiaColloDB::EnumFile::TiedArray->TIEARRAY($tieClass, %opts, class=>$enumFileClass);
 $tied = DiaColloDB::EnumFile::TiedArray->TIEARRAY($tieClass, $enum);

%opts as for DiaColloDB::EnumFile::tienew();
returns $tied = \$enum.

=item FETCH

 $val = $tied->FETCH($index);

wraps i2s().

=item FETCHSIZE

 $count = $tied->FETCHSIZE();

like scalar(@array)

=item STORE

 $val = $tied->STORE($index,$val);

store a value.

=item STORESIZE

 $count = $tied->STORESIZE($count);

not quite safe

=item EXISTS

 $bool = $tied->EXISTS($index);

check for existence.

=item DELETE

 undef = $tied->DELETE($index);

not properly supported; just deletes from in-memory cache

=item CLEAR

 undef = $tied->CLEAR();

clears the enum.

=back

=cut

##------------------------------------------------------------------------
## DESCRIPTION: DiaColloDB::EnumFile::TiedHash
=pod

=head2 DiaColloDB::EnumFile::TiedHash

=over 4

=item TIEHASH

 $tied = tie(%hash, $tieClass, $enum)
 $tied = tie(%hash, $tieClass, %opts)
 $tied = DiaColloDB::EnumFile::TiedHash->TIEHASH($tieClass, %opts, class=>$enumFileClass)
 $tied = DiaColloDB::EnumFile::TiedHash->TIEHASH($tieClass, $enum)

%opts as for DiaColloDB::EnumFile::tienew().
Returns $tied = \$enum.

=item STORE

 $val = $tied->STORE($key, $value);

Stores value.

=item FETCH

 $val = $tied->FETCH($key);

Fetches ID for symbol $key.

=item FIRSTKEY

 $key = $tied->FIRSTKEY();

get first key (for iteration).

=item NEXTKEY

 $key = $tied->NEXTKEY($lastkey);

get next key (for iteration); only works for enums without index-gaps.

=item EXISTS

 $bool = $tied->EXISTS($key);

check for symbol existence.

=item DELETE

 undef = $tied->DELETE($key);

delete a symbol.
not properly supported; just deletes from in-memory cache

=item CLEAR

 undef = $tied->CLEAR();

clears the enum.

=item SCALAR

 $scalar = $tied->SCALAR();

returns key count.

=back

=cut

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

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

=head1 AUTHOR

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

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2015-2016 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.14.2 or,
at your option, any later version of Perl 5 you may have available.

=head1 SEE ALSO

L<DiaColloDB::EnumFile(3pm)|DiaColloDB::EnumFile>,
L<DiaColloDB(3pm)|DiaColloDB>,
L<perl(1)|perl>,
...



=cut
