Free Tools for GIS Developers
Navigation:
  What's New
 
GIS Tools:
  AVPython
  NTXShape
  SHPTRANS
 
Other Tools:
  SciTE
  Tomcat
 
About:
  The Author
  These Pages

SciTE Lua Scripting Extension

I have been working to revive the SciTE Lua Scripting Extension, and also to implement the multiplexer that was conceived in the documentation for the SciTE Extension Interface so that FilerX support would not be broken when Lua support was added. This is currently working on Win32, and may also be working on Linux, although I haven't done any testing on Linux myself.


Lua Scripting Extension Notes


This build of SciTE includes an updated revision of the Lua Scripting
extension.  Although the scripting extension is becoming quite robust,
it is not yet considered release-ready.

If you do not use Lua in your property files, and do not use the
extension mechanism to define tool commands (i.e. subsystem 3), then
the Lua scripting engine is not loaded.  If you do use the Lua Scripting
extension, keep in mind that you are then using functionality that has
not been subject to the same level of testing and scrutiny as the rest 
of Scintilla and SciTE; and that the APIs are likely to change at any
time.

So that the Lua extended build of SciTE can be distinguished easily from
Neil Hodgson's official build, it is given a distinct version label
in the Help/About SciTE window.

-

The SciTE Lua Extension uses a verbatim copy of Lua 5.0 as its scripting
engine.  Currently, all of the standard libraries are included, although
this list may be trimmed in a future revision.  When compiling with GCC,
the normal Lua make files are used to generate libraries that are linked
with SciTE.  When using other compilers (which the Lua makefiles do not
support directly), the Lua source code is compiled and linked directly
into SciTE.

Lua is Copyright (C) 2003 TeCGraf, PUC-Rio.  The complete Lua license is
included in license.txt in the SciTE installation directory.  To find more
information about Lua, including documentation for the language itself,
visit http://www.lua.org.

-

SciTE Properties that influence Lua:

To begin experimenting with Lua scripting, you can uncomment the line
"ext.lua.startup.script=$(SciteDefaultHome)\SciTEStartup.lua" near the
bottom of SciTEGlobal.properties.  The default SciTEStartup.lua file, 
found in the SciTE installation folder, contains a sample script that
displays messages in the output pane as you switch buffers or open new
files.

You can also use the SciTE "extension.<filepattern>" property to
define an "extension script".  Unlike the startup script, a different
extension script may be defined for each file type.  The extension
script is re-read whenever you switch buffers, even if the file type
is the same for the two buffers.  Refer to the SciTE documentation for
more information on the extension property.

By default, the startup script is "not" re-executed when you change
buffers.  Instead, the global state is restored using a lazier method.
However, this default behavior can be overridden by setting the property
"ext.lua.reset=1".  Then the Lua global scope will be completely reset,
and the startup script will be re-executed whenever you switch buffers.
Although this is inefficient, you probably won't notice the difference
on modern hardware.  One case where the reset property may be useful is
when you are updating and testing the startup script itself.

You can handle any user event exposed by the SciTE Extension interface
by defining the functions onOpen, onSwitchFile, onSave, onChar, 
onSavePointReached, onSavePointLeft, onStyle, onDoubleClick, onUpdateUI,
and/or onMarginClick.

You can use Lua to define new commands that are available through the
Tools menu.  Lua commands use subsystem 3 (see the SciTE documentation
for more details on command subsystems).  To define a 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.  Note that the command line
is "not" evaluated directly as a Lua script.  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

-

Predefined Lua Functions and Objects:

Within Lua scripts you can use the following functions / objects:
  alert(s) - writes the string to the output pane with "<" prefix.
  dostring(s) - executes s as a Lua string, like Lua 4's dostring.
  editor - the editor pane
  output - the output pane
  trace(s) - writes the string s to the output pane
  property(s) - gets the value of the property named s
  RGB(r,g,b) - packs an RGB value for use in style colors

In addition, all constants defined in Scintilla.iface are exposed as Lua
globals.  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 alert().  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 editor and output panes support the following properties / methods:
  insert(pos, text) - inserts text at the specified position
  remove(startPos, endPos) - removes the text in the range
  range(startPos, endPos) - gets the text in the specified range
  selection() - returns the start and end of the selection range
  search(text, [flags], [startPos, [endPos]]) 
    - returns the start and end of the first match, or -1 if no match

The send method, although still present in the source code, is no longer
recommended and will soon be removed.

Most of the functions defined in Scintilla.iface are also be exposed as
pane methods.  Those functions having simple parameters (strings and
numeric types) are fully supported, e.g. editor:SetTabWidth(8).  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.

Functions that have more complex parameters are not yet supported.  The 
keymod parameter type has partial support.  For a keymod parameter, you 
would pass a string in the same notation used in SciTEGlobal.properties
for key sequences, e.g. "Ctrl+Shift+F5".  This is not tested and, as it
turns out, may be of very limited usefulness.

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.

-

Other SciTE-specific Object Types:

When you implement a handler for the onStyle event, one of the arguments
is a special Accessor object supporting the following properties / methods:
  startat(pos, chMask)
  startsegment(startPos)
  colourto(endPos, chAttr)

I have not worked much with styling objects, so I leave it for someone else
to submit documentation for these methods, and for onStyle in general.
However, the methods are just proxies for the ones defined on the Accessor
abstract class, and are implemented in DocumentAccessor.





Source and Binary Snapshots

I have published a zip file containing the modified source files here. This is a work in progress; it changes frequently, but at present it appears to be quite robust on most computers.

The source archive does not contain complete copies of all the files that have changed; that was getting unwieldly. Instead it contains a patch file, along with instructions for how to apply the changes to your repository. If you haven't used patch before, don't worry: it's very easy, and safer than overwriting complete files. Still, I recommend you apply the patch to a copy of your source tree, not to the original; this is discussed in the how-to guide included in the archive.

For those who do not have a C++ compiler, a binary snapshot of Sc1 is published here. This is updated on the same schedule as the source code snapshots.

Although these files have no datestamp in their names, you can find the date of the last change in the file LuaChangeLog.txt in the sc1 snapshot, or near the top of the patch in the source code snapshot. LuaChangeLog is also published here as a separate file.
|