scripting.pod

Gtkabber - scripting

Lua

Scripting in gtkabber is done in Lua (http://www.lua.org/). Lua is pretty clean and it's easy to use even if you don't really know it; you will see in the Examples section.

Of course you can spend sime time learning it, it will not be wasted and will give you more opportunities. Take look at Programming in Lua to learn your way around.

Callbacks

Callback are lua functions you write to react on certain Gtkabber events. Just write a function with a proper name and you're ready.

message_cb (from, to, msg)

called when the message passes, there or another way. 'from' and 'to' keep the sender's and receiver's jid (with a resource), msg keeps the message body

message_markup (who, what)

this function lets you modify what gets printed in the chat tab on the incoming (or outcoming) message instead of the default <nick>: <msg>. Returning nil leaves the default markup unchanged. See some nice and friendly examples in the examples section.

presence_cb (jid, status, status_msg)

called on the presence arrival. Again, 'jid' contains the full jabber id (with resource), status is the current buddy's status type (online, free for chat, away, not available, do not disturb or offline), status_msg keeps the status message (e.g. "Gone fishing")

post_connect ()

called after a successful connection. You can set initial status in here, send some greeting messages or something

Gtkabber API

Callback won't be as fun and useful if we had no gtkabber specific functions to call. All the functions are prefixed with 'gtkabber.' to avoid possible conflicts

gtkabber.print (txt)

print txt in a gtkabber's status tab

gtkabber.sendmsg (to, body)

send a message to somebody

gtkabber.sendstatus (to, type, msg)

send a status to a buddy or a server (provide nil as a 'to' parameter to set the status globally). Only the first character of the 'type' parameter is checked, so you don't really have to type much (though you can). Examples:

* online - online

* ffc - free for chat

* away - away

* xa - not availble/extended away

* dnd - do not disturb

* anything else - offline

If msg is not provided, the message will be taken from the status message box in the gui.

More coming soon :)

User-defined actions

User can define his own actions which can be easily called from gtkabber's user interface. To use this feature, create (in your config file) an array called 'actions' containing... ah, let me show you an example:

actions = {
                { name = "_Test", action = function () os.execute("xcowsay 'This is a test!' &") end },
                { name = "Go _away", action = gtkabber.sendstatus(nil, "away") }
}

The following will result in creating two buttons in your options bar, each with a mnemonic (the character prefixed with an underscore), launching a specified action when clicked.

Examples

See also 'actions' array example in "User-defined actions" section.

-- automagically respond to 'ping'
function message_cb (jid, msg) 
        if string.find(msg, "ping") then
                gtkabber.sendmsg(jid, "pong")
                gtkabber.print("Automagically responded to ".. jid .."'s 'ping'\n")
        end
end

-- keep an eye on your Juliet
        function presence_cb (jid, status, status_msg)
                if string.find(jid, "juliet@example.com") then
                os.execute("xcowsay 'Juliet is coming!' &")
        end
end

-- keep naggers away
function post_connect (jid, msg)
        gtkabber.sendstatus("foobar@example.com", "dnd")
end

-- modify the message printing format
function message_markup (who, what)
        -- this one changes the outcoming messages only (if your xmpp username is johndoe)
        ret = nil
        if (who == "johndoe") then
                ret = "<u>I said</u>: " .. what "\n"
        end
end