In this article I'll show how to make a CLI application to manage an Elo ranking ladder using the CapyElo object. If you don't know about the Elo ranking system, have a look at here first.

(The complete code is available at the end of the article)

First, lets define some structures to hold all the needed data.

// Structure to memorise an entity's info typedef struct { // Elo rank of the entity double elo; // Elo update double diff; } Entity; // Dictionary of entities (the key is the name of the entity) CapyDecDict(Ladder, Entity) CapyDefDict(Ladder, Entity) // Rank for new entities, arbitrarily set to 0.0 #define INITAL_ELO 0.0 // Structure to memorise the appli variables struct App { // Return code at the end of execution int ret; // Parser to process the command line arguments CapyArgParser parser; // Ladder and result files char* pathLadder; CapyStreamIo streamLadder; char* pathResult; CapyStreamIo streamResult; // Ladder, results (as in the result file) and single results Ladder* ladder; CapyListArrChar* results; }; // Shortcuts #define ENTITY(name) ($(app->ladder, getPtr)(name))

Calculating the new Elo rank given a result and two entity is as simple as creating the CapyElo instance:

CapyElo capyElo = CapyEloCreate();

and getting the value to add/substract to their current Elo rank:

double diff = $(&capyElo, get)(elo[0], result, elo[1]);

So, almost all of the application consists only in loading the ladder and results, and saving them back.

// Main function int main( int argc, char** argv) { ... // Instance of the application struct App app; // Initialise the return value of the application app.ret = EXIT_SUCCESS; ... try { ... // Load the results LoadResults(&app); // Load the current ladder LoadLadder(&app); // Process the results ProcessResults(&app); // Update the ladder (or only print infos if in dry mode) ApplyResults(&app); } catchDefault { ... } endCatch; return app.ret; }

It only needs two arguments: the file containing the ladder and the one containing the results to add. I'll add an optional argument for a "dry" mode (which shows the modification that would be done without actually doing them). The argument definition then looks as follow:

CapyArg args[] = { {.lbl=argv[0], .nbVal=2, .help="Elo rank ladder management application.\n" "Take two arguments: the path to the ladder file, and " "the path to the result file. If the ladder file doesn't " "exist, it is created.\n" "The ladder file format is as follow. One ranked entity " "per line. Each line contains the name of the entity and " "the Elo rank (a double value) of the entity separated by " "a comma. For example: \"Alice,100.0\"\n" "The result file format is as follow. One result per " "line. Each line contains a two entities name " "separated by '>' or '=' according to the result. For " "examples:\n" "\"Alice>Bob\" means \"Alice has won against Bob\"\n" "\"Alice=Bob\" means \"Alice had a tie against Bob\"\n" "Spaces around names in both files do matter.\n" "The ladder is kept sorted after modification"}, {.shortLbl="-d", .lbl="--dry", .nbVal=capyArg_noVal, .help="Do not modify the ladder file. Instead, print the " "modifications that would be done if not in dry mode."}, };

and the actual parsing is done with:

app.parser = CapyArgParserAlloc(argc, argv, args); app.pathLadder = $(&(app.parser), getAsStr)(argv[0], 0); app.pathResult = $(&(app.parser), getAsStr)(argv[0], 1);

To process any problem cleanly, we'll use some purpose made exceptions:

// App exceptions enum AppExceptions { excInvalidLadderFile = CapyExc_LastID, excInvalidResultFile, lastAppException }; // Label for the AppExceptions char* exceptionStr[] = { "Invalid ladder file, check the format (cf help)", "Invalid result file, check the format (cf help) and the path", }; char const* ExcToStr(int16_t exc) { // If the exception ID is one of AppExceptions, // return the exception's explanation if (exc >= excInvalidLadderFile && exc < lastAppException) return exceptionStr[exc - excInvalidLadderFile]; // Else, the exception ID is not one of AppExceptions, return NULL else return NULL; }

The ExcToStr conversion function is set with:

CapyAddExcToStrFun(ExcToStr);

The ladder consists of a CapyDict where keys are the entities' name, and values are a pair of value: the current rank and the rank update. It is loaded as follow:

// Load the current ladder void LoadLadder(struct App* const app) { // Try to open the ladder file try { $(&(app->streamLadder), open)(app->pathLadder, "r"); } endCatch; // If the ladder could be opened if ($(&(app->streamLadder), isOpened)()) { // Load the ladder data CapyListArrChar* data = $(&(app->streamLadder), readLines)(); // Loop on the data forEach (line, data->iter) { // If the line is not empty if (line.data[0] != '\n' && line.data[0] != '\0') { // Get the position of the comma, if it isn't found raise an // exception char* ptrComma = strchr(line.data, ','); if (ptrComma == NULL || ptrComma == line.data || ptrComma[1] == '\n' || ptrComma[1] == '\0') { $(&capyDecoratorRed, fprintf)( stdout, "Invalid format on line #%zu: %s", data->iter.idx, line.data); raiseExc(excInvalidLadderFile); } // Replace the comma with a null character to split the line *ptrComma = '\0'; // Convert the Elo rank from string to double, if the conversion // fails raise an exception char* endPtr = NULL; double elo = strtod(ptrComma + 1, &endPtr); if (endPtr == ptrComma + 1) { *ptrComma = ','; $(&capyDecoratorRed, fprintf)( stdout, "Invalid format on line #%zu:\n%s\n", data->iter.idx, line.data); raiseExc(excInvalidLadderFile); } // Add the entity to the ladder $(app->ladder, set)(line.data, (Entity){.elo=elo, .diff=0.0}); } } } }

The results consists of pair of entities' name separated by a character indicating a win or a tie. They are loaded as follow:

// Load the results void LoadResults(struct App* const app) { // Try to open the result file try { $(&(app->streamResult), open)(app->pathResult, "r"); } endCatch; // If the result file could not be opened, raise an exception if (!$(&(app->streamResult), isOpened)()) raiseExc(excInvalidResultFile); // Load the results app->results = $(&(app->streamResult), readLines)(); }

The results are processed line by line. The win/tie character is located and the two names identified, then the current Elo rank of each entity is gotten from the ladder, finally the Elo update is calculated and memorised. If an entity name doesn't exist in the ladder it will be automatically added thanks to the CapyDict internal behaviour.

// Process the results void ProcessResults(struct App* const app) { // Elo rank calculator CapyElo capyElo = CapyEloCreate(); // Loop on the results forEach (line, app->results->iter) { // If the line is not empty if (line.data[0] != '\n' && line.data[0] != '\0') { // Get the position of the result mark, if it can't be found raise // an exception char* ptrWin = strchr(line.data, '>'); char* ptrTie = strchr(line.data, '='); if ((ptrWin == NULL && ptrTie == NULL) || (ptrWin != NULL && ptrTie != NULL)) { $(&capyDecoratorRed, fprintf)( stdout, "Invalid format on line #%zu:\n%s\n", app->results->iter.idx, line.data); raiseExc(excInvalidResultFile); } // Memorise the result CapyEloResult result = (ptrWin != NULL ? capyElo_win : capyElo_tie); // Get the pointers to the names of the two entities, if they are // empty raise an exception char* ptrResult = (ptrWin != NULL ? ptrWin : ptrTie); char* names[2] = {line.data, ptrResult + 1}; if (names[0] == ptrResult || names[1][0] == '\0' || names[1][0] == '\n') { $(&capyDecoratorRed, fprintf)( stdout, "Invalid format on line #%zu:\n%s\n", app->results->iter.idx, line.data); raiseExc(excInvalidResultFile); } // Replace the winning character with a null character to split the // line *ptrResult = '\0'; // If we are in dry mode and the entities are new, let the user // now that a new entity will be added to the ladder if ($(&(app->parser), isSet)("--dry")) loop (i, 2) if ($(app->ladder, hasKey)(names[i]) == false) println("[%s] will be added to the ladder.", names[i]); // Get the current Elo rank of each entity in the ladder double elo[2]; loop (i, 2) elo[i] = ENTITY(names[i])->elo; // Get the Elo difference for that single result double diff = $(&capyElo, get)(elo[0], result, elo[1]); // Sum the difference over the single results loop (i, 2) ENTITY(names[i])->diff += diff * (double)(1 - 2 * i); } } }

And finally the updated ladder is saved (or displayed in dry mode) as follow:

