irc/doc/API.txt

IRC Mod API
-----------
This file documents the API exported by the IRC mod.


BASICS
------
In order to allow your mod to interface with this mod, you must add `irc'
 (without the quotes) to your mod's `depends.txt' file.


REFERENCE
---------

mt_irc.say ( [name ,] message )
  Sends <message> to either the channel (if <name> is nil or not specified),
   or to the given user (if <name> is specified).
  Example:
    mt_irc.say("Hello, Channel!")
    mt_irc.say("john1234", "How are you?")

mt_irc.register_bot_command ( name, cmddef )
  Registers a new bot command named <name>.
  When an user sends a private message to the bot starting with `!name', the
   command's function is called.
  Here's the command definition (<cmddef>):
    cmddef = {
      params = "<param1> ...",      -- A short help text for !help
      description = "My command",   -- What does the command? (one-liner)
      func = function ( from, param )
        -- This function gets called when the command is invoked.
        -- <from> is the name of the user that invoked the command.
        -- <param> is the rest of the input (after removing !command)
      end,
    };
  Example:
    mt_irc.register_bot_command("hello", {
      params = nil, -- No params
      description = "Greet user",
      func = function ( from, param )
        mt_irc.say(from, "Hello!")
      end,
    });

mt_irc.connected_players [ name ]
  This table holds the players who are currently on the channel (may be less
   than the players in the game). It is modified by the /part and /join chat
   commands.
  Example:
    if (mt_irc.connected_players["joe"]) then
      -- Joe is talking on IRC
    end

mt_irc.register_callback ( name, func )
  Registers a function to be called when an event happens. <name> is the name
   of the event, and <func> is the function to be called. See CALLBACKS below
   for more information
  Example:
    mt_irc.register_callback("channel_msg", function ( from, msg )
      if (from == "joe") then
        mt_irc.say("joe", "You are not allowed to do that!")
        return true
      end
    end)

This mod also supplies some utility functions:

string.expandvars ( string, vars )
  Expands all occurrences of the pattern "$(varname)" with the value of
   `varname' in the <vars> table. Variable names not found on the table
   are left verbatim in the string.
  Example:
    local tpl = "$(foo) $(bar) $(baz)"
    local s = tpl:expandvars({ foo=1, bar="Hello" })
    -- `s' now contains "1 Hello $(baz)" 

In addition, all the configuration options decribed in `README.txt' are
 available to other mods, though they should be considered "read only". Do
 not modify these settings at runtime or you will most likely crash the
 server!


CALLBACKS
---------
The `mt_irc.register_callback' function can register functions to be called
 when some events happen. These are the events supported:

msg_out ( from, message )
  Called right before the bot sends a message to the channel.
  <from> is the name of the user sending the message. <message> is the
   unmodified message sent by the user.
  Return values:
    "string"    New message to be sent.
    false       Filter out the message (do not send anything).
    nil         Use original message
    other       Use a string repr of the value as message.
  Example:
    mt_irc.register_callback("msg_out", function ( from, msg )
      if (from == "joe") then
        mt_irc.say("joe", "You are not allowed to do that!")
        return false
      end
    end)

msg_in ( from, to, message )
  Called right before the bot sends a private message to an user.
  <from> is the name of the user sending the message. <to> is the recipient
   of the message. <message> is the unmodified message sent by the user.
  Return values:
    "string"    New message to be sent.
    false       Filter out the message (do not send anything).
    nil         Use original message
    other       Use a string repr of the value as message.
  Example:
    mt_irc.register_callback("msg_in", function ( from, to, msg )
      if (to == "admin") then
        mt_irc.say(from, "You are not allowed to do that!")
        return true
      end
    end)

nick_change ( old_nick, new_nick )
  Called when an user in IRC changes nickname.
  <old_nick> and <new_nick> are self-explanatory.
  Return value:
    none
  Example:
    mt_irc.register_callback("nick_change", function ( old_nick, new_nick )
      mt_irc.say(from, "Hello "..new_nick.."! You were "..old_nick.."?")
    end)

part ( nick, part_msg )
  Called when an user leaves the IRC channel.
  <nick> is the user leaving; <part_msg> is the "parting message".
  Return value:
    none
  Example:
    mt_irc.register_callback("part", function ( nick, part_msg )
      mt_irc.say(from, nick.." has left the building!")
    end)