# 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("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

  IRC Event

# Procs

    proc send(irc: PIRC; message: string; sendImmediately = false) {.raises: [],
        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: [],
        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: [],
        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: [EInvalidValue, E_Base, EOS],
        tags: [FTime, FWriteIO, TEffect, FReadIO].}

  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, EInvalidValue, E_Base],
        tags: [FTime, FWriteIO, TEffect, 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.

Generated: 2013-05-21 09:55:22 UTC