// Update the Elo rank in the ladder void ApplyResults(struct App* const app) { // Create the StreamIo to write data app->streamResult = CapyStreamIoCreate(); // Loop on the entries in the ladder which have a change in Elo rank forEach (entry, app->ladder->iter) if (!equal(entryPtr->val.diff, 0.0)) { // If we are in dry mode if ($(&(app->parser), isSet)("--dry")) // Print what would be the modification println( "[%s]'s rank changes by %lf from %lf to %lf.", entryPtr->key, entryPtr->val.diff, entryPtr->val.elo, (entryPtr->val.diff + entryPtr->val.elo)); // Else, we are not in dry mode, apply the modification else entryPtr->val.elo += entryPtr->val.diff; } // If we are not in dry mode, save the updated ladder if (!$(&(app->parser), isSet)("--dry")) { // Keep the ladder sorted qsort( app->ladder->data, $(app->ladder, getSize)(), sizeof(LadderEntry), CmpEntries); // Open the ladder file $(&(app->streamLadder), open)(app->pathLadder, "w"); // Loop on the entries in the ladder and write the name and Elo // of the entity in the ladder format (cf help) forEach (entry, app->ladder->iter) safeFPrintf( app->streamLadder.stream, "%s,%lf\n", entryPtr->key, entryPtr->val.elo); } }

The function used to keep the ladder sorted is as follow:

// Comparison function to sort the ladder based on the Elo rank int CmpEntries( void const* entryA, void const* entryB) { double eloA = ((LadderEntry*)entryA)->val.elo; double eloB = ((LadderEntry*)entryB)->val.elo; if (equal(eloA, eloB)) return 0; else if (eloA > eloB) return -1; else return 1; }

I skip intentionally releasing memory. This is done automatically at the end of the program, which is so small and simple that there is nothing to fear here. Everything put together, it becomes:

