# WeeChat Developer’s Guide

Sébastien Helleu
`<flashcode@flashtux.org>`
version 0.4.2, 2017-04-27

This manual documents WeeChat chat client, it is part of WeeChat.

Latest version of this document can be found on this page: http://weechat.org/doc

## 1. Introduction

WeeChat (Wee Enhanced Environment for Chat) is a free chat client, fast and light, designed for many operating systems.

This manual documents WeeChat internals:

- repository (sources, doc, …)

- coding rules

- core internals

- plugin internals

- how to contribute to WeeChat

## 2. Repository

WeeChat has two main repositories:

- core repository: it contains source code and documentation, URL is: http://git.savannah.gnu.org/gitweb/?p=weechat.git

- scripts: the official scripts submitted on weechat.org, URL is: http://git.savannah.gnu.org/gitweb/?p=weechat/scripts.git;a=summary

This manual documents only core repository.

### 2.1. Overview

The main WeeChat directories are:

Directory | Description
--- | ---

     debian/

Debian packaging

     src/

Root of sources

        core/

Core functions: entry point, internal structures

        gui/

Functions for buffers, windows, … (used by all interfaces)

           curses/

Curses interface

        plugins/

Plugin and scripting API

           alias/

Alias plugin

           aspell/

Aspell plugin

           charset/

Charset plugin

           fifo/

Fifo plugin (FIFO pipe used to remotely send commands to WeeChat)

           irc/

IRC plugin

           logger/

Logger plugin (write messages displayed to files)

           relay/

Relay plugin (irc proxy + relay for remote interfaces)

           rmodifier/

Rmodifier plugin (alter modifier strings with regular expressions)

           script/

Scripts manager

           python/

Python scripting API

           perl/

Perl scripting API

           ruby/

Ruby scripting API

           lua/

Lua scripting API

           tcl/

Tcl scripting API

           guile/

Guile (scheme) scripting API

           xfer/

Xfer (IRC DCC file/chat)

     doc/

Documentation

     po/

Translations files (gettext)

     test/

Weercd: WeeChat flood irc server, written in Python

### 2.2. Sources

#### 2.2.1. Core

WeeChat "core" reside in following directories:

- src/core/: core functions (for data manipulation)

- src/gui/: functions about interface (buffers, windows, …)

Path/file | Description
--- | ---

     core/

Core functions: entry point, internal structures

        weechat.c

Entry point, command line options, main functions, startup

        wee-backtrace.c

Display backtrace after a segfault

        wee-command.c

WeeChat core commands

        wee-completion.c

Completion on command line

        wee-config-file.c

Configuration file management

        wee-config.c

Configuration options for WeeChat core (file weechat.conf)

        wee-debug.c

Some debug functions

        wee-eval.c

Evaluate expressions with references to internal vars

        wee-hashtable.c

Hashtables

        wee-hdata.c

Hdata (direct access to data using hashtables)

        wee-hook.c

Hooks

        wee-infolist.c

Infolists (lists built with data about objects)

        wee-input.c

Input of commands/text

        wee-list.c

Sorted lists

        wee-log.c

Write to WeeChat log file (weechat.log)

        wee-network.c

Network functions (connection to servers, proxy)

        wee-proxy.c

Proxy management

        wee-secure.c

Secured data options (file sec.conf)

        wee-string.c

Functions on strings

        wee-upgrade-file.c

Internal upgrade system

        wee-upgrade.c

Upgrade for WeeChat core (buffers, lines, history, …)

        wee-url.c

URL transfer (using libcurl)

        wee-utf8.c

UTF-8 functions

        wee-util.c

Some other functions

        wee-version.c

Functions for WeeChat version

     gui/

Functions for buffers, windows, … (used by all interfaces)

        gui-bar-item.c

Bar items

        gui-bar-window.c

Bar windows

        gui-bar.c

Bars

        gui-buffer.c

Buffers

        gui-chat.c

Chat functions (display message, …)

        gui-color.c

Color functions

        gui-completion.c

Default completions

        gui-cursor.c

Cursor mode (free movement of cursor)

        gui-filter.c

