profanity/DESIGN

Responsibilities are generally seperated into modules.

profanity.c
===========

Contains initialisation, main loop, and shutdown functions.

Initialisation is loading preferences, initialising any libraries/files/data 
structures used.

The main loop is where the work is done.  It will keep checking for a new
character on the input, if there is one deals with it, if not, goes around the
loop again.

If the character was a newline, the input line is processed, the result of
processing input will either continue (TRUE) or stop (FALSE, if the input 
was "/quit").

Shutting down just involves clearing up resources.

title_bar.c, windows.c, status_bar.c, input_win.c
=================================================

These represent the different windows in Ncurses.

    +----------------------------------------------+
    |  TITLE_BAR                                   |
    +----------------------------------------------+
    |                                              |
    |                                              |
    |  WINDOWS                                     |
    |                                              |
    |                                              |
    +----------------------------------------------+
    |  STATUS_BAR                                  |
    +----------------------------------------------+
    |  INPUT_WIN                                   |
    +----------------------------------------------+

The interface to the UI is all through ui.h, all UI modules share this
header:


                               ui.h
                                |
                                |
          --------------------------------------------------
         |             |               |                    |
    title_bar.c     windows.c       status_bar.c        inp_win.c



So any calls to the UI are through ui.h

title_bar.c and status_bar.c are relatively trivial.

windows.c
---------

Contains a list of prof_win structs called _wins, which consist of:

    from:  A string, the name of the recipient for this chat window
    win:   An ncurses pad containing the chat contents
    y_pos: The current position in the chat window
    paged: Whether or not the pad has been paged (i.e not showing the end)

The console is _wins[0], and has a special 'from' value of "_cons".

This module contains things like a pointer to the console window, the index
of the current window being displayed, a dirty flag that indicates the current
windows should be updated next time around the loop.

inp_win.c
---------

Doesn't do much more than handle each character with inp_get_char().  Deals
with all special chars for editing the input, HOME, PAGE UP, UP, DOWN etc.

command.c
=========

When the main input loop gets a '\n', process_input() is called with the 
line of input.

This is where each command/message is handled.

jabber.c
========

All interaction with libstrophe is done here.  Contains a references to the
libstrophe objects: connection, context etc.

Functions ending 'handler' are callback handlers registered with libstrophe,
e.g. for incomming messages.

contact.c
=========

PContact represents a contact with:

    name:   The contacts JID, e.g. somecontact@server.org
    show:   "Online", "Away" etc
    status: "I'm not here right now", "At lunch" etc

It's an opaque pointer so all access to a PContact is encapsulated in this
module.

contact_list.c
==============

Currently has two purposes.

First, stores a live list of online contacts.  "Live" meaning jabber.c will 
call contact_list_add() and contact_list_remove() as it gets presence
notifications from the server.

Secondly it is used for autocompleting contact names when typing them, hence
it stores the contact in a PAutocomplete, described later.

history.c
=========

Stores a history of all input and allows navigating through it, bash style.

Uses PHistory object, described later.

preferences.c
=============

Deals with loading and setting preferences saved in ~/.profanity.

Also allows autocomplete of previous JIDs the user has logged in with 
(stored in ~/.profanity) by storing them in a PAutocomplete.

common.c
========

Functions written for compatibility with older versions of GLib.

util.c
======

Some util functions, should probably move to common.c.

log.c
=====

Stores a reference to the log file, and provides functions for writing to it.

Library like modules
====================

prof_history.c and prof_autocomplete.c implement a generic way to deal with 
command history and command autocompletion respectively.

The rest of Profanity uses them indirectly, via history.c for example, 
and they know nothing about Profanity (no includes to profanity modules).

These modules use opaque pointers so all access must be through functions
exposed in their headers.

The idea is that these modules could be included in other applications.

The "prof_" prefix is just because they were created whilst developing
Profanity.

prof_autocomplete.c
-------------------

Two types of PAutocomplete can be created.

p_autocomplete_new() creates a PAutocomplete that can store strings, the
simple case.

p_obj_autocomplete_new() creates a PAutocomplete of arbitrary data 
structures. This function must be passed function pointers of the following
types:

    PStrFunc:       A function that will get a string out of the data structure
    PCopyFunc:      A function that will make a copy the data structure, allocating
        memory for it.
    PEqualDeepFunc: A function to compare two structures by comparing all members.
    GDestroyNotify: A function that will free memory for the data structure.