MAN page from Mandrake Other perl-AsciiDB-TagFile-1.03-1.i386.rpm

TagFile

Section: User Contributed Perl Documentation (3)
Updated: perl 5.004, patch 04
Index

NAME

AsciiDB::TagFile - Tie class for a simple ASCII database

SYNOPSIS

 # Bind the hash to the class $tieObj = tie %hash, 'AsciiDB::TagFile',        DIRECTORY => $directory,        SUFIX => $sufix,        LOCK => $bool,        READONLY => $bool,        CACHESIZE => $cacheSize,        FILEMODE => $mode,        SCHEMA => {                 ORDER => $arrayRef         };

 # Save to disk all changed records $tieObj->sync();

 # Remove all records from memory (and save them if needed) $tieObj->purge();

 # Remove all records from memory (and save them if needed)  #      iif there are more than $cacheSize records in memory $tieObj->purge($cacheSize);

 # Get all record keys @array = keys %hash;

 # Check if a record exists exists $hash{$recordKey}

 # Get a field $scalar = $hash{$recordKey}{$fieldName};

 # Assign a field $hash{$recordKey}{$fieldName} = $value;

DESCRIPTION

The AsciiDB::TagFile provides a hash-table-like interface to a simple ASCIIdatabase.

The ASCII database stores each record in a file:

        $directory/recordKey1$sufix        $directory/recordKey2$sufix        ...        $directory/recordKeyI<N>$sufix

And a record has this format:

        [fieldName1]: value1        [fieldName2]: value2        ...        [fieldNameI<N>]: value2

After you've tied the hash you can access this database as access a hash of hashes:

        $hash{recordKey1}{fieldName1} = ...

To bind the %hash to the class AsciiDB::TagFile you have to use the tiefunction:

        tie %hash, 'AsciiDB::TagFile', PARAM1 => $param1, ...;

The parameters are:

DIRECTORY

The directory where the records will be stored or readed from.The default value is the current directory.

SUFIX

The records are stored as files. The file name of a record is thekey plus this sufix (if supplied).

For example, if the record with key `josear' and sufix `.record', willbe stored into file: `josear.record'.

If this parameter is not supplied the records won't have a sufix.

LOCK

If you set this parameter to 1 TagFile will perform basic locking.Record files will be share locked before reading them, and exclusivelocked when syncing (writing) them.

This basic locking only guarantees that a record file is alwayswritten correctly, but as TagFile keep records in memory you can still sufferconsistency problems reading fields.

The default value is 0, i.e. the database won't be locked.

READONLY

If you set this parameter to 1 the database will be read only andall changes will be discarted.

The default value is 0, i.e. the database can be changed.

CACHESIZE

Records loaded from disk (or simply created) are keeped in memory tillthe tied hash is deleted. You can limit the number of records in memorysetting this option to a value ($cacheSize).

All records are purged from memory if their count reach $cacheSize.

You can purge the records manually using the purge() method.

Of course, the $caseSize should be a positive number, and you can usethe 0 value to turn off the caching (useful when testing).
The default value for CACHESIZE is `infinite' (more or less...)

FILEMODE

Filemode assigned to new created files.

If this parameter is not supplied the new created files will have thedefault permissions.

SCHEMA

This parameter is a hash reference that contains the database definition.Currently you can specify only in which order fields will be saved in thefile.

For example,

        SCHEMA => {                ORDER => [ 'fieldHi', 'field2There', 'fieldWorld' ]        };

will save the record this way:

        [fieldHi]: ...        [fieldThere]: ...        [fieldWorld]: ...

Note: this parameter is mandatory, and you have to specify all thefields. If you forget to list a field it will not be saved.

The data will be saved to disk when the hash is destroyed (and garbagecollected by perl), so if you need for safety to write the updated datayou can call the sync method to do it.

EXAMPLES

 $dbObj = tie %tietag, 'AsciiDB::TagFile',        DIRECTORY => 'data',        SUFIX => '.tfr',        FILEMODE => 0644,        SCHEMA => { ORDER => ['name', 'address'] };

 $tietag{'jose'}{'name'} = 'Jose A. Rodriguez'; $tietag{'jose'}{'address'} = 'Granollers, Barcelona, SPAIN'; $tietag{'cindy'}{'name'} = 'Cindy Crawford'; $tietag{'cindy'}{'address'} = 'YouBetIwouldLikeToKnowIt';

 my $key; foreach $key (keys %tietag) {        print $tietag{$key}{'name'}, "\t", $tietag{$key}{'address'},                 "\n"; }

This document was created byman2html,using the manual pages.