Filters

        gui-focus.c

Functions about focus (for cursor mode and mouse)

        gui-history.c

commands/text saved in buffers

        gui-hotlist.c

Hotlist management (list of buffers with activity)

        gui-input.c

Input functions (input bar)

        gui-key.c

Keyboard functions

        gui-layout.c

Layout

        gui-line.c

Lines in buffers

        gui-mouse.c

Mouse

        gui-nicklist.c

Nicklist in buffers

        gui-window.c

Windows

        curses/

Curses interface

           gui-curses-bar-window.c

Display in bar windows

           gui-curses-chat.c

Display in chat area (messages)

           gui-curses-color.c

Color functions

           gui-curses-key.c

Keyboard functions (default keys, read of input)

           gui-curses-main.c

WeeChat main loop (waiting for keyboard/network events)

           gui-curses-mouse.c

Mouse

           gui-curses-term.c

Functions about terminal

           gui-curses-window.c

Windows

#### 2.2.2. Plugins

Path/file | Description
--- | ---

     plugins/

Root of plugins

        plugin.c

Plugins management (load/unload dynamic C libraries)

        plugin-api.c

Extra functions for plugin API (wrapper around WeeChat core functions)

        plugin-config.c

Plugin configuration options (file plugins.conf)

        plugin-script.c

Common functions used by script plugins

        plugin-script-api.c

Script API functions: wrappers around some plugin API functions

        plugin-script-callback.c

Callback management for scripts

        weechat-plugin.h

Header designed to be distributed with WeeChat plugins, in order to compile them

        alias/

Alias plugin

           alias.c

Main alias functions

           alias-config.c

Alias config options (file alias.conf)

           alias-info.c

Alias info/infolists/hdata

        aspell/

Aspell plugin

           weechat-aspell.c

Main aspell functions

           weechat-aspell-bar-item.c

Aspell bar items

           weechat-aspell-command.c

Aspell commands

           weechat-aspell-completion.c

Aspell completions

           weechat-aspell-config.c

Aspell config options (file aspell.conf)

           weechat-aspell-info.c

Aspell info/infolists/hdata

           weechat-aspell-speller.c

Spellers management

        charset/

Charset plugin

           charset.c

Charset functions

        fifo/

Fifo plugin

           fifo.c

Main fifo functions

           fifo-info.c

Fifo info/infolists/hdata

        guile/

Guile (scheme) plugin

           weechat-guile.c

Main guile functions (load/unload scripts, execute guile code)

           weechat-guile-api.c

Guile scripting API functions

        irc/

IRC (Internet Relay Chat) plugin

           irc.c

Main IRC functions

           irc-bar-item.c

IRC bar items

           irc-buffer.c

IRC buffers

           irc-channel.c

IRC channels

           irc-color.c

Color functions

           irc-command.c

IRC commands

           irc-completion.c

IRC completions

           irc-config.c

IRC config options (file irc.conf)

           irc-ctcp.c

IRC CTCP

           irc-debug.c

IRC debug functions

           irc-ignore.c

IRC Ignore

           irc-info.c

IRC info/infolists/hdata

           irc-input.c

Input of commands/text

           irc-message.c

Functions to manipulate IRC messages

           irc-mode.c

Functions about channel/nick modes

           irc-msgbuffer.c

Target buffer for IRC messages

           irc-nick.c

IRC nicks

           irc-notify.c

IRC notify lists

           irc-protocol.c

IRC protocol (RFCs 1459/2810/2811/2812/2813)

           irc-raw.c

IRC raw buffer

           irc-redirect.c

Redirection of IRC command output

           irc-sasl.c

SASL authentication with IRC server

           irc-server.c

I/O communication with IRC servers

           irc-upgrade.c

Save/restore IRC data when upgrading WeeChat

        logger/

Logger plugin

           logger.c

Main logger functions

           logger-buffer.c

Logger buffer list management

           logger-config.c

Logger config options (file logger.conf)

           logger-info.c

Logger info/infolists/hdata

           logger-tail.c

Return last lines of a file

        lua/

Lua plugin

           weechat-lua.c