/* Capelo - An Elo rank ladder managing appli. Copyright (C) 2021 Pascal Baillehache baillehache.pascal@gmail.com https://baillehachepascal.dev This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>. */ #include <LibCapy/capy.h> // App exceptions enum AppExceptions { excInvalidLadderFile = CapyExc_LastID, excInvalidResultFile, lastAppException }; // Label for the AppExceptions char* exceptionStr[] = { "Invalid ladder file, check the format (cf help)", "Invalid result file, check the format (cf help) and the path", }; char const* ExcToStr(int16_t exc) { // If the exception ID is one of AppExceptions, // return the exception's explanation if (exc >= excInvalidLadderFile && exc < lastAppException) return exceptionStr[exc - excInvalidLadderFile]; // Else, the exception ID is not one of AppExceptions, return NULL else return NULL; } // Structure to memorise an entity's info typedef struct { // Elo rank of the entity double elo; // Elo update double diff; } Entity; // Dictionary of entities (the key is the name of the entity) CapyDecDict(Ladder, Entity) CapyDefDict(Ladder, Entity) // Rank for new entities, arbitrarily set to 0.0 #define INITAL_ELO 0.0 // Structure to memorise the appli variables struct App { // Return code at the end of execution int ret; // Parser to process the command line arguments CapyArgParser parser; // Ladder and result files char* pathLadder; CapyStreamIo streamLadder; char* pathResult; CapyStreamIo streamResult; // Ladder, results (as in the result file) and single results Ladder* ladder; CapyListArrChar* results; }; // Shortcuts #define ENTITY(name) ($(app->ladder, getPtr)(name)) // Load the results void LoadResults(struct App* const app) { // Try to open the result file try { $(&(app->streamResult), open)(app->pathResult, "r"); } endCatch; // If the result file could not be opened, raise an exception if (!$(&(app->streamResult), isOpened)()) raiseExc(excInvalidResultFile); // Load the results app->results = $(&(app->streamResult), readLines)(); } // Load the current ladder void LoadLadder(struct App* const app) { // Try to open the ladder file try { $(&(app->streamLadder), open)(app->pathLadder, "r"); } endCatch; // If the ladder could be opened if ($(&(app->streamLadder), isOpened)()) { // Load the ladder data CapyListArrChar* data = $(&(app->streamLadder), readLines)(); // Loop on the data forEach (line, data->iter) { // If the line is not empty if (line.data[0] != '\n' && line.data[0] != '\0') { // Get the position of the comma, if it isn't found raise an // exception char* ptrComma = strchr(line.data, ','); if (ptrComma == NULL || ptrComma == line.data || ptrComma[1] == '\n' || ptrComma[1] == '\0') { $(&capyDecoratorRed, fprintf)( stdout, "Invalid format on line #%zu: %s", data->iter.idx, line.data); raiseExc(excInvalidLadderFile); } // Replace the comma with a null character to split the line *ptrComma = '\0'; // Convert the Elo rank from string to double, if the conversion // fails raise an exception char* endPtr = NULL; double elo = strtod(ptrComma + 1, &endPtr); if (endPtr == ptrComma + 1) { *ptrComma = ','; $(&capyDecoratorRed, fprintf)( stdout, "Invalid format on line #%zu:\n%s\n", data->iter.idx, line.data); raiseExc(excInvalidLadderFile); } // Add the entity to the ladder $(app->ladder, set)(line.data, (Entity){.elo=elo, .diff=0.0}); } } } } // Process the results void ProcessResults(struct App* const app) { // Elo rank calculator CapyElo capyElo = CapyEloCreate(); // Loop on the results forEach (line, app->results->iter) { // If the line is not empty if (line.data[0] != '\n' && line.data[0] != '\0') { // Get the position of the result mark, if it can't be found raise // an exception char* ptrWin = strchr(line.data, '>'); char* ptrTie = strchr(line.data, '='); if ((ptrWin == NULL && ptrTie == NULL) || (ptrWin != NULL && ptrTie != NULL)) { $(&capyDecoratorRed, fprintf)( stdout, "Invalid format on line #%zu:\n%s\n", app->results->iter.idx, line.data); raiseExc(excInvalidResultFile); } // Memorise the result CapyEloResult result = (ptrWin != NULL ? capyElo_win : capyElo_tie); // Get the pointers to the names of the two entities, if they are // empty raise an exception char* ptrResult = (ptrWin != NULL ? ptrWin : ptrTie); char* names[2] = {line.data, ptrResult + 1}; if (names[0] == ptrResult || names[1][0] == '\0' || names[1][0] == '\n') { $(&capyDecoratorRed, fprintf)( stdout, "Invalid format on line #%zu:\n%s\n", app->results->iter.idx, line.data); raiseExc(excInvalidResultFile); } // Replace the winning character with a null character to split the // line *ptrResult = '\0'; // If we are in dry mode and the entities are new, let the user // now that a new entity will be added to the ladder if ($(&(app->parser), isSet)("--dry")) loop (i, 2) if ($(app->ladder, hasKey)(names[i]) == false) println("[%s] will be added to the ladder.", names[i]); // Get the current Elo rank of each entity in the ladder double elo[2]; loop (i, 2) elo[i] = ENTITY(names[i])->elo; // Get the Elo difference for that single result double diff = $(&capyElo, get)(elo[0], result, elo[1]); // Sum the difference over the single results loop (i, 2) ENTITY(names[i])->diff += diff * (double)(1 - 2 * i); } } } // Comparison function to sort the ladder based on the Elo rank int CmpEntries( void const* entryA, void const* entryB) { double eloA = ((LadderEntry*)entryA)->val.elo; double eloB = ((LadderEntry*)entryB)->val.elo; if (equal(eloA, eloB)) return 0; else if (eloA > eloB) return -1; else return 1; } // Update the Elo rank in the ladder void ApplyResults(struct App* const app) { // Create the StreamIo to write data app->streamResult = CapyStreamIoCreate(); // Loop on the entries in the ladder which have a change in Elo rank forEach (entry, app->ladder->iter) if (!equal(entryPtr->val.diff, 0.0)) { // If we are in dry mode if ($(&(app->parser), isSet)("--dry")) // Print what would be the modification println( "[%s]'s rank changes by %lf from %lf to %lf.", entryPtr->key, entryPtr->val.diff, entryPtr->val.elo, (entryPtr->val.diff + entryPtr->val.elo)); // Else, we are not in dry mode, apply the modification else entryPtr->val.elo += entryPtr->val.diff; } // If we are not in dry mode, save the updated ladder if (!$(&(app->parser), isSet)("--dry")) { // Keep the ladder sorted qsort( app->ladder->data, $(app->ladder, getSize)(), sizeof(LadderEntry), CmpEntries); // Open the ladder file $(&(app->streamLadder), open)(app->pathLadder, "w"); // Loop on the entries in the ladder and write the name and Elo // of the entity in the ladder format (cf help) forEach (entry, app->ladder->iter) safeFPrintf( app->streamLadder.stream, "%s,%lf\n", entryPtr->key, entryPtr->val.elo); } } // Main function int main( int argc, char** argv) { // Set the conversion function for raised exceptions CapyAddExcToStrFun(ExcToStr); // Instance of the application struct App app; // Initialise the return value of the application app.ret = EXIT_SUCCESS; // Create the StreamIo to read and write data app.streamResult = CapyStreamIoCreate(); app.streamLadder = CapyStreamIoCreate(); // Create the dictionary to memorise the ladder app.ladder = LadderAlloc((Entity){ .elo=INITAL_ELO, .diff=0.0 }); try { // Definition of the arguments from the command line CapyArg args[] = { {.lbl=argv[0], .nbVal=2, .help="Elo rank ladder management application.\n" "Take two arguments: the path to the ladder file, and " "the path to the result file. If the ladder file doesn't " "exist, it is created.\n" "The ladder file format is as follow. One ranked entity " "per line. Each line contains the name of the entity and " "the Elo rank (a double value) of the entity separated by " "a comma. For example: \"Alice,100.0\"\n" "The result file format is as follow. One result per " "line. Each line contains a two entities name " "separated by '>' or '=' according to the result. For " "examples:\n" "\"Alice>Bob\" means \"Alice has won against Bob\"\n" "\"Alice=Bob\" means \"Alice had a tie against Bob\"\n" "Spaces around names in both files do matter.\n" "The ladder is kept sorted after modification"}, {.shortLbl="-d", .lbl="--dry", .nbVal=capyArg_noVal, .help="Do not modify the ladder file. Instead, print the " "modifications that would be done if not in dry mode."}, }; // Create the argument parser and parse the arguments app.parser = CapyArgParserCreate(argc, argv, args); app.pathLadder = $(&(app.parser), getAsStr)(argv[0], 0); app.pathResult = $(&(app.parser), getAsStr)(argv[0], 1); // Load the results LoadResults(&app); // Load the current ladder LoadLadder(&app); // Process the results ProcessResults(&app); // Update the ladder (or only print infos if in dry mode) ApplyResults(&app); } catchDefault { // Inform the user about the raised exception $(&capyDecoratorRed, fprintf)( stdout, "Sorry, an exception occured. Exiting.\n"); $(&capyDecoratorRed, fprintf)( stdout, "%s\n", CapyExcToStr(CapyGetLastExcId())); app.ret = EXIT_FAILURE; } endCatch; return app.ret; }

