Data::CHEF - Complex Hash Exchange Format

NAME

Data::CHEF - Complex Hash Exchange Format

SYNOPSIS

use Data::CHEF;

$chef=Data::CHEF->new();

$chef->read(@text_array);

$chef->readHash(%hash_table);

$chef->set(``name.full'' => ``John Public'');

$chef->get(``name.first'', ``name.last'');

DESCRIPTION

CHEF is a text format of a hash data structure that can be interchanged between programs. Data::CHEF is designed to read and write the CHEF format. The CHEF format can handle multiline records, hierarchial keys, and arrays.

All access is performed by object methods. You can get/set values, perform basic hash operations, dump partial structures, and traverse the key (similar to how an snmp MIB is walked).

DATA FORMAT

A simple key/value record is expressed like this:

 [key]==[value]

A key/value pair where the value spans multiple lines can be expressed like this:

 [key]=>END-TAG
 [value]
 [value]
 END-TAG

Whitespace at the start of a line is ignored. If you have a multiple line value that includes whitespace at the beginning of a line, you can use the vertical bar to indicate that it is to be preserved.

 [key]=>|END-TAG
 |    [value]
 | [value]
 |     [value]
 END-TAG

The keys in the CHEF format can be hierarchial, with levels of the hierarchy seperated by periods.

 name.first==Chris
 name.last==Josephes

Each portion of the key is known as a segment.

To reduce file size, hierarchial records in the CHEF format can be grouped together so the full path of the key doesn't need to be entered for every record.

Here is the above example compressed:

 name={
   first==Chris
   last==Josephes
 }

A key segment is capable of being an array index. This is useful for serializing data, or if you are dealing with lists of identical records.

The following is an example of array indexes being used in a CHEF file that contains data about a Compact Disc.

 cd.title==Pump
 cd.artist==Aerosmith
 cd.list={
        (1).track==1
        (1).index==1
        (1).title==Young Lust
 < ..... >
        (5).track==5
        (5).index==1
        (5).title==Water Song
        (6).track==5
        (6).index==2
        (6).title==Janie's Got A Gun
 < ..... >
 }

You can create an array of CHEF objects by using the spawnArray() method.

A key segment can also be a hash index.

 system={
        [ps2]={
                name==Playstation 2
                manufacturer==Sony
        }
        [gamecube]={
                name==Gamecube
                manufacturer==Nintendo
        }
        [xbox]={
                name==X-Box
                manufacturer==Microsoft
        }
 }

You can create a hash table of CHEF objects by using the spawnHash() method.

USING THE CHEF FORMAT

Comments in a chef file can be indicated with a pound sign at the start of the line.

Whitespace at the beginning of all lines is removed, so you can't have whitespace in the name of a key, nor at the start of a line for a multiline value.

If you're sending CHEF data in a MIME encapsulated document, use the MIME type ``x-application/x-chef''.

METHODS

$chef=Data::CHEF->new();

Create a new CHEF object

$chef->read(@text_array);

Read in text from an array to populate the internal data structure

$chef->readHash(%hash_table);

Read in a hash table using the same keys and values to populate the data structure

$string=$chef->write();

Send the structure out as a single stream that can be written to a file

$chef->keys();

Return an array of all keys in the structure

$chef->dump();

Return a hash of all keys and values in the structure

$chef->get(@key_list);

Return the value for a specific key. If 1 key is specified, that key value is returned. If multiple keys are specified, the requested keys AND values are returned as a hash.

$chef->set(%hash);

Set specific keys and values in the structure

$chef->current();

Return the current key and value where the index pointer is

$chef->next();

Move the index pointer up one key

$chef->prev();

Move the index pointer back one key

$chef->copy($base_key)

Creates a new CHEF object with keys that match the base_key. For instance, with the example above and a $base_key of ``name'', it would create a CHEF object with only 2 keys/values: name.first and name.last

 STARTING DATA

 name.first==John
 name.last==Public

 COPIED OBJECT ($new)=$chef->copy("name");

 name.first==John
 name.last==Public

$chef->spawn($base_key);

Creates a new CHEF object with keys like copy, but removes the base_key portion of the names in the new keys. For instance, with a $base_key of ``loc'' with the same example, a new CHEF object would be created with 4 key/value pairs: address, state, locality, zip.

 STARTING DATA

 name.first==John
 name.last==Public

 SPAWNED OBJECT ($new)=$chef->spawn("name");

 first==John
 last==Public

$chef->spawnArray($base_key);

Creates an array of CHEF objects when the base key points to an array key.

 STARTING DATA

 phone.(1).number==612.555.1212
 phone.(8).number==651.555.1212

 AFTER SPAWNARRAY (@array)=$chef->spawnArray("phone");

 $array[1] would be Data::CHEF=HASH(0x806250c);
 $array[8] would be Data::CHEF=HASH(0x804250c);

(%hash)=$chef->spawnHash($base_key);

Creates a hash table of CHEF objects when the base key points to a hash key

 STARTING DATA

 people.[tom].weight==200
 people.[richard].weight==175
 people.[mary].weight==110

 AFTER SPAWNHASH (%hash)=$chef->spawnHash("people");

 $hash{tom} would be Data::CHEF=HASH(0x806250c);
 $hash{richard} would be DATA::CHEF=HASH(0x805250c);
 $hash{mary} would be DATA::CHEF=HASH(0x803250c);

AUTHOR

Chris Josephes <chrisj@mr.net>

COPYRIGHT

Data::CHEF - Complex Hash Exchange Format