Main lua functions (load/unload scripts, execute lua code)

           weechat-lua-api.c

Lua scripting API functions

        perl/

Perl plugin

           weechat-perl.c

Main perl functions (load/unload scripts, execute perl code)

           weechat-perl-api.c

Perl scripting API functions

        python/

Python plugin

           weechat-python.c

Main python functions (load/unload scripts, execute python code)

           weechat-python-api.c

Python scripting API functions

        relay/

Relay plugin (IRC proxy and relay for remote interfaces)

           relay.c

Main relay functions

           relay-buffer.c

Relay buffer

           relay-client.c

Clients of relay

           relay-command.c

Relay commands

           relay-completion.c

Relay completions

           relay-config.c

Relay config options (file relay.conf)

           relay-info.c

Relay info/infolists/hdata

           relay-network.c

Network functions for relay

           relay-raw.c

Relay raw buffer

           relay-server.c

Relay server

           relay-upgrade.c

Save/restore relay data when upgrading WeeChat

           relay-websocket.c

Websocket server functions for relay (RFC 6455)

           irc/

IRC proxy

              relay-irc.c

Main IRC proxy functions

           weechat/

Relay for remote interface

              relay-weechat.c

Relay for remote interface (main functions)

              relay-weechat-msg.c

Send binary messages to clients

              relay-weechat-nicklist.c

Nicklist functions

              relay-weechat-protocol.c

Read commands from clients

        rmodifier/

Rmodifier plugin

           rmodifier.c

Main rmodifier functions

           rmodifier-command.c

Rmodifier commands

           rmodifier-completion.c

Rmodifier completions

           rmodifier-config.c

Rmodifier config options (file rmodifier.conf)

           rmodifier-debug.c

Rmodifier debug functions

           rmodifier-info.c

Rmodifier info/infolists/hdata

        ruby/

Ruby plugin

           weechat-ruby.c

Main ruby functions (load/unload scripts, execute ruby code)

           weechat-ruby-api.c

Ruby scripting API functions

        script/

Scripts manager

           script.c

Main functions for scripts manager

           script-action.c

Actions on scripts (load/unload, install/remove, hold, …)

           script-buffer.c

Buffer for scripts manager

           script-command.c

Commands for scripts manager

           script-completion.c

Completions for scripts manager

           script-config.c

Config options for scripts manager (file script.conf)

           script-info.c

Script manager info/infolists/hdata

           script-repo.c

Download and read repository file

        tcl/

Tcl plugin

           weechat-tcl.c

Main tcl functions (load/unload scripts, execute tcl code)

           weechat-tcl-api.c

Tcl scripting API functions

        xfer/

Xfer plugin (IRC DCC file/chat)

           xfer.c

Main xfer functions

           xfer-buffer.c

Xfer buffer

           xfer-chat.c

Xfer DCC chat

           xfer-command.c

Xfer commands

           xfer-completion.c

Xfer completions

           xfer-config.c

Xfer config options (file xfer.conf)

           xfer-dcc.c

Xfer DCC file

           xfer-file.c

File functions for xfer

           xfer-info.c

Xfer info/infolists/hdata

           xfer-network.c

Network functions for xfer

           xfer-upgrade.c

Save/restore xfer data when upgrading WeeChat

### 2.3. Documentation / translations

Documentation files:

Path/file | Description
--- | ---

     doc/

Documentation

        asciidoc.conf

Asciidoc configuration file (some macros)

        asciidoc.css

Asciidoc style

        docgen.py

Python script to build files in "autogen/" directory (see below)

        XX/

Documentation for language XX (languages: en, fr, de, it, …)

           weechat.1.XX.txt

Man page

           weechat_quickstart.XX.txt

Quickstart guide

           weechat_user.XX.txt

User’s guide

           weechat_faq.XX.txt

FAQ

           weechat_plugin_api.XX.txt

Plugin API reference

           weechat_scripting.XX.txt

Scripting guide

           weechat_tester.XX.txt

Tester’s guide

           weechat_dev.XX.txt

Developer’s guide (this document)

           weechat_relay_protocol.XX.txt

Relay protocol

           cmdline_options.XX.txt

