dxirc Lua Scripting Reference
since version 0.60.0

Contents

1. Introduction
2. Available Functions
   1. Obligatory Functions
   2. Optional Functions
3. Complex Example
4. Available Scripts
5. Copyright and Licence

1  Introduction

Since version 0.40.0, dxirc supports scripting using Lua programming language. This document tries to provide thorough description of the available functions.

Note that in order to support Lua scripts, dxirc has to be built with Lua scripting enabled — you can check this in the About dialog.

With this update, the tab ids are now fixed and no longer correspond to the order in which they are presented to a user.

2  Available Functions

2.1  Obligatory Functions

dxirc_Register()

It has to return exactly three values: the script name, its version and short description. When this function is missing, the script will not be loaded.

Example:

function dxirc_Register()
  local name = "test"
  local version = "0.1"
  local description = "Testing script"

  return name, version, description
end

dxirc_Init()

The function to be called when the script is loaded.

Example:

function dxirc_Init()
  dxirc.AddCommand("test", "OnTest", "testing command")
end

2.2  Optional Functions

dxirc.AddCommand(name, funcname, helptext)

Binds specified function to selected command. It accepts following arguments:

• name — command name,
• funcname — name of the function to be called when the command is invoked,
• helptext — command description for the help.

The function funcname is then invoked as funcname(text, id), where:

• text — command argument, i.e. "first second" when invoked as /test first second,
• id — id of tab from which the command was invoked.

Example:

dxirc.AddCommand("test", "OnTest", "testing command")

dxirc.AddEvent(name, funcname)

Binds specified function to selected event. It accepts following arguments:

• name — name of the event to be caught; currently supported events are:
  • "privmsg" - incoming messages.
  • "join" - someone joins into channel.
  • "part" - someone leaves channel.
  • "ownmsg" - user input (unless it is a command).
  • "newtab" - new tab created.
  • "quit" - dxirc quit.
  • "all" - every command.
  • "raw" - raw incomming line.
• funcname — name of the function to be called when the event is caught.

For PRIVMSG event, the funcname is then invoked as funcname(from, text, id), where:

• from — nickname of the message author,
• text — message text,
• id — id of the tab from which the message was received.

For JOIN event, the funcname is then invoked as funcname(nick, id), where:

• nick — nickname of the joined person,
• id — id of the tab from which the event was received.

For PART event, the funcname is then invoked as funcname(nick, id), where:

• nick — nickname of the left person,
• id — id of the tab from which the event was received.

For OWNMSG event, the funcname is then invoked as funcname(text, id), where:

• text — entered text,
• id — id of tab from which the message was entered.

For NEWTAB event, the funcname is then invoked as funcname(tab), where the resulting tab table contains following keywords:

• "id" — id of tab,
• "name" — tab name,
• "type" — tab type, i.e. server, channel, query, dccchat or other,
• "servername" — server name,
• "port" — port number,
• "nick" — user's nick name on the corresponding server.

For QUIT event, the funcname is then invoked as funcname().

For ALL event, the funcname is then invoked as funcname(command, text, id), where:

• command — command name, i.e. "test" when invoked as /test first second, nil when invoked as Hello, World!
• text — command argument, i.e. "first second" when invoked as /test first second, "Hello, World!" when invoked as Hello, World!
• id — id of tab from which the command was invoked.

For RAW event, the funcname is then invoked as funcname(text, server), where:

• text — raw incomming line.
• server — table contains following keywords:
• "servername" — server name,
• "port" — port number,
• "nick" — user's nick name on the corresponding server.

Example:

dxirc.AddEvent("JOIN", "SayHello")

dxirc.RemoveName(name)

Removes command or event binding previously added using dxirc.AddCommand() or dxirc.AddEvent(). It accepts following argument:

• name — command/event name.

Example:

dxirc.RemoveName("test")
dxirc.RemoveName("join")

dxirc.Command(command, [id])

Runs selected command as if it was invoked manually. It accepts following arguments:

• command — command to be executed,
• id — optional tab id; unless specified or equal -1, the command is executed in the current tab.

Example:

dxirc.Command("/join #test", 0)
dxirc.Command("Lua scripting rocks!")

dxirc.Print(text, [id], [style])

Prints text to the dxirc window. It accepts following arguments:

• text — text to be displayed.
• id — optional tab id; unless specified or equal -1, the message is printed to the current tab window.
• style — optional style number; unless specified, the message is formatted as ordinary text. Available styles are as follows:
  • 1 — user message,
  • 2 — action message,
  • 3 — notice,
  • 4 — error,
  • 5 — bold text,
  • 6 — underlined text,
  • 7 — bold and underlined text,
  • 8 — highlighted message.

You can also use following sequence in text for styled text in dxirc:

• \002 - bold text
• \031 - underline text
• \003#......[,#......] - colors
• \003xx,xx - colors. Where xx is number 0~15 (mirc color)
• \022 - reverse text
• \015 - reset style

Example:

dxirc.Print("\003#ffffff,#ff0000Color with backround\002 bold \031underline+bold\015 reset")

prints: Color with backround bold underline+bold reset

Example:

dxirc.Print("The script is running and ready.", 0, 4)

dxirc.GetServers()

Returns the list of currently connected servers. The resulting table contains tables with following items:

• "server" — server name,
• "port" — port number,
• "nick" — user's nick name.

If there is no connected server, the values are nil.

Example:

local servers = dxirc.GetServers()

dxirc.GetTab(name, server)

Returns the id of the tab that matches selected name and server. It accepts following arguments:

• name — channel/query name,
• server — server name or its id.

If no matching tab can be found, the function returns the id of the current tab instead. When there are no tabs at all, it returns -1.

Example:

local tab_id = dxirc.GetTab("#test", "irc.freenode.net")

dxirc.GetChannelNames(name, server)

Returns the list of names on the channel. It accepts following arguments:

• name — channel name,
• server — server name or its id.

If no matching tab can be found, the function returns nil.

Example:

local names = dxirc.GetChannelNames("#test", "irc.freenode.net")
if names ~= nil then 
  for i = 1,# names do
    print(names[i])
  end
end

dxirc.GetCurrentTab()

Returns the id of the current tab.

Example:

local tab_id = dxirc.GetCurrentTab()

dxirc.GetVersion()

Returns the version of dxirc.

Example:

local version = dxirc.GetVersion()

dxirc.GetTabInfo(id)

Returns information about the tab with selected id. The resulting table contains following keywords:

• "name" — tab name,
• "type" — tab type, i.e. server, channel, query, dccchat or other,
• "servername" — server name,
• "port" — port number,
• "nick" — user's nick name on the corresponding server.

If there is no tab with specified id, the values are nil.

Example:

local tab_info = dxirc.GetTabInfo(1)
local channel = dxirc.GetTabInfo(id)["name"]

dxirc.GetTabCount()

Returns the number of the tabs.

Example:

local tab_number = dxirc.GetTabCount()

dxirc.SetTab(id)

Changes focus to the selected tab. It accepts following argument:

• id — desired tab id.

Example:

dxirc.SetTab(0)

dxirc.CreateTab(name)

Creates the new tab with type other. It accepts following argument:

• name — name for the new tab.

Example:

dxirc.CreateTab("test")

dxirc.Clear(id)

Clears chat on the selected tab. It accepts following argument:

• id — desired tab id.

Example:

dxirc.Clear(0)

3  Complex Example

-- test.lua, a dxirc Lua scripting sandbox
-- Copyright (C) 2009 David Vachulka

function dxirc_Register()
  return "test", "0.1", "testing script"
end

function dxirc_Init()
  dxirc.AddCommand("foo", "OnFoo", "yet another testing command")
  dxirc.AddEvent("privmsg", "OnPrivmsg")
  dxirc.AddEvent("join", "OnJoin")
  dxirc.AddAll("OnAll")
end

function OnFoo(text, id)
  dxirc.Print("text:"..text, id, math.random(0, 8))
  dxirc.RemoveName(text)
end

function OnPrivmsg(from, text, id)
  dxirc.Print(from.." says: "..text.." on "..dxirc.GetTabInfo(id)["name"])
end

function OnJoin(nick, id)
  dxirc.Print(nick.." has joined on "..dxirc.GetTabInfo(id)["name"])
end

function OnAll(command, text, id)
  if command == nil then
    dxirc.Print("text: "..text)
    dxirc.Command(text, id)
  else
    dxirc.Print("command: "..command..", text: "..text)
    dxirc.Command("/"..command.." "..text, id)
  end
end

4  Available Scripts

5  Copyright and Licence

Copyright © 2009, 2010 David Vachulka
Translation © 2010 Jaromír Hradílek

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

For more information, see <http://www.gnu.org/licenses/fdl.html>.