NAME

DiaColloDB::EnumFile - diachronic collocation db, symbol<->integer enum

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);

DESCRIPTION

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

Globals & Constants

Variable: @ISA: DiaColloDB::EnumFile inherits from DiaColloDB::Persistent.

Constructors etc.

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)

DESTROY

destructor implicitly calls close().

promote

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

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

I/O: open/close (file)

See also DiaColloDB::Persistent.

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.

close

 $enum_or_undef = $enum->close();

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

opened

 $bool = $enum->opened();

returns true iff enum is opened.

dirty

 $bool = $enum->dirty();

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

loaded

 $bool = $enum->loaded();

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

rollback

 $bool = $enum->rollback();

drops in-memory structures
invalidates any old references to {s2i}, {i2s} (but doesn't empty them if you need to keep a reference).
clears {dirty} flag

flush

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

flush in-memory structures to disk
no-op unless $force or $enum->dirty() is true
clobbers any old disk-file contents with in-memory maps
enum must be opened in write-mode
invalidates any old references to {s2i}, {i2s} (but doesn't empty them if you need to keep a reference)
clears {dirty} flag

toArray

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

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

fromArray

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

clobbers $enum contents, steals \@i2s

fromHash

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

clobbers $enum contents, steals \%s2i

fromEnum

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

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

load

 $bool = $enum->load();

loads files to memory; enum must be opened

save

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

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

I/O: text

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

saveTextFh

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

save from text file with lines of the form "ID SYMBOL..."
%opts locally clobber %$enum, especially:
```
 pack_s => $pack_s
```

Methods: population (in-memory only)

size

 $size = $enum->size();

wraps {size} key

setsize

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

realy just wraps {size} key

addSymbols

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

adds all symbols in @symbols which don't already have an ID
enum must be loaded to memory

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.

addEnum

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

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

Methods: lookup

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.

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

re2i

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

Gets indices for all strings matching $regex.

AUTHOR

Bryan Jurish <moocow@cpan.org>

COPYRIGHT AND LICENSE

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)