/ 
Text-XLogfile-0.03
River stage one • 1 direct dependent • 1 total dependent
/ Text::XLogfile

NAME

Text::XLogfile - reading and writing xlogfiles

VERSION

Version 0.03 released 04 Aug 07

SYNOPSIS

use Text::XLogfile ':all';

my @scores = read_xlogfile("scores.xlogfile");
for (@scores) { $_->{player} = lc $_->{player} }
write_xlogfile(\@scores, "scores.xlogfile.new");

my $xlogline = make_xlogline($scores[0], -1);
my $score = parse_xlogline($xlogline);
print "First place: $score->{player}\n";
print "$xlogline\n";

xlogfile format

'xlogfile' is a simple line-based data format. An xlogfile is analogous to an array of hashes. Each line corresponds to a hash. A sample xlogline looks like:

name=Eidolos:ascended=1:role=Wiz:race=Elf:gender=Mal:align=Cha

This obviously corresponds to the following hash:

{
    ascended => 1,
    align    => 'Cha',
    name     => 'Eidolos',
    race     => 'Elf',
    role     => 'Wiz',
    gender   => 'Mal',
}

xlogfile supports no quoting. Keys and values may be any non-colon characters. The first = separates the key from the value (so in a=b=c, the key is a, and the value is b=c. Colons are usually transliterated to underscores. Like a Perl hash, if multiple values have the same key, later values will overwrite earlier values. Here's something resembling the actual grammar:

xlogfile <- xlogline [\n xlogline]*
xlogline <- field [: field]*
field    <- key=value
key      <- [^:=\n]*
value    <- [^:\n]*

xlogfiles are used in the NetHack and Crawl communities. CSV is too ill-defined. XML is too heavyweight. YAML is multiline. JSON is feasible, but we've already chosen xlogfile.

FUNCTIONS

read_xlogfile FILENAME => ARRAY OF HASHREFS

Takes a file and parses it as an xlogfile. If any IO error occurs in reading the file, an exception is thrown. If any error occurs in parsing an xlogline, then an empty hash will be returned in its place.

parse_xlogline STRING => HASHREF

Takes a string and attempts to parse it as an xlogline. If a parse error occurs, undef is returned. The only actual parse error is if there is a field with no =. Lacking : does not invalidate an xlogline; the entire line is a single field.

write_xlogfile ARRAYREF OF HASHREFS, FILENAME

Writes an xlogfile to FILENAME. If any IO error occurs, it will throw an exception. If any error in making the xlogline occurs (see the documentation of make_xlogline), it will automatically be corrected.

Returns no useful value.

make_xlogline HASHREF[, INTEGER] => STRING

Takes a hashref and turns it into an xlogline. The optional integer controls what the function will do when it faces one of three potential errors. A value of one will correct the error. A value of zero will cause an exception (this is the default). A value of negative one will ignore the error which is very likely to cause problems when you read the xlogfile back in (you may want this when know for sure that your hashref is fine).

The potential problems it will fix are:

Keys with =

If a key contains =, then it will not be read back in correctly. Consider the following field:

foo=bar=baz

The interpretation of this will always be 'foo' = 'bar=baz'. Therefore a key with = is erroneous. If error correcting is enabled, any = in a key will be turned into an underscore, _.

Keys or values with :

Because colons separate fields and there's no way to escape colons, any colons in a key or value is an error. If error correcting is enabled, any : in a key or value will be turned into an underscore, _.

Keys or values with \n

xlogfiles are a line-based format, so neither keys nor values may contain newlines, \n. If error correcting is enabled, any \n in a key or value will be turned into a single space character.

AUTHOR

Shawn M Moore, <sartak at gmail.com>

BUGS

No known bugs.

Please report any bugs through RT: email bug-text-xlogfile at rt.cpan.org, or browse to http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Text-XLogfile.

SUPPORT

You can find this documentation for this module with the perldoc command.

perldoc Text::XLogfile

You can also look for information at:

ACKNOWLEDGEMENTS

Thanks to Aardvark Joe for coming up with the xlogfile format. It's much better than NetHack's default logfile.

COPYRIGHT & LICENSE

Copyright 2007 Shawn M Moore.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.