.\" t
.ds ST \\fB@PACKAGE_NAME@\\fP
.
.
.TH "@PACKAGE@" 7 \
    "@DATE@" \
    "@PACKAGE_NAME@ Version @PACKAGE_VERSION@"
.
.
.SCITECO_TOPIC language
.SH NAME
@PACKAGE@ \-\-
Language reference for the \*(ST text editor and language
.
.
.SH INTRODUCTION AND PHILOSOPHY
.SCITECO_TOPIC philosophy
.
\*(ST is a powerful editor and interactive programming language
following an unique paradigm of text editing.
It is both different from popular screen editors like \fIex\fP and
traditional command-based editors like \fIed\fP.
Both of these paradigms can be understood as language-based.
Screen editors use simple languages based on commands that closely
correspond with key presses (keyboard commands) while command-based
editors use more complex, often turing-complete languages.
Screen editors interpret their language immediately while command-based
editors do so only after complete input of an expression.
Some editors like \fIVi\fP or \fIemacs\fP support both screen-editing
and command-lines in different modes of operation.
While such editors represent a compromise between both paradigms
(they support both paradigms to some extent), \*(ST represents a
.BR synthesis .
In \*(ST the screen-editing and command languages are the same!
The \*(ST language can be interpreted interactively and commands
can be as simple as single key presses or as complex as nested
high-level structured programming constructs.
While screen-editors often support an undo-stack to undo simple
operations, \*(ST supports undoing and redoing on a per-character,
per-command or even user-configurable level undoing most of the
side-effects on the overall editor state.
.LP
.SCITECO_TOPIC TECO
\*(ST is a member of the TECO family of text editor languages,
invented by Dan Murphy in the 1960s.
TECO was initially a purely command-driven editor that evolved
screen editing features later on, culminating in the invention of
Emacs as a TECO customization (macro package) in the 1970s.
Emacs later became an independent program that eventually
dropped TECO as its scripting language in favour of Lisp.
\*(ST is not the first attempt to devise a TECO-based interactive
screen editor.
.SCITECO_TOPIC "Video TECO"
It is very similar to \fIVideo TECO\fP, a little known editor
that pioneered the concept.
When \fIVideo TECO\fP wanted to \(lqoutdo classic TECOs in every way\(rq,
\*(ST wants to outdo \fIVideo TECO\fP in every way.
.LP
When using \*(ST in interactive mode, it is important to know exactly
how \*(ST translates and processes user input.
Generally speaking, the user inputs TECO code that is parsed and executed
on the fly by a stream parser/executor.
Deleting characters from the end of the input stream is called
rub out and has the effect of reversing the side-effects of
the rubbed out characters.
Rubbed out characters are kept and displayed to the user
who has the possibility of re-inserting rubbed out characters
into the input stream.
The input stream is called command line macro.
Since \*(ST's undo capabilities requires memory and other
resources, command lines may be terminated, reclaiming all
resources and emptying the command line macro.
The language of the command-line macro is basically the same
as the language used in batch processing, with the exception
of some commands that depend on the command line macro or
undo-capabilities that are disabled in batch mode.
To add to or remove from the command line macro, \*(ST supports
a number of special keys called immediate editing commands.
The key-processing for immediate editing commands is described in the
next two sections.
While immediate editing commands can be understood as yet another \(em
albeit limited \(em language for screen editing, \*(ST also supports
regular commands for command-line editing.
.
.
.SH KEY TRANSLATION
.
When the user presses a key or key-combination it is first translated
to an UTF-8 string.
The rules for translating keys are as follows:
.RS
.IP 1. 4
Keys with a printable representation (letters, digits and special
characters) are translated to their printable representation
according to the current keyboard layout and modifier keys.
On the Gtk UI, \*(ST tries to automatically take ANSI letter
values in situations where the parser accepts only ANSI
characters.
On Curses, you might need key macros to achieve the same.
.IP 2.
.SCITECO_TOPIC ctrl
Control-combinations (e.g. CTRL+A) are translated to control
codes, that is a code smaller than 32.
The control code can be calculated by stripping the seventh bit
from the upper-case letter's ASCII code.
So for instance, the upper or lower case A (65) will be translated
to code 1, B (66) to code 2, ecetera.
\*(ST will always use latin letters regardless of the current
keyboard layout.
\*(ST echos control codes as Caret followed by the corresponding
upper case letter, so you seldomly need to know a control codes
actual numeric code.
For instance, control code 2 \(em typed CTRL+B \(em will be echoed
\(lq^B\(rq.
\*(ST also treats Caret-letter combinations equivalent to
control codes under most circumstances.
.IP 3.
A few keys with non-printable representation are translated to
control codes as well.
The most prominent is the Escape key \(em it is translated to
code 27.
The backspace key will always be translated to code 8, and the Tab key
to code 9.
The return/enter key is always translated to code 10 (line feed).
Naturally, all of these control codes can also be typed using a
Control-key combination (e.g. CTRL+I for the tab character) and
there is often an equivalent typed with the caret character
(e.g. \(lq^I\(rq).
.IP 4.
A selection of other keys without printable representation (called
function keys) are looked up as key macros, allowing user-definable character
sequences to be inserted, including immediate editing commands.
If there is no matching key macro, nothing is inserted.
The key macro feature is explained in the next subsection.
.IP 5.
All keys with printable representations are also looked up
as key macros, allowing them to be remapped just like function keys.
Otherwise the corresponding UTF-8 strings are inserted into the command stream.
.IP 6.
The result of key macro lookups or the default printable representations
are processed as immediate editing commands in a context-sensitive manner
(see section
.BR "COMMANDLINE EDITING" ).
By default they are inserted into the command line macro and are
immediately executed.
.RE
.
.LP
While \*(ST handles keys with arbitrary Unicode representations,
all immediate editing commands and regular \*(ST commands operate on
a language based solely on
.B ASCII
codes, which is a subset of Unicode.
\# This is because we cannot assume the presence of any particular non-ANSI
\# symbol on a user's keyboard.
\# Immediate editing commands do not operate directly on function keys
\# because we didn't want to introduce an UI-independent representation
\# of function keys - it would also complicate insertion of immediate
\# editing commands from key macros.
Since the \*(ST parser is Unicode-aware, this does not exclude
using Unicode glyphs wherever a single character is expected,
i.e. \fB^^\fIx\fR and \fBU\fIq\fR works with arbitrary Unicode glyphs.
All \*(ST macros must be in valid UTF-8.
.
.SS Key Macros
.
.SCITECO_TOPIC "key macro" ^K
By default function keys except Escape, Backspace and Return are
ignored by \*(ST.
With certain interfaces (curses) the Escape key might only be handled
after a short delay.
This is because it might be used by the terminal to transmit
Escape Sequences.
This delay is minimized by \*(ST, so using the escape key
should not be a problem even on ncurses/UNIX.
If the default delay is too small, it can be tweaked with the
.B ESCDELAY
environment variable and if necessary a key macro can be
defined as an escape surrogate as described in this section
.RB ( fnkeys.tes
defines the delete key as an escape surrogate for instance).
.LP
To make use of function keys or to remap all other keys,
special Q-Register strings can be defined that are inserted into the command stream
before immediate editing command handling.
The following list of key macro registers are supported:
.
.TP 9
.SCITECO_TOPIC ^KDOWN
.B ^KDOWN
.TQ
.SCITECO_TOPIC ^KUP
.B ^KUP
Inserted when the down/up cursor keys are pressed.
.TP
.SCITECO_TOPIC ^KLEFT
.B ^KLEFT
.TQ
.SCITECO_TOPIC ^KSLEFT
.B ^KSLEFT
Inserted when the left or shift-left cursor keys are
pressed.
.TP
.SCITECO_TOPIC ^KRIGHT
.B ^KRIGHT
.TQ
.SCITECO_TOPIC ^KSRIGHT
.B ^KSRIGHT
Inserted when the right or shift-right cursor keys are
pressed.
.TP
.SCITECO_TOPIC ^KHOME
.B ^KHOME
.TQ
.SCITECO_TOPIC ^KSHOME
.B ^KSHOME
Inserted when the Home or shift-Home keys are pressed.
.TP
.SCITECO_TOPIC ^KF
.BI ^KF x
Inserted when the F\fIx\fP-key is pressed
.RI ( x
is a number between 0 and 63).
.TP
.SCITECO_TOPIC ^KDC
.B ^KDC
.TQ
.SCITECO_TOPIC ^KSDC
.B ^KSDC
Inserted when the Delete or shift-Delete key is pressed.
.TP
.SCITECO_TOPIC ^KIC
.B ^KIC
.TQ
.SCITECO_TOPIC ^KSIC
.B ^KSIC
Inserted when the Insert or shift-Insert key is pressed.
.TP
.SCITECO_TOPIC ^KPPAGE
.B ^KPPAGE
.TQ
.SCITECO_TOPIC ^KNPAGE
.B ^KNPAGE
Inserted when the Page-Up or Page-Down key is pressed.
.TP
.SCITECO_TOPIC ^KPRINT
.B ^KPRINT
.TQ
.SCITECO_TOPIC ^KSPRINT
.B ^KSPRINT
Inserted when the Print or shift-Print key is pressed.
.TP
.SCITECO_TOPIC ^KA1
.B ^KA1
.TQ
.SCITECO_TOPIC ^KA3
.B ^KA3
.TQ
.SCITECO_TOPIC ^KB2
.B ^KB2
.TQ
.SCITECO_TOPIC ^KC1
.B ^KC1
.TQ
.SCITECO_TOPIC ^KC3
.B ^KC3
Inserted when the numeric key pad's upper left key (7),
upper right key (9), central key (5), lower left key (1),
or lower right key (3) is pressed and num-lock is disabled.
The key-pad's cursor keys are handled like the regular
cursor keys.
.TP
.SCITECO_TOPIC ^KEND
.B ^KEND
.TQ
.SCITECO_TOPIC ^KSEND
.B ^KSEND
Inserted when the End or shift-End key is pressed.
.TP
.SCITECO_TOPIC ^KHELP
.B ^KHELP
.TQ
.SCITECO_TOPIC ^KSHELP
.B ^KSHELP
Inserted when the Help or shift-Help key is pressed.
.TQ
.SCITECO_TOPIC ^KCLOSE
.B ^KCLOSE
Inserted when the Close key has been pressed.
More importantly, this key is emulated in some GUIs
(notably GTK+) when the user tries to close \*(ST's
window or when the \fBSIGTERM\fP signal is received.
This allows customizing \*(ST's behaviour when
program termination is requested (e.g. only quit if
there are no unsaved buffers).
The close key is also special because
it has a default action if the \(lq^KCLOSE\(rq macro is undefined:
It unconditionally quits \*(ST.
The default action is \fBnot\fP performed when
\(lq^KCLOSE\(rq has merely been masked out in the
current parser state (see below).
.TP
.SCITECO_TOPIC ^KMOUSE
.B ^KMOUSE
Mouse event occurred.
This will not be delivered on Curses unless bit 7 (64) is set in the
\fBED\fP flags.
You can use \fBEJ\fP with negative keys to retrieve
the event type, mouse coordinates and other information
about the last mouse event.
.TP
.BI ^K x
Any other key with printable representation and all control codes
are looked up with a \(lq^K\(rq prefix.
\fIx\fP can usually only be a single Unicode glyph.
\# Although the result of IMEs is looked up in Gtk, which I suppose
\# can be multiple codepoints.
If undefined, \fIx\fP is inserted unmodified.
\# NOTE: Since all function key macros are longer than 2
\# characters, there shouldn't be any namespace collisions.
.
.LP
\(lq^K\(rq corresponds to CTRL+K (ASCII code 11) in the above list but
might be typed with a caret due to string building characters
in long Q-Register names.
The names are all derived from key definitions of the curses
library \(em not all of them may be supported on any particular
user interface.
.LP
The result of key macro expansion differs from
consecutive key presses in that they are considered an unity.
If insertion of a single character fails (raises an error),
the entire macro expansion is automatically rubbed out.
.LP
By default key macros are effective everywhere \(em
pressing a key has the same effect as processing
the characters of the corresponding key macro as
immediate editing commands (or self-inserting characters).
However key macros that rewrite the current command line
will only work correctly from specific \*(ST parser states.
Another common use of key macros would be to define
aliases of \*(ST commands for non-latin keys on Curses.
\*(ST therefore allows you to mask key macros in
specific parser states by evaluating the Q-Register's numeric
part, thus allowing you to control \fIwhere\fP a key
macro is effective.
The numeric part represents a bitmask of states where
keys macros are \fIdisabled\fP (so the default value 0
enables that key macro everywhere).
\*(ST defines the following state flags:
.IP 1 4
Bit 0 represents the \(lqstart\(rq state where \*(ST accepts the
beginning of a command.
This is the state you will want command line editing macros
to be enabled in.
.IP 2
Bit 1 represents any string argument.
.IP 4
Bit 2 represents any case insensitive syntactic character.
This is the state you might want to use for translating
non-latin characters to their latin equivalent.
.LP
All other bits/flags represent any other parser state.
Consequently, setting the register to the inverse of a bitmask of
state flags enables the corresponding macro only for the specified
states.
For instance, to enable the \(lq^KRIGHT\(rq key macro
only in the \(lqstart\(rq state, you could set:
.SCITECO_TT
.EX
1^_U[^KRIGHT]
.SCITECO_TT_END
.EE
.LP
A set of useful key macros for function keys is provided in the
standard library
.BR fnkeys.tes .
It demonstrates how key macros may be used to define
alternate Escape keys (so the delay issue is not experienced),
or do insertion and command-line editing using function keys.
.
.
.SH COMMANDLINE EDITING
.
After all key presses have been translated to characters \*(ST
interpretes some of them in a special way to perform command line
editing and a few other actions that cannot depend on regular
command execution.
These special characters are called Immediate Editing Commands
and are outlined in the following subsection.
All characters not handled as immediate editing commands
are self-inserting, i.e. they insert themself into the command
stream and may be processed as regular commands or part of them.
.
.SS Immediate Editing Commands
.SCITECO_TOPIC immediate
.
In the following table, the Immediate Editing Commands are outlined.
Some of them are ubiquitous and are not used used as regular
commands (because it would be hard to type them).
Some however are context-sensitive and are only available in or depend
on the current language context (at the end of the command line) that
is always known to \*(ST.
Because of this superior parsing and command line editing, editing
is much less dangerous and much more interactive than in classic
TECO implementations.
Most of these commands are control codes, so their control code
mnemonics are given as well.
.
.\" FIXME: The auto-completion immediate editing commands
.\" should probably be broken out of this table to keep it
.\" small and moved into their own table in the AUTO COMPLETIONS
.\" section.
.SCITECO_TT 90n
.TS
expand,allbox,tab(;);
LBW0 LBW0 LBW0 LBW0 LB
L L L L L.
Name;Code;Mnemonics;Context;Description
T{
.SCITECO_TOPIC ^G toggle
Toggle modifier
T};7;^G;T{
Everywhere
T};T{
Toggle the immediate editing command modifier and display
its new state.
If enabled, the rubout commands will perform analoguous
re-insertions of previously rubbed out characters.
Therefore \fB^G\fP (CTRL+G)
effectively switches between undo and redo modes.
The modifier also influences the behaviour of the TAB key.
T}
T{
Case insensitive command character
T};\(em;Any letter;T{
Beginning of case-insensitive commands
.br
(automatic case folding enabled)
T};T{
At the beginning of case-insensitive commands,
the case of letters is inverted.
One or two letter commands will thus typically
be inserted in upper case.
This only happens if bit 3 of the \fBED\fP flags
is set, e.g. by executing:
.EX
0,8ED
.EE
T}
T{
.SCITECO_TOPIC ^J enter LF CR
Insert end of line sequence
T};10;^J, Return, Enter;T{
Everywhere
.br
(no automatic EOL translation)
T};T{
If automatic end of line sequence translation is disabled,
the return key will insert the current buffer's end of line
sequence (line feed; carriage return, line feed; or
carriage return) according to the
.SCITECO_TOPIC SCI_GETEOLMODE
.B SCI_GETEOLMODE
Scintilla message.
In auto-EOL-translation mode, the return key will always
insert a line feed.
T}
T{
.SCITECO_TOPIC ^H backspace
Rub out character
T};8;^H, Backspace;T{
Everywhere
.br
(modifier \fIdisabled\fP)
T};T{
Rubs out the command line's last character.
T}
T{
Re-insert character
T};8;^H, Backspace;T{
Everywhere
.br
(modifier \fIenabled\fP)
T};T{
Inserts the next character from the rubbed out part
of the command line.
T}
T{
.SCITECO_TOPIC ^W
Rub out word/command
T};23;^W;T{
Non-empty file name arguments
.br
(modifier \fIdisabled\fP)
T};T{
Rub out directory separator at end of filename and the
last filename component up to but not inluding
the preceding directory separator.
T}
\^;\^;\^;T{
Non-empty string arguments
.br
(modifier \fIdisabled\fP)
T};T{
Rub out to beginning of last word according to Scintilla's definition of a word
as set by
.SCITECO_TOPIC SCI_SETWORDCHARS
.BR SCI_SETWORDCHARS ,
analogous to \fBY\fP command.
T}
\^;\^;\^;T{
Miscelleaneous
.br
(modifier \fIdisabled\fP)
T};T{
Rub out last command, i.e. rub out at least one character until
a new command could begin.
T}
T{
Re-insert word/command
T};23;^W;T{
File name arguments
.br
(modifier \fIenabled\fP)
T};T{
Re-insert next file name component up to and including the next
directory separator from the rubbed-out command line.
T}
\^;\^;\^;T{
String arguments
.br
(modifier \fIenabled\fP)
T};T{
Re-insert next word from the rubbed-out command line according to
Scintilla's definition of a word as set by
.BR SCI_SETWORDCHARS .
T}
\^;\^;\^;T{
Miscelleaneous
.br
(modifier \fIenabled\fP)
T};T{
Re-insert next command from the rubbed-out command line,
i.e. insert at least one character and repeat until
a new command could begin.
T}
T{
.SCITECO_TOPIC ^U
Rub out string
T};21;^U;T{
String arguments
.br
(modifier \fIdisabled\fP)
T};T{
Rub out the entire current string argument.
T}
T{
Re-insert string
T};21;^U;T{
String arguments
.br
(modifier \fIenabled\fP)
T};T{
Re-insert the entire current string argument from previously
rubbed-out part of the command line, stopping at the string's
terminating character.
T}
T{
Auto complete Q-Register name
T};9;^I, Tab;T{
Q-Register specifications
T};T{
In all Q-Register specifications \(em either after a command
with a Q-Register argument like \fBM\fP or as part of a string building
construct like \fB^EQ\fP (of course including string building
constructs \fIwithin\fP Q-Register specifications) \(em
auto complete the local or global register name beginning at
the start of the specification.
In the case of one or two-letter specifications (\fB#\fIxy\fR),
only one or two-letter register names are considered for
auto-completion.
In the case of long specifications (\fB[\fIname\fB]\fR),
fully completed names are terminated with a closing bracket,
thus ending the specification.
T}
T{
Auto complete filename
T};9;^I, Tab;T{
String arguments
.br
(modifier \fIenabled\fP)
T};T{
Auto complete filename beginning after the last space (or beginning
of the string argument).
Fully completed filenames are terminated with a space.
This autocompletion works in every string argument (as long as
the \fB^G\fP modifier is enabled.
T}
\^;\^;\^;T{
Operating system command arguments
T};\^
\^;\^;\^;T{
File name arguments
T};T{
Auto complete filename beginning at the start of the argument.
Fully completed filenames terminate the string argument,
except if the \(lq{\(rq terminator is used.
T}
T{
Auto complete directory
T};9;^I, Tab;T{
Directory arguments
T};T{
Auto complete directory beginning at the start of the argument.
T}
T{
Auto complete symbol
T};9;^I, Tab;T{
Scintilla symbol arguments
T};T{
In Scintilla Symbol arguments
.RB ( ES
commands), complete beginning with the symbol, terminating fully
completed symbols with a comma.
T}
T{
Auto complete Goto label
T};9;^I, Tab;T{
Goto command arguments
T};T{
In Goto label arguments (\fBO\fP command),
complete beginning with the current label, terminating fully
completed labels with a comma.
T}
T{
Auto complete help topic
T};9;^I, Tab;T{
Help topic arguments
T};T{
In help topic arguments (\fB?\fP command),
complete beginning at the start of the command.
Fully completed topics terminate the string argument,
effectively opening the corresponding \fIwomanpage\fP,
except if the \(lq{\(rq terminator is used.
T}
T{
Indent to next tab stop
T};9;^I, Tab;T{
Text insertion arguments
T};T{
Expands to spaces so that following text is inserted
at the next tab stop into the buffer.
This takes Scintilla's indention policy into account
and results in the same indention as the \fB^I\fP command.
T}
T{
.SCITECO_TOPIC ^Z suspend
Suspend process
T};26;^Z;T{
Everywhere
T};T{
Suspends process using
.SCITECO_TOPIC SIGTSTP
.BR SIGTSTP .
This is only an immediate editing command on platforms supporting
this signal (usually Unices).
The process can be suspended from another process as well, for
instance by pressing CTRL+Z in the console \(em this will also work
if \*(ST is busy.
Therefore with GUI user interfaces (GTK+), this command will only
work as an immediate editing command in the GUI or as a signal
dispatched from an associated console or from another process.
T}
T{
.SCITECO_TOPIC interrupt
Interrupt
T};3;^C;T{
\*(ST is busy
T};T{
.B "Not a real immediate editing command."
Will interrupt the current operation (character processing),
yielding a \*(ST error.
On some GUIs it depends on asynchronous delivery of the
.B SIGINT
signal and is useful to interrupt infinite loops.
Since not all user interfaces support interruptions via
\fB^C\fP, it may be necessary to deliver the signal by
pressing \fB^C\fP on the attached console or by explicitly
sending it.
If \*(ST is not busy,
.B ^C
is self-inserting and might be typed as part of regular commands.
The \fB^C\fP command itself is disallowed in interactive mode, though.
T}
.TE
.SCITECO_TT_END SP
.
.SS Undo and Redo
.
The immediate editing commands that rub out and re-insert characters
effectively constitute \*(ST's undo and redo support.
As all features implemented by the immediate editing commands,
undo and redo is only possible when using \*(ST interactively.
.LP
.SCITECO_TOPIC rubout undo
When a character is rubbed out, \*(ST reverses the side effects it
had when it was typed.
The rubbed out characters are not discarded immediately but kept
in a rubbed out part of the command line.
The user interface displays this area as characters at or after the
command line cursor and tries to highlight them (e.g. by underlining
and greying them out).
Therefore, since characters that resulted in errors (not accepted
into the command line macro) are automatically rubbed out,
they can still be seen in the command line's rubbed out area.
The rubbed out command line is not a part of the command-line macro,
though.
.LP
.SCITECO_TOPIC rubin redo
Changes can be redone by typing the characters at the command line
cursor or using one of the re-insertion commands \(em therefore
undo and redo looks like moving the command line cursor back and forth.
The re-insertion commands are the same as the rubout commands
but need the immediate editing modifier to be enabled.
The \fB^G\fP (CTRL+G) command toggles this modifier and thus has the
primary effect of switching between undo and redo modes.
The rubbed out command-line is discarded by \*(ST once you type
or insert a character that is not a prefix of the rubbed out
command line.
This will also automatically disable the \fB^G\fP modifier.
The \fB^G\fP modifier is \fIdisabled\fP by default, so the
corresponding commands work similar to their Unix shell counterparts.
.LP
Since \*(ST's undo stack requires an increasing amount of memory
and other resources proportional to the length of the command line,
it is occasionally useful to reclaim these resources, especially after
operations that consumed a lot of memory.
In some cases, commands like tight loops might even make the system
swap until \*(ST hits its configurable memory limit.
It is therefore possible to terminate command lines using the
\fB$$\fP (double escape) command \(em or in other words by returning from the
command line macro.
Since this is a regular command respecting \*(ST's syntax, it is
much less likely to accidentally terminate a command line than
in classic TECOs where \fB$$\fP is a special immediate editing key
sequence.
Command line termination will reclaim all undo-related resources without
undoing any side effects, thus \(lqpersisting\(rq or \(lqcommitting\(rq
them.
Since undoing those side effects (of the last command line) will
no longer be possible, command line termination will also reset
the command line macro.
Global and local Q-Registers are not affected by command line termination.
.
.SS Auto Completion
.
.SCITECO_TOPIC autocomplete
The immediate editing commands, that perform auto-completions, do
so in a manner similar to Posix shells.
Upon first invocation they try to fully or partially complete the file
name (or token).
If the token can be fully completed, the current command or Q-Register
specification will also usually be terminated automatically.
If no completion can be performed, the invocation will display a
list of file names (or tokens) that begin with the token to complete
in \*(ST's popup area.
If the popup area is not large enough to display all possible
completions, this is highlighted by the user interface
using scroll bars.
If the immediate editing command is invoked again, the next page
of file names or tokens is displayed in the popup area.
I.e. it is possible to cycle through long lists of possible
auto-completions.
.LP
You can also scroll through the popup area with the mouse wheel.
Furthermore, you can click on entries in the popup area with the
mouse in order to fully complete them.
Often this will also automatically terminate the current command or
Q-Register specification, just like an unambiguous completion via
immediate editing commands.
On Curses, mouse events are not processed unless bit 7 (64) is set
in the \fBED\fP flags.
.LP
When completing file names, hidden files are not considered for
completion unless a prefix of the hidden file's name has already
been typed.
On Unix, \*(ST considers files and directories beginning with \(lq.\(rq
as hidden.
On Windows, the \fIhidden\fP file attribute is evaluated.
On other platforms, \*(ST might not identify hidden files correctly.
.LP
Both forward and backslash directory separators are supported
as arguments to \*(ST commands on Windows:
The separator style used for auto-completions is determined by
the last separator in the supplied file name and defaults
to backslash.
Therefore forward-slash auto-completion is possible on Windows,
e.g. by using a forward-slash in the file name or by prefixing
file names with \(lq./\(rq.
This is useful for writing cross-platform \*(ST macros (see
.BR "FILE NAMES AND DIRECTORIES" ).
.LP
File name completions are case-sensitive or insensitive depending
on operating system defaults.
On some operating systems \*(ST can determine the case-sensitivity
of individual directories as well.
\# Should be supported on Mac OS and newer versions of Windows,
\# but it's still untested.
.LP
Note that completions take place after string building and
tilde-expansion is also performed by file name completions,
so for instance both \(lq~/foo\(rq and \(lq^EQ[$HOME]/foo\(rq
will complete a file in the user's home directory.
Auto-completion also takes care of \fIquoting\fP string termination
and string building characters, which might be relevant especially
when autocompleting Q-Register names.
.
.
.SH USER INTERFACE
.SCITECO_TOPIC UI "user interface"
.
\*(ST can be built with support for different textual and
graphical user interfaces.
In \*(ST's batch mode, there is little difference between
the user interfaces (as no graphical window will be visible).
Naturally the interfaces have different graphical capabilities
but \*(ST tries to provide a consistent look and feel across
all user interfaces and reasonable defaults to make writing
user-interface agnostic macros and profiles easier.
The user interface will always be segmented into the following
areas from top of the program window to bottom:
.IP \(bu 2
.SCITECO_TOPIC info
The \fIinfo area\fP identifying the currently edited buffer or
Q-Register.
This area is currently sometimes omitted.
If technically possible, \*(ST will include the same information in the
window's title.
.IP \(bu
The \fIScintilla area\fP displaying the current document's
contents.
This corresponds to a Scintilla view (see section \fBBUFFER RING\fP)
and can be customized extensively using Scintilla messages
(see the \fBES\fP command).
.IP \(bu
The \fImessage area\fP which will show the last \*(ST message
that occurred.
This area will show errors, warnings, \(lquser messages\(rq
and other notes and tries to highlight them appropriately.
.IP \(bu
.SCITECO_TOPIC popup
The auto-completion \fIpopup area\fP which is only shown when
presenting the user with a choice of auto-completions.
This area will overlap the \fIScintilla\fP and \fImessage
areas\fP.
.IP \(bu
The \fIcommand line area\fP, showing the currently effective
and rubbed-out command line as it is edited.
This is currently a single line of text that is scrolled
automatically.
.
.SS Colors and Theming
.SCITECO_TOPIC colors theming
.
\*(ST supports customizing its look predominantly by setting
up the current Scintilla view using Scintilla messages
(see the \fBES\fP command and Scintilla documentation).
Most visual properties of the Scintilla view can be set
via its styles.
This is also how syntax highlighting (lexing) is set up.
.LP
.SCITECO_TOPIC STYLE_DEFAULT
The \fBSTYLE_DEFAULT\fP (32) style defines the default foreground,
background color, font etc. and is initialized to white on
black with some monospaced font by \*(ST.
The \fBSTYLE_DEFAULT\fP is also accessed by \*(ST to style the
\fIinfo area\fP, \fImessage area\fP (if it is empty or when
showing \(lquser messages\(rq) and \fIcommand line area\fP.
The info and message areas are styled reverse to the setting
of this style to provide good contrast, i.e. with foreground and
background colors swapped.
The colors used to highlight errors, warnings and other messages
in the \fImessage area\fP are currently hardcoded and cannot
be customized.
The command line area on the other hand will be styled with
the original colors of \fBSTYLE_DEFAULT\fP and should look
similar to the current Scintilla view.
.LP
.SCITECO_TOPIC STYLE_CALLTIP
The \fBSTYLE_CALLTIP\fP (38) style is also accessed by
\*(ST to style the \fIpopup area\fP and is initialized
to black on white by \*(ST.
.LP
On curses user interfaces, only a selection of 16 terminal
colors can be used, although it is possible to request changing
the default color mapping (see \fBEJ\fP command).
.LP
Scintilla styles will usually be set up in the profile
macro or \fBED\fP hook (for syntax highlighting).
\*(ST ships with a standard library with color schemes
and lexer configurations for a wide range of languages.
.
.SS Gtk CSS Styling
.SCITECO_TOPIC CSS
.
While the tools mentioned above are sufficient for
Curses UIs, the Gtk+ 3 UI has many more styling possibilities.
The basic color scheme will be automatically effective for
the buffer view since this is handled by Scintilla.
In order to apply the color scheme to the other UI components,
a CSS file must be provided that overrides certain styling
settings of the Gtk theme.
.LP
Therefore \*(ST automatically exports the following Gtk
CSS variables that can be referred to by user-provided
CSS files:
.TP
.SCITECO_TOPIC @sciteco_default_fg_color
.B @sciteco_default_fg_color
The foreground color of Scintilla's \fBSTYLE_DEFAULT\fP.
.TP
.SCITECO_TOPIC @sciteco_default_bg_color
.B @sciteco_default_bg_color
The background color of Scintilla's \fBSTYLE_DEFAULT\fP.
.TP
.SCITECO_TOPIC @sciteco_calltip_fg_color
.B @sciteco_calltip_fg_color
The foreground color of Scintilla's \fBSTYLE_CALLTIP\fP.
.TP
.SCITECO_TOPIC @sciteco_calltip_bg_color
.B @sciteco_calltip_bg_color
The background color of Scintilla's \fBSTYLE_CALLTIP\fP.
.LP
Furthermore, \*(ST defines named widgets for its
main UI components as well as several CSS classes.
.LP
The CSS file is loaded from
.B $SCITECOCONFIG/.teco_css
if it is existing.
Else, \*(ST loads the fallback CSS at
.BR @scitecodatadir@/fallback.css ,
which can also be used as a template when writing \fB.teco_css\fP.
The fallback CSS can also be consulted for additional documentation
on \*(ST's named widgets and special CSS classes.
The CSS file can be written such that it works for any
\*(ST color scheme and may also be used to tweak other
aspects of \*(ST's user interface.
Please refer to the Gtk documentation for more details on
CSS theming.
.
.
.SH ARITHMETICS AND EXPRESSIONS
.SCITECO_TOPIC arithmetics expressions
.
\*(ST abstracts classic TECO's scheme of commands accepting at most
two prefix arguments and returning at most one value for the next command
into a much more elaborate scheme where commands accept
.I n
arguments and return
.I n
arguments.
This is done using an integer value stack.
The stack is used for passing arguments and for arithmetics.
\*(ST is thus a stack-based language.
Nevertheless unary prefix and binary infix operators including operator
preference are supported.
Since the same stack is used for arithmetics and command arguments,
arithmetics and arbitrary code may be freely mixed like in
expression-centered languages and some classic TECOs.
In fact, in \*(ST digits are basically stack-operating commands.
For the sake of macro portability all integers are 64-bit signed
integers regardless of the host's architecture.
The integer storage size may be changed at \*(ST build time
however.
In this specific build, integers are @TECO_INTEGER@-bit.
.LP
Some commands expect or return booleans, most often signifying
success or failure.
Booleans are also integers but unlike in ordinary (sane) languages
where 0 represent false and other values represent true,
in \*(ST negative values (smaller than zero) represent success
and non-negative values (larger than or equal to zero) represent
failure.
Therefore \*(ST booleans may be negated by performing a
binary (bit by bit) negation for instance using the
.B ^_
command.
.
.SS Operators
.SCITECO_TOPIC operators
.
The following binary operators are supported with descending
precedence, whereas borders separate operators of the \fIsame\fP
precedence:
.SCITECO_TT 90n
.TS
expand,box,tab(;);
LW0 L.
\fIbase\fB ^* \fIpower\fR;T{
.SCITECO_TOPIC ^* power
Raise \fIbase\fP to \fIpower\fP.
T}
=
\fIa\fB ^/ \fIb\fR;T{
.SCITECO_TOPIC ^/ remainder modulo
Remainder of \fIa\fP divided by \fIb\fP.
It is actually a modulo operation conforming to the
host C compiler's modulo semantics.
T}
\fIa\fB / \fIb\fR;T{
.SCITECO_TOPIC / divide slash
Divide \fIa\fP by \fIb\fP.
Naturally it is a division without remainder.
T}
\fIa\fB * \fIb\fP;T{
.SCITECO_TOPIC * multiply asterisk
Multiply \fIa\fP by \fIb\fP.
T}
=
\fIa\fB - \fIb\fP;T{
.SCITECO_TOPIC - subtract minus
Subtract \fIb\fP from \fIa\fP.
T}
\fIa\fB + \fIb\fP;T{
.SCITECO_TOPIC + add plus
Add \fIb\fP to \fIa\fP.
T}
=
\fIa\fB & \fIb\fP;T{
.SCITECO_TOPIC & and ampersand
Binary AND.
T}
=
\fIa\fB ^# \fIb\fP;T{
.SCITECO_TOPIC ^# xor
Binary exclusive OR (XOR).
T}
=
\fIa\fB # \fIb\fP;T{
.SCITECO_TOPIC # or hash
Binary OR.
T}
.TE
.SCITECO_TT_END SP
.LP
.SCITECO_TOPIC associativity
All binary operators are \fIleft-associative\fP, i.e. associate
from left to right, in \*(ST.
.SCITECO_TOPIC ( ) brackets
Round brackets may be used for grouping expressions to override
operator precedence and associativity.
For instance, since \(lq\fB^/\fP\(rq, \(lq\fB/\fP\(rq and \(lq\fB*\fP\(rq
all have the same precedence, the expression \(lq1 ^/ 2 / 3 * 4\(rq is
equivalent to \(lq(((1 ^/ 2) / 3) * 4)\(rq.
The opening bracket also represents an argument barrier, i.e. the first
command after the opening bracket does not see and cannot pop any
arguments from the stack.
This may be useful for mixing commands with arithmetic expressions.
An expression enclosed in brackets returns all of the values that have
been pushed onto the stack.
\*(ST currently performs minimal checking on the validity of braces
(i.e. the closing brace \(lqcommand\(rq) which are handled more or less
like regular commands with regards to flow control.
Care should thus be taken when jumping out of braces or leaving open
braces at the end of macros as this might leave the parser in an unexpected state.
Conversely, the return command \fB$$\fP has special support for
dealing with braces.
As the current behaviour has probably little benefits, the rules
governing braces might be made stricter in a future release of \*(ST.
.LP
.SCITECO_TOPIC , comma barrier
Another construct that may be used as an argument barrier to explicitly
separate arguments is the comma (\(lq,\(rq).
It is obligatory when trying to push a sequence of number constants
like in \(lq1,2\(rq but is optional in many contexts where it is
mandatory in classic TECO, like in \(lq.ZD\(rq.
I recommend to use it as much as possible in code where clarity
matters.
.LP
The arithmetic evaluation order established by the operator precedence
or braces must not be confused with the execution order of \*(ST commands
which is always strictly from left to right (unless flow control
commands are used).
.LP
The only unary operator currently supported is
.RB \(lq - \(rq.
The minus-operator is special and has unique semantics.
.SCITECO_TOPIC prefix
It sets the so called \fBprefix sign\fP which is 1 by default
to -1.
This prefix sign may be evaluated by commands \(em most often it is the
default value if the argument stack is empty so that expressions like
\(lq-C\(rq are roughly equivalent to \(lq-1C\(rq.
However in front of opening brackets, like in \(lq-(1+2)\(rq, it is
roughly equivalent to \(lq-1*(1+2)\(rq so that values calculated in
brackets can be easily negated.
In front of digits the prefix sign specifies whether the digit is
added or subtracted from the value on the stack so that in front of
numbers the result is a negative number.
.
.
.SH BUFFER RING
.SCITECO_TOPIC ring
.
\*(ST organizes files to edit in the so called buffer ring.
The ring is a circular list of buffers.
A buffer is a named or unnamed Scintilla document, and may
be thought of as \*(ST's second important primary data type.
There is at most one unnamed buffer in the ring, identified
by the empty name.
Named buffers are buffers with an associated file name.
The file might or might not already exist in the file system.
The file name uses the host system's directory separator, but for
the sake of macro portability the directory separators are
normalized to \(lq/\(rq when accessing the current buffer's
file name with the \(lq*\(rq Q-Register.
File names are always tried to be normalized to absolute
paths to make them independant of \*(ST's current working
directory.
New buffers are always added at the end of the buffer ring.
The Id of a buffer corresponds to its position in the ring
(the first one has Id 1, the second one Id 2, etc.).
Buffers may be marked dirty by destructive operations.
.LP
Every buffer has its own Scintilla view, which means
that it behaves like a standalone Scintilla instance.
This means that all Scintilla messages you send to the
current buffer (using the \fBES\fP command) affect
only this buffer.
If you change some setting (like syntax highlighting),
switch the buffer and eventually switch back, all
settings will still be in effect.
If a configuration should be applied to all buffers,
\fBED\fP hooks should be used (see below).
Note that Q-Registers behave differently \(em they can
also be edited like regular buffers but share
one Scintilla instance for performance reasons.
.LP
\*(ST is a character-oriented editor, so every character
in a buffer/document may be addressed by a position
integer.
The first character is addressed by position 0.
Every document has a current position called dot
(after the \(lq.\(rq command that returns it).
A document may contain any sequence of bytes but positions
refer to characters that might not correspond to individual
bytes depending on the document's encoding (see \fBEE\fP command).
The \fB^E\fP command can be used to translate between byte
and character/glyph positions.
Consequently when querying the code at a character position
or inserting characters by code, the code may be an Unicode
codepoint instead of byte-sized integer.
.LP
Currently, \*(ST supports buffers in UTF-8 and single-byte
ANSI encodings, that can also be used for editing raw binary files.
\# You can configure other single-byte code pages with EE,
\# but there isn't yet any way to insert characters.
UTF-8 is the default codepage for new buffers and Q-Registers
unless the 2nd \fBED\fP flag bit is set.
You can also specify \fB--8bit\fP to optimize \*(ST for
8-bit cleanliness.
While navigation in documents with single-byte encodings
takes place in constant time, \*(ST uses heuristics in
UTF-8 documents for translating between byte and character
offsets which are slower especially when \(lqjumping\(rq
into very large lines.
\# But there are optimizations for R, C and A...
.LP
.SCITECO_TOPIC "EOL translation"
To simplify working with files using different end of line
sequences (combinations of carriage return and line feed),
\*(ST implements an \fIautomatic EOL translation\fP
feature.
When loading files with the \fBEB\fP and \fBEQ\fP commands \(em
or when reading from an external process with the \fBEC\fP and
\fBEG\fP commands \(em
\*(ST will normalize all end of line sequences to line feeds.
It will also detect, correct and warn about inconsistent EOL sequences
in the source file or process output.
EOL normalization is thus a lossy process.
The file's original EOL mode as guessed by \*(ST is still saved
as the corresponding Scintilla document's EOL mode
(see \fBSCI_SETEOLMODE\fP and the \fBEL\fP command).
If the EOL mode could not be guessed, the document will retain
a platform-default EOL mode (e.g. carriage return, line feed on
Windows and line feed on UNIX).
The EOL mode is used when saving files with the \fBEW\fP and \fBE%\fP
commands or when writing to an external process with the \fBEC\fP and \fBEG\fP
commands in order to reconstruct the original EOL characters.
Translation on write-out will also work when the source document
has inconsistent or mixed line breaks.
Therefore macros can assume each line to be terminated by
a single line feed character while working with files that have
different EOL styles.
The feature is enabled by default but is controlled by bit 4
of the \fBED\fP flag setting.
It can be turned off by executing:
.SCITECO_TT
.EX
16,0ED
.SCITECO_TT_END
.EE
This may be beneficial when working with very large files \(em
as the EOL translation imposes a performance penalty \(em
or non-text (binary) files.
No automatic guessing of documents' EOL mode is performed
when disabling this feature, so all documents will have
platform-default EOL modes set.
.LP
For more details, please refer to this manual's command
reference.
.
.SS Buffer Editing Hooks
.SCITECO_TOPIC hooks
.
When opening or editing a file with the \fBEB\fP command
or when closing a file with the \fBEF\fP command, you
often want to configure the editor for a particular language.
For instance, when opening C++ files you might want to
enable C++ lexing and syntax highlighting automatically.
\*(ST thus provides user-configurable hooks into buffer
editing operations.
Hooks are by default disabled.
To enable them, set bit 5 in the \fBED\fP flags:
.SCITECO_TT
.EX
0,32ED
.SCITECO_TT_END
.EE
\*(ST will now execute the macro in global Q-Register \(lqED\(rq
whenever a relevant operation is performed.
This macro \fBmust\fP be provided if \fBED\fP hooks are
enabled.
.LP
The \(lqED\(rq macro will receive an argument that specifies the
type of operation that has just been performed or is
just about to be performed.
The \(lqED\(rq macro is executed in a more or less
isolated way by \*(ST, i.e. it will not see any other
argument that is on the expression stack when the hook
is executed and all values it may leave on the expression
stack are discarded.
This way, \fPED\fP hooks should not interfere with
the stack-semantics of commands triggering them.
.LP
Possible arguments to the \(lqED\(rq macro begin with 1 and
are defined consecutively so the macro can branch to the
operation using a computed goto.
The different values are defined as follows:
.TP
.B 1
A file has been \fBadded\fP to the buffer ring.
It may or may not already exist in the file system.
This file is \*(ST's current document when this hook
executes.
Scintilla lexing may be configured in this hook \(em it
usually only has to be done once.
.TP
.B 2
A buffer has been \fBedited\fP (made the current file).
This hook is not executed when a file is freshly added
to the buffer ring, since this can be simulated easily
by branching within the \(lqED\(rq macro.
In this hook you may want to define language-specific
auxiliary macros, for instance.
.TP
.B 3
A buffer is about to be \fBclosed\fP (removed from the
buffer ring).
The buffer that is about to be closed, is still the
current document when this hook runs.
.TP
.B 4
\*(ST is about to \fBquit\fP, i.e. exit normally.
This is \*(ST's equivalent of
.BR atexit (3)
handlers.
The hook is not run when some command fails,
but only when \*(ST exits normally.
This is the case when control in a macro specified via
\fB--eval\fP reaches the end, or otherwise returns
(using \fB^C\fP or by returning from the top-level
macro via \fB$$\fP).
Similarily the hook is executed when a munged
file calls \fB^C\fP or \fBEX\fP has been called before
the top-level macro returns.
It is also called after the interactive mode has shut down
by calling \fBEX$$\fP.
The \fBquit\fP hook will always run in \fIbatch\fP
mode (after any user interface has shut down).
Errors in the hook's execution will not prevent
\*(ST from exiting, but an error trace will
be printed and \*(ST exit code will be a failure code.
It is not possible to cancel program termination
via \fBquit\fP hooks.
The \fBquit\fP hook may be used to transparently
save a buffer session, for instance.
.LP
The side-effects of the hook executions are reversed
when rubbing out the command that resulted in its
execution.
Unless otherwise noted, errors during hook
execution will propagate and let the command
triggering the hook execution fail.
.LP
The \*(ST standard library contains a framework
for configuring Scintilla lexing and other useful
hooks (see
.BR lexer.tes ).
.
.
.SH COMMAND SYNTAX
.SCITECO_TOPIC syntax
.
\*(ST's command syntax is quite flexible and diverse but may be
categorized into some base command types.
.TP
.B C
.TQ
.B EF
A simple command consists of one or more printable or control
characters whose case is insignificant.
Only \fBat the beginning\fP of a command, carets followed by
one character are equivalent to the corresponding control
character.
Since it does not make any sense whatsoever to support a
caret-form of non-operational (ignored) control character commands
(i.e. form feed, carriage return, line feed, vertical tab),
their caret forms (e.g. \(lq^J\(rq) are reserved for future
use as operational commands.
The command is executed as soon as it has been completely specified.
.TP
.BI Q q
A command identifier may be followed by a Q-Register specification
.IR q .
It specifies a Q-Register to be accessed by the command
(e.g. to query, set, increase).
.TP
.BI I string $
.TQ
.BI FS string1 $ string2 $
A command identifier (and Q-Register specification) may be followed
by one or more string arguments.
String arguments are terminated by Escape characters (27) by default,
but this may be changed using modifiers.
If enabled, string arguments may contain special string building characters
for instance to embed other strings or to quote the argument terminator.
The detection of the end of a string is aware of string building characters,
i.e. string building constructs may contain the current terminator.
String building may be enabled or disabled by default for a command.
In interactive mode the command is often executed as soon as it
has been completely specified and updates to the string arguments
are handled interactively.
.
.SS Modifiers
.SCITECO_TOPIC modifiers
.
A command's behaviour or syntax may be influenced by so called
modifiers written in front of commands.
Their specific influence of a modifier always depends on the concrete
command following it.
When specifying more than one modifier, their order is insignificant.
.LP
.SCITECO_TOPIC : colon
The colon (\fB:\fP) modifier usually prevents a command from
failing and instructs it to return a condition (success/failure)
boolean instead.
.SCITECO_TT
.EX
1000:C=
.SCITECO_TT_END
.EE
For instance if \(lq1000C\(rq would fail, \(lq1000:C\(rq will
return 0 instead.
.LP
.SCITECO_TOPIC ::
Two colons (\fB::\fP) can sometimes further modify a command's behavior \(em
currently it is used by the \fB::S\fP search comparison command.
On all other commands it will behave like a single colon.
.LP
.SCITECO_TOPIC @ at
When put in front of a command with string arguments,
the at (\fB@\fP) modifier always allows the string termination character
to be changed for that particular command.
The alternative termination character must be specified just before
the first string argument.
For instance:
.SCITECO_TT
.EX
@FS/foo/bar/
.SCITECO_TT_END
.EE
Any character may be used as an alternative termination character.
There is one special case, though.
If specified as the opening curly brace (\fB{\fP), a string argument
will continue until the closing curly brace (\fB}\fP).
Curly braces must be balanced and after the closing curly brace
the termination character is reset to Escape and another one may
be chosen.
This feature is especially useful for embedding TECO code in
string arguments, as in:
.SCITECO_TT
.EX
@^Um{
  @FS{foo}/bar/
}
.SCITECO_TT_END
.EE
The termination character can be \fIquoted\fP if you want to handle
it like any regular character.
For instance, you could write \(lqS^Q\fB$$\fP\(rq to search for the
escape character itself.
.LP
The at (\fB@\fP) modifier may also sometimes be supported by commands,
that do not accept string arguments.
For instance, \fB@X\fIq\fR cuts text into Q-Register \fIq\fP.
\# But there is no common semantics for @ on regular commands, yet.
\# We may some day add @Mq/.../ for passing string arguments to macro calls,
\# but it will be yet another special case.
.
.SH Q-REGISTERS
.SCITECO_TOPIC Q-Register
.
\*(ST may store data in so called Q-Registers.
Each Q-Register cell has an integer and string part (can store
both at the same time).
Strings are actually Scintilla documents.
Therefore Q-Register strings may be edited just like buffers
(see \fBEQ\fP command).
However, in contrast to buffers which represent standalone
Scintilla instances (views), all Q-Registers share a single
Scintilla view.
This means that some settings, like parts of the lexer
configuration is the same for every Q-Register you edit.
It is not straight-forward to see which settings are saved
by Scintilla per-document.
Fortunately, \*(ST cares about saving the most important properties
(like the cursor position, selections and scroll state)
per document, even though Scintilla does not do so by default.
.LP
Q-Register cells have case-sensitive names and are stored
in Q-Register tables.
These tables are Red-Black trees internally.
Therefore the Q-Register namespace may be (ab)used as a
complex data structure e.g. for records, arrays and maps.
\*(ST provides a global Q-Register table (for global registers)
and arbitrarily many local Q-Register tables (for local registers).
Only one global and local Q-Register table may be accessed at a
time.
Macro invocations might create new local Q-Register tables for
the executed code.
\*(ST initializes the Q-Registers \(lqA\(rq to \(lqZ\(rq and
\(lq0\(rq to \(lq9\(rq in every Q-Register table.
.LP
There are global Q-Registers with special significance for \*(ST
because they may be accessed by commands opaquely.
Some of these registers represent information beyond their
textual and numeric cells \(em they overwrite default operations
with custom side-effects in order to support unique idioms.
Some of the registers with special significance are initialized
by \*(ST while others must be manually defined.
The following list is an overview of all special \fIglobal\fP registers:
.TP 2
.SCITECO_TOPIC "search condition"
.BR _ " (underscore)"
Search string and search condition register.
Also used by the globbing command \fBEN\fP, so it is also
the glob string and condition register.
It is initialized automatically on startup.
.TP
.BR - " (minus)"
Replacement string register.
Its integer part is currently unused.
It is initialized automatically on startup.
.TP
.BR : " (colon)"
The current document's position (dot).
This changes dot when set as with the
.B J
and other movement commands.
This allows you to change dot temporarily with the following idiom:
.SCITECO_TT
.EX
[: ! ...change dot... ! ]:
.SCITECO_TT_END
.EE
The string part of this register is currently unused.
.TP
.SCITECO_TOPIC filename
.BR * " (asterisk)"
File name (string part) and id (numeric part) of current
buffer in ring.
The unnamed buffer has an empty name.
If the current document is a register, this returns the
name or id of the buffer last edited.
Buffer file names are \fItried\fP to be made absolute paths
by \*(ST, but this might not always be possible.
Also, file names accessed with the \(lq*\(rq register will
always have forward-slash directory separators even if they
are displayed differently in the user interface.
The \(lq*\(rq register may also be edited but changing its
string contents has no effect on the file name of the buffer.
Setting and appending to the \(lq*\(rq register is unsupported.
Setting the numeric part of the \(lq*\(rq register,
as in \(lq1U*\(rq, is equivalent to editing a buffer by id
(e.g. \(lq1EB\fB$\fP\(rq) but is shorter since there is no
string parameter.
This allows the useful idioms of changing to the previous
buffer with \(lq-%*\fB$\fP\(rq, changing to the next
buffer with \(lq%*\fB$\fP\(rq and changing the current buffer
temporarily:
.SCITECO_TT
.EX
[* ! ...change current buffer... ! ]*
.SCITECO_TT_END
.EE
The register is initialized automatically on startup.
.TP
.SCITECO_TOPIC "working directory"
.BR $ " (dollar)"
The process' current working directory (string part).
Its numeric part is currently unused.
The working directory will always be returned as an
absolute path with normalized forward-slash directory
separators.
It is possible to set this register using the \fB^U\fP or
\fBEU\fP commands which will change the current working
directory in a manner similar to the \fBFG\fP command.
This allows you to change the current directory temporarily
with the following idiom:
.SCITECO_TT
.EX
[$ ! ...change current directory... ! ]$
.SCITECO_TT_END
.EE
As with \fBFG\fP, relative directories may be specified
but querying \(lq$\(rq will still return an absolute path.
The \(lq$\(rq register may also be edited but changing its
string contents this way has no effect on the current
working directory.
Appending to the \(lq$\(rq register is unsupported.
The register is initialized automatically on startup.
.TP
.BR $ " (Escape)"
Command-line replacement register.
Its integer part is unused.
It is initialized automatically on startup.
.TP
.BI $ variable
Global Q-Registers beginning with a dollar sign that
do not contain any \(lq=\(rq represent the process environment
(the environment variables).
The register \(lq$\(rq does \fBnot\fP belong to the process
environment.
Some environment variables are initialized with default values
if the corresponding environment variable is unset and
some may be accessed internally by \*(ST commands.
In other respects, the environment registers are ordinary
non-customized registers that support all operations.
Their numeric parts are currently unused.
The mechanisms involved are documented more elaborately in
.BR sciteco (1).
.TP
.SCITECO_TOPIC ~ clipboard
.BI ~ clipboard
These registers constitute \*(ST's support for system clipboards.
Clipboard support is highly UI-specific, so different
UIs might support different clipboards (or X11 selections)
or no clipboard at all.
\*(ST thus initializes registers beginning with \(lq~\(rq for
every available clipboard either on startup or only when
entering interactive mode.
The register \(lq~\(rq refers to the default clipboard which
will always exist if clipboards are supported.
.SCITECO_TOPIC ~P ~S ~C
Other commonly used clipboard registers are \(lq~P\(rq for the
primary selection, \(lq~S\(rq for the secondary selection and
\(lq~C\(rq for the clipboard selection.
The existence of a clipboard register can thus be checked
in macros to determine whether getting and modifying that
particular clipboard is supported natively.
.br
\*(ST supports two ways of driving the clipboard on ncurses.
.SCITECO_TOPIC OSC-52 xterm
First of all, there is built-in support for OSC-52 escape sequences,
as were introduced by sufficiently recent versions of
.BR xterm (1)
and have since been adopted by several other terminal emulators.
Since the operability of OSC-52 clipboards cannot be tested
automatically, users will have to set the flag 256 of the
\fBED\fP flags if and only if their terminal emulator is properly
configured.
.BR xterm (1)
for instance must be configured for allowing
the \fISetSelection\fP and \fIGetSelection\fP window operations.
It is nevertheless observed to be a very buggy and unreliable feature.
If running under
.BR xterm (1),
\*(ST will still check whether the XTerm version is sufficient.
.SCITECO_TOPIC Kitty
Other terminal emulators like Kitty may ask for permission to read the
clipboard (\fBread-clipboard-ask\fP).
This is not supported by \*(ST and must be disabled
(use \fBread-clipboard\fP instead).
.br
Alternatively, if OSC-52 clipboards are disabled, you can set the
\fB$SCITECO_CLIPBOARD_SET\fP and \fB$SCITECO_CLIPBOARD_GET\fP
environment variables (or corresponding Q-Registers) to shell
commands, that receive the clipboard
contents on stdin and output the requested clipboard on stdout.
This allows integrating with various windowing environments.
See \fBENVIRONMENT\fP in
.BR sciteco (1)
for more details.
.br
Setting the string part of a clipboard register will set that
clipboard. \*(ST will perform automatic EOL-translation according
to the EOL-mode of the Q-Register view, so e.g. on Windows
clipboards will usually be set with the expected DOS linebreaks.
Appending to clipboard registers is currently not supported.
Furthermore, \*(ST will restore the contents of the clipboard
at the time of the operation when an assignment is rubbed out in
interactive mode.
When retrieving a clipboard register, the contents of the
clipboard at the time of the operation are returned.
EOL normalization will take place (if enabled), so that pasting
clipboards does not introduce unexpected EOL sequences.
The Q-Register view's EOL mode will \fBnot\fP be guessed from
the original clipboard contents, though.
The numeric parts of the clipboard registers are currently
not used by \*(ST.
.TP
.BI ^K key
Key macro registers as documented in section
.BR "KEY TRANSLATION" .
Their string-content represents a key macro
and their numeric part is a key macro mask.
None of those registers are automatically initialized
on startup.
.TP
.B ED
The \fBED\fP hook Q-Register.
Its string-content is called as a macro when bit 5 is set
in the \fBED\fP flags (see subsection \fBBuffer Editing Hooks\fP).
The numeric part of register \fBED\fP is currently unused and
the register is not automatically initialized on startup.
.LP
Furthermore, \*(ST supports special local Q-Registers.
The values of these properties will therefore be known at the beginning
of macro calls (unless these calls are colon-modified).
The following list is an overview of all special \fIlocal\fP registers:
.TP 2
.BR ^R " (CTRL+R)"
The current radix as reported and configurable with the
\fB^R\fP, \fB^O\fP and \fB^D\fP commands (10 by default).
The string part of this register is currently unused.
.TP
.BR ^X " (CTRL+X)"
The current search mode flag as set and reported by the
.B ^X
command.
The default value of 0 means that searches are always
case-insensitive at the beginning of macro calls.
The string part of this register is currently unused.
.LP
Some commands may create and initialize new registers if
necessary, while it is an error to access undefined registers
for some other commands.
The string part of a register is only ever initialized
when accessed.
This is done opaquely, but allows you to use register
tables as purely numeric data structures without the
overhead of empty Scintilla documents.
.
.SS Q-Register Specifications
.
Q-Registers may be referred to by commands using Q-Register
specifications:
.TP 10
.I c
.TQ
.BI . c
Refers to a one character Q-Register.
The one character name is upper-cased.
All one character names except for \(lq.\(rq, \(lq^\(rq and \(lq#\(rq
can be referenced this way.
If lead by a dot, the name refers to a local Q-Register,
otherwise to a global one.
.TP
.BI ^ c
.TQ
.BI .^ c
Refers to a Q-Register, whose name is a single byte control code.
Those can be typed with upcarets as well.
.TP
.BI # cc
.TQ
.BI .# cc
Refers to a two character global or local Q-Register whose
name is upper-cased.
\# FIXME: Space characters could/should be disallowed here.
.TP
.BI [ name ]
.TQ
.BI .[ name ]
Refers to a Q-Register with an arbitrary
.IR name .
The name is \fBnot\fP upper-cased.
String building characters may be used so that Q-Register names
may be calculated.
Curly braces can be used in \fIname\fP as long as they are
balanced.
The short single or double character specifications refer
to registers in the same namespace as long specifications.
For instance the specifications \(lqa\(rq and \(lqA\(rq
are equivalent to \(lq[A]\(rq.
.
.SS Push-Down List
.SCITECO_TOPIC "push down" stack
.
Another data structure supported by \*(ST is the Q-Register
push-down list.
Register contents may be pushed onto and popped from this list,
for instance to save and restore global registers modified
by a macro.
The global Q-Register push-down list is handled using the
.BI [ q
and
.BI ] q
commands.
For instance to search in a macro without overwriting the
contents of the search register you could write:
.SCITECO_TT
.EX
[_ Sfoo$ ]_
.SCITECO_TT_END
.EE
To copy the string and numeric contents of register \(lqA\(rq to \(lqB\(rq,
you could write \(lq[a ]b\(rq.
.
.SH STRING-BUILDING CHARACTERS
.SCITECO_TOPIC "string building"
.
As alluded to earlier \*(ST supports special characters in
command string arguments and long Q-Register names.
These are called string-building characters.
String-building character processing may be enabled or
disabled for specific commands by default but is
always enabled in long Q-Register specifications.
String building and processing is performed in the following
stages:
.RS
.IP 1. 4
Carets followed by characters are translated to control codes,
so \(lq^a\(rq and \(lq^A\(rq are equivalent to CTRL+A (code 1).
\# FIXME: Should we change the double-caret behavior?
A double caret \(lq^^\(rq is translated to a single caret,
but Ctrl+caret (code 30) is not translated at all.
This caret-handling is independent of the caret-handling in
command names.
.IP 2.
String building characters are processed, resulting in expansions
or translations of subsequent characters.
.IP 3
Command-specific character processing.
Some commands, most notably the search and replace commands,
might interprete special characters and domain specific languages
after string building.
Care has been taken so that the string building and
command-specific languages do not clash (i.e. to minimize necessary
escaping).
.RE
.LP
String building characters/expressions are always lead by a control
character and their case is insignificant.
In the following list of supported expressions, the caret-notation
thus refers to the corresponding control code:
.TP
.SCITECO_TOPIC ^Qc ^Rc quote
.BI ^Q c
.TQ
.BI ^R c
Escape character \fIc\fP.
The character is not handled as a string building or string termination
character, so for instance \(lq^Q^Q\(rq translates to \(lq^Q\(rq.
Furthermore, some immediate editing commands are inhibited right after \fB^Q\fR,
so you can type \(lq^Q^U\(rq and \(lq^Q^W\(rq, which translate to control codes
21 and 23.
.TP
.SCITECO_TOPIC ^V^V ^Vc lower
.B ^V^V
.TQ
.BI ^V c
Translates all following characters, including the expansions of \fB^EQ\fP,
\fB^EU\fP etc., into lower case.
When \fB^V\fP is not followed by \fB^V\fP, a single character
\fIc\fP is lower-cased.
\# Which is pretty pointless nowadays.
.TP
.SCITECO_TOPIC ^W^W ^Wc
.B ^W^W
.TQ
.BI ^W c
Analogous to \fB^V\fP, but upper-cases characters.
Since \fB^W\fP is an immediate editing command, this can practically be typed
only with upcarets in interactive mode.
.TP
.SCITECO_TOPIC ^E\[rs] ^E\[rs]q
.BI ^E\(rs q
Expands to the formatted number stored in the
numeric part of Q-Register \fIq\fP.
The number is formatted according to the current
radix and exactly the same as the backslash (\fB\(rs\fP)
command would format it.
Currently, long Q-Register names have a separate independant
level of string building character processing, allowing you
to build Q-Register names whose content is then expanded.
.TP
.SCITECO_TOPIC ^EU ^EUq
.BI ^EU q
Expands to the character whose code is stored in the numeric
part of Q-Register \fIq\fP.
For instance if register \(lqA\(rq contains the code 66,
\(lq^EUa\(rq expands to the character \(lqB\(rq.
The interpretation of this code depends on the context.
Within inserts and searches (\fBI\fP, \fBS\fP, etc.) bytes or Unicode codepoints
are expected depending on the buffer's encoding.
Operations on registers (\fBEU\fP) similarily consult the
register's encoding.
Everything else expects Unicode codepoints.
.TP
.SCITECO_TOPIC ^EQ ^EQq
.BI ^EQ q
Expands to the string contents of the Q-Register specified by
\fIq\fP.
.TP
.SCITECO_TOPIC ^E@ ^E@q
.BI ^E@ q
Expands to the shell-quoted string contents of the Q-Register
specified by \fIq\fP.
The quoting will be such that an UNIX98 \(lq/bin/sh\(rq will
interpret the quoted string like the original contents of
\fIq\fP.
This is useful when generating UNIX shell code or when passing
registers with unknown contents as parameters to external
commands using the \fBEC\fP command.
.TP
.SCITECO_TOPIC ^EN ^ENq
.BI ^EN q
Expands to the string contents of the Q-Register specified
by \fIq\fP but with glob pattern wildcards escaped.
This is useful for commands accepting glob patterns to
pass file names which will not be interpreted further
(e.g. if the file name may contain \(lq*\(rq or other
special characters).
.TP
.BI ^E c
All remaining \fB^E\fP combinations are passed down
unmodified.
Therefore \fB^E\fP pattern match characters do not have to
be escaped.
.
.
.SH PATTERN MATCH CHARACTERS
.SCITECO_TOPIC pattern
.
\*(ST's search and replace commands allow the use of wildcards
for pattern matching.
These pattern match characters are all led by control characters
and their case is insignificant,
so they usually require much less escaping and thus less typing
than regular expressions.
Nevertheless they describe a similar class of languages.
Pattern match character processing is performed after string building
by search and replace commands.
.LP
The following pattern match constructs are supported for matching
one character in different character classes
(caret-notations refer to the corresponding control characters):
.TP
.BI ^Q c
.TQ
.BI ^R c
Escape character \fIc\fP.
Since these are interpreted as string building characters as well,
you may have to type two or three \fB^Q\fP in a row to escape a
pattern match character.
.TP
.SCITECO_TOPIC ^S ^EB
.B ^S
.TQ
.B ^EB
Matches all non-alpha-numeric characters.
.TP
.SCITECO_TOPIC ^EA
.B ^EA
Matches all alphabetic characters.
.TP
.SCITECO_TOPIC ^EC
.B ^EC
Matches all symbol constituents.
These are currently defined as alpha-numeric characters,
dot (.) and dollar ($) signs.
.TP
.SCITECO_TOPIC ^ED
.B ^ED
Matches all digits.
.TP
.SCITECO_TOPIC ^EG ^EGq
.BI ^EG q
Matches all characters in the string of the Q-Register
specified by \fIq\fP, i.e. one of the characters in
the register.
.TP
.SCITECO_TOPIC ^EL
.B ^EL
Matches all line break characters.
These are defined as carriage return, line-feed, vertial tab and
form feed.
.TP
.SCITECO_TOPIC ^ER
.B ^ER
Matches all alpha-numeric characters.
.TP
.SCITECO_TOPIC ^EV
.B ^EV
Matches all lower-case alphabetic characters.
.TP
.SCITECO_TOPIC ^EW
.B ^EW
Matches all upper-case alphabetic characters.
.TP
.I c
All other (non-magic) characters represent a class that
contains only the character itself.
.LP
The following additional pattern match constructs are supported
(caret-notations refer to the corresponding control characters):
.TP
.SCITECO_TOPIC ^X ^EX
.B ^X
.TQ
.B ^EX
Matches any character.
.TP
.SCITECO_TOPIC ^N
.BI ^N class
Matches any character \fBnot\fP in \fIclass\fP.
All constructs listed above for matching classes may be used.
.TP
.SCITECO_TOPIC ^EM
.BI ^EM pattern
Matches many occurrences (at least one) of \fIpattern\fP.
Any pattern match construct and non-magic character may be used.
.TP
.SCITECO_TOPIC ^ES
.B ^ES
Matches any sequence of whitespace characters (at least one).
Whitespace characters are defined as line-break characters,
the space and horizontal tab characters.
.TP
.SCITECO_TOPIC ^E[
.BI ^E[ pattern1 , pattern2 , ... ]
Matches one in a list of patterns.
Any pattern match construct may be used.
The pattern alternatives must be separated by commas.
.LP
All non-pattern-match-characters match themselves.
Note however that currently, all pattern matching is performed
.BR case-insensitive .
.
.
.SH FILE NAMES AND DIRECTORIES
.
One class of \*(ST commands accepts file names or directory
path arguments.
The most prominent is the \fBEB\fP command.
All file names or directories can be absolute or relative
paths.
Relative paths will be resolved according to the process'
current working directory (as can be set e.g. via the
\fBFG\fP command).
Nevertheless, \*(ST will function properly after changing
the working directory as \*(ST canonicalizes relative
paths to absolute paths if necessary.
Both buffer file names and some special Q-Registers
corresponding to environment variables documented in
.BR sciteco (1)
are canonicalized in this way.
.LP
The directory separator style (forward or backslash) accepted
by \*(ST commands is platform dependent.
Forward slash directory separators can be used on every supported
platform.
On Windows, both forward and backslash directory separators
are accepted in order to faciliate a native look and feel.
Since on some supported platforms (notably UNIX), forward slash
directory separators are the only supported separator style,
they are recommended when writing cross-platform \*(ST macros.
File names queried via some \*(ST command or Q-Register
are also normalized to contain only forward slash directory
separators (on platforms supporting both styles) in order to
ease the task of cross-platform macros.
.LP
Currently all path name arguments also support string building
characters.
Therefore it is possible to refer to environment variables
in path arguments.
For instance, \(lq^EQ[$HOME]/.teco_ini\(rq will refer to the
\*(ST profile on UNIX by default.
.LP
Even though the \(lqHOME\(rq environment variable is initialized
to a sane value by \*(ST, it is cumbersome to type in frequently
used commands.
Therefore, \*(ST also supports UNIX-shell-like tilde-expansions.
So for instance, the file name \(lq~/.teco_ini\(rq also expands
to the \*(ST profile on UNIX by default and is roughly equivalent
to \(lq^EQ[$HOME]/.teco_ini\(rq.
It is important to note that \(lq~\(rq is not part of the file
name proper (not even on UNIX) but a token that needs to be
expanded first.
In \*(ST this expansion takes place \fIafter\fP processing
string building characters.
Unlike the UNIX-shell, \*(ST will only expand the \fIcurrent
user's\fP home directory using the value of the
\(lq$HOME\(rq environment register.
Thus the \(lq~\fIusername\fP\(rq syntax is \fBnot\fP supported.
.LP
There is special immediate editing command support for
file and directory path arguments (e.g. tab-completions and
specialized rub-out/rub-in commands).
These are documented in the section
.BR "COMMANDLINE EDITING" .
.
.SS Glob Patterns
.SCITECO_TOPIC glob
.
Some commands accept glob patterns
in their file name arguments to perform pattern matching
on arbitrary strings or to work with multiple existing files
(see \fBEN\fP and \fBEB\fP commands).
\*(ST glob patterns mimic the POSIX
.BR fnmatch (3)
syntax, but work uniformly across all platforms.
The following wildcard constructs are supported:
.TP
.B *
Matches an arbitary number of characters or no character
at all.
.TP
.B ?
Matches a single arbitrary character.
.TP
.BI [ set ]
Matches one character in the given character \fIset\fP.
For instance \(lq[ch]\(rq matches both \(lqc\(rq and \(lqh\(rq.
A hyphen may be used to specify character ranges as in
\(lq[0-9]\(rq to match all decimal digits.
Within a character class, the \(lq*\(rq and \(lq?\(rq wildcards
have no special meanings and represent their corresponding
characters.
To include a hypen in the \fIset\fP, write it first or last.
To include a closing bracket in the \fIset\fP, write it first,
as in \(lq[]ch]\(rq.
.TP
.BI [^ set ]
.TQ
.BI [! set ]
Matches one character which is \fBnot\fP in the given character
\fIset\fP.
Otherwise behaves exactly like \fB[\fIset\fB]\fR.
.LP
All other characters match themselves.
Brackets can be used to escape wildcard characters.
For instance, \(lq[*]\(rq may be used to match a literal asterisk.
To facilitate passing filenames verbatim to commands
accepting glob patterns, there is the \fB^EN\fIq\fR string
building construct which automatically escapes glob pattern
wildcards.
.
.
.SH FLOW CONTROL
.SCITECO_TOPIC flow
.
\*(ST is a structured imperative language.
Commands are executed from left to right.
The white space characters space, form feed, carriage return,
line feed and vertical tab are non-operational (ignored)
commands.
All of the standard structured (and unstructured) flow control
constructs are supported:
gotos, loops and conditionals.
Flow control commands have a syntax similar to commands but allowing
code blocks.
They are documented in the following subsections.
.LP
It is important to note that in contrast to classic TECOs and Video
TECO, \*(ST handles flow control constructs much more elaborately.
While classic TECOs control flow by linearilly searching the
program code, paying no attention to string boundaries and comments,
\*(ST always parses code even when not executing so you do not have
to care about characters relevant for flow control in string arguments
and the like.
\*(ST will never ever jump into string arguments!
Also \*(ST caches program counters in tables and dedicated stacks
so that flow-control statements are generally faster than
in classic TECOs.
.
.SS Gotos and Labels
.
The most basic flow control command in \*(ST is the Go-to command.
Since it is really an ordinary command, exceptional only in setting
the program counter and influencing parsing, it is described in this
document's command reference.
\*(ST can perform simple unconditional and computed gotos.
.LP
.SCITECO_TOPIC label
Labels are symbolic and are defined with the following syntax:
.br
.BI ! label !
.br
Whereas \fIlabel\fP is an arbitrary non-empty string.
Labels however cannot practically begin with an asterisk sign (*).
String building is not performed on \fIlabel\fP, i.e. it is used
verbatim.
When a label is encountered, it is cached in a macro-invocation level
specific goto table if it is not in there already.
Therefore every macro invocation has its own label namespace and gotos
to a label have constant complexity once a label has been parsed.
\# The table lookup is not constant of course.
Terminating a macro execution (or command line) fails if a label that
is jumped to has not been defined.
Labels are also historically used as comments in TECO code.
That's why \*(ST allows several identical labels in the same scope \(em
goto commands will always jump to the first occurrance of the label.
In case of label redefinition, a warning will be printed, so you are
encouraged to use \(lqtrue\(rq comments as described below.
.
.SS Comments
.SCITECO_TOPIC comment
.
In addition to labels and unlike most classic TECO dialects,
\*(ST also supports true comments.
True comments are parsed faster than labels and do not
take up memory in goto tables.
.SCITECO_TOPIC "block comment"
One form of comments is the block comment:
.br
.BI !* comment *!
.br
Single exclamation marks (!) can be embedded in the \fIcomment\fP if they are not
following asterisk signs (unlike in goto-labels).
Block comments can span multiple lines.
They are analoguous to C's
.BI /* ... */
comments.
.LP
.SCITECO_TOPIC "EOL comment"
The second form of real comments are end-of-line comments,
which are analogous to C++'s \fB//\fP comments:
.br
.BI !! comment
.LP
The idiom \(lq0<\fIcommands\fP>\(rq
is also sometimes useful to comment out large blocks of \*(ST code.
However, all \fIcommands\fP must still be syntactically correct.
.
.SS Loops
.SCITECO_TOPIC < > loop
.
Gotos may be used for looping, but \*(ST also supports a dedicated
structured looping construct.
Its syntax is as follows:
.br
\# [n]< code >
\fR[\fIn\fR]\fB< \fIcode\fB >\fR
.br
In other words, sharp brackets (less-than and greater-than signs)
correspond to the loop start and end.
The opening bracket acts as an argument barrier (i.e. the command
immediately following does not see any argument) just like a round
bracket and the closing sharp bracket discards all values accumulated
on the expression stack since the loop's beginning
(similar to a \fB^[\fP command).
The opening bracket takes an optional argument \fIn\fP.
If \fIn\fP is omitted, -1 is implied.
The loops behaviour depends on the value of \fIn\fP:
.TP
.IR n " > 0"
Execute \fIcode\fP exactly \fIn\fP times.
You may break from the loop earlier though, using the semicolon
(\fB;\fP) command.
.TP
.IR n " = 0"
Skip loop.
\fIcode\fP is not executed but \*(ST parses until the loop's
end before continuing execution.
.TP
.IR n " < 0"
Infinite loop.
The loop does not terminate automatically but you must break
from it manually.
Consequently, if \fIn\fP is omitted the loop will be an
infinite one.
.LP
Additionally \*(ST supports special colon-modified
\(lqpass-through\(rq forms of the loop start and end commands
for processing the argument stack dynamically.
.SCITECO_TOPIC :>
The \fB:>\fP loop end command will \fInot\fP pop values left
on the stack since the beginning of the loop and can be used
to aggregate stack values.
For instance, the following command will leave the numbers
1 to 5 on the expression stack:
.SCITECO_TT
.EX
0Ua 5<%a:>
.SCITECO_TT_END
.EE
The command can be understood as equivalent to the expressions
\(lq(%a)(%a)(%a)(%a)(%a)\(rq or \(lq(%a,%a,%a,%a,%a)\(rq.
.SCITECO_TOPIC :<
Consequently, the colon-modified loop start command will
\fInot\fP represent an argument barrier and the corresponding
loop end command will not discard any values which is useful
for looping over the contents of the stack.
E.g. the following command will print the numbers 1 to 5
(actually every additional number argument):
.SCITECO_TT
.EX
1,2,3,4,5,-1:<"~1;'=>
.SCITECO_TT_END
.EE
If the loop start is colon-modified, the colon in front
of the loop end command is ignored if present.
.LP
Furthermore there are a number of flow control commands that
may be used in loops like \fBF<\fP and \fBF>\fP.
They are described in the reference section of this manual.
.
.SS Conditionals
.\" NOTE: Two quoted double-quotes are necessary to escape
.\" a single double quote in macro arguments
.SCITECO_TOPIC """" conditional if then else
.
Last but not least, \*(ST supports so called conditionals.
They correspond to structured IF-THEN-ELSE statements
in other imperative languages.
The general syntax of conditionals is as follows:
.br
\# [n]"c if [| else ]'
[\fIn\fP]\fB"\fIc if \fR[\fB|\fI else \fR] \fB'\fR
.br
Whereas \fIn\fP is a value on the stack to test,
\fIc\fP is a case-insignificant character identifying a
condition to check for,
\fIif\fP is a code block to execute if the condition applies and
\fIelse\fP is an optional code block to execute if the condition
does not apply.
The conditional pops at most one argument from the expression
stack \(em the remaining arguments may be evaluated by the
\fIif\fP or \fIelse\fP blocks.
Values accumulated on the expression stack by the \fIif\fP or \fIelse\fP
blocks are not discarded by the terminating single-quote.
In other words, conditionals may also return values.
The possible conditions are defined in the following list.
Unless \fIn\fP is defined optional, the conditionals described
below yield an error if \fIn\fP is omitted:
.TP
.SCITECO_TOPIC """~"
\# [n]"~
[\fIn\fP]\fB\(dq~\fP
Applies if \fIn\fP is \fBnot\fP given (i.e. the argument
stack is empty).
If \fIn\fP is given (i.e. the stack is not empty), it is \fBnot\fP
removed from the expression stack.
This construct is especially useful in macros to imply default
parameter values.
For instance the following macro inserts \fIn\fP tab characters
(one by default):
.SCITECO_TT
.EX
@^Ut{
  "~1'<9@I//>
}
.SCITECO_TT_END
.EE
.TP
.SCITECO_TOPIC """A"
.IB n \(dqA
Applies if \fIn\fP is the Unicode codepoint of an alphabetic character.
.TP
.SCITECO_TOPIC """C"
.IB n \(dqC
Applies if \fIn\fP is the Unicode codepoint of a symbol constituent.
Like in pattern matching, a symbol constituent is defined
as an alpha-numeric character, dot, dollar or underscore.
.TP
.SCITECO_TOPIC """D"
.IB n \(dqD
Applies if \fIn\fP is the Unicode codepoint of a digit character.
The current radix is insignificant.
.TP
.SCITECO_TOPIC """I"
.IB n \(dqI
Applies if \fIn\fP is the code of a directory separator
(e.g. \(lq/\(rq on UNIX, \(lq\\\(rq or \(lq/\(rq on Windows).
This is useful for macros that have to work with different
separator styles in a portable manner.
Note that, \*(ST itself is designed not to produce non-forward-slash
separators and at least allows the user to generate forward-slashes
in portable macros.
This is not the case, for instance when working with environment
registers.
.TP
.SCITECO_TOPIC """S" """T"
.IB n \(dqS
.TQ
.IB n \(dqT
Applies if \fIn\fP is a condition boolean signifying
success (or truth).
Therefore it is equivalent to a check for less than
zero (negative).
.TP
.SCITECO_TOPIC """F" """U"
.IB n \(dqF
.TQ
.IB n \(dqU
Applies if \fIn\fP is a condition boolean signifying
failure (or falsehood).
Therefore it is equivalent to a check for greater than
or equal to zero (non-negative).
.TP
.SCITECO_TOPIC """E" """="
.IB n \(dqE
.TQ
.IB n \(dq=
Applies if \fIn\fP equals zero.
.br
To check two values \fIa\fP and \fIb\fP for equality you
will commonly write:
.IB a - b \(dq=
.TP
.SCITECO_TOPIC """G" """>"
.IB n \(dqG
.TQ
.IB n \(dq>
Applies if \fIn\fP is greater than zero (positive).
.br
To check if a value \fIa\fP is greater than a value \fIb\fP you
will commonly write:
.IB a - b \(dq>
.TP
.SCITECO_TOPIC """L" """<"
.IB n \(dqL
.TQ
.IB n \(dq<
Applies if \fIn\fP is less than zero (negative).
.br
To check if a value \fIa\fP is less than a value \fIb\fP you
will commonly write:
.IB a - b \(dq<
.TP
.SCITECO_TOPIC """N"
.IB n \(dqN
Applies if \fIn\fP is not zero.
.br
To check two values \fIa\fP and \fIb\fP for inequality you
will commonly write:
.IB a - b \(dqN
.TP
.SCITECO_TOPIC """R"
.IB n \(dqR
Applies if \fIn\fP is the Unicode codepoint of an alpha-numeric character.
.TP
.SCITECO_TOPIC """V"
.IB n \(dqV
Applies if \fIn\fP is the Unicode codepoint of a lower-case alphabetic
character.
.TP
.SCITECO_TOPIC """W"
.IB n \(dqW
Applies if \fIn\fP is the Unicode codepoint of an upper-case alphabetic
character.
.LP
There are also a number of flow-control commands like
\fBF'\fP and \fBF|\fP that may be used in conditionals.
They are described in the reference section of this manual.
Note also that it is safe to invoke gotos and breaks from
loops in conditional blocks.
.
.
.SH COMMAND REFERENCE
.SCITECO_TOPIC reference
.
This section documents all of the commands supported by
\*(ST.
The command reference adheres to a few typographic conventions:
.RS
.IP \(bu 3
The first lines in each command subsection descibes the
command's syntax.
Each line corresponds to one alternative.
.IP \(bu
.RI [ ... ]
denotes an optional value or construct.
.IP \(bu
Alternatives are separated by \(lq|\(rq.
.IP \(bu
.I Italic
(or underlined) words refer to variable values or characters.
.IP \(bu
.B Bold
characters are of syntactic significance.
.IP \(bu
A right arrow (\(->) is followed by the command's return
values (i.e. values pushed onto the expression stack).
.IP \(bu
.B $
separates string arguments since the default string
terminator Escape (code 27) is echoed as a dollar sign
by \*(ST.
.RE
.LP
The same conventions are used elsewhere in this manual.
.
.\" Expanded with the command reference:
.TEDOC
.
.
.SH COMPATIBILITY
.
\*(ST is not compatible with any particular TECO dialect,
but is quite similar to
.BR "Video TECO" .
Most Video TECO and many Standard TECO programs should
be portable with little or no changes.
This manual mentions differences on several occasions.
.
.
.SH SEE ALSO
.
.\" FIXME: The URLs do not format in FreeBSD's man or in woman pages.
.TP
Program invocation and options:
.BR sciteco (1)
.TP
Scintilla messages and other documentation:
.UR http://scintilla.org/ScintillaDoc.html
Scintilla
.UE
.TP
Scinterm website, documenting the mapping of \(lqRGB\(rq values to terminal colors on curses user interfaces:
.UR https://orbitalquark.github.io/scinterm/
Scinterm website
.UE
.TP
Scintillua manual, detailing usage of Lua-based Scintilla lexers:
.UR https://orbitalquark.github.io/scintillua/manual.html
Scintillua manual
.UE
.TP
Suitable terminal fonts for icon support in Curses (see \fBED\fP flags):
.UR https://www.nerdfonts.com/
Nerd Fonts
.UE
.TP
Gtk+ 3 documentation, containg details about its CSS support and syntax:
.UR https://docs.gtk.org/gtk3/css-overview.html
Overview of CSS in GTK
.UE
.
.
.SH AUTHOR
.
This manpage and the \*(ST program was written by
.MT robin.haberkorn@googlemail.com
Robin Haberkorn
.ME .
\# EOF