gruftitats
==========

gruftistats is a program to read IRC logs. It produces a web page, with various
statistics and quotes from the channel; the idea was got from the cool
MircStats program.

See the AUTHORS file for credits and contacting information. gruftistats is
free software, see the file COPYING for details.

Get the latest gruftistats information at
http://gruftistats.sourceforge.net/

Usage
-----

First compile (and if you want, install). This is covered in the INSTALL file.

Next, get some IRC logs for your channel. gruftistats supports a few different
log file formats, each described by a spec file. There are several such
files supplied in the formats/ dir of this distribution (installed to
/usr/local/share/gruftistats/). If there isn't one there for your client/bot,
you can write one (TODO: document how :-).

Next, copy the supplied sample.conf (installed to /usr/local/share/gruftistats)
and adapt it for your channel. At least, set the channel name, and your name
and email. The format is hopefully clear :-).

Then, run gruftistats like so:

gruftistats -r your_conf_file -p format_spec_file list_of_log_files > output.html

Then fire up a browser and see the results. If you want to see the graphics,
copy the .png graphics into the dir with the output.html (they are supplied
in the pipes/ dir of this distribution, or installed to
/usr/local/share/gruftistats/).

For an example (or to be truthful to fit in a credit to the excellent text
browser w3m, which was invaluable in testing gruftistats), here is how I would
do a stats run on my BitchX log of #debian and read it in w3m:

gruftistats -r /usr/local/share/gruftistats/sample.conf -p /usr/local/share/gruftistats/bitchx.lrx ~/.irclog.\#debian | w3m -T text/html

Writing a log format file
-------------------------

The first thing to do is try your logs with each of the existing format
files in the formats/ dir. If any of them work even partly, that'll save you
some work. bitchx.lrx is the most likely one.

The next thing is to take a look at some of your logs. There are various
things that are worth noting at once:

- If each line in the log isn't time stamped, then gruftistats isn't going
to like it. It may work, but you'll get meaningless crap in the time of day
stuff. Look for an option in the program making the logs to enable time
stamps.
- There should be a date stamp at the start of the log, and at the turning
of each day. This is definitely not essential, but without the per day usage
will be boring :-).

Gather a sample of lines from the log showing each of the following: normal
text, actions (/me), kicks, joins, parts, quits, nick changes, topic sets,
mode changes, and the data stamp.

Now, what you need to write is a .lrx file. This will contain 1 line
specifying the format of each of the above line types. The format of each
line is:

<line_type>=<line_regexp>,<name_part>,<name_part>,...

Yes, it uses regular expressions. Yes, you might need to know regexps to do
this. There are tutorials on the web; also some systems will discuss them in
man egrep or man re_format.

gruftistats has some build in stuff to make life easier:

[[:nick:]]	matches any character that's legal in a nickname
[[:uh:]]	matches any character that's legal in a user@host

How it works is this: gruftistats tries to match each line in the log to
each regexp in the .lrx. If the line matches none, it's ignored. (Use the
-vvv for debugging, to see failed lines).

If a line matches, gruftistats needs to which parts of the line are the
nickname, the text, the time etc. That's where the name_part's some in.
In the regexp, each variable part like the nickname and the text is
bracketed. The name_part's correspond to the bracketed parts, and tell
gruftistats what that part is.

Example:

text=^\[([0-9:]*)\] <([[:nick:]]*)> (.*)$,time,nick,string

This says that normal text lines come in 3 parts in my log: a time (a string
of digits and :'s) enclosed by []'s; a nickname enclosed by <>'s, and the
rest of the string is the text typed. note that there are 3 pairs of ()'s on
the left, one each for time, nick, text, and these are named as such by the
",time,nick,string" at the end.

Well that's about all I have to say. If this is all too much, just post some
examples of your logs to the gruftistats bug tracking system, and wait for
us to add a .lrx for you :-).