# Module irc

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("irc.server.net", joinChans = @["#channel"])
    client.connect()
    while True:
      var event: TIRCEvent
      if client.poll(event):
        case event.typ
        of EvDisconnected: break
        of EvMsg:
          # Where all the magic happens.

# Imports

sockets, strutils, parseutils, times, asyncio

# Types

    TIRC* = object of TObject
      address: string
      port: TPort
      nick, user, realname, serverPass: string
      sock: TSocket
      status: TInfo
      lastPing: float
      lastPong: float
      lag: float
      channelsToJoin: seq[string]
      msgLimit: bool
      messageBuffer: seq[tuple[timeToSend: float, m: string]]

    PAsyncIRC* = ref TAsyncIRC

    TAsyncIRC* = object of TIRC
      handleEvent: proc (irc: var TAsyncIRC; ev: TIRCEvent) {.closure.}
      asyncSock: PAsyncSocket

    TIRCMType* = enum
      MUnknown, MNumeric, MPrivMsg, MJoin, MPart, MMode, MTopic, MInvite, MKick,
      MQuit, MNick, MNotice, MPing, MPong, MError

    TIRCEventType* = enum
      EvMsg, EvDisconnected

    TIRCEvent* = object
      case typ*: TIRCEventType
      of EvDisconnected:
        nil
      of EvMsg:
          cmd*: TIRCMType
          nick*, user*, host*, servername*: string
          numeric*: string
          params*: seq[string]
          origin*: string
          raw*: string

  The channel/user that this msg originated from

# Procs

    proc send*(irc: var TIRC; message: string; sendImmediately = false)

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

    proc privmsg*(irc: var TIRC; target, message: string)

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

    proc notice*(irc: var TIRC; target, message: string)

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

    proc join*(irc: var TIRC; channel: string; key = "")

  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: var TIRC; channel, message: string)

  Leaves `channel` with `message`.

    proc close*(irc: var TIRC)

  Closes connection to an IRC server.

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

    proc connect*(irc: var TIRC)

  Connects to an IRC server as specified by `irc`.

    proc irc*(address: string; port: TPort = 6667.TPort; nick = "NimrodBot";
              user = "NimrodBot"; realname = "NimrodBot"; serverPass = "";
              joinChans: seq[string] = @ []; msgLimit: bool = true): TIRC

  Creates a `TIRC` object.

    proc poll*(irc: var TIRC; ev: var TIRCEvent; timeout: int = 500): bool

  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: var TIRC): float

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

  If latency is unknown, returns -1.0.

    proc isConnected*(irc: var TIRC): bool

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

    proc connect*(irc: PAsyncIRC)

  Equivalent of connect for `TIRC` but specifically created for asyncio.

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

  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.

    proc register*(d: PDispatcher; irc: PAsyncIRC)

  Registers `irc` with dispatcher `d`.

Generated: 2012-09-23 21:47:54 UTC