Using the Twisted IRC Client

A complete howto would explain how to actually use the IRC client. However, until that howto is written, here is a howto that explains how to do text formatting for IRC.

Text formatting

The text formatting support in Twisted Words is based on the widely used mIRC format which supports bold, underline, reverse video and colored text; nesting these attributes is also supported.

Creating formatted text

The API used for creating formatted text in the IRC client is almost the same as that used by Twisted insults . Text attributes are built up by accessing and indexing attributes on a special module-level attribute, twisted.words.protocols.irc.attributes , multiple values can be passed when indexing attributes to mix text with nested text attributes. The resulting object can then be serialized to formatted text, with twisted.words.protocols.irc.assembleFormattedText , suitable for use with any of the IRC client messaging functions.

Bold, underline and reverse video attributes

Bold, underline and reverse video attributes are just flags and are the simplest text attributes to apply. They are accessed by the names bold , underline and reverseVideo , respectively, on twisted.words.protocols.irc.attributes . For example, messaging someone the bold and underlined text “Hello world!”:

from twisted.words.protocols.irc import assembleFormattedText, attributes as A

# Message "someone" the bold and underlined text "Hello world!"
anIRCClient.msg('someone', assembleFormattedText(
    A.bold[
        A.underline['Hello world!']])

The “normal” attribute

At first glance a text attribute called “normal” that does not apply any unusual text attributes may not seem that special but it can be quite useful, both as a container:

A.normal[
    'This is normal text. ',
    A.bold['This is bold text! '],
    'Back to normal',
    A.underline['This is underlined text!']]

And also as a way to temporarily disable text attributes without having to close and respecify all text attributes for a brief piece of text:

A.normal[
    A.reverseVideo['This is reverse, ', A.normal['except for this'], ', text']]

It is worth noting that assembled text will always begin with the control code to disable other attributes for the sake of correctness.

Color attributes

Since colors for both the foreground and background can be specified with IRC text formatting another level of attribute access is introduced. Firstly the foreground or background, through the fg and bg attribute names respectively, is accessed and then the color name is accessed. The available color attribute names are:

• white

• black

• blue

• green

• lightRed

• red

• magenta

• orange

• yellow

• lightGreen

• cyan

• lightCyan

• lightBlue

• lightMagenta

• gray

• lightGray

It is possible to nest foreground and background colors to alter both for a single piece of text. For example to display black on green text:

A.fg.black[A.bg.green['Like a terminal!']]

Parsing formatted text

Most IRC clients format text so it is logical that you may want to parse this formatted text. twisted.words.protocols.irc.parseFormattedText will parse text into structured text attributes. It is worth noting that while feeding the output of parseFormattedText back to assembleFormattedText will produce the same final result, the actual structure of the parsed text will differ. Color codes are mapped from 0 to 15, codes greater than 15 will begin to wrap around.

Removing formatting

In some cases, such as an automaton handling user input from IRC, it is desirable to have all formatting stripped from text. This can be accomplished with twisted.words.protocols.irc.stripFormatting .