A Quick SciTE Tour

• Editing With SciTE
  • Configuring SciTE
  • Opening And Browsing Files
  • Selecting Text
  • Abbreviations and Completing Text
• Running Programs
• Using Lua Interactively
• Debugging Programs

SciTE is a general-purpose programmer's editor that also allows you to debug Lua scripts. It is very extendable using its own built-in Lua interpreter, in fact the debugger support is almost entirely done in Lua. With SciTE as you can do step by step debugging of Lua source, set breakpoints, watch variables, trace the stack, inspect variables and more.

Editing With SciTE

The SciTE window consists of the following parts:

• caption bar ('title')
• menu
• toolbar (can hide this with View|Tool Bar)
• tabbar (with a tab for each open file, or 'buffer')
• edit window
• output pane (will open automatically if any output or errors are generated)
• status bar (usually shows line and column number)

The edit window has three margins:

• line numbers (usually invisible, use View|Line Numbers to show)
• marker margin (shows markers, breakpoints, etc. Can click here to select a line)
• fold margin (clicking on a fold margin will 'collapse' the folded block)

Simple editing with SciTE with easy because it uses standard Windows editing conventions. In particular, if you have used Visual Studio you will find many of the shortcuts familiar. However, it is a good exercise to know what an editor can do for you, and learn a few shortcuts, because with a little work you can save a lot of time when performing your editing tasks. The only way to learn is to experiment, and always remember that Edit|Undo (Ctrl+Z) is your friend - no mistake is permanent.

Configuring SciTE

title.full.path=0

if then

end

for k,v in pairs( ) do

end

Another general feature is autocompletion. This examines your document and provides a set of suggested complete words. Unlike the similar feature in OpenOffice, it will present you with a drop-down list of possible candidates. This can be a godsend if you find yourself writing long variable names like SearchCompletedList repeatedly. (If you prefer, you can switch off automatic word completion by setting autocompleteword.automatic to 0 (see setting options), and then you can use Edit|Complete Word (Ctrl+Enter) to get a list of suggested words.)

For working with Lua code specifically, there is also Edit|Complete Symbol (Ctrl+I). This uses the supplied Lua api file to complete the library function. For example, if I type 'st' in a Lua file, then Ctrl+I will supply a drop-down list of all Lua library functions that begin with 'st', such as 'string.byte','string.char', etc. Furthermore, if you then choose one of these functions, then as soon as you enter '(' SciTE will provide a calltip with the parameters and a helpful one-line summary. This will also happen whenever you have typed one of these library functions in directly.

Running Programs

Tools|Go (F5) will run the current script. (This operation is also available from the toolbar as the green arrow) If the script needs command-line parameters, up to four parameters can be specified with View|Parameters. If you have a runaway program stuck in a loop then Tools|Stop Executing (Ctrl+Break) will kill it; the icon next to the Run icon will be enabled and can also be used.

Any output or errors will appear in the Output pane; If the execution of a script fails, then the error line is automatically shown. This can also be achieved by clicking on a error message. (Or by using Tools|Next Message (F4), which is useful if there are many compile errors. This also works for the results of Search|Find in Files)

The Output pane also supports the usual selection and clipboard operations; these are also available through the right-click context menu. To open or close the Output pane, use F8.

Using Lua Interactively

The little prompt icon will put you into a Lua interactive prompt. This prompt is different from the usual Lua prompt because tables will be printed out nicely. Plus, it is now easy to copy stuff to the clipboard.

> = 5*2
10
> t = {1,2,3}
> = t
{1,2,3}

This Lua prompt will automatically stay in the same directory as the current file, which is very useful for testing small bits of code. For instance, save this as 'sqr.lua':

function sqr(x)
  return x*x
end

You can now move to the output pane (just click it with the mouse, or Ctrl-F6 if you prefer using the keyboard), load the file using dofile "sqr.lua" and type sqr(10)

> dofile 'sqr.lua'
> sqr(10)
100
> sqr('10')
100
> sqr('bonzo')
stdin:1: attempt to perform arithmetic on local 'x' (a string value)
...

