irc

stable

Encode and decode IRC protocol messages (RFC 2812) as raw strings ready to send over a TCP connection.

use plugin irc::{encode_privmsg, encode_join, encode_part, …}

/ filter jk navigate Esc clear

Functions (22)

Overview

irc is a stateless codec for the IRC client protocol (RFC 2812): it turns high-level intentions into the exact wire lines a server expects, and turns raw lines coming back off the socket into structured tables. It opens no connections and holds no session state — every function is a pure string-in / string-out (or string-in / table-out) transformation, so you stay in full control of the TCP layer and can drive any transport you like. The encoders all return a complete line terminated with \r\n, ready to write straight to a socket; the parsers (parse_message, parse_prefix) accept a single raw line and hand back fields you can branch on.

Use it whenever you are building an IRC client, bot, or bridge in Zolo and want correct framing without hand-assembling protocol strings. The mental model is a loop: read a line from the server, parse_message it, react (often by emitting another encode_* line), and write the result back.

Common patterns

use plugin irc::{encode_pass, encode_nick, encode_user}

let lines = [
  encode_pass("s3cr3t"),
  encode_nick("zolo_bot"),
  encode_user("zolo_bot", "Zolo IRC Bot"),
]
for line in lines {
  print(line)
}

Keep the connection alive by answering server pings — parse the incoming line and echo the token back as a PONG:

use plugin irc::{parse_message, encode_pong}

let msg = parse_message("PING :irc.libera.chat\r\n")
if msg["command"] == "PING" {
  print(encode_pong(msg["trailing"]))
}

Dispatch an incoming PRIVMSG: figure out who sent it, whether it landed in a channel, and reply in the right place:

use plugin irc::{parse_message, parse_prefix, is_channel, encode_privmsg}

let msg = parse_message(":alice!alice@host PRIVMSG #general :hello bot\r\n")
let who = parse_prefix(msg["prefix"])
let reply_to = if is_channel(msg["params"][0]) { msg["params"][0] } else { who["nick"] }
print(encode_privmsg(reply_to, "hi {who["nick"]}!"))

encode_privmsg(target, message) → string

Encode a PRIVMSG command

