SciTE-tools Manual

Written by Mitchell Foral. (mitchell{att}caladbolg.net)

Introduction

These modules serve to extend SciTE's default capabilities with very powerful text-editing utilities and modes. As their names suggest, modules can be loaded on demand, and you can load whichever ones you want; it doesn't have to be all of them.

Requirements

Some Lua scripts (in particular scripts/scite/snippets.lua) utilize the Ruby programming language. If it is not installed on your system, you can get it from http://ruby-lang.org.

Installation

The modules can be placed in any directory you specify, as long as your Lua startup script adds that directory to the package.path Lua variable so you can require them.

Using SciTE-tools

You cannot mix SciTE-st's Lua scripts with SciTE-tool's scripts.

Remember that the LuaDoc is a valuable resource for all Lua aspects of SciTE-tools. Not only does it contain SciTE-tool's Lua API, it also contains textual documentation for the more complicated parts of the scripts. This manual is only aimed to answer the most frequent questions. Most everything else is covered in the LuaDoc. Anything that is not is most probably covered in the SciTE documentation.

Also, a decent knowledge of Lua is assumed.

Loading a module on demand is as simple as a Lua require statement. A description of the statement is available here.

All modules are stored in the global modules table after they are required. Each directory is the name of a specific module located in that table (e.g. modules.scite refers to the Lua scripts in the scite/ directory). A simple Lua startup script might look like this:

PLATFORM = 'linux' -- or 'windows'
if PLATFORM == 'linux' then
  LUA_PATH = props['SciteDefaultHome']..'/scripts/?.lua'
elseif PLATFORM == 'windows' then
  LUA_PATH = props['SciteDefaultHome']..'\\scripts\\?.lua'
end
package.path  = package.path..';'..LUA_PATH

require 'scite/scite' -- load scite module

There are a few things to note about this example:

There is a global PLATFORM variable. It is used for most modules to set platform-specific options, but only needs to be set globally once, because its value is inherited in other modules.
The ? gets replaced by the argument to require.
You might see some redundancy in the fact that scite/scite is being loaded. The first scite is the directory, and the second is the module loader script that happens to have the same name as the directory for clarity. If it really bugs you, you could move each module loader a directory level up.

You can load modules on a per-language basis as well via an extension script. As an example,

extension.*.lua=$(SciteDefaultHome)/scripts/lua/lua.lua

loads the Lua module (located in the lua/ directory) when editing a Lua file. Taking a look at the lua.lua script, you'll see that commands.lua is loaded on init. This means all Lua-specific commands are accessible via the modules.lua.commands table. This same idea applies to all modules.

For more information on how to setup startup and extension scripts, please see the SciTE documentation.

Module commands can be invoked in one of two ways: via the SciTE Tools menu, or by key command. If you'd like to use the Tools menu, add a command like you would normally in SciTE, but prepend dostring before the function call. e.g.

command.1.*=dostring modules.scite.snippets.insert()

If you would like to use a key command, scite/key_commands.lua would be an optimal place to put it. There are good examples in that file to give you an idea of how to declare one. For more information about key commands, please see the LuaDoc.

Notes

If key commands are not working expected, check scripts/scite/key_commands.lua and make sure the ALTERNATIVE_KEYS flag is set to false. I occasionally forget to reset the flag when I commit.

Credits

The snippets used in the Ruby module are from James Edward Gray II's Textmate bundle.

Links

Screenshots