Lua Scripting Extension Notes
The SciTE Lua Scripting Extension uses a verbatim copy of Lua 5.0.2 as
its scripting engine. Currently, all of the standard libraries are
included, although this list may be trimmed in a future revision.
Lua is Copyright (C) 2003 TeCGraf, PUC-Rio. The complete Lua license
is included in luaCOPYRIGHT in the SciTE installation directory. To
find more information about Lua, including documentation for the
language itself, visit www.lua.org.
For more ideas about what Lua can do, you may also want to check out
the community portal, lua-users.org.
SciTE Properties and Lua Event / Command Handlers
The properties ext.lua.startup.script and extension.filepattern
can be used to define commands and event handlers that will be called
by the SciTE. Other properties beginning with ext.lua may also
influence how Lua behaves. See the SciTE Documentation
for more details on this.
By defining functions in the startup script or the active extension
script, you can tailor SciTE to your needs, adding new behavior and
functionality that is tightly integrated.
To begin, you can handle any many of the events exposed by the
SciTE Extension Interface. You do
this simply by defining functions with the same name as the event.
Currently, OnOpen, OnSwitchFile, OnSave, OnBeforeSave, OnChar,
OnSavePointReached, OnSavePointLeft, OnDoubleClick, and OnMarginClick
are supported.
For some of these events, SciTE will pass one or more arguments to
the event handler function: OnOpen, OnSwitchFile, OnSave, and
OnBeforeSave will receive the filename of the affected buffer as
their first argument. OnChar can expect a single-character string
argument. The other event handlers will not be passed any arguments.
Event handlers return a boolean value to indicate whether SciTE should
continue processing the event. Return a true value to indicate that
the event has been fully handled, and that no further handlers should
be called. Return a false value to give other extensions a chance to
process the same event. In many but not all cases, a well behaved
event handler will return false. Remember that, in Lua, the only
non-true values are false and nil. Unlike in C++, Python and many
other languages, 0 evaluates to true.
In addition to event handlers, you can also use define new commands
that are available through the Tools menu or through keyboard shortcuts.
To specify that a command that will be handled by Lua, specify
subsystem 3 for the command. Then, to implement the command using Lua,
just define a global function. The command name is the function name.
You can also use predefined functions like dofile and dostring as tool
commands.
Anything specified after the command name is passed to the Lua function
as a single string argument. An example of a command, using the
built-in dofile command, is shown below.
command.name.1.*=Run My Script
command.subsystem.1.*=3
command.1.*=dofile $(SciteDefaultHome)/My Script.lua
Note that the command line is "not" evaluated directly
as a Lua script.
If there is no function matching the command name, no error will be
displayed. This is because Lua assumes in this case that the command
is meant for some other extension, such as the SciTE Director
Extension. However, if the command function is found, but fails
to execute, an error is reported.
-
Predefined Lua Functions and Objects:
Within Lua scripts you can use the following functions / objects:
trace(s) - writes s to the output pane (no prefix, no newlines)
dostring(s) - executes s as a Lua string, like Lua 4's dostring
editor - the editor pane
output - the output pane
props - a pseudo-table representing the SciTE properties
In addition, all constants defined in Scintilla.iface are exposed as
Lua globals variables. Function names are exposed as their block
capital equivalents, with the SCI_ prefix.
All functions and objects defined in the Lua standard library are also
available. Although dostring was deprecated in Lua 5, it is restored
since some have said it would be useful in tool commands.
A function _ALERT() is also defined to be an alias for the built-in
print(), which prints the alert message (plus a newline) to the window.
This provides a reasonable way for Lua to present error messages to
the user. You are free to override _ALERT with a different definition
if you prefer.
The props pseudo-table allows you to read or write properties by name
using normal Lua table-access semantics, e.g. props["property.name"].
The editor and output panes support the following properties and
methods:
textrange(startPos, endPos) - gets the text in the specified range
findtext(text, [flags], [startPos, [endPos]])
- returns the start and end of the first match, or (-1, nil)
- flags can be 0 (the default), or a combination of SCFIND constants
such as SCFIND_WHOLEWORD, SCFIND_MATCHCASE, and SCFIND_REGEXP
match(text, [flags], [startPos])
- returns a generator that allows you to loop over the matches
i.e. for m in editor:match(text, flags) do ... end
- the match object (i.e. the loop counter m in the above
example) supports read-only properties pos, len, and text;
and also supports a function replace(replaceText) to
support search and replace.
- while looping through matches, if the document is modified
by any method other than the loop counter's replace method,
this may cause the match generator to lose its place.
- also, do not attempt to store the match object for later
access outside the loop; it will not be useable.
append(text) - appends text to the end of the document
insert(pos, text) - inserts text at the specified position
remove(startPos, endPos) - removes the text in the range
Most of the functions defined in Scintilla.iface are also be exposed
as pane methods. Those functions having simple parameters (string,
boolean, and numeric types) are fully supported. For example,
editor:InsertText(pos, text) does practically the same thing as
editor:insert(pos, texT). Functions having a stringresult parameter
will include a string in the return value. For both strings and
stringresults, if the function is documented as expecting a length
as its first parameter, you do not pass the length from Lua. Instead,
it is inferred from the context.
The keymod parameter type has partial support. When an iface function
is declared as taking a keymod, the Lua equivalent expects two
numbers: first the key code (e.g. SCK_LEFT or string.byte("'"), and
second the modifiers (e.g. SCMOD_CTRL).
Functions that have more complex parameters are not supported.
Functions that are declared to return a numeric type have the result
added to their return value. If the function also has a stringresult,
that comes first, followed by the numeric return value.
Some functions are declared as 'get' or 'set' rather than 'fun' in
the iface file. These are generally exposed to Lua as properties,
e.g. editor.TabSize = 8. Some of the getters and setters also have
a parameter. Where possible, these are exposed to Lua as indexed
properties, e.g. editor.StyleBold[SCE_PROPS_DEFAULT] = true.
However, if the functions can't be handled as properties, they
are exposed as functions instead.
It is intended that a complete guide to the iface functions and
properties should be added to the documentation, so you don't have
to look at the iface file and do the mental text manipulation.
This is not done yet, but would be a good project for someone.
ScintillaDoc would be a good template to follow. An api file
would also be a good addition.
-
Disabling Lua
Lua is currently loaded just-in-time, before it is first used. The
ways that Lua can become are through the ext.lua.startup.script
property, by naming a lua file named in the extension.filepattern
property, or by using the extension mechanism to define tool commands
(i.e. subsystem 3). If you do not do any of these things, the Lua
scripting engine is not loaded, and for all practical purposes, SciTE
should behave as it did before Lua was added.
Nevertheless, it is still possible to build SciTE without the Lua
support. To do this, simply define the variable NO_LUA when you build
it, e.g. for MSVC, nmake -f scite.mak -DNO_LUA; or with GNU tools,
make NO_LUA=1.