Encodes a PRIVMSG command. target can be a channel (e.g. #general) or a nick. Returns the raw IRC line with \r\n.

use plugin irc::{encode_privmsg}

let line = encode_privmsg("#general", "Hello everyone!")
print(line)

The same encoder sends a private message to a single user — just pass a nick instead of a channel as the target:

use plugin irc::{encode_privmsg}

print(encode_privmsg("alice", "thanks for the help!"))

encode_join(channel) → string

Encode a JOIN command

Encodes a JOIN command for the given channel name.

use plugin irc::{encode_join}

let line = encode_join("#rust")
print(line)

encode_part(channel) → string

Encode a PART command

Encodes a PART command to leave the given channel.

use plugin irc::{encode_part}

let line = encode_part("#rust")
print(line)

encode_nick(nickname) → string

Encode a NICK command

Encodes a NICK command to set or change the client's nickname.

use plugin irc::{encode_nick}

let line = encode_nick("zolo_bot")
print(line)

encode_user(username, realname) → string

Encode a USER command

Encodes a USER command used during connection registration. Produces USER <username> 0 * :<realname>\r\n.

use plugin irc::{encode_nick, encode_user}

let nick = encode_nick("zolo_bot")
let user = encode_user("zolo_bot", "Zolo IRC Bot")
print(nick)
print(user)

encode_ping(server) → string

Encode a PING command

Encodes a PING command to the given server name.

use plugin irc::{encode_ping}

let line = encode_ping("irc.libera.chat")
print(line)

encode_pong(server) → string

Encode a PONG command

Encodes a PONG reply. Use this to respond to server PING messages and stay connected.

use plugin irc::{encode_pong, parse_message}

let msg = parse_message("PING :irc.libera.chat\r\n")
let server = msg["trailing"]
let reply = encode_pong(server)
print(reply)

encode_quit(message) → string

Encode a QUIT command

Encodes a QUIT command with a farewell message.

use plugin irc::{encode_quit}

let line = encode_quit("Goodbye!")
print(line)

encode_pass(password) → string

Encode a PASS command

Encodes a PASS command for server password authentication, sent before NICK and USER.

use plugin irc::{encode_pass, encode_nick, encode_user}

let pass = encode_pass("s3cr3t")
let nick = encode_nick("my_bot")
let user = encode_user("my_bot", "My Bot")

encode_kick(channel, nick, reason) → string

Encode a KICK command

Encodes a KICK command to remove a user from a channel.

use plugin irc::{encode_kick}

let line = encode_kick("#general", "spammer", "Spam is not allowed")
print(line)

encode_mode(target, modes) → string

Encode a MODE command

Encodes a MODE command to set channel or user modes.

use plugin irc::{encode_mode}

let line = encode_mode("#general", "+m")
print(line)

encode_topic(channel, topic) → string

Encode a TOPIC command

Encodes a TOPIC command to set the channel topic.

use plugin irc::{encode_topic}

let line = encode_topic("#general", "Welcome to #general — be kind!")
print(line)

encode_notice(target, message) → string

Encode a NOTICE command

Encodes a NOTICE command. Like PRIVMSG but clients should not auto-reply to notices.

use plugin irc::{encode_notice}

let line = encode_notice("alice", "You have a private message.")
print(line)

encode_invite(nick, channel) → string

Encode an INVITE command

Encodes an INVITE command to invite a user to a channel.

use plugin irc::{encode_invite}

let line = encode_invite("alice", "#private")
print(line)

encode_list(channel?) → string

Encode a LIST command

Encodes a LIST command. Pass a channel name to list only that channel; omit it to list all channels.

use plugin irc::{encode_list}

let all = encode_list("")
let one = encode_list("#rust")
print(all)
print(one)

encode_names(channel?) → string

Encode a NAMES command

Encodes a NAMES command to list users in a channel. Omit the channel to list all visible users.

use plugin irc::{encode_names}

let line = encode_names("#general")
print(line)

encode_whois(nick) → string

Encode a WHOIS command

Encodes a WHOIS command to look up information about a user.

use plugin irc::{encode_whois}

let line = encode_whois("alice")
print(line)

encode_raw(command) → string

Encode any raw IRC command

Appends \r\n to any raw IRC command string. Use this for commands not covered by the typed encoders.

use plugin irc::{encode_raw}

let line = encode_raw("CAP LS 302")
print(line)

parse_message(raw) → table

Parse a raw IRC message line

Parses a raw IRC message line into {prefix, command, params, trailing}. prefix and trailing may be nil if absent.

use plugin irc::{parse_message}

let msg = parse_message(":alice!user@host PRIVMSG #general :Hello!\r\n")
print(msg["prefix"])
print(msg["command"])
print(msg["trailing"])

Positional arguments land in the params table (keyed from index 0), while the final :-prefixed segment becomes trailing — useful for reading the channel a message was sent to:

use plugin irc::{parse_message}

let msg = parse_message(":bob!bob@host PRIVMSG #zolo :ship it\r\n")
print("channel: {msg["params"][0]}")
print("text:    {msg["trailing"]}")

parse_prefix(prefix) → table

Parse a nick!user@host prefix

Parses a nick!user@host prefix string into {nick, user, host}. Works with server names too (user and host may be empty strings).

use plugin irc::{parse_prefix, parse_message}

let msg = parse_message(":[email protected] PRIVMSG #chat :hi\r\n")
let who = parse_prefix(msg["prefix"])
print(who["nick"])
print(who["host"])

format_ctcp(command, params?) → string

Format a CTCP message

Wraps a CTCP command in the required \x01 delimiters. Use the result as the message body of a PRIVMSG or NOTICE.

use plugin irc::{format_ctcp, encode_privmsg}

let ctcp = format_ctcp("VERSION", "")
let line = encode_privmsg("alice", ctcp)
print(line)

Pass params to build an action message ("/me waves") or a timestamped PING:

use plugin irc::{format_ctcp, encode_privmsg}

let action = format_ctcp("ACTION", "waves at the channel")
print(encode_privmsg("#general", action))

is_channel(target) → bool

Check if a target is a channel name

Returns true if the target string starts with #, &, +, or ! (IRC channel prefixes).

use plugin irc::{is_channel}

print(is_channel("#general"))
print(is_channel("alice"))

Use it to route a reply to the right place — back to the channel for public messages, or to the sender's nick for one-on-one chats:

use plugin irc::{is_channel, parse_prefix, encode_privmsg}

let target = "#zolo"
let sender = parse_prefix("dave!dave@host")
let dest = if is_channel(target) { target } else { sender["nick"] }
print(encode_privmsg(dest, "got it"))

View source code