Command-line options (file included in man page and user’s guide)

           autogen/

Files auto-built with script docgen.py (do NEVER update manually!)

              user/

Files auto-built for user’s guide (do NEVER update manually!)

              plugin_api/

Files auto-built for plugin API (do NEVER update manually!)

Translations for WeeChat and plugins are done with gettext, files are in po/ directory:

Path/file | Description
--- | ---

     po/

Translation files (gettext)

        XX.po

Translations for language XX (fr, de, it, …), base language is English

        weechat.pot

Template for translations (auto-built)

## 3. Coding rules

### 3.1. General rules

- In source code, your comments, variable names, .. must be written in English only (no other language is allowed)

- Use a copyright header in each new source file, with date, name, e-mail, license and below that a short description of file. Example in C:

    /*
     * Copyright (C) 2013 Your Name <your@email.com>
     *
     * This file is part of WeeChat, the extensible chat client.
     *
     * WeeChat 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.
     *
     * WeeChat 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 WeeChat.  If not, see <http://www.gnu.org/licenses/>.
     */

    /*
     * weechat.c: core functions for WeeChat
     */

### 3.2. C style

Some basic rules you must follow when you write C code:

- Use 4 spaces for indentation. Don’t use tabs, they are evil.

- Try to not exceed 80 chars by line, except if this is needed to increase readability.

- Use comments `/* comment */` (not C99-style comments like `// comment`).

- Add a comment before any function, to explain what does the function (always use a multi-line comment, even if description is very short).

Example:

    /*
     * Checks if a string with boolean value is valid.
     *
     * Returns:
     *   1: boolean value is valid
     *   0: boolean value is NOT valid
     */

    int
    foo ()
    {
        int i;

        /* one line comment */
        i = 1;

        /*
         * multi-line comment: this is a very long description about next block
         * of code
         */
        i = 2;
        printf ("%d\n", i);
    }

- Use explicit variable names, for example "nicks_count" instead of "n" or "nc". Exception: in `for` loops, where variables like "i" or "n" are OK.

- Initialize local variables after declaration, in body of function, example:

    void
    foo ()
    {
        int nick_count, buffer_count;

        nick_count = 0;
        buffer_count = 1;
        /* ... */
    }

- Use parentheses to explicitly show how expression is evaluated, even if they are not required, for example: write `x + (y * z)` instead of `x + y * z`

- Place curly brackets `{ }` alone on lines, and indent them with number of spaces used for line above opening curly bracket (the `if` in example):

    if (nicks_count == 1)
    {
        /* something */
    }

- Use empty lines to separate many different blocks inside functions, and if possible add a comment for each one, like this:

    /*
     * Sends a message from out queue.
     */

    void
    irc_server_outqueue_send (struct t_irc_server *server)
    {
        /* ... */

        /* send signal with command that will be sent to server */
        irc_server_send_signal (server, "irc_out",
                                server->outqueue[priority]->command,
                                server->outqueue[priority]->message_after_mod,
                                NULL);
        tags_to_send = irc_server_get_tags_to_send (server->outqueue[priority]->tags);
        irc_server_send_signal (server, "irc_outtags",
                                server->outqueue[priority]->command,
                                server->outqueue[priority]->message_after_mod,
                                (tags_to_send) ? tags_to_send : "");
        if (tags_to_send)
            free (tags_to_send);

        /* send command */
        irc_server_send (server, server->outqueue[priority]->message_after_mod,
                         strlen (server->outqueue[priority]->message_after_mod));
        server->last_user_message = time_now;

        /* start redirection if redirect is set */
        if (server->outqueue[priority]->redirect)
        {
            irc_redirect_init_command (server->outqueue[priority]->redirect,
                                       server->outqueue[priority]->message_after_mod);
        }

        /* ... */
    }

- Indent the `if` conditions, and use parentheses around conditions with an operator (not needed for single booleans), like this:

    if (something)
    {
        /* something */
    }
    else
    {
        /* something else */
    }

    if (my_boolean1 && my_boolean2 && (i == 10)
        && ((buffer1 != buffer2) || (window1 != window2)))
    {
        /* something */
    }
    else
    {
        /* something else */
    }

