329 lines
16 KiB
HTML
Executable File
329 lines
16 KiB
HTML
Executable File
<?xml version="1.0"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta name="generator" content="SciTE" />
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
|
<title>
|
|
SciTE Lua Scripting Extension
|
|
</title>
|
|
<style type="text/css">
|
|
.example {
|
|
color: #00A000;
|
|
font-weight: bold;
|
|
}
|
|
DIV.example {
|
|
background: #F7FCF7;
|
|
border: 1px solid #C0D7C0;
|
|
margin: 0.3em 3em;
|
|
padding: 0.3em 0.6em;
|
|
font-size: 80%;
|
|
}
|
|
</style>
|
|
</head>
|
|
<body bgcolor="#FFFFFF" text="#000000">
|
|
<table bgcolor="#000000" width="100%" cellspacing="0" cellpadding="0" border="0">
|
|
<tr>
|
|
<td>
|
|
<img src="SciTEIco.png" border="3" height="64" width="64" alt="Scintilla icon" />
|
|
</td>
|
|
<td>
|
|
<a href="index.html" style="color:white;text-decoration:none"><font size="5">
|
|
SciTE Lua Scripting Extension</font></a>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<h3>Lua Scripting Extension Notes</h3>
|
|
The SciTE Lua Scripting Extension uses a copy of Lua 5.1 as
|
|
its scripting engine. Currently, all of the standard libraries are
|
|
included, although this list may be trimmed in a future revision.
|
|
<p>
|
|
Lua is Copyright (C) 1994-2007 Lua.org, PUC-Rio. The complete Lua license
|
|
is included in <tt>luaCOPYRIGHT</tt> in the SciTE installation directory. To
|
|
find more information about Lua, including documentation for the
|
|
language itself, visit <a href="http://www.lua.org">www.lua.org</a>.
|
|
</p><p>
|
|
For more ideas about what Lua can do, you may also want to check out
|
|
the community portal, <a href="http://lua-users.org/">lua-users.org</a>,
|
|
<a href="http://lua-users.org/wiki/UsingLuaWithScite">an introduction to using Lua with SciTE,</a>
|
|
and <a href="http://lua-users.org/wiki/SciteScripts">some example scripts</a>.
|
|
</p>
|
|
<h4>SciTE Properties and Lua Event / Command Handlers</h4>
|
|
<p>
|
|
The properties ext.lua.startup.script and extension.<i>filepattern</i>
|
|
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 <a href="SciTEDoc.html">SciTE Documentation</a>
|
|
for more details on this.
|
|
</p><p>
|
|
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.
|
|
</p><p>
|
|
To begin, you can handle any many of the events exposed by the
|
|
<a href="SciTEExtension.html">SciTE Extension Interface</a>. You do
|
|
this simply by defining functions with the same name as the event.
|
|
Currently, <tt>OnOpen</tt>, <tt>OnClose</tt>, <tt>OnSwitchFile</tt>, <tt>OnSave</tt>,
|
|
<tt>OnBeforeSave</tt>, <tt>OnChar</tt>, <tt>OnKey</tt>,
|
|
<tt>OnSavePointReached</tt>, <tt>OnSavePointLeft</tt>, <tt>OnDwellStart</tt>,
|
|
<tt>OnDoubleClick</tt>, <tt>OnMarginClick</tt>,
|
|
and <tt>OnUserListSelection</tt> are supported.
|
|
</p><p>
|
|
For some of these events, SciTE will pass one or more arguments to
|
|
the event handler function: <tt>OnOpen</tt>, <tt>OnClose</tt>,
|
|
<tt>OnSwitchFile</tt>, <tt>OnSave</tt>, and
|
|
<tt>OnBeforeSave</tt> will receive the filename of the affected buffer as
|
|
their first argument.
|
|
An <tt>OnChar</tt> handler should expect a single-character string argument.
|
|
An <tt>OnKey</tt> handler should expect an integer keycode and boolean
|
|
shift, control, and alt arguments. The keycode is currently a platform specific value
|
|
but this may change in future.
|
|
<tt>OnDwellStart</tt> will receive the position of the mouse and the
|
|
word under the mouse as arguments and the word will be empty when the mouse starts moving.
|
|
<tt>OnUserListSelection</tt> receives two arguments: a number
|
|
indicating the list type, and a string indicating the selected
|
|
item text. The other event handlers will not be passed any arguments.
|
|
</p><p>
|
|
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 <tt>false</tt> and <tt>nil</tt>. Unlike in C++, Python and many
|
|
other languages, 0 evaluates to <tt>true</tt>.
|
|
</p><p>
|
|
There is one additional event handler, <tt>OnClear</tt>, that is not
|
|
expressly defined in the Extension interface, but is exposed to Lua.
|
|
Whenever SciTE re-reads the properties (which occurs every time you
|
|
switch buffers or open a new file, but can also occur at other times),
|
|
the Lua Extension removes any globals that were created since the last
|
|
time properties were read, and restores any globals that were
|
|
overwritten. Then, if the startup script defines a function
|
|
<tt>OnClear</tt>, that function will be called so that scripts have a
|
|
chance to clean up other changes they might have made outside of the
|
|
Lua global scope (e.g. dynamic properties modified through the props
|
|
object; see below) and/or to tailor the Lua environment according to
|
|
local properties for the current buffer.
|
|
</p><p>
|
|
After this, SciTE reads the properties and ultimately loads the
|
|
extension script, if one is defined. However, at the time when the
|
|
<tt>OnClear</tt> event fires, the extension script is not yet loaded.
|
|
Thus, <tt>OnClear</tt> can only be defined in the startup script,
|
|
not in an extension script.
|
|
</p><p>
|
|
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.
|
|
</p><p>
|
|
You can also use predefined functions like <tt>dofile</tt> and <tt>dostring</tt> as tool
|
|
commands.
|
|
</p><p>
|
|
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.
|
|
</p>
|
|
<div class="example">
|
|
command.name.1.*=Run My Script<br />
|
|
command.subsystem.1.*=3<br />
|
|
command.1.*=dofile $(SciteDefaultHome)/My Script.lua<br />
|
|
</div>
|
|
<p>
|
|
Note that the command line is "not" evaluated directly
|
|
as a Lua script.
|
|
</p><p>
|
|
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 <a href="SciTEDirector.html">SciTE Director
|
|
Extension</a>. However, if the command function is found, but fails
|
|
to execute, an error is reported.
|
|
</p>
|
|
<h4>Multiple handlers</h4>
|
|
<p>
|
|
<a href="http://lua-users.org/wiki/SciteExtMan">Scite Ext Man</a> can help in
|
|
more complex applications where you have
|
|
multiple scripts needing to handle an event.
|
|
</p>
|
|
<hr noshade="noshade" width="80%" align="left" />
|
|
<h4>Predefined Lua Functions and Objects:</h4>
|
|
<p>
|
|
Within Lua scripts you can use the following functions / objects:
|
|
</p><pre><tt> 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
|
|
buffer - a table associated with the current buffer or document
|
|
scite - a namespace for functions which control SciTE.
|
|
</tt></pre><p>
|
|
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.
|
|
</p><p>
|
|
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.
|
|
</p><p>
|
|
A function <tt>_ALERT()</tt> is also defined to be an alias for the built-in
|
|
<tt>print()</tt>, 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 <tt>_ALERT</tt> with a different definition
|
|
if you prefer.
|
|
</p><p>
|
|
The props pseudo-table allows you to read or write properties by name
|
|
using normal Lua table-access semantics, e.g. <tt>props["property.name"]</tt>.
|
|
As with Lua tables, you can also un-set a property by assigning nil to its key.
|
|
</p><p>
|
|
When you assign a value to a property from Lua, this overrides any values
|
|
specified in the configuration files for that setting. The underlying file
|
|
properties are not changed. If you later assign nil to the same property
|
|
from Lua, this removes the run-time setting, allowing any file-based
|
|
property setting to show through once again.
|
|
</p><p>
|
|
The editor and output panes support the following properties and
|
|
methods:
|
|
</p><pre><tt> 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 nil if no match
|
|
- flags can be 0 (the default), or a combination of <a href="http://scintilla.sourceforge.net/ScintillaDoc.html#searchFlags">SCFIND constants</a>
|
|
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
|
|
</tt></pre><p>
|
|
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,
|
|
<tt>editor:InsertText(pos, text)</tt> does practically the same thing as
|
|
<tt>editor:insert(pos, text)</tt>. 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.
|
|
</p><p>
|
|
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. <tt>SCK_LEFT</tt> or <tt>string.byte("'")</tt>, and
|
|
second the modifiers (e.g. <tt>SCMOD_CTRL</tt>).
|
|
</p><p>
|
|
Functions that have more complex parameters are not supported.
|
|
</p><p>
|
|
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.
|
|
</p><p>
|
|
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. <tt>editor.TabSize = 8</tt>. Some of the getters and setters also have
|
|
a parameter. Where possible, these are exposed to Lua as indexed
|
|
properties, e.g. <tt>editor.StyleBold[SCE_PROPS_DEFAULT] = true</tt>.
|
|
However, if an iface function is declared as get / set but cannot be
|
|
mapped to a Lua property, it is exposed as a Lua function instead.
|
|
</p><p>
|
|
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.
|
|
<a href="http://scintilla.sourceforge.net/ScintillaDoc.html">ScintillaDoc</a> would be a good template to follow. An api file
|
|
would also be a good addition.
|
|
</p>
|
|
The <tt>scite</tt> namespace includes the following functions:
|
|
</p><pre><tt> scite.Open(filename)
|
|
- opens a file in a new buffer
|
|
- activates the file's buffer if it is already opened.
|
|
|
|
scite.SendEditor(SCI_constant, ...)
|
|
- sends a message to the editor pane
|
|
- equivalent to the corresponding iface function or property
|
|
|
|
scite.SendOutput(SCI_constant, ...)
|
|
- sends a message to the output pane
|
|
|
|
scite.ConstantName(number)
|
|
- returns the symbolic name of a Scintilla / SciTE constant
|
|
|
|
scite.MenuCommand(IDM_constant)
|
|
- equivalent to the corresponding IDM_ command defined in SciTE.h
|
|
</tt></pre><p>
|
|
<tt>Open</tt> requires special care. When the buffer changes in SciTE, the
|
|
Lua global namespace is reset to its initial state, and any extension
|
|
script associated with the new buffer is loaded. Thus, when you call
|
|
Open, this may change the environment in which your current script is
|
|
running. When possible, you can avoid confusion by simply returning
|
|
after scite.Open, but when that is not possible, just bear in mind
|
|
that there are side effects. Local variables, unlike globals, will
|
|
be retained after the buffer change until your script returns.
|
|
</p><p>
|
|
The <tt>SendEditor</tt> and <tt>SendOuput</tt> functions duplicate the
|
|
functionality of the editor and output objects, providing access to these
|
|
through an interface that is more familiar to Scintilla C++ developers.
|
|
This may be useful for prototyping C++ code using Lua. Internally,
|
|
<tt>SendEditor</tt> and <tt>SendOutput</tt> are translated to the
|
|
corresponding iface function or property, so their arguments and
|
|
return types are identical. (Although the calling convention for
|
|
properties is obviously different.)
|
|
</p><p>
|
|
The <tt>ConstantName</tt> function may be useful when generating debug messages,
|
|
or if extending the SciTE LuaExtension to support macro recording.
|
|
</p><p>
|
|
The <tt>MenuCommand</tt> function enables usage of SciTE's menu commands
|
|
as defined in SciTE.h.
|
|
</p>
|
|
|
|
<h4>Lua 5.1</h4>
|
|
<pre>
|
|
Despite some of the big changes in Lua 5.1 dealing with changes
|
|
in the language, most of the compatibility options have been
|
|
turned on.
|
|
Compatibilities:
|
|
- table.getn still works, but the '#' operator should be used
|
|
- Lua 5.0's varargs are still available
|
|
- Lua 5.0's math.mod is still available, as well as 5.1's
|
|
math.fmod
|
|
- Lua 5.0's string.gfind is still available, as well as 5.1's
|
|
string.gmatch
|
|
- [C API] Lua 5.0's luaL_openlib behavior is still available
|
|
Changes:
|
|
- table.setn was deprecated
|
|
- loadlib was moved into the package table (package.loadlib)
|
|
- Lua 5.0's long string nesting throws an error
|
|
</pre>
|
|
|
|
<hr noshade="noshade" width="80%" align="left" />
|
|
|
|
<h4>Disabling Lua</h4>
|
|
<p>
|
|
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.<i>filepattern</i>
|
|
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.
|
|
</p><p>
|
|
Nevertheless, it is still possible to build SciTE without the Lua
|
|
support. To do this, simply define the variable <tt>NO_LUA</tt> when you build
|
|
it, e.g. for MSVC, <tt>nmake -f scite.mak -DNO_LUA</tt>; or with GNU tools,
|
|
<tt>make NO_LUA=1</tt>.
|
|
</p>
|
|
</body>
|
|
</html>
|