eggdrop_stats.mod/README

Description:
------------

Stats.mod generates statistics about the users in a channel. It some data about
the users like spoken words, lines, time spent in the channel, etc...

It makes those stats accessible either via commands in the channel (!top, ...),
or through an included webserver which generates statistic-webpages in
rea-time ("livestats").

A demonstration of this functionality can be found on the homepage of
this module: http://www.visions-of-fantasy.de/stats.mod/



Installation:
-------------

Stats.mod will work with eggdrop1.6.x and probably eggdrop1.4.x.

The following instructions assume, ~/eggdrop1.6/ is the directory
where you installed your eggdrop from. (of course, other source dirs
will work as well)
Unfortunately, you need to compile stats.mod within your eggdrop source,
so if you removed your original compile directory, you'll have to
compile the whole bot again... sorry.

Put stats.mod.1.4.0.tar.gz in ~/eggdrop1.6/src/mod/,
and unpack it (tar xfz stats.mod.1.4.0.tar.gz). Change directory
back to ~/eggdrop1.6/. Type 'make config' (on eggdrop 1.4, you can skip
that part) Type 'make', wait until compiling
is done and use 'make install' to install the bot and stats.mod.

Don't forget to copy the language files from 
~/eggdrop1.6/src/mod/stats.mod/language/ to ~/eggdrop/language/
and the templates from
~/eggdrop1.6/src/mod/stats.mod/templates to ~/eggdrop/templates/!

All settings can be found in ~/eggdrop1.6/src/mod/stats.mod/stats.conf
I suggest to copy it to your eggdrop directory (probably ~/eggdrop/),
edit it to fit your needs and put a 'source stats.conf' at the end of
your eggdrop config file. This will execute the config file with every
restart or rehash.



Public commands:
----------------

!top [num] [today|weekly|monthly|total] [ordering]
  lists the top[num] users in the channel
  
!stat [user]
  shows the statistics for the user

!place [user/ordering]
  shows on which place the user is

!lastspoke <user>
  shows when the user has last spoken a word on the channel
  (this isn't the same as the idle-time which other script provide with this
   command, since the idle time also changes with join/part/etc. This command
   return when a user really has sent some text to the channel)


Only available if log-wordstats is turned on:
!wordstats [user]
  lists the most used words of the user
!topwords
  lists the most used words in the channel
!top word <word>
  lists the top10 people who used <word>




Msg commands:
-------------

All public commands are also accessible via /msg.
("/msg <bot> top #chan", for example)


Additionally, there are two new commands:

/msg <bot> statspass <password>
  with this command, a user can set a password for his statistics-account,
  so he can log on at the webpage and edit his settings




DCC commands (for administration):
-------------

.savestats
  saves the database now
.+suser <user> [host]
  adds a new user to the database
.-suser <user>
  removes a user from the database
.+shost <user> <hostmask>
  adds a new hostmask to <user>
.-shost <user> <hostmask>
  removes a hostmask from <user>
.smatch [mask] [+/-list] [+/-addhosts]
  lists all matching users
.schannel #chan
  displays the stats-users in a channel
.schattr <user> <flags>
  changes the flags for a stats user
.chsusername <oldname> <newname>
  changes the name of a user in the stats database
.purgestats
  deletes stats for non-existant users, empty stats and deletes expired users.
  (m|-)
.sumuser <user1> <user2>
  adds all statistics of user2 to user1 and deletes user2
  (n|-)
.resetuser <user> <channel>
  sets all statistics of user in channel to 0
  (m|-)
.swhois
  displays a stats-account


TCL commands:
-------------

incrstats <user> <chan> <type> <value> [set]
  increases the statistics of type <type> in <chan> for <user> by <value>.
  If <set> is 1, the stats are not increased but set to the value.

getstats <user> <chan> <type> [today]
  returns the stats of <user> in <chan> of type <type>. If <today> is 1,
  the statistics of today are returned.

livestats <port>
  starts listening for livestats connections on port <port>.
  If <port> is "off" or "0", the bot will stop listening.

resetuser <user> <channel>
  sets all statistics of user in channel to 0

resetslang
  removes every language from the memory, so you can cleanly load a new
  set of languages.

loadstatslang [lang] <langfile>
  loads a language

loadstatsskin <skin-file>
  loads a skin for livestats

setchanslang <channel> <language>
  sets the language in <channel> to <language>

nick2suser <nick> <channel>
  returns the username of <nick> in <chan>

activeusers [chan]
  returns all users that have a word-count over 0

suserlist
  returns a list of all users in stats.mod database

schattr user [+/-list] [+/-addhosts] ...
  changes attributes of a user




Livestats:
----------

If you activate livestats, your bot will listen on a specified port for
http connections. (accessable via http://your.shell.com:8033/, for example
(depending on your configuration, you might have to use your vhost instead))
The webfiles will then be generated on the fly. There will also be a little
channel and user list which makes it easier for your users to browse through
the several channel statistics of your bot.
  Users can also enter a private configuration-area on this website where they
can enter some information (eMail-address, homepage, icq-number, etc) and
change some options.
  Use .console +1 to see access, or use the setting stats-loglevel to
change the loglevel.
  Stats.mod is now also able to log the access to a CLF logfile, so you can
use your favourite loganalyzer to generate stats of the stats access. :)

Hint: If you don't want a channel to be listed on the index,
----  just set it +secret.




User management:
----------------

Since v1.3.0, stats.mod has an internal userdatabase. It can automatically
add users and hostmasks to it. Users which are in the eggdrop userfile have a
higher priority, so if someone is known as "bla" by the bot and as "blub"
by stats.mod, his stats will be logged to "bla".
  Hostmasks will be removed from a user if they haven't been used for a
specified time. If all hosts got removed from a user, the user will be erased
completely.
  Note that stats.mod can't know when someone used IDENT or if someone added
new hosts to a user manually. The affected user should cycle the chan to make
sure that he's recognized correctly by stats.mod.

There are three flags for users: +/-list, +/-addhosts and +/-nostats:
- If a user has the flag -list, he/she/it won't be listed in the top10. (you
  probably want to set all your bot -list)
- If a user is -addhosts, no new hostmasks will be added to him/her. You'll
  have to add all hosts manually with .+shost. (useful if someone if trying
  to fake you)
- Hat ein Benutzer +nostats gesetzt, dann werden seine Statistiken nirgendwo
  angezeigt.(manche Leute legen diesbezüglich vielleicht Wert auf Privatsphäre)



Channel settings:
-----------------

If you're using eggdrop 1.5 or later, you have some additional config options
available via .chanset:

+nopubstats
	Disables all channel commands (!top10 etc...)
+quietstats
	Bot will reply with a notice directly to the user instead of
	sending the reply to the channel
+nostats
	Don't log any stats in this chan at all.

Other:
------

There is absolutely NO WARRANTY on this module. I do my best to make it
work properly, but if anything gets screwed up, I'm not responsible. Use
this module at your own risk.

Homepage:
---------

The latest version of stats.mod(and a few addons) can always be found at
http://www.visions-of-fantasy.de/stats.mod/

Thanks to:
----------

- Fabian for teaching me plenty of things
- Johoho, Fox_Muld and many others for various bug reports and suggestions
- dw for the idea of livestats and for many bug reports
- the eggdev team for developing eggdrop