K-Meleon Lua extension tutorial

Reading

Where to start

By default, the plugin only reads one file: macros.lua.

require "copyaslink"
require "google"
require "multiclip"

function Eval()
        local a, b
        a = prompt("lua", "k-meleon", "")
        if a then
                b = loadstring(a)
                if b then
                        alert(b(), "lua", ICON_INFO)
                end
        end
end

require

The require statements indicate that other .lua (or .lc) files are to be included as well.

.lc is the extension for precompiled Lua files, which you don't need to worry about.

function

The plugin allows K-Meleon to run Lua functions. The above Eval function can be called from K-Meleon accel/macro/menu/toolbar as luamacros(Eval).

local

local declares new local variables. You can see that there are no type declaration. That's because, in Lua, a variable can hold any value.

prompt

prompt is a Lua plugin function which “show[s] a modal 'prompt' dialog that returns a string value”. For this kind of functions, you should refer to the api.txt file included with the Lua plugin package.

loadstring

loadstring is a Lua core function which takes a string and compiles it. The resulting value can be accessed as a function (which is why the expression b() makes sense). Refer to lua-users' CoreFunctionsTutorial wikipage for explanations on all Lua core functions.

How do we determine which library/module a function comes from?

The Lua plugin includes the core, string, and table modules from Lua. (It seems that debug, io, math, and os are disabled.) It also includes its own K-Meleon- and Windows-related functions, specified in api.txt.

There is no easy way to know where a function is declared other than by trial and error, helped by a bit of guesswork (e.g. string.gsub most probably comes from string).

alert

alert is another Lua plugin function, so check api.txt to see what it does and its parameters.

Writing

Comments

-- Single-line Lua comment

--[[ Multiline
Lua
comment ]]

Conditionals

if «condition» then
        «statements»
elseif «condition» then  -- optional, can be repeated
        «statements»
else                     -- optional
        «statements»
end

Loops

Most K-Meleon macros don't need looping. See lua-users' ControlStructureTutorial wikipage when you need to use it.

Event handlers

The Lua plugin exposes several K-Meleon events through special functions, for example OnOpenWindow, OnCloseWindow, and so on (for the full list, see hook.lua).

A common mistake is to define these functions in your own code. The problem with that is, those functions will either override or be overridden by other extensions which also define them.

The Lua extensions plugin comes with a hook.lua file that should be used when you want to handle K-Meleon events.

require "hook"

if hook then
        hook.add(OpenWindowHook, function()
                -- Do something here.
        end)
end

Useful references

Lua

Lua tutorials - easiest to understand, but incomplete.
Lua short reference - for quick reference after you've mastered the basics of the language.
Lua 5.1 reference manual - the definitive guide, which is surprisingly rather easy to understand. (Lua 5.1 is the version used in version 0.2.2 of the plugin.)

Lua extension plugin

readme.eng - contains explanations on how to use the plugin. There is some extremely important information there not covered in this tutorial, so please read it.
api.txt - contains explanations on all functions supported by the plugin in addition to the Lua library functions.

This work is licenced under the Creative Commons Attribution-ShareAlike 2.5 License. To view a copy of this licence, visit http://creativecommons.org/licenses/by-sa/2.5/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.

The AsciiDoc source of this document is available by request.