UIOverview

Irssi Text UI Overview

Irssi is deliberately designed to allow most of the actual text and formatting to be customised by themes and scripts. This is achieved by a combination of expandable markup templates, and special escape codes to generate colour and other formatting features.

• Internals documents the underlying mechanism for how these features are implemented, but this page in intended to give an overview for people looking to write or customise their theme files.

• Irssi::UI::Theme also contains details of the functions available to script writers who wish to use themes and formats within their code.

• Formats describes the various markup syntax used within the theme templates for colour and other formatting.

• Complete Format List categorises the available internal formats and themes in a way that can be easily searched for those trying to customise a specific aspect.

See also Theme Editing for practical details on writing or modifying a theme file.

One of the prime benefits of this approach is the ability to modify abstracts and formats to produce completely different themed instances, or even to translate into other languages.

Templates

Templates are the main workhorse of Irssi the display customisations. In use, they take the form {template_name arg1 arg2 ...}, or are used in the [[printformat $msg_level, $format, @params|Irssi#wiki-Printing]]

In construction, they are typically written as

# bold the first argument, followed by a space and then all subsequent args.
some_format = "%_$0%_ $1-";

Named arguments are not possible, they expand only based on positional arguments, so it is often necessary to read the code or comments surrounding them to determine the positional value of each argument.

They are subject to various rules of expansion before display, as will be outlined below. The variables and custom variable syntax is defined in Formats.

Templates are often built on top of other templates, to make global changes easier. For example, the format notify_join has the following definition:

notify_join = "{nick $0} [$1@$2] [{hilight $3}] has joined to $4";

This format takes 4 arguments. The first, $0, is passed to the {nick} format, which is defined as an abstract. The second and third and rendered directly, whilst $3 is also a recursively expanded pattern {hilight}.

{hilight $0-} itself, is merely a wrapper for '%_$0-%_';

Replaces

Replaces are a special case of "not-quite-templates", but rather global mappings which are applied to rendered templates once everything else is complete.

By default, their only function is to darken the [] brace characters, as shown by the line in Format List#Replacements.

Replaces are generally applied, but there are some special cases, such as being evaluated using the [[format_expand()|theme#wiki-format_expand_$theme,$format,$flags]] using the EXPAND_FLAG_IGNORE_REPLACES flag, they are not.

format_expand() also has a few other interesting flags.

• EXPAND_FLAG_IGNORE_EMPTY -- If the root template expands to the empty string, it is not returned. Useful for places where variables may be optional, and a half-filled template would look out of places.

• EXPAND_FLAG_RECURSIVE_MASK -- The template processor only runs a single pass over the template. Embedded templates more than one cycle deep remain untouched and appear verbatim.

Abstracts

Abstracts are the core contents of each theme file, and define the basic templates which are built upon by formats.

In order to decouple the actual display syntax from the internal formats, abstracts are used as a bridge, and define such templates as:

hilight = "%_$*%_";

Abstracts are used not only in the construction of formats, but also play a significant role in the rendering of window items, such as status bars.

Abstracts are difficult to work with in a running Irssi instance. The functions that operate on them like [[get_format()|theme#wiki-get_format_$theme,$module,$tag]] explicitly prevent scripts from TODO: use things outside package.

Formats

Formats are special, top-level flavours of templates, in that they are exposed to the use via the /FORMAT <module> <key> <value> command.

Generally, modifying these formats directly is a bad idea, since they are easy to break, especially if you place the arguments in the wrong order, and a /SAVE command will save them to the theme file where they will persist.

Unlike abstracts and replaces, formats each reside in a particular namespace, as defined by their module identifiers (i.e.: perl Packages}..

Those identifiers are (assuming core modules are loaded:)

• fe-common/core
• fe-common/fe-text
• fe-common/irc/dcc
• fe-common/irc/notifylist
• fe-common/irc
• fe-common/perl

Internals/Formats has a more in-depth desccription of these modules, and how the formats are used internally with irssi.