- Indent the `switch` statements like this:

    switch (string[0])
    {
        case 'A': /* first case */
            foo ("abc", "def");
            break;
        case 'B': /* second case */
            bar (1, 2, 3);
            break;
        default: /* other cases */
            baz ();
            break;
    }

- Use `typedef` for function prototypes, not structures:

    typedef int (t_hook_callback_fd)(void *data, int fd);

    struct t_hook_fd
    {
        t_hook_callback_fd *callback;      /* fd callback                       */
        int fd;                            /* socket or file descriptor         */
        int flags;                         /* fd flags (read,write,..)          */
        int error;                         /* contains errno if error occurred  */
                                           /* with fd                           */
    };

    /* ... */

    struct t_hook_fd *new_hook_fd;

    new_hook_fd = malloc (sizeof (*new_hook_fd));

- This lisp code can be used in your ~/.emacs.el to indent properly if you are using Emacs as text editor:

    (add-hook 'c-mode-common-hook '(lambda ()
                                     (c-toggle-hungry-state t)
                                     (c-set-style "k&r")
                                     (setq c-basic-offset 4
                                           c-tab-always-indent t)
                                     (c-set-offset 'case-label '+)))

### 3.3. Python style

See http://www.python.org/dev/peps/pep-0008/

## 4. Core internals

### 4.1. Naming convention

#### 4.1.1. Files

File names are composed by letters and hyphens, with format: xxx-yyyyy.[ch], where xxx is directory/component (can be abbreviation) where the file is, and yyyyy a name for the file, which shows the purpose of file.

The main file of a directory may have same name as directory, for example irc.c in irc plugin.

Examples:

Directory | Files
--- | ---

     src/core/

weechat.c, wee-backtrace.c, wee-command.c, …

     src/gui/

gui-bar.c, gui-bar-item.c, gui-bar-window.c, …

     src/gui/curses/

gui-curses-bar.c, gui-curses-bar-window.c, gui-curses-chat.c, …

     src/plugins/

plugin.c, plugin-api.c, plugin-config.c, plugin-script.c, …

     src/plugins/irc/

irc.c, irc-bar-item.c, irc-buffer.c, …

     src/plugins/python/

weechat-python.c, weechat-python-api.c, …

The headers of C files have same name as file, for example wee-command.h for file wee-command.c.

#### 4.1.2. Structures

Structures have name t_X_Y or t_X_Y_Z:

- X: directory/component (can be abbreviation)

- Y: end of file name

- Z: name for structure (optional)

Example: an IRC nick (from src/plugins/irc/irc-nick.h):

    struct t_irc_nick
    {
        char *name;                     /* nickname                              */
        char *host;                     /* full hostname                         */
        char *prefixes;                 /* string with prefixes enabled for nick */
        char prefix[2];                 /* current prefix (higher prefix set in  */
                                        /* prefixes)                             */
        int away;                       /* 1 if nick is away                     */
        char *color;                    /* color for nickname in chat window     */
        struct t_irc_nick *prev_nick;   /* link to previous nick on channel      */
        struct t_irc_nick *next_nick;   /* link to next nick on channel          */
    };

#### 4.1.3. Variables

Global variables (outside functions) have name X_Y_Z:

- X: directory/component (can be abbreviation)

- Y: end of file name

- Z: name for variable

Exception are variables for "last" node of a list, name is last_X (where X is name of variable, using singular form).

Example: windows (from src/gui/gui-window.c):

    struct t_gui_window *gui_windows = NULL;        /* first window             */
    struct t_gui_window *last_gui_window = NULL;    /* last window              */
    struct t_gui_window *gui_current_window = NULL; /* current window           */

There is no naming convention for local variables (in functions). The only recommendation is that name is explicit (not too short). Nevertheless, pointers to structures are often named ptr_xxxx, for example a pointer on a struct t_gui_buffer * will be: *ptr_buffer.

#### 4.1.4. Functions

Naming convention for functions is the same as variables.

