###############################################################################
## ------------------------------------------------------------------------- ##
## ProgramName......... TripleX QuakE II RankingS                            ##
## ------------------------------------------------------------------------- ##
## Programmer.......... TripleX                                              ##
## eMail............... mrbrain@cs.tu-berlin.de                              ##
## Homepage............ http://triplex.home.pages.de/                        ##
## ------------------------------------------------------------------------- ##
## current Version..... 3.37                                                 ##
## ReleaseDate......... 10th December 1998                                   ##
## SoftwareStatus...... FreeWare                                             ##
## ------------------------------------------------------------------------- ##
## Requirements........ - Perl as Version 5 or above                         ##
##                      - CGI-Usage                                          ##
##                      - Quake II Server                                    ##
## ------------------------------------------------------------------------- ##
## History..... v2.02 : - first public Release                               ##
##              v2.03 : - some Colors changed a bit                          ##
##              v2.04 : - corrected Output in ErrorMessages                  ##
##                      - corrected Division by Zero                         ##
##              v2.05 : - added LastSeen-Value                               ##
##              v2.06 : - added Enemy/Victim-Stats                           ##
##              v2.08 : - made some small Improvements to the Code           ##
##                      - now supports some more Mods which simply added     ##
##                        Dots at the LineEnds (like Lithium)                ##
##                        (sugguested by Simon Lindsay)                      ##
##              v2.10 : - added MatrixView to Statistics                     ##
##              v2.12 : - eliminated new Bugs...                             ##
##              v2.20 : - added Support for GibStat-LogFile-Standard         ##
##                        (used by Lithium, PureDM and others)               ##
##                        MANY THANX TO SIMON LINDSAY who did the most of    ##
##                        this Job!                                          ##
##                      - added optional DataBase-FilenamePrefix for more    ##
##                        than one existing DataBase                         ##
##              v3.00 : - complete Redesing of the CGI for more Flexibility  ##
##                      - complete different DirectoryStructure              ##
##                      - allows User-customized HTML-Output                 ##
##                      - now supports single ConfigFiles for different      ##
##                        Configurations                                     ##
##                      - Syntax changed a bit to reflect new Handling       ##
##                      - corrected SyntaxError in GibStatsParser            ##
##                      - canceled MatrixView for now                        ##
##                      - added FragsLimit for valid Skill                   ##
##                      - added much more Documentation                      ##
##              v3.01 : - added LMCTF Parsing to ConsoleParser (no GibStats) ##
##                      - included needed HTML-Keywords for CTF Output       ##
##                      - added Sorting on CTF-Values                        ##
##                      - build ExampleHTMLs for nearly all Features         ##
##                      - included old Design of v2 as HTML and CFG          ##
##              v3.02 : - changed #PLAYER_GFX# to #PLAYER_SKILL_GFX#         ##
##                      - added Efficiency in % (#PLAYER_EFF# and            ##
##                        #PLAYER_EFF_GFX#)                                  ##
##                      - added eff_fraglimit to CFG                         ##
##                      - added Sort for Efficiency                          ##
##                      - corrected SyntaxBug... SuperShotgun_GFX now works  ##
##              v3.03 : - corrected some SyntaxErrors and Bugs               ##
##              v3.04 : - now supports LMCTF in GibStats too                 ##
##                      - added MODS.TXT                                     ##
##                      - completed some missing Phrases with GibStats       ##
##              v3.05 : - corrected Division by Zero on empty DataFiles      ##
##              v3.06 : - corrected some more small Bugs in Display          ##
##              v3.07 : - added idCTF ConsoleLogging (GibStats untested)     ##
##                        (many Thanx to ANDREAS BANZE for this!)            ##
##              v3.08 : - added Grappling Hook Kills to GibStats             ##
##                        (Console still missing) (Syntax from Lithium)      ##
##                      - added needed Keywords for Hook as Weapon           ##
##                      - included HookStats in some of the HTMLs            ##
##                        (Lithium, LmCTF, XxX)                              ##
##                      - removed own Nick from Victims & Enemies            ##
##              v3.09 : - Arena2 uses HyperBlaster instead of Hyperblaster   ##
##                        for GibStats - it's now included in the Parser     ##
##                      - Arena2 has another Bug - it says BFG10k on some    ##
##                        Kills - even when BFG10k is totaly disabled!       ##
##                        I emailed this many Weeks ago and got no Response! ##
##              v3.10 : - integrated PureDM into ConsoleParser               ##
##                      - included Fields for unknown Kills & Deaths         ##
##                        (for older Logs or unknown GibStatsValues)         ##
##                      - updated XxX-HTML-Templates to include new Fileds   ##
##                      - included older "was killed by" Message in          ##
##                        ConsoleParser                                      ##
##                      - cut off large ExampleDatabases                     ##
##              v3.11 : - included FilterFunction to search for Players      ##
##                      - included Funktionality in most HTML-Templates      ##
##                        (XxX-Templates still for Reference)                ##
##              v3.12 : - Filter doesn't apply to Details anymore to show    ##
##                        real Victims/Enemies                               ##
##                      - included some ActivityOutput as LifeSigns in       ##
##                        Parsers                                            ##
##              v3.13 : - included time_maxidle to ConfigFiles to clean      ##
##                        up the Database of too old Players                 ##
##                        (specified in Days - 0 disables cleaning)          ##
##              v3.14 : - fixed a DisplayBug in Victims/Enemies              ##
##                      - added some Comments to XxX.cfg                     ##
##                      - added some more Documentation here                 ##
##              v3.15 : - shit happens... Player named "a" which would get   ##
##                        deleted do to long IdleTime took most others with  ##
##                        them - SubString-Match - i fixed this!             ##
##              v3.20 : - now also counts Kills/Deaths/Suicids per Map       ##
##                      - additionaly computes the HighScores of above       ##
##                        Values per Map                                     ##
##                      - included needed Functionality in both Parsers      ##
##                        (Console uses FileName - GibStats MapName!!!)      ##
##                      - included needed KeyWords                           ##
##                      - cleaning Output from remaining #...#'s             ##
##                      - added needed Output to XxX-HTML                    ##
##                        (can't be complete with ALL Options any longer!)   ##
##                      - implemented all needed extra SortAlgorithms and    ##
##                        matching Arguments                                 ##
##              v3.21 : - fixed Bug where last Level of LogFile was not      ##
##                        evaluated for HiScores                             ##
##              v3.30 : - implemented Possibility of more than one           ##
##                        PlayerLoop                                         ##
##                      - updated the Examples as needed and implemented     ##
##                        some cool Features to use this in XxX-Example!     ##
##                        (dynamic HTML ;)                                   ##
##                      - you will need to change your #PLAYERLOOP# to       ##
##                        #PLAYERLOOP_1# and edit the CFG as shown in the    ##
##                        new Examples!                                      ##
##              v3.31 : - removed last known Bugs                            ##
##                      - changes some of the Examples                       ##
##                      - removed all ExampleDatabases except XxX from ZIP   ##
##                        to lower FileSize!                                 ##
##              v3.32 : - fixed Bug in MapFeature with GibStats              ##
##                      - changed some of the Examples                       ##
##              v3.33 : - fixed DisplayBug with PlayerNames inclduing "<"    ##
##              v3.34 : - as suggested by VeSpA the searched Players are now ##
##                        displayed with their current Place in the complete ##
##                        Rankings rather then with listing Index!           ##
##              v3.35 : - the SearchString now supports AND to search for    ##
##                        more than 1 Player at a Time! Nice Feature to      ##
##                        compare different Players in the OverView          ##
##              v3.36 : - no End in Sight ;) I just added the long missing   ##
##                        #LASTUPDATE# KeyWord to inform all the Players     ##
##                        of the last Time the DataBase updated              ##
##                      - changed the HTML to use that new Feature           ##
##              v3.37 : - another Bug fixed... Credits - as usual ;) - to    ##
##                        VeSpA for that... Names with "=" in made Problems  ##
##                        when expanding the Victims/Enemies List...         ##
##                        it's fixed now!                                    ##
##                      - smoothed out some PerlCode to be more reliable     ##
## ------------------------------------------------------------------------- ##
## Purpose............. This Package of Scripts can be used to provide       ##
##                      some nice Rankings for a Quake II Server. It         ##
##                      splits in an CommandLine-Util to build up some       ##
##                      DataBase and a CGI-Script that uses this DataBase    ##
##                      to show the Rankings on a WebPage.                   ##
## ------------------------------------------------------------------------- ##
## Features............ - reads the ConsoleLogFile of Quake II v3.12+        ##
##                      - supports GibStatsLogFileStandard now!!!            ##
##                      - filters all DeathMatchInformations of Interest     ##
##                      - ConsoleParser also filters LMCTF Output            ##
##                      - complete UserDefined Output possible               ##
##                      - allows Overview on all Players                     ##
##                      - Table sortable by Name, Kills, Deaths, Frags,      ##
##                        Skill, Date and some others                        ##
##                      - shows configurable Number of TopPlayers            ##
##                      - counts WeaponUsage and SuicidReasons               ##
##                      - gives all this Data even for every single Player   ##
##                      - extra Enemy/Victim-Stats for every Player          ##
##                      - collects Kills/Deaths per Map per Player           ##
##                      - ConfigFiles to support more than one Server        ##
##                      - default Values mostly can be changed through       ##
##                        additional Arguments at URL                        ##
## ------------------------------------------------------------------------- ##
## planed Features..... - Support for more Mods                              ##
##                      - Improvments in Configurability                     ##
##                      - complete Support for Mods in GibStats & Console    ##
##                        (where possible)                                   ##
##                      - some fair SkillValue for CTF based Mods            ##
## ------------------------------------------------------------------------- ##
## known Bugs.......... none                                                 ##
## ------------------------------------------------------------------------- ##
## Usage............... You'll first need some Quake II Server running       ##
##                      DeathMatch or any supported Mod. The Server has to   ##
##                      be at least Version 3.12. Former Versions have       ##
##                      different ConsoleMessages and are really outdated!   ##
##                                                                           ##
##                      This Server has to write some LogFile. This can be   ##
##                      some simple ConsoleLogfile or a GibStatsFile (if     ##
##                      the Mod supports that). To get a ConsoleLogfile      ##
##                      just use SET LOGFILE 2 at the Console of the Server. ##
##                      For the needed Options to get some GibStatsFile      ##
##                      you'll have to check the Description of the used     ##
##                      Mod.                                                 ##
##                                                                           ##
##                      Please be reminded that only unaltered Deathmatch-   ##
##                      Messages can be parsed out of the ConsoleLogfile.    ##
##                      GibStats is a Standard and should make no Problems.  ##
##                                                                           ##
##                      I included two Parsers with this Package. One for    ##
##                      ConsoleLogfile and another for GibStatsFile.         ##
##                      It should be obvious which one you'll have to use.   ##
##                                                                           ##
##                      Befor you can use any of these you'll need to create ##
##                      the needed ConfigFile. This takes little Time.       ##
##                      Just open any of the provided CFGs and alter the     ##
##                      Settings to fit your needs. Remember to place only   ##
##                      TABs between the Name and the Value!                 ##
##                      I also recommend to keep with the Directories again. ##
##                                                                           ##
##                      HINT: XxX.cfg is the only complete ConfigFile with   ##
##                            additional Documentation - so you might want   ##
##                            to take this one as a Template for yours!      ##
##                                                                           ##
##                      Now a Parser will read the LogFile and create the    ##
##                      DataBase for you. The Input will allways be added    ##
##                      to the existing DataBase - so keep in Mind that      ##
##                      no LogFile should be added twice! Allways MOVE the   ##
##                      LogFile out of the ServerDirectory. So a new LogFile ##
##                      of the same Name will be startet and you can be sure ##
##                      to rank everything just ones!                        ##
##                      If you're able to build some Script that does this   ##
##                      Job for you - do it! Otherwise you'll have to do     ##
##                      this by Hand - let's say ones a Day.                 ##
##                                                                           ##
##                      To add the LogFile to the Database just type:        ##
##                                                                           ##
##                      perl parser/ParserQ2Console.pl <config>     OR       ##
##                      perl parser/ParserQ2GibStats.pl <config>             ##
##                                                                           ##
##                      <config> specifies a former defined ConfigFile.      ##
##                      Don't specify the ".cfg" Ending of this ConfigFile - ##
##                      (i.e. for Server.cfg just specify Server).           ##
##                      This is needed to locate the Database and Logfile    ##
##                      to use. So be sure you allready setup your CFG.      ##
##                                                                           ##
##                      IMPORTANT: Allways run the Parser with the current   ##
##                                 WorkingDirectory of the CGI! Otherwise    ##
##                                 the specified Paths won't match the       ##
##                                 targeted ones and the Database would be   ##
##                                 created in the wrong Location!            ##
##                                                                           ##
##                      On many Systems you can let the starting Perl off.   ##
##                      On UnixSystems you can also renice this Process with ##
##                      /usr/bin/nice -n 19 perl parser/Parser... which is   ##
##                      less CPU-consuming but it will take more Time to     ##
##                      finish the Parsing.                                  ##
##                                                                           ##
##                      I sugguest to place all Files in the Directories     ##
##                      provided.                                            ##
##                                                                           ##
##                      Now you've created your actual Database. The Package ##
##                      also includes a CGI to browse this Database.         ##
##                      The CGI will use the HTML-Files specified in the     ##
##                      CFG. For some first Look you can just use the        ##
##                      provided Examples. But for final Usage you should    ##
##                      edit these to fit your Needs.                        ##
##                                                                           ##
##                      HINT: XxX-HTML is the only one that includes all     ##
##                            Features and least additional Text - you       ##
##                            should use this one as Template!               ##
##                            Just remove the Cells you won't need and add   ##
##                            some Text of your Choice...                    ##
##                                                                           ##
##                      The Output of the CGI is structured in a simple Way. ##
##                      On running the CGI it will use the main HTML         ##
##                      first! In this HTML many KEYWORDS are located which  ##
##                      will be replaced with the right Values before the    ##
##                      HTML will be uploaded to your WebBrowser. I sugguest ##
##                      to take a Look at this HTML first. Also take a Look  ##
##                      into the KEYWORDS.TXT provided. There all supported  ##
##                      Keywords are listed.                                 ##
##                      For a Listing of possible ARGUMENTS to the CGIs URL  ##
##                      take a Look at ARGUMENTS.TXT for Details. This       ##
##                      allows you to overwrite some of the default Options  ##
##                      in the CFG. I use this to make the List              ##
##                      UserBrowsable through Links.                         ##
##                                                                           ##
##                      Within this MainHTML it is possible to place a       ##
##                      PlayerLoop. This will be added as many as the Number ##
##                      in the ConfigFile specifies. From there you can      ##
##                      provide a Link to the second Display of the CGI -    ##
##                      the PlayerDetails. In this HTML you are able to      ##
##                      place an EnemyLoop and a VictimLoop. Again all other ##
##                      Keywords just get replaced with their Values.        ##
##                                                                           ##
##                      If this all sounds to complicated to you then just   ##
##                      use one of the provided HTML-Definitions. But if     ##
##                      you wish to customize your Output then you'll have   ##
##                      to take some Look at these - mostly you only need    ##
##                      to add some simple Words or Headers into the HTML.   ##
##                      But you are also able to customize your complete     ##
##                      RankingsOutput.                                      ##
##                                                                           ##
##                      Now you should setup the RANK.CGI with a Link        ##
##                      on your WebSite. To get some first Look at the       ##
##                      Output use the following URL:                        ##
##                                                                           ##
##                      http://.../rank.pl?cfg=<config>                      ##
##                                                                           ##
##                      without more Arguments. Replace <config> as above!   ##
##                      I don't need to say that the CGI needs to be         ##
##                      executable to work. Some WebServers even rely on     ##
##                      fixed Directories - but i'm sure you know about      ##
##                      that. Ask your SystemAdministrator for Help if you   ##
##                      need some! Check also if the first Line of the CGI   ##
##                      uses the right Path to your local PerlInstallation!  ##
##                      Otherwise the CGI can't be executed!!!               ##
##                                                                           ##
##                      This URL gives you the complete Overview. Play a     ##
##                      bit with the Links in the ControlWindow and choose   ##
##                      the one you like the most for your WebPage. Then     ##
##                      copy the URL of this Page to your WebSite for        ##
##                      Access. Keep in Mind that the complete Overview      ##
##                      takes some Time to display the Table to the User -   ##
##                      so use the Top10 or Top50... not the complete one.   ##
##                      The User will have the Possibilty to use the Link    ##
##                      for that!                                            ##
##                                                                           ##
##                      That's all for you to do!                            ##
##                                                                           ##
##                      Remember to maintain the DataBase and never rank     ##
##                      the same LogFile twice... HAVE FUN!                  ##
## ------------------------------------------------------------------------- ##
##         (C) Copyright 1998 by TripleX - All Rights reserved!              ##
## ------------------------------------------------------------------------- ##
###############################################################################
