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.
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.
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 are just flags and are the
simplest text attributes to apply. They are accessed by the names
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!']])
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.
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
bg attribute names respectively, is
accessed and then the color name is accessed. The available color
attribute names are:
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!']]
Most IRC clients format text so it is logical that you may want to parse
this formatted text.
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.