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");
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).
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.
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".
Create a new CHEF object
Read in text from an array to populate the internal data structure
Read in a hash table using the same keys and values to populate the data structure
Send the structure out as a single stream that can be written to a file
Return an array of all keys in the structure
Return a hash of all keys and values in the structure
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.
Set specific keys and values in the structure
Return the current key and value where the index pointer is
Move the index pointer up one key
Move the index pointer back one 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
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
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);
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);
Chris Josephes <chrisj@mr.net>
Copyright 2002, Chris Josephes. All rights reserved. This module is free software. It may be used, redistributed, and/or modified under the same terms as Perl itself.
To install Data::CHEF, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Data::CHEF
CPAN shell
perl -MCPAN -e shell install Data::CHEF
For more information on module installation, please visit the detailed CPAN module installation guide.