Example: creation of a new window (from src/gui/gui-window.c):

    /*
     * Creates a new window.
     *
     * Returns pointer to new window, NULL if error.
     */

    struct t_gui_window *
    gui_window_new (struct t_gui_window *parent_window, struct t_gui_buffer *buffer,
                    int x, int y, int width, int height,
                    int width_pct, int height_pct)
    {
        /* ... */

        return new_window;
    }

### 4.2. Single thread

WeeChat is single threaded. That means every part of code should execute very fast, and that calls to functions like `sleep` are strictly forbidden (it is true for WeeChat core, but also C plugins and scripts).

If for some reasons you have to sleep a while, use `hook_timer` with a callback.

### 4.3. Doubly linked lists

Most of WeeChat linked lists are doubly linked lists: each node has pointer to previous and next node.

Example: list of buffers (from src/gui/gui-buffer.h):

    struct t_gui_buffer
    {
        /* data */

        /* ... */

        struct t_gui_buffer *prev_buffer;  /* link to previous buffer           */
        struct t_gui_buffer *next_buffer;  /* link to next buffer               */
    };

Then the two list pointers, to the head and tail of list:

    struct t_gui_buffer *gui_buffers = NULL;           /* first buffer          */
    struct t_gui_buffer *last_gui_buffer = NULL;       /* last buffer           */

### 4.4. Color codes in strings

WeeChat uses own color codes in strings to display attributes (bold, underline, …) and colors on screen.

All attributes/colors are prefixed with a char in string, which can be:

- 0x19: color code (followed by color code(s))

- 0x1A: set attribute (followed by attribute on one char)

- 0x1B: remove attribute (followed by attribute on one char)

- 0x1C: reset (nothing after)

Allowed attributes are (one or more chars):

- `*`: bold

- `!`: reverse

- `/`: italic

- `_`: underline

- `|`: keep attributes

Possible colors are:

- standard color: optional attributes + number on 2 digits

- extended color: `@` + optional attributes + number on 5 digits

In following table, these conventions are used:

- `STD`: standard color (2 digits)

- `(A)STD`: standard color with optional attributes (attributes + 2 digits)

- `EXT`: extended color (`@` + 5 digits)

- `(A)EXT`: extended color with optional attributes (`@` + attributes + 5 digits)

- `ATTR`: one attribute char (`*`, `!`, `/`, `_` or `|`)

All combinations are summarized in this table:

Code | Example | Areas | Description
--- | --- | --- | ---
19 + STD | 19 `01` | chat + bars | Set attributes and color using option, see table below
19 + EXT | 19`@00001` | chat | Set color with a ncurses pair (used only on `/color` buffer)
19 + "F" + (A)STD | 19 `F*05` | chat + bars | Set foreground (WeeChat color)
19 + "F" + (A)EXT | 19 `F@00214` | chat + bars | Set foreground (extended color)
19 + "B" + STD | 19 `B05` | chat + bars | Set background (WeeChat color)
19 + "B" + EXT | 19 `B@00124` | chat + bars | Set background (extended color)
19 + "*" + (A)STD | 19`*05` | chat + bars | Set foreground (WeeChat color)
19 + "*" + (A)EXT | 19`*@00214` | chat + bars | Set foreground (extended color)
19 + "*" + (A)STD + "," + (A)STD | 19`*08,05` | chat + bars | Set foreground/background (WeeChat colors)
19 + "*" + (A)STD + "," + (A)EXT | 19`*01,@00214` | chat + bars | Set foreground (WeeChat color) and background (extended color)
19 + "*" + (A)EXT + "," + (A)STD | 19`*@00214,05` | chat + bars | Set foreground (extended color) and background (WeeChat color)
19 + "*" + (A)EXT + "," + (A)EXT | 19`*@00214,@00017` | chat + bars | Set foreground/background (extended colors)
19 + "b" + "F" | 19 `bF` | bars | Set bar foreground color
19 + "b" + "D" | 19 `bD` | bars | Set bar delimiter color
19 + "b" + "B" | 19 `bB` | bars | Set bar background color
19 + "b" + "_" | 19 `b_` | input bar | Start input char (used only in item "input_text")
19 + "b" + "-" | 19 `b-` | input bar | Start input hidden char (used only in item "input_text")
19 + "b" + "#" | 19 `b#` | input bar | Move cursor char char (used only in item "input_text")
19 + "b" + "i" | 19 `bi` | bars | Start item
19 + "b" + "l" (lower L) | 19 `bl` | bars | Start line item
19 + "E" | 19 `E` | chat + bars | Emphasize text (new in version 0.4.2)
19 + 1C | 19 1C | chat + bars | Reset color (keep attributes)
1A + ATTR | 1A`*` | chat + bars | Set attribute
1B + ATTR | 1B`*` | chat + bars | Remove attribute
1C | 1C | chat + bars | Reset attributes and color

