# Module `irc`

LuaIRC - IRC framework written in Lua

Release: 0.3

## Functions

act (name, action) | Perform a /me action.
channels () | Iterate over currently joined channels.
connect (args) | Start a connection to the irc server.
ctcp_ping (cb, nick) | Send a CTCP ping request.
ctcp_time (cb, nick) | Send a localtime request.
ctcp_version (cb, nick) | Send a client version request.
get_ip () | Get the local IP address for the server connection.
join (channel) | Join a channel.
notice (name, message) | Send a notice to a user or channel.
part (channel) | Leave a channel.
quit (message) | Close the connection to the irc server.
register_callback (name, fn) | Register a user function to be called when a specific event occurs.
say (name, message) | Send a message to a user or channel.
send (command, ...) | Send a raw IRC command.
server_time (cb) | Request the current time of the server you are connected to.
server_version (cb) | Request the version of the IRC server you are currently connected to.
set_ip (new_ip) | Set the local IP manually (to allow for NAT workarounds)
whois (cb, nick) | Request WHOIS information about a given user.

## Functions

act (name, action)
  Perform a /me action.

  ### Parameters

  - name: User or channel to send the action to
  - action: Action to send
channels ()
  Iterate over currently joined channels. channels() is an iterator function for use in for loops. For example,

      for chan in irc.channels() do print(chan:name) end

  See also: irc.channel
connect (args)
  Start a connection to the irc server.

  ### Parameters

  - args: Table of named arguments containing connection parameters. Defaults are the all-caps versions of these parameters given at the top of the file, and are overridable by setting them as well, i.e.

        irc.NETWORK = irc.freenode.net

    Possible options are:
    - network: address of the irc network to connect to (default: 'localhost')
    - port: port to connect to (default: '6667')
    - pass: irc server password (default: don't send)
    - nick: nickname to connect as (default: 'luabot')
    - username: username to connect with (default: 'LuaIRC')
    - realname: realname to connect with (default: 'LuaIRC')
    - timeout: amount of time in seconds to wait before dropping an idle connection (default: '60')
ctcp_ping (cb, nick)
  Send a CTCP ping request.

  ### Parameters

  - cb: Callback to call when the information is available. The single table parameter to this callback will contain the fields:
    - nick: the nick which responded to the request
    - time: the roundtrip ping time, in seconds
  - nick: User to ping
ctcp_time (cb, nick)
  Send a localtime request.

  ### Parameters

  - cb: Callback to call when the information is available. The single table parameter to this callback will contain the fields:
    - nick: the nick which responded to the request
    - time: the localtime reported by the remote client
  - nick: User to request the localtime from
ctcp_version (cb, nick)
  Send a client version request.

  ### Parameters

  - cb: Callback to call when the information is available. The single table parameter to this callback will contain the fields:
    - nick: the nick which responded to the request
    - version: the version reported by the remote client
  - nick: User to request the client version from
get_ip ()
  Get the local IP address for the server connection.

  ### Return value:

  A string representation of the local IP address that the IRC server connection is communicating on
join (channel)
  Join a channel.

  ### Parameters

  - channel: Channel to join
notice (name, message)
  Send a notice to a user or channel.

  ### Parameters

  - name: User or channel to send the notice to
  - message: Message to send
part (channel)
  Leave a channel.

  ### Parameters

  - channel: Channel to leave
quit (message)
  Close the connection to the irc server.

  ### Parameters

  - message: Quit message (optional, defaults to 'Leaving')
register_callback (name, fn)
  Register a user function to be called when a specific event occurs.

  ### Parameters

  - name: Name of the event
  - fn: Function to call when the event occurs, or nil to clear the callback for this event

  ### Return value:

  Value of the original callback for this event (or nil if no previous callback had been set)
say (name, message)
  Send a message to a user or channel.

  ### Parameters

  - name: User or channel to send the message to
  - message: Message to send
send (command, ...)
  Send a raw IRC command.

  ### Parameters

  - command: String containing the raw IRC command
  - ...: Arguments to the command. Each argument is either a string or an array. Strings are sent literally, arrays are CTCP quoted as a group. The last argument (if it exists) is preceded by a : (so it may contain spaces).
server_time (cb)
  Request the current time of the server you are connected to.

  ### Parameters

  - cb: Callback to call when the information is available. The single table parameter to this callback will contain the fields:
    - server: the server which responded to the request
    - time: the time reported by the server
server_version (cb)
  Request the version of the IRC server you are currently connected to.

  ### Parameters

  - cb: Callback to call when the information is available. The single table parameter to this callback will contain the fields:
    - server: the server which responded to the request
    - version: the server version
    - comments: other data provided by the server
set_ip (new_ip)
  Set the local IP manually (to allow for NAT workarounds)

  ### Parameters

  - new_ip: IP address to set
whois (cb, nick)
  Request WHOIS information about a given user.

  ### Parameters

  - cb: Callback to call when the information is available. The single table parameter to this callback may contain any or all of the fields:
    - nick: the nick that was passed to this function (this field will always be here)
    - user: the IRC username of the user
    - host: the user's hostname
    - realname: the IRC realname of the user
    - server: the IRC server the user is connected to
    - serverinfo: arbitrary information about the above server
    - awaymsg: set to the user's away message if they are away
    - is_oper: true if the user is an IRCop
    - idle_time: amount of time the user has been idle
    - channels: array containing the channels the user has joined
  - nick: User to request WHOIS information about