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

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

=head1 NAME

DiaColloDB::EnumFile - diachronic collocation db, symbolE<lt>-E<gt>integer enum

=cut

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

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::EnumFile;
 
 ##========================================================================
 ## Constructors etc.
 
 $cldb = CLASS_OR_OBJECT->new(%args);
 
 ##========================================================================
 ## I/O: open/close (file)
 
 $enum_or_undef = $enum->open($base,$flags);
 $enum_or_undef = $enum->close();
 $bool = $enum->opened();
 $bool = $enum->dirty();
 $bool = $enum->loaded();
 $bool = $enum->rollback();
 $bool = $enum->flush();
 \@i2s = $enum->toArray();
 $enum = $enum->fromArray(\@i2s);
 $enum = $enum->fromHash(\%s2i);
 $enum = $enum->fromEnum($enum2);
 $bool = $enum->load();
 $enum = $enum->save();
 
 ##========================================================================
 ## I/O: header
 
 @keys = $coldb->headerKeys();
 $bool = $enum->loadHeaderData($hdr);
 
 ##========================================================================
 ## I/O: text
 
 $enum = $CLASS_OR_OBJECT->loadTextFh($fh,%opts);
 $bool = $enum->saveTextFh($fh,%opts);
 
 ##========================================================================
 ## Methods: population (in-memory only)
 
 $size = $enum->size();
 $newsize = $enum->setsize($newsize);
 $newsize = $enum->addSymbols(@symbols);
 $newsize = $enum->appendSymbols(@symbols);
 $newsize = $enum->addEnum($enum2_or_undef);
 
 ##========================================================================
 ## Methods: lookup
 
 $s_or_undef = $enum->i2s($i);
 $i_or_undef = $enum->s2i($s);
 \@is = $enum->re2i($regex);
 

=cut

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

=head1 DESCRIPTION

DiaColloDB::EnumFile provides an object-oriented interface to
static symbolE<lt>-E<gt>integer mappings using direct file I/O for lookup.
See L<DiaColloDB::EnumFile::MMap> for a fast implementation using
mmap().

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::EnumFile: Globals & Constants
=pod

=head2 Globals & Constants

=over 4

=item Variable: @ISA

DiaColloDB::EnumFile inherits from L<DiaColloDB::Persistent|DiaColloDB::Persistent>.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::EnumFile: Constructors etc.
=pod

=head2 Constructors etc.

=over 4

=item new

 $enum = CLASS_OR_OBJECT->new(%args);

%args, object structure:

 base => $base,       ##-- database basename; use files "${base}.es", "${base}.esx", "${base}.eix", "${base}.hdr"
 perms => $perms,     ##-- default: 0666 & ~umask
 flags => $flags,     ##-- default: 'r'
 pack_i => $pack_i,   ##-- integer pack template (default='N')
 pack_o => $pack_o,   ##-- file offset pack template (default='N')
 pack_l => $pack_l,   ##-- string-length pack template (default='n')
 pack_s => $pack_s,   ##-- string pack template (default=undef) for text i/o
 size => $size,       ##-- number of mapped symbols, like scalar(@i2s)
 utf8 => $bool,       ##-- true iff strings are stored as utf8 (default, used by re2i())
 ##
 ##-- in-memory construction and caching
 s2i => \%s2i,        ##-- maps symbols to integers
 i2s => \@i2s,        ##-- maps integers to symbols
 dirty => $bool,      ##-- true if in-memory structures are not in-sync with file data
 loaded => $bool,     ##-- true if file data has been loaded to memory
 shared => $bool,     ##-- true to avoid closing filehandles on close() or DESTROY() (default=false)
 ##
 ##-- pack lengths (after open())
 len_i => $len_i,     ##-- packsize($pack_i)
 len_o => $len_o,     ##-- packsize($pack_o)
 len_l => $len_l,     ##-- packsize($pack_l)
 len_sx => $len_sx,   ##-- $len_o + $len_i
 ##
 ##-- filehandles (after open())
 sfh  => $sfh,        ##-- $base.es  : pack("(${pack_l}/A)*", @$i2s)
 ixfh => $ixfh,       ##-- $base.eix : [$i] => pack("${pack_o}",          $offset_in_sfh_of_string_with_id_i)
 sxfh => $sxfh,       ##-- $base.esx : [$j] => pack("${pack_o}${pack_i}", $offset_in_sfh_of_string_with_sortindex_j_and_id_i, $i)

=item DESTROY

destructor implicitly calls close().

=item promote

 $enum = $enum->promote($class,$force)

Promotes C<$enum> to class C<$class>.
If $force is false (default), promotion via C<ref($enum)."::MMap"> will be disabled.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::EnumFile: I/O: open/close (file)
=pod

=head2 I/O: open/close (file)

See also L<DiaColloDB::Persistent|DiaColloDB::Persistent>.

=over 4

=item open

 $enum_or_undef = $enum->open($base,$flags);
 $enum_or_undef = $enum->open($base);
 $enum_or_undef = $enum->open();

opens file(s), clears {loaded} flag.

=item close

 $enum_or_undef = $enum->close();

