README for StandingsBuilder v1.42
===========

This is program for building standings for ACM contests from different sources like other standings or logs of contests. The result of work is HTML file with merged standings

To generate configuration script execute

	autoreconf -i

The program requires libxml2 and lua 5.2 in order to work properly. Also it is recommended to have libcurl installed, so program will be able to download files from internet. If you don't want this, you can run configuration script as follows:

	./configure --without-libcurl

In case you use Ubuntu to install libxml2 you should install package with name libxml2-dev. And for lua 5.2 you need liblua5.2-dev
To install libcurl, you may install either of 3 packages: libcurl4-openssl-dev, libcurl4-gnutls-dev or libcurl4-nss-dev.

Program requires XML config of the following form (case sensitive):

    <Builder>
      <ProblemCount>11</ProblemCount>
      <RefreshRate>300</RefrestRate>
      <OutputFile>output.html</OutputFile>
      <OutputScript>script.lua</OutputScript>
      <Parsers>
        ...List of parsers to use...
      </Parsers>
    </Builder>

ProblemCount is number of problems in current contest or id of last problem written in capital letters
RefreshRate is delay in seconds, after which output file will be rewritten
OutputFile is path to file, where the result of program will be written
OutputScript is path to script file in Lua which will fill the output file. For more information on it see the section below

Parsers should contain list of parsers (programs, that fetch information and
place it into log). Currently supported parsers:

 > EjudgeParser
     _Provides time_
     Necessary attribute: [Path] or [URL]
     Optional attribute: [Timeless]=No/Yes
     Downloads Ejudge standings either on local computer from[Path] or by link [URL], parses it and puts teams in it into resulting standing. If [Timeless] is true, the parser will not attempt to get and store time of submissions
     Optional attribute: [IgnoreColumns]
     List of space separated numbers of columns, that should be ignored to properly parse table.

 > NEERCXmlParser
     Necessary attribute: [Path] or [URL]
     Parses NEERC contests history pack and unrolles by simulating attempts from it.

 > NEERCHtmlParser
     Necessary attribute: [Path] or [URL]
     Optional attribute: [HideUnsolved]=No/Yes
     Reads final standings of NEERC contest in HTML format and attempts to simulate it. It is unknown, when were wrong attempts made, so for problems that were accepted all wrong attempts were made simultaneously with accepted one. If problem wasn't solved, all attempts will be shown at start or won't be shown at all depending on [HideUnsolved]

 > NYParser
     Necessary attribute: [Path] or [URL]
     Optional attribute: [HideUnsolved]=No/Yes
     Reads final standings of New York Regional Contest in HTML format and attempts to simulate it. It is unknown, when were wrong attempts made, so for problems that were accepted all wrong attempts are assumed to be made simultaneously with accepted one. If problem wasn't solved, all attempts will be shown at the start or won't be shown at all depending on [HideUnsolved]

 > Timer
     _Provides time_
     Necessary attribute: [StartTime]
     Optional attribute: [StartDate]
     Doesn't really parses anything or affects standings directly. It's only purpose is to count time from contest start. By default StartDate equals to present date. StartTime should be in format "hh:mm". Format for StartDate is "yyyy/mm/dd"

To run the program first argument of program must be XML config. If none 
provided will be shown help message

Every parser may have additional parameter [Style]. Also every parser has parameter [Prefix]. All teams, handled by this parser will be prepended by its value.

The example of configuration file:

 <Builder>
   <ProblemCount>11</ProblemCount>
   <RefreshRate>300</RefreshRate>
   <OutputFile>output.html</OutputFile>
   <OutputScript>script.lua</OutputScript>
   <Parsers>
     <Timer StartTime="00:00"/>
     <NEERCXmlParser Path="standings.xml" Style="yellow" Prefix="*"/>
   </Parsers>
 </Builder>

Output Script
===========

StandingsBuilder uses Lua scripts to build resulting standings. Once application starts, it will parse and execute Output Script file. From this moment forward every time new standings is built, function "printStandings" will be called with three arguments: file, teams and time.

  First argument is the opened Output File in which standings should be built. 
  Second argument is table of team names, ordered by their position in standings. 
  Third argument is current elapsed time since contest start.

You shouldn't close file, it will be closed automatically.

To get information about teams, StandingsBuilder provides library "contest" with following content (T=team, pID=problemID):

  countproblems()            - returns number of problems in contest
  teamplace(T)               - returns string, which indicates team's place in contest. If several teams share same score and penalty, a range instead of single number will be returned. Possible results are: "1", "2-3", "4-10"
  teamstyle(T)               - returns string specified in [Style] attribute of parser which was the last to modify team
  teamproblemssolved(T)      - returns number of problems, solved by team
  teampenalty(T)             - returns team's penalty
  teamproblemattempts(T,pID) - returns number of unsuccessfull attempts by team
  teamsolved(T,pID)          - returns whether problem pID was solved by team         
  teamproblemtime(T,pID)     - returns time, when problem was solved by team. If time is unknown or problem is unsolved, -1 is returned

If the script has "init" function, it will be called at the start. "init" function is expected to have exactly one argument: all properties of OutputScript passed in a table.

Example of Lua script, which will produce standings list:

function printStandings ( file, teams, time )

	n=#teams
	p=contest.countproblems()

	for i,team in ipairs(teams) do
		file:write( contest.teamplace(team) .. ". \""..team.."\" - " ..
		contest.teamproblemssolved(team).."/"..p.." "..contest.teampenalty(team).."\n")
	end
end