300 lines
13 KiB
Plaintext
Executable File
300 lines
13 KiB
Plaintext
Executable File
# A Quick SciTE Tour
|
|
|
|
|
|
|
|
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
|
|
|
|
<a name="options"/>
|
|
|
|
SciTE is a very configurable editor. To set global options,
|
|
open the options file using `Options|Open Global Options File`.
|
|
If you prefer not to have the full file path in the caption bar, then you
|
|
would edit `title.full.path` to be 0 (zero) like so, and save this file.
|
|
|
|
title.full.path=0
|
|
|
|
Simularly, if you would prefer not to see line numbers by default, then set
|
|
`line.margin.visible` to 0. View the SciTE Help file with `Help|SciTE Help` to see
|
|
a full list of available _properties_. Some changes will only be visible after restarting SciTE.
|
|
|
|
### Opening And Browsing Files
|
|
|
|
There will be a 'Edit with SciTE' on the right-mouse context menu when
|
|
selecting a Lua file. Once SciTE is launched, you can also drag and drop
|
|
files onto SciTE to open them. By default, `File|Open` will open files in the
|
|
same directory as the current file.
|
|
|
|
Once files are open, you can move to them by either clicking on the
|
|
appropriate tab, or going to the Buffers menu. Alt+1, Alt+2, etc will let you
|
|
go directly to the file in that particular tab. Ctrl+Tab will switch between the
|
|
two recently used buffers. F12 will provide a drop-down list
|
|
of open files in recently-used order; you can move in this list with the up
|
|
and down keys.
|
|
|
|
It is useful to set bookmarks in longer scripts, so you can revisit them
|
|
again. A bookmark can be set or unset with `Search|Toggle Bookmark (Ctrl-F2)`
|
|
and `Search|Next bookmark (F2)` will move to the next bookmark.
|
|
`Search|Go to... (Ctrl+G)` will take you to a specific line.
|
|
(To see line numbers, use `View|Line Numbers`)
|
|
|
|
`File|Open Selected Filename (Ctrl+Shift+O)` will try to open a filename at the cursor.
|
|
For instance, if the line was `require "date"` and the cursor was on 'date', it will open
|
|
`date.lua`, either in the current directory, or on the Lua path.
|
|
|
|
A very useful operation is `Search|Find in Files (Ctrl+Shift+F)` which will search for a word
|
|
or phrase in the current directory and any subdirectories. The results will appear in
|
|
the Output Pane; double-clicking on a result will take you to that place in the file. (You can
|
|
use F4 to quickly go through all occurances.)
|
|
|
|
A good way to get an overview of a whole file is `View|Toggle All Folds`.
|
|
|
|
### Selecting Text
|
|
|
|
It is always possible to select text using the mouse, and to select a line
|
|
just click in the left-most margin. Dragging the mouse in the left-most margin will
|
|
select a range of lines. The usual meaning of double-clicking is to select a word,
|
|
but this SciTE version generalizes this action to select a whole string or comment.
|
|
|
|
If you have defined a bookmark, then you can select all the text following it up to the cursor.
|
|
This is useful if you want to move a section of a file; place the bookmark at
|
|
the top of the section, go to the end of the section, and then select with `Alt+F2`.
|
|
|
|
A useful shortcut is `Edit|Block Select (Ctrl+Shift+A)` which intelligently selects the current block; if you position the cursor on the first line of a function, it will select all of that function.
|
|
There is a complementary 'smart paste' operation `Edit|Smart Paste (Ctrl+Shift+V)` which
|
|
inserts the contents of the clipboard and tries to adjust the block to the current indentation, leaving the block selected in case the paste was not as smart as it thought! Once a block is
|
|
selected, it can be indented with `Tab` and un-indented with `Ctrl+Tab`.
|
|
|
|
### Abbreviations and Completing Text
|
|
|
|
Writing code involves a lot of repetitive typing, and SciTE can help you code faster. This version
|
|
comes with a set of predefined abbreviations to make Lua programming easier; for instance, if you type 'if' and press `Ctrl+B` (`Edit|Expand Abbreviation`) then SciTE will insert this:
|
|
|
|
if then
|
|
|
|
end
|
|
|
|
and the cursor will be positioned just after 'if', ready for you to type the condition. Likewise, 'for' `Ctrl+B` will give you:
|
|
|
|
for k,v in pairs( ) do
|
|
|
|
end
|
|
|
|
with the cursor placed in the brackets after 'pairs'. Please note that abbreviations are
|
|
inserted properly, respecting your indentation. If you find yourself typing some patterns out
|
|
repeatedly, then consider adding a custom abbreviation. To do this you can edit
|
|
`abbrev.properties` (in the same directory as `SciTE.exe`.)
|
|
|
|
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](#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.
|
|
|