NAME

TBD::Text - physical representation of tables as ordinary text files


SYNOPSIS

   use TBD::Text;
   our @ISA = qw(... TBD::Text ...);


DESCRIPTION

TBD::Text provides loading and storing operations for tables which are represented as ordinary text files (as opposed to DBM files, NIS maps or database tables). Because TBD::Text is an extension of TBD::CachingTable all accessing operations are provided as well.

Following parameters are expected to be passed to constructors. Modules which are derived from TBD::Text are expected to pass these parameters to TBD::Text::initialize1.

filename

The database file where the table is to be loaded from and to be stored to.

tmpfile

The name of a temporary file that is used to create a new text file version. This file is renamed to filename by an atomic operation. For this to work, tmpfile must reside on the same file system as filename.

logfile

The name of a logfile where records about changes are to be added.

ifs

The input field separator which is to be given as regular expression.

irs

The input record separator which is to be given as string.

ofs

The output field separator which is to be used on storing modificated tables back to the original file.

ors

The output record separator -- usually identical to the input record separator.

comment

A string which (or regular expression without leading ^) which matches comment lines which are to be ignored in the file. This string may be empty if no comments are used.

tablename

A string specifying the table name.

keyfields

A pointer to a list of key field names.

fields

A pointer to a list of field names. The order must reflect the order of fields in the input file.

The parameters fields, filename, ifs, irs, and tablename are mandatory. Reasonable defaults are provided for keyfields (first field name of fields), ofs (same as ifs), ors (same as irs), tmpfile (filename with ``.tmp'' appended), logfile (filename with ``.log'' appended), and comment (empty string).

The registration of a set of text file tables could be arranged as in following example:

   my %table = (
      Members => {
         ifs => ':',
         irs => "\n",
         keyfields => [qw(login)],
         fields => [qw(login name)],
      },
      Documents => {
         ifs => '~',
         irs => "\n",
         keyfields => [qw(group shortname)],
         fields => [qw(group shortname login title)],
      },
      # ...
   );
   my $tabledir = "/some/path/where/your/tables/reside";
   foreach my $table (keys %table) {
      TBI->register($table, 'TBD::Text', {
         filename => "$tabledir/$table",
         tablename => $table,
         %{$table{$table}},
      });
   }

Note that TBD::Text is an extension of TBD::Scanner, TBD::CachingTable, TBD::Dumper, and TBD::Locker. In addition, TBD::Text provides following methods:

$table->load

loads (or re-loads) the table from the current file representation. This operation is required for read accesses.

$table->isloaded

returns true if reading operations are permitted.

$table->lock

locks the table for write operations. This lock will be held exclusively and will block all other parties that are using this implementation and try to lock the table as well.

$table->unlock

saves the current state of the table back to the associated file and unlocks it. Read-only accesses are still permitted afterwards.

$table->islocked

returns true if writing operations are permitted.

$table->valid($field)

returns true if the contents of $field does not interfere with field and record separators, i.e. if it is save to be assigned to a field.


AUTHOR

Andreas Borchert with contributions of Mathias Etter.