ircfmt

Documentation

Overview

Package ircfmt handles IRC formatting codes, escaping and unescaping.

This allows for a simpler representation of strings that contain colour codes, bold codes, and such, without having to write and handle raw bytes when assembling outgoing messages.

This lets you turn raw IRC messages into our escaped versions, and turn escaped versions back into raw messages suitable for sending on IRC connections. This is designed to be used on things like PRIVMSG / NOTICE commands, MOTD blocks, and such.

The escape character we use in this library is the dollar sign ("$"), along with the given escape characters:

--------------------------------
 Name           | Escape | Raw
--------------------------------
 Dollarsign     |   $$   |  $
 Bold           |   $b   | 0x02
 Colour         |   $c   | 0x03
 Monospace      |   $m   | 0x11
 Reverse Colour |   $v   | 0x16
 Italic         |   $i   | 0x1d
 Strikethrough  |   $s   | 0x1e
 Underscore     |   $u   | 0x1f
 Reset          |   $r   | 0x0f
--------------------------------

Colours are escaped in a slightly different way, using the actual names of them rather than just the raw numbers.

In our escaped format, the colours for the fore and background are contained in square brackets after the colour ("$c") escape. For example:

Red foreground:
	Escaped:  This is a $c[red]cool message!
	Raw:      This is a 0x034cool message!

Blue foreground, green background:
	Escaped:  This is a $c[blue,green]rad message!
	Raw:      This is a 0x032,3rad message!

When assembling a raw message, we make sure to use the full colour code ("02" vs just "2") when it could become confused due to numbers just after the colour escape code. For instance, lines like this will be unescaped correctly:

No number after colour escape:
	Escaped:  This is a $c[red]cool message!
	Raw:      This is a 0x034cool message!

Number after colour escape:
	Escaped:  This is $c[blue]20% cooler!
	Raw:      This is 0x030220% cooler

Here are the colour names and codes we recognise:

--------------------
 Code | Name
--------------------
  00  | white
  01  | black
  02  | blue
  03  | green
  04  | red
  05  | brown
  06  | magenta
  07  | orange
  08  | yellow
  09  | light green
  10  | cyan
  11  | light cyan
  12  | light blue
  13  | pink
  14  | grey
  15  | light grey
  99  | default
--------------------

These other colours aren't given names: https://modern.ircdocs.horse/formatting.html#colors-16-98

Index

• func Escape(in string) string
• func Strip(in string) string
• func Unescape(in string) string
• type ColorCode
  • func ParseColor(str string) (color ColorCode)
• type FormattedSubstring
  • func Split(raw string) (result []FormattedSubstring)
  • func (f *FormattedSubstring) IsFormatted() bool

Functions

func Escape

func Escape(in string) string

Escape takes a raw IRC string and returns it with our escapes.

IE, it turns this: "This is a \x02cool\x02, \x034red\x0f message!" into: "This is a $bcool$b, $c[red]red$r message!"

func Strip

func Strip(in string) string

Strip takes a raw IRC string and removes it with all formatting codes removed IE, it turns this: "This is a \x02cool\x02, \x034red\x0f message!" into: "This is a cool, red message!"

func Unescape

func Unescape(in string) string

Unescape takes our escaped string and returns a raw IRC string.

IE, it turns this: "This is a $bcool$b, $c[red]red$r message!" into this: "This is a \x02cool\x02, \x034red\x0f message!"

Types

type ColorCode

type ColorCode struct {
	IsSet bool
	Value uint8
}

ColorCode is a normalized representation of an IRC color code, as per this de facto specification: https://modern.ircdocs.horse/formatting.html#color The zero value of the type represents a default or unset color, whereas ColorCode{true, 0} represents the color white.

func ParseColor

func ParseColor(str string) (color ColorCode)

ParseColor converts a string representation of an IRC color code, e.g. "04", into a normalized ColorCode, e.g. ColorCode{true, 4}.

type FormattedSubstring

type FormattedSubstring struct {
	Content         string
	ForegroundColor ColorCode
	BackgroundColor ColorCode
	Bold            bool
	Monospace       bool
	Strikethrough   bool
	Underline       bool
	Italic          bool
	ReverseColor    bool
}

FormattedSubstring represents a section of an IRC message with associated formatting data.

func Split

func Split(raw string) (result []FormattedSubstring)

Split takes an IRC message (typically a PRIVMSG or NOTICE final parameter) containing IRC formatting control codes, and splits it into substrings with associated formatting information.

func (*FormattedSubstring) IsFormatted

func (f *FormattedSubstring) IsFormatted() bool

IsFormatted returns whether the section has any formatting flags switched on.