Compile with the following Makefile:

CAPY_PARAM=-std=c18 -I./ -Wall -Wextra -Wshadow -Wno-format-truncation -Werror -Wfatal-errors -O0 -ggdb -fopenmp -DPNG_SKIP_SETJMP_CHECK `pkg-config --cflags gtk+-3.0` -D_XOPEN_SOURCE=700 -DCAPY_WITH_GUI=1 CAPY_LINK=-lcapy -lm -fopenmp -lpng `pkg-config --libs gtk+-3.0` capelo: main.o Makefile gcc -o capelo main.o $(CAPY_LINK) main.o: main.c Makefile gcc $(CAPY_PARAM) -c main.c

Example of use:

> cat result.csv Alice> > > capelo ladder.csv result.csv Invalid format on line #0: Alice> Sorry, an exception occured. Exiting. Invalid result file, check the format (cf help) and the path > > cat result.csv Alice<Bob > > capelo ladder.csv result.csv Invalid format on line #0: Alice<Bob Sorry, an exception occured. Exiting. Invalid result file, check the format (cf help) and the path > > ls ladder.csv ls: cannot access 'ladder.csv': No such file or directory > cat result.csv Alice>Bob > > capelo ladder.csv result.csv --dry [Alice] will be added to the ladder. [Bob] will be added to the ladder. [Alice]'s rank changes by 8.000000 from 0.000000 to 8.000000. [Bob]'s rank changes by -8.000000 from 0.000000 to -8.000000. > ls ladder.csv ls: cannot access 'ladder.csv': No such file or directory > > capelo ladder.csv result.csv > ls ladder.csv ladder.csv > cat ladder.csv Alice,8.000000 Bob,-8.000000 > > cat result.csv Bob>Alice Bob>Carla Carla=Alice > > capelo ladder.csv result.csv --dry [Carla] will be added to the ladder. [Alice]'s rank changes by -8.552328 from 8.000000 to -0.552328. [Bob]'s rank changes by 16.552328 from -8.000000 to 8.552328. [Carla]'s rank changes by -8.000000 from 0.000000 to -8.000000. > cat ladder.csv Alice,8.000000 Bob,-8.000000 > > capelo ladder.csv result.csv > cat ladder.csv Bob,8.552328 Alice,-0.552328 Carla,-8.000000