This module implements an asynchronous IRC client.

Currently this module requires at least some knowledge of the IRC protocol. It provides a function for sending raw messages to the IRC server, together with some basic functions like sending a message to a channel. It automizes the process of keeping the connection alive, so you don't need to reply to PING messages. In fact, the server is also PING'ed to check the amount of lag.

var client = irc("picheta.me", joinChans = @["#bots"])
client.connect()
while True:
  var event: TIRCEvent
  if client.poll(event):
    case event.typ
    of EvConnected: nil
    of EvDisconnected:
      client.reconnect()
    of EvMsg:
      # Write your message reading code here.

Warning: The API of this module is unstable, and therefore is subject to change.

Imports

sockets, strutils, parseutils, times, asyncio, os

Types

TIRC = object of TObject address: string port: TPort nick, user, realname, serverPass: string case isAsync: bool of true: handleEvent: proc (irc: PAsyncIRC; ev: TIRCEvent) {.closure.} asyncSock: PAsyncSocket myDispatcher: PDispatcher of false: dummyA: pointer dummyB: pointer dummyC: pointer sock: TSocket status: TInfo lastPing: float lastPong: float lag: float channelsToJoin: seq[string] msgLimit: bool messageBuffer: seq[tuple[timeToSend: float, m: string]] lastReconnect: float
PIRC = ref TIRC
PAsyncIRC = ref TAsyncIRC
TAsyncIRC = object of TIRC
TIRCMType = enum MUnknown, MNumeric, MPrivMsg, MJoin, MPart, MMode, MTopic, MInvite, MKick, MQuit, MNick, MNotice, MPing, MPong, MError
TIRCEventType = enum EvMsg, EvConnected, EvDisconnected
TIRCEvent = object case typ*: TIRCEventType of EvConnected: nil ## Connected to server. ## Only occurs with AsyncIRC. of EvDisconnected: nil ## Disconnected from the server of EvMsg: ## Message from the server cmd*: TIRCMType ## Command (e.g. PRIVMSG) nick*, user*, host*, servername*: string numeric*: string ## Only applies to ``MNumeric`` params*: seq[string] ## Parameters of the IRC message origin*: string ## The channel/user that this msg originated from raw*: string ## Raw IRC message timestamp*: TTime ## UNIX epoch time the message was received: IRC Event

Procs

proc send(irc: PIRC; message: string; sendImmediately = false) {. raises: [EInvalidValue], tags: [FTime, FWriteIO].}

Sends message as a raw command. It adds \c\L for you.

proc privmsg(irc: PIRC; target, message: string) {.raises: [EInvalidValue], tags: [FTime, FWriteIO].}

Sends message to target. Target can be a channel, or a user.

proc notice(irc: PIRC; target, message: string) {.raises: [EInvalidValue], tags: [FTime, FWriteIO].}

Sends notice to target. Target can be a channel, or a user.

proc join(irc: PIRC; channel: string; key = "") {.raises: [EInvalidValue], tags: [FTime, FWriteIO].}

Joins channel.

If key is not "", then channel is assumed to be key protected and this function will join the channel using key.

proc part(irc: PIRC; channel, message: string) {.raises: [EInvalidValue], tags: [FTime, FWriteIO].}

Leaves channel with message.

proc close(irc: PIRC) {.raises: [], tags: [].}

Closes connection to an IRC server.

Warning: This procedure does not send a QUIT message to the server.

proc connect(irc: PIRC) {.raises: [EOS, EInvalidValue], tags: [FReadIO, FTime, FWriteIO].}

Connects to an IRC server as specified by irc.

proc reconnect(irc: PIRC; timeout = 5000) {.raises: [EOS, EInvalidValue], tags: [FTime, FReadIO, FWriteIO].}

Reconnects to an IRC server.

Timeout specifies the time to wait in miliseconds between multiple consecutive reconnections.

This should be used when an EvDisconnected event occurs.

proc irc(address: string; port: TPort = 6667.TPort; nick = "NimrodBot"; user = "NimrodBot"; realname = "NimrodBot"; serverPass = ""; joinChans: seq[string] = @ []; msgLimit: bool = true): PIRC {. raises: [], tags: [FTime].}

Creates a TIRC object.

proc poll(irc: PIRC; ev: var TIRCEvent; timeout: int = 500): bool {. raises: [ETimeout, EOS, EInvalidValue], tags: [FReadIO, FTime, FWriteIO].}

This function parses a single message from the IRC server and returns a TIRCEvent.

This function should be called often as it also handles pinging the server.

This function provides a somewhat asynchronous IRC implementation, although it should only be used for simple things for example an IRC bot which does not need to be running many time critical tasks in the background. If you require this, use the asyncio implementation.

proc getLag(irc: PIRC): float {.raises: [], tags: [].}

Returns the latency between this client and the IRC server in seconds.

If latency is unknown, returns -1.0.

proc isConnected(irc: PIRC): bool {.raises: [], tags: [].}

Returns whether this IRC client is connected to an IRC server.

proc getNick(irc: PIRC): string {.raises: [], tags: [].}

Returns the current nickname of the client.

proc register(d: PDispatcher; irc: PAsyncIRC) {.raises: [], tags: [].}

Registers irc with dispatcher d.

proc connect(irc: PAsyncIRC) {.raises: [EOS], tags: [FReadIO].}

Equivalent of connect for TIRC but specifically created for asyncio.

proc reconnect(irc: PAsyncIRC; timeout = 5000) {.raises: [EOS], tags: [FTime, FReadIO].}

Reconnects to an IRC server.

Timeout specifies the time to wait in miliseconds between multiple consecutive reconnections.

This should be used when an EvDisconnected event occurs.

When successfully reconnected an EvConnected event will occur.

proc asyncIRC(address: string; port: TPort = 6667.TPort; nick = "NimrodBot"; user = "NimrodBot"; realname = "NimrodBot"; serverPass = ""; joinChans: seq[string] = @ []; msgLimit: bool = true; ircEvent: proc (irc: PAsyncIRC; ev: TIRCEvent) {.closure.}): PAsyncIRC {. raises: [EOS], tags: [FTime].}

Use this function if you want to use asyncio's dispatcher.

Note: Do NOT use this if you're writing a simple IRC bot which only requires one task to be run, i.e. this should not be used if you want a synchronous IRC client implementation, use irc for that.

Module irc

Imports

Types

Procs