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:

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

Example:

dxirc.AddCommand("test", "OnTest", "testing command")
dxirc.AddEvent(name, funcname)

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

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

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

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

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

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

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

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

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

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:

Example:

dxirc.RemoveName("test")
dxirc.RemoveName("join")
dxirc.Command(command, [id])

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

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:

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:

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:

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:

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:

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:

Example:

dxirc.SetTab(0)
dxirc.CreateTab(name)

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

Example:

dxirc.CreateTab("test")
dxirc.Clear(id)

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

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

Script Description
amarok Control the Amarok directly from dxirc and/or send the currently playing track to the channel/query.
banshee Control the Banshee music player directly from dxirc and/or send the currently playing track to the channel/query. Make sure the Banshee is already running before using this script.
clementine Control the Clementine music player directly from dxirc and/or send the currently playing track to the channel/query. Make sure the Clementine is already running before using this script.
exaile Control the Exaile music player directly from dxirc and/or send the currently playing track to the channel/query. Make sure the Exaile is already running before using this script.
mpc Control the Music Player Daemon directly from dxirc and/or send the currently playing track to the channel/query. Note that mpc has to be installed in order to run this script.
rhythmbox Control the Rhythmbox directly from dxirc and/or send the currently playing track to the channel/query.

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>.