You now understand the limitations of your simple function; it cannot square things which cannot be converted into numbers. (The icon next to the Lua prompt icon has the same effect as typing dofile directly.

Another feature which can be very useful is that three commands are available (cd, dir and edit) which work like DOS commands. For example:

> dir *.lua
controller.lua
remdebug
remdebug.lua
> cd
C:\Program Files\SciTE\scite-debug\remDebug
> cd remdebug
> dir
engine.lua
> edit engine.lua

Where edit will open the file in SciTE.

Generally, interactive Lua is the best place to learn about the available libraries and to test out things like string patterns, etc. The idea is that writing longer programs is easier once you have tested tricky bits interactively.

To leave the Lua prompt, just type quit.

Debugging Programs

Debugging involves running your program in a controlled environment where you can stop at specified lines called breakpoints, and then move a line at a time, called stepping. Single-stepping goes to the next line that will be executed, and will enter functions, whereas 'stepping over' will step over any function calls and stop at the line after the call. Here is an example script ('script1.lua'); note that the line numbers are not part of the program! (script1.lua is available in the scite-debug\tests directory)

01 function two(x)
02   print(x)
03 end
04 function one(y)
05   print(y)
06   two('go')
07   print('there')
08 end
09
10 one('dolly')

When you start the debugger, it will stop at the first executable line. You can now single-step your way to the code of interest, but it's easier to set a breakpoint using F9 and then use Debug|Run again to continue. The stopped line is shown with a green background, and the text on the status bar changes to 'active'. Set a breakpoint for line 10 and continue.

Single-stepping will then lead you to line 5; stepping again will put you on line 6. If you now single-step again, you will enter the function two at line 2; if you had stepped over, you would have directly proceeded to line 7.

When stopped, you can inspect any value in two different ways; by letting the mouse hover over a variable (called 'tooltip evaluation') or explicitly using Debug|Inspect or the toolbar inspect icon. In this case the value will be written out to the Output pane. For example, when stopped at line 2, hovering the mouse over 'x' will give the tooltip "x = 'go'". Hovering over 'y' in line 4 will give no value, because y is a local variable which is only meaningful when you are in function one.

When you are stopped at line 2, you can print out the call stack Debug|Backtrace, ctrl+alt+B:

[1] two in script1.lua:2 ***
[2] one in script1.lua:6
[3] main in script1.lua:10
[4] C in [C]:-1

Moving 'up' (alt+U) means going back to the point where two() was called; moving up again gets you to where one() was called at line 10. Simularly, you can now move down. The call stack gets deeper, which is why moving down gets you back to the current position. You can always move to a particular stack frame by double-clicking on one of the lines in the stack trace. When you have moved to a particular stack frame, the context changes so that the local variables at that point become available again. But note that in this case the execution point is still at line 2, so if you single-step again you will go back to the 'bottom' of the stack and move onto line 3.

If your program crashes at any point, the line changes to red and a stack trace is automatically printed. Note that the program is not dead! You can inspect any values you like, move up and down the stacktrace, etc. To finish the program, either kill it with Debug|Kill (alt+K) or just by contining Debug|Run, alt+R. (The red icon at the end of the toolbar achieves the same result.)

It is often useful to watch how a variable changes, which is set with Debug|Watch. Each time you stop at a line, watch expressions will be printed out in the Output Pane.

All these operations are available on the toolbar, but there are keyboard shortcuts as well:

F9     set breakpoint at current line
alt+R  start debugging; if stopped at a line, continue execution.
alt+C  single step to the next line
alt+N  step over functions ('next line')
alt+G  run until cursor ('go to')
alt+I  inspect expression at cursor
alt+W  add expression to watches
alt+U  go up to the function that called this function
alt+D  go down to the function that was called from here
ctrl+alt+B backtrace

Once your Lua script is fully debugged, you can run it from the command line by typing in the name of the script at the command line or double clicking on the Lua script file from Windows Explorer.