• format_expand $theme, $format, $flags

• get_format $theme, $module, $tag

• Loading and Testing

• TEMPLATES

• COLOURS

format_expand $theme, $format, $flags

$flags is an optional bitmask of any of the following flags:

EXPAND_FLAG_IGNORE_REPLACES

Any replacements specified in the theme are not applied to this expansion.

EXPAND_FLAG_RECURSIVE_MASK

TODO: dunno

EXPAND_FLAG_IGNORE_EMPTY

If the format contains variables and no values are specified, an empty string is returned instead of a partially filled template.

TODO: What?

Example:

my $formatted_str = Irssi::current_theme()->format_expand('{hilight Hello}');

Note: it seems that this only operates on abstract templates, not those accessible with /FORMAT. Weird

get_format $theme, $module, $tag

Returns the unexpanded format template for the format name supplied in $tag.

Valid values for $module are:

fe-common/perl

fe-common/perl

fe-common/irc/dcc

fe-common/irc/dcc

fe-common/irc

fe-common/irc

fe-common/core

fe-common/core

fe-common/irc/notifylist

fe-common/irc/notifylist

fe-text

fe-text

To get your own themes, use __PACKAGE__ as the module

Example:

my $pubmsg_format = Irssi::current_theme->get_format('fe-common/core', 'pubmsg');

# returns: '{pubmsgnick $2 {pubnick $0}}$1'

You can change themes by issuing a /SET theme theme-name command from Irssi. Reloading is slightly harder, since Irssi will only reload and process a new theme if the theme variable changes.

You can force a reload of the theme (and everything else) with /RELOAD. This reloads the configuration file too, so if you did any changes remember to /SAVE first.

Remember also that /SAVE overwrites the theme file with old data so keep backups :)

Better alternatives are the following aliases:

/ALIAS THEMERELOAD SCRIPT EXEC Irssi::themes_reload();

or

/ALIAS THEMERELOAD SET theme default; EVAL SET theme $theme

The former is preferred if you have scripting support, whereas the latter will work without scripting (Perl) support loaded, but requires that you are editing a custom theme, rather than modifying default.theme.

The actual mechanism used by Irssi to print text into the client involves a certain amount of indirection, which allows themes to reformat messages in various ways before they are displayed.

The overall structure of these templates is based around 3 basic ideas:

Nested Templates

Colour Codes

Variable Expansion

Special Variables

The real text formats that irssi uses are the ones you can find with /FORMAT command. Back in the old days all the colors and texts were mixed up in those formats, and it was really hard to change the colors since you might have had to change them in tens of different places. So, then came this templating system.

Now the /FORMATs don't have any colors in them, and they also have very little other styling. Most of the stuff you need to change is in this theme file. If you can't change something here, you can always go back to change the /FORMATs directly, they're also saved in the *.theme files.

So, the templates. They're those {blahblah} parts you see all over the /FORMATs and here. Their usage is simply {name parameter1 parameter2}.

When irssi sees this kind of text, it goes to find name from the abstracts block below and sets parameter1 into $0 and parameter2 into $1 (you can have more parameters of course). Templates can have sub-templates. Here's a small example:

/FORMAT format hello {colorify {underline world}}

abstracts = { colorify = "%G$0-%n"; underline = "%U$0-%U"; }

When irssi expands the templates in "format", the final string would be:

hello %G%Uworld%U%n

ie. underlined bright green "world" text. and why $0-, why not $0? $0 would only mean the first parameter, $0- means all the parameters. With {underline hello world} you'd really want to underline both of the words, not just the hello (and world would actually be removed entirely).

See also Formats/Arguments for details on the variable to argument mapping.

You can find definitions for the colour format codes in Formats/Colours.

There's one difference here though. %n format. Normally it means the default color of the terminal (white mostly), but here it means the "reset color back to the one it was in higher template". For example if there was /FORMAT test %g{foo}bar, and foo = "%Y$0%n", irssi would print yellow "foo" (as set with %Y) but "bar" would be green, which was set at the beginning before the {foo} template. If there wasn't the %g at start, the normal behaviour of %n would occur. If you really want to use the terminal's default color, use %N.