Color codes using options (see t_gui_color_enum, in file src/gui/gui-color.h):

Code | Option
--- | ---
`00` | weechat.color.separator
`01` | weechat.color.chat
`02` | weechat.color.chat_time
`03` | weechat.color.chat_time_delimiters
`04` | weechat.color.chat_prefix_error
`05` | weechat.color.chat_prefix_network
`06` | weechat.color.chat_prefix_action
`07` | weechat.color.chat_prefix_join
`08` | weechat.color.chat_prefix_quit
`09` | weechat.color.chat_prefix_more
`10` | weechat.color.chat_prefix_suffix
`11` | weechat.color.chat_buffer
`12` | weechat.color.chat_server
`13` | weechat.color.chat_channel
`14` | weechat.color.chat_nick
`15` | weechat.color.chat_nick_self
`16` | weechat.color.chat_nick_other
`17` | (not used any more since WeeChat 0.3.4)
`18` | (not used any more since WeeChat 0.3.4)
`19` | (not used any more since WeeChat 0.3.4)
`20` | (not used any more since WeeChat 0.3.4)
`21` | (not used any more since WeeChat 0.3.4)
`22` | (not used any more since WeeChat 0.3.4)
`23` | (not used any more since WeeChat 0.3.4)
`24` | (not used any more since WeeChat 0.3.4)
`25` | (not used any more since WeeChat 0.3.4)
`26` | (not used any more since WeeChat 0.3.4)
`27` | weechat.color.chat_host
`28` | weechat.color.chat_delimiters
`29` | weechat.color.chat_highlight
`30` | weechat.color.chat_read_marker
`31` | weechat.color.chat_text_found
`32` | weechat.color.chat_value
`33` | weechat.color.chat_prefix_buffer
`34` | weechat.color.chat_tags (new in version 0.3.6)
`35` | weechat.color.chat_inactive_window (new in version 0.3.6)
`36` | weechat.color.chat_inactive_buffer (new in version 0.3.6)
`37` | weechat.color.chat_prefix_buffer_inactive_buffer (new in version 0.3.6)
`38` | weechat.color.chat_nick_offline (new in version 0.3.9)
`39` | weechat.color.chat_nick_offline_highlight (new in version 0.3.9)
`40` | weechat.color.chat_nick_prefix (new in version 0.4.1)
`41` | weechat.color.chat_nick_suffix (new in version 0.4.1)
`42` | weechat.color.emphasis (new in version 0.4.2)
`43` | weechat.color.chat_day_change (new in version 0.4.2)

WeeChat colors are:

Code | Color
--- | ---
`00` | Default (terminal foreground/background)
`01` | Black
`02` | Dark gray
`03` | Dark red
`04` | Light red
`05` | Dark green
`06` | Light green
`07` | Brown
`08` | Yellow
`09` | Dark blue
`10` | Light blue
`11` | Dark magenta
`12` | Light magenta
`13` | Dark cyan
`14` | Light cyan
`15` | Gray
`16` | White

Examples of color codes:

Code | Description
--- | ---
19 `01` | Color of option "01" (chat text)
19`*08,03` | Yellow on red
19`*@00214` | Orange (extended color 214)
19`*@*_00214,@00017` | Bold underlined orange (214) on dark blue (17)
1A`_` | Set underline
1B`_` | Remove underline
1C `bD` | Reset attributes and color

## 5. Plugin internals

The file src/plugins/weechat-plugin.h defines and exports all functions available for API.