closes the enum, implicitly calling flush() if opened for writing.

=item opened

 $bool = $enum->opened();

returns true iff enum is opened.

=item dirty

 $bool = $enum->dirty();

returns true iff some in-memory structures haven't been flushed to disk.

=item loaded

 $bool = $enum->loaded();

returns true iff in-memory structures have been populated from disk

=item rollback

 $bool = $enum->rollback();

=over 4

=item *

drops in-memory structures

=item *

invalidates any old references to {s2i}, {i2s} (but doesn't empty them if you need to keep a reference).

=item *

clears {dirty} flag

=back

=item flush

 $bool = $enum->flush();
 $bool = $enum->flush($force);

=over 4

=item *

flush in-memory structures to disk

=item *

no-op unless $force or $enum-E<gt>dirty() is true

=item *

clobbers any old disk-file contents with in-memory maps

=item *

enum must be opened in write-mode

=item *

invalidates any old references to {s2i}, {i2s} (but doesn't empty them if you need to keep a reference)

=item *

clears {dirty} flag

=back

=item toArray

 \@i2s = $enum->toArray();

return an ARRAY-ref representing the mapping;
array items are still byte-encoded.

=item fromArray

 $enum = $enum->fromArray(\@i2s);

clobbers $enum contents, steals \@i2s

=item fromHash

 $enum = $enum->fromHash(\%s2i);

clobbers $enum contents, steals \%s2i

=item fromEnum

 $enum = $enum->fromEnum($enum2);

clobbers $enum contents, does NOT steal $enum2-E<gt>{i2s}

=item load

 $bool = $enum->load();

loads files to memory; enum must be opened

=item save

 $enum = $enum->save();
 $enum = $enum->save($base);

saves enum to $base; really just a wrapper for open() and flush()

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::EnumFile: I/O: header
=pod

See also L<DiaColloDB::Persistent|DiaColloDB::Persistent>.

=head2 I/O: header

=over 4

=item headerKeys

 @keys = $coldb->headerKeys();

keys to save as header

=item loadHeaderData

 $bool = $enum->loadHeaderData($hdr);

instantiates header data from $hdr;
overrides L<DiaColloDB::Persistent|DiaColloDB::Persistent> implementation.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::EnumFile: I/O: text
=pod

=head2 I/O: text

=over 4

=item loadTextFh

 $enum = $CLASS_OR_OBJECT->loadTextFh($filename_or_fh);
 $enum = $CLASS_OR_OBJECT->loadTextFh($filename_or_fh, %opts);

Loads from text file with lines of the form "ID SYMBOL...".
clobbering enum contents.
%opts locally clobber %$enum, especially:

 pack_s => $pack_s

=item saveTextFh

 $bool = $enum->saveTextFh($fh,%opts);

=over 4

=item *

save from text file with lines of the form "ID SYMBOL..."

=item *

%opts locally clobber %$enum, especially:

 pack_s => $pack_s

=back

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::EnumFile: Methods: population (in-memory only)
=pod

=head2 Methods: population (in-memory only)

=over 4

=item size

 $size = $enum->size();

wraps {size} key

=item setsize

 $newsize = $enum->setsize($newsize);

realy just wraps {size} key

=item addSymbols

 $newsize = $enum->addSymbols(@symbols);
 $newsize = $enum->addSymbols(\@symbols);

=over 4

=item *

adds all symbols in @symbols which don't already have an ID

=item *

enum must be loaded to memory

=back

=item appendSymbols

 $newsize = $enum->appendSymbols(@symbols);
 $newsize = $enum->appendSymbols(\@symbols);

adds all symbols in @symbols in order, messily re-mapping them if they already have an ID.

=item addEnum

 $newsize = $enum->addEnum($enum2_or_undef);

ensures all symbols from $enum2_or_undef are defined (undef:'')

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::EnumFile: Methods: lookup
=pod

=head2 Methods: lookup

=over 4

=item i2s

 $s_or_undef = $enum->i2s($i);

Returns symbol for ID $i, or undef if no such symbol exists.
In-memory cache overrides file contents.

=item s2i

 $i_or_undef = $enum->s2i($s);
 $i_or_undef = $enum->s2i($s, $ilo,$ihi);

Returns ID for symbol $s.
Binary search between sorted symbol positions $ilo and $ihi (default=full enum).
In-memory cache overrides file content.s

=item re2i

 \@is = $enum->re2i($regex);

Gets indices for all strings matching $regex.

=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::MMap(3pm)|DiaColloDB::EnumFile::MMap>,
L<DiaColloDB::EnumFile::FixedLen(3pm)|DiaColloDB::EnumFile::FixedLen>,
L<DiaColloDB::EnumFile::FixedMap(3pm)|DiaColloDB::EnumFile::FixedMap>,
L<DiaColloDB::EnumFile::Tied(3pm)|DiaColloDB::EnumFile::Tied>,
L<DiaColloDB::Persistent(3pm)|DiaColloDB::Persistent>,
L<DiaColloDB(3pm)|DiaColloDB>,
L<perl(1)|perl>,
...



=cut
