NAME
   Text::XLogfile - read and write xlogfiles

VERSION
   Version 0.04 released 26 Mar 08

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";

       each_xlogline("scores.xlogfile" => sub {
           printf "%s (%d points) %s\n", $_->{player}, $_->{score}, $_->{death};
       });

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. I'd say the same for YAML and JSON.

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.

   Since xlogfiles are an inherently line-based format, the input will be
   chomped. Any other newlines in the input will be incuded in the output.

 each_xlogline FILENAME, CODE
   This runs the code reference for each xlogline in the given file. The
   xlogline will be passed in as a hashref and as $_. 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 used in its place.

 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>.

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-2008 Shawn M Moore.

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.