A structure called t_weechat_plugin is used to store info about plugin (filename, name, author, description, …) and all API functions, as pointers to WeeChat functions.

Then some macros are defined to call these functions in an easier way.

For example, function hook_timer is defined in structure t_weechat_plugin like this:

    struct t_hook *(*hook_timer) (struct t_weechat_plugin *plugin,
                                  long interval,
                                  int align_second,
                                  int max_calls,
                                  int (*callback)(void *data,
                                                  int remaining_calls),
                                  void *callback_data);

And the macro used to call this function is:

    #define weechat_hook_timer(__interval, __align_second, __max_calls,     \
                               __callback, __data)                          \
        weechat_plugin->hook_timer(weechat_plugin, __interval,              \
                                   __align_second, __max_calls,             \
                                   __callback, __data)

So in a plugin, the call to function will be for example:

    server->hook_timer_sasl = weechat_hook_timer (timeout * 1000,
                                                  0, 1,
                                                  &irc_server_timer_sasl_cb,
                                                  server);

## 6. Contribute to WeeChat

### 6.1. Git repository

Git repository is at this URL: http://git.savannah.gnu.org/gitweb/?p=weechat.git

Any patch for bug or new feature must be done on master branch, preferred format is a patch made with `git diff` or `git format-patch`, sent by e-mail.

Format of commit message is the following:

    component: fix a problem (bug #12345)

Where component is one of following:

- WeeChat core: core (files in directory src/ except doc and plugins)

- documentation files: doc (files in directory doc/)

- name of a plugin: irc, python, relay, … (files in directory src/plugins/)

Some rules to follow:

- use only English

- use infinitive form of verb

- if commit is related to something in tracker (bug, task, patch), write it in parenthesis after the message (format: bug #12345, task #12345, patch #12345)

Examples of commit messages:

    core: add callback "nickcmp" for nick comparison in buffers
    irc: fix freeze when reading on socket with SSL enabled (bug #35097)
    ruby: add detection of ruby version 1.9.3 in cmake
    python: fix crash when unloading a script without pointer to interpreter
    core: update Japanese translations (patch #7783)

### 6.2. Translations

#### 6.2.1. Gettext

Gettext files are in directory po/. If you want to initialize a new language, use command `msginit`. For example to create a dutch empty file:

    $ cd po
    $ msginit -i weechat.pot -l nl_NL -o nl.po

Base language for WeeChat is English, so you must of course understand English in order to translate to your language.

When done, you have to check your file with script msgcheck.py (https://github.com/flashcode/msgcheck):

    $ msgcheck.py xx.po

##### Build auto-generated files

Files in directory doc/XX/autogen/ are auto-generated by script doc/docgen.py.

Copy this python script to your python directory (for example ~/.weechat/python). Then you can load this script in your WeeChat, and setup path to your /doc directory:

    /python load docgen.py
    /set plugins.var.python.docgen.path "~/src/weechat/doc"

Then create this alias to build files:

    /alias doc /perl unload; /python unload; /ruby unload; /lua unload; /tcl unload; /guile unload; /python load docgen.py; /wait 1ms /docgen

And use command `/doc` to build all auto-generated files (for all languages).

Important | When using command `/doc`, be sure all C plugins (irc, charset, …) are loaded, because files are built using options currently in memory.

#### 6.2.2. Asciidoc

Asciidoc files are in directory doc/XX/ where XX is language (en, fr, de, it, …)

First make a copy of an English asciidoc file (in directory doc/en/), then work on it.

The translations missing in files are indicated by this string:

    // TRANSLATION MISSING

You must translate whole file except links and special keywords for notes, warnings, … These words must be kept unchanged:

    [[link_name]]
    <<link_name>>

    [NOTE]
    [TIP]
    [IMPORTANT]
    [WARNING]
    [CAUTION]

When there is a name after `<<link_name>>`, then you must translate it:

    <<link_name,this text must be translated>>

Please make sure special chars below titles are exactly same length as title (not too short or too long):

    This is a correct title
    =======================

    This is a wrong title
    ============

    This is a wrong title
    =============================