TshwaneLua: TshwaneLex/TshwaneTerm Scripting

TshwaneLex 3.0 brings built-in programmability to TshwaneLex and TshwaneTerm via integration of the Lua scripting language.

• Getting Started with TshwaneLua Scripting
• Sample Scripts
• Frequently Asked Questions

Getting Started with TshwaneLua Scripting

TshwaneLex and TshwaneTerm have a built-in programming (scripting) language. We have chosen to embed the OpenSource Lua scripting language. There are primarily two types of scripts:

1. Lua Script Attributes: A Lua script attribute is just another attribute in the document, but is special in that instead of ordinary data, it contains a piece of Lua script that is executed in order to generate the resulting output for that attribute value, very similar in principle to a 'formula' in spreadsheet applications.
2. Stand-alone Scripts: Stand-alone (or external) scripts exist in the form of a text file, and are loaded and executed via the "Tools / Execute Lua Script" menu option in TshwaneLex or TshwaneTerm.

Other types of scripts include "click scripts" and "search scripts". The main script types will be dealt with here.

1. Lua Scripting Attributes

A good place to start learning about Lua script attributes is to have a look at the "Lua Scripting Attribute" sample file in the Samples folder. To view the sample's script attribute contents, go to "Dictionary/Customise DTD", select the "Sense" element on the left, then select the "SenseNumLua" attribute under "Attributes of this element", click in the "Default/fixed value" box at the bottom right of the DTD editor, and press F12 to open the script in the overlay editor window. This sample demonstrates the use of a fixed Lua attribute value to generate automatic sense numbering in a manner currently not supported by the automatic numbering styles: Specifically, repeating the sense number of the parent at every subsense (e.g. "2a ... 2b ..."). The return value of the script is the value that is output in the Preview etc. (with the usual styles and so on applied, just as with any other attribute).

Note that for a Lua script attribute you can choose if the attribute value should be "fixed" or not. If "fixed" (as in the sample), the script is entered once - in the DTD editor - and the same script is always executed. If not fixed, a different script can be entered for the attribute on an individual entry/element basis.

To create a Lua DTD attribute, create an attribute as usual in the DTD editor, then select "Lua script" as the "Data type".

Note the use of the gCurrentNode global. This value always contains the node (i.e. element in the document tree) that the attribute on which the script is currently being executed belongs to. (Related to this is also a gCurrentEntry global, pointing to the owner entry.)

Note how all local variables are explicitly declared as such - in Lua, variables are global unless otherwise specified.

2. Stand-alone Scripts

Stand-alone (or external) scripts are basically text files containing Lua code. They can be executed via the "Tools / Execute Lua Script" menu option in TshwaneLex or TshwaneTerm. By default they use a ".lua" file extension but this is not necessary. Such a script can be used to perform pretty much any kind of manipulation on the database.

Note that the file encoding for Lua scripts is always UTF8 (without UTF8 marker).

General Lua Tips

TshwaneLua Reference: The TshwaneLua API (Application Programming Interface) reference can be viewed via "Start menu / Programs / TshwaneLex / TshwaneLua Scripting API". Good starting points are the "Detailed Description" sections of tcNode and tcDocument.

Note that we implement Lua 5.0. For general Lua information (e.g. syntax or standard Lua function reference), it is suggested that you make use of the Lua reference manual [PDF].

Keep in mind the use of F12 to open the overlay editor window when editing scripts - this is virtually indispensable.

In our API, indexes are always zero-based unless otherwise specified. Strings are always UTF8.

Sample Scripts

Tip: Always hit 'File/Create a backup' before running/testing any script that could make extensive or negative changes to your document.

Template script: This script calls a function on all lemmas/entries in the database.

-- TshwaneLex/TshwaneTerm sample script
--
-- Call a function on all entries in the currently selected language/section
-- window that pass the currently applied filter.

function YourFunc(ENTRY)
	tLuaLog(ENTRY:GetLemmaSign());
end

-- Make sure we have a document open
local DOC = tApp():GetCurrentDoc();
if DOC == nil then
	return "No document open";
end

-- Iterate through all 'sections'/languages, and for each section, through all entries.
local i, j;
for i=0,DOC:GetDictionary():GetNumLanguages()-1,1 do
	local SECTION = DOC:GetDictionary():GetLanguage(i);
	for j=0,SECTION:GetNumEntries()-1,1 do
		local ENTRY = SECTION:GetEntry(j);
		YourFunc(ENTRY);
	end
end

return "";

Template script: This script calls a function in the currently selected language/section window on all entries that pass the currently applied filter.

-- TshwaneLex sample script
--
-- Call a function on all entries in the currently selected language window that
-- pass the currently applied filter.

function YourFunc(ENTRY)
	tLuaLog(ENTRY:GetLemmaSign());
end

-- Make sure we have a document open
local DOC = tApp():GetCurrentDoc();
if DOC == nil then
	return "No document open";
end

-- Get selected section/language window
local FRAME = tFrameWindow();
local SECTION = FRAME:GetSelectedSectionWindow();
local LANG = SECTION:GetLanguage();
-- Get filter tool
local FILTER = SECTION:GetFilter();
local i;
for i=0,LANG:GetNumEntries()-1,1 do
	local ENTRY = LANG:GetEntry(i);
	local include = true;
	if FILTER:IsFiltered() then
		include = FILTER:PassFilter(ENTRY);
	end

	if include then	
		YourFunc(ENTRY);
	end
end

return "";

If you have created scripts that you feel may be useful to others and you'd like them uploaded here, you are welcome to send them to us!

TshwaneLua FAQ

Q: How to typecast an object?

If you have (for example) a variable of type tcNode called NODE which (NB) you know is of type tcReference, you can typecast it using tolua.cast as follows:

local Reference = tolua.cast(NODE, "tcReference");

Q: I get a "C stack overflow" message

Try declaring variables and/or functions "local" (i.e. with local keyword in front).