User Guide

Contents

• The main loop
• Modules

This page gives an overview of the code base, the various modules and their responsibilities.

It was originally written in 2015 and might not be up to date, but can help you navigate the profanity codebase nevertheless.

The main loop

Everything in Profanity happens within a simple loop. When you run:

profanity

The main() function is called in:

src/main.c

At the end of main(), a call is made to prof_run() which can be found in:

src/profanity.c

At time of writing, this function is as follows:

void
prof_run(const int disable_tls, char *log_level, char *account_name)
{
    _init(disable_tls, log_level);
    _connect_default(account_name);
    ui_update();

    log_info("Starting main event loop");

    char *line = NULL;
    while(cont) {
        log_stderr_handler();
        _check_autoaway();

        line = ui_readline();
        if (line) {
            ProfWin *window = wins_get_current();
            cont = cmd_process_input(window, line);
            free(line);
            line = NULL;
        } else {
            cont = TRUE;
        }

#ifdef HAVE_LIBOTR
        otr_poll();
#endif
        notify_remind();
        jabber_process_events(10);
        ui_update();
    }
}

The important sequence of events in the main loop are:

- Check if the user entered a line (ui_readline() at src/ui/core.c).
- If they did, attempt to process the input (cmd_process_input() at src/command.c).
- Check for and handle any incoming XMPP events (jabber_process_events() at src/xmpp/connection.c).
- Refresh the UI (ui_update() at src/ui/core.c).
- Loop

Modules

Commands

All code related to running user entered commands, for example /who.

Location: src/command

Configuration

Code related to looking up and storing information in configuration files.

Location: src/config

src/config/account.c - Data structure representing an account.
src/config/accounts.c - Access to the accounts config file.
src/config/preferences.c - Access to the profrc config file.
src/config/theme.c - Access to themes.

Events

Work in progress. The intention is to move all events that could involve a plugin hook into this directory. Currently only a small number of functions have been moved here.

Location: src/event

src/event/client_events.c - Events initiated by Profanity, e.g. connecting, or sending a message.
src/event/server_events.c - Events received from the XMPP server, e.g. an incoming message.
src/event/common.c - Common functions used in both client and server events.

Off The Record Encryption

Code to deal with OTR encryption using the libotr library. Hides the different library version API's from the core Profanity code.

Location: src/otr

OpenPGP Encryption

Code to handle PGP encryption.

Location: src/pgp

OMEMO Encryption

Code to handle OMEMO encryption.

Location: src/omemo

Common Tools

Basic utility functions and common code such as autocomplete implementation.

Location: src/tools

User Interface

All User Interface code, input handling, window rendering etc.

Location: src/ui

src/ui/buffer.c - Buffer of all output, used for redrawing the UI on resize.
src/ui/console.c - Display functions for the console window.
src/ui/core.c - Display functions for most other operations involving the main window area.
src/ui/inputwin.c - Functions to handle the input window (where the user types).
src/ui/notifier.c - Desktop notification functions.
src/ui/occupantswin.c - Functions for rendering the Occupants panel in chat rooms.
src/ui/rosterwin.c - Functions for rendering the Roster panel in the console window.
src/ui/statusbar.c - Drawing the status bar (above the input line).
src/ui/titlebar.c - Drawing the title bar (the top line).
src/ui/window.c - Data structures representing different window types and functions to manipulate them.