Key Macros

By default function keys except Escape, Backspace and Return are ignored by SciTECO. 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 SciTECO, 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 ESCDELAY environment variable and if necessary a key macro can be defined as an escape surrogate as described in this section (fnkeys.tes defines the delete key as an escape surrogate for instance).

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:

^KDOWN

^KUP

Inserted when the down/up cursor keys are pressed.

^KLEFT

^KSLEFT

Inserted when the left or shift-left cursor keys are pressed.

^KRIGHT

^KSRIGHT

Inserted when the right or shift-right cursor keys are pressed.

^KHOME

^KSHOME

Inserted when the Home or shift-Home keys are pressed.

^KFx

Inserted when the Fx-key is pressed (x is a number between 0 and 63).

^KDC

^KSDC

Inserted when the Delete or shift-Delete key is pressed.

^KIC

^KSIC

Inserted when the Insert or shift-Insert key is pressed.

^KPPAGE

^KNPAGE

Inserted when the Page-Up or Page-Down key is pressed.

^KPRINT

^KSPRINT

Inserted when the Print or shift-Print key is pressed.

^KA1

^KA3

^KB2

^KC1

^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.

^KEND

^KSEND

Inserted when the End or shift-End key is pressed.

^KHELP

^KSHELP

Inserted when the Help or shift-Help key is pressed.

^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 SciTECO's window or when the SIGTERM signal is received. This allows customizing SciTECO'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 “^KCLOSE” macro is undefined: It unconditionally quits SciTECO. The default action is not performed when “^KCLOSE” has merely been masked out in the current parser state (see below).

^Kx

Any other key with printable representation and all control codes are looked up with a “^K” prefix. x can usually only be a single Unicode glyph. If undefined, x is inserted unmodified.

“^K” 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 — not all of them may be supported on any particular user interface.

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.

By default key macros are effective everywhere — 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 SciTECO parser states. Another common use of key macros would be to define aliases of SciTECO commands for non-latin keys on Curses. SciTECO therefore allows you to mask key macros in specific parser states by evaluating the Q-Register's numeric part, thus allowing you to control where a key macro is effective. The numeric part represents a bitmask of states where keys macros are disabled (so the default value 0 enables that key macro everywhere). SciTECO defines the following state flags:

1

Bit 0 represents the “start” state where SciTECO accepts the beginning of a command. This is the state you will want command line editing macros to be enabled in.

2

Bit 1 represents any string argument.

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.

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 “^KRIGHT” key macro only in the “start” state, you could set:

1^_U[^KRIGHT]

A set of useful key macros for function keys is provided in the standard library 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.

Immediate Editing Commands

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 SciTECO. 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.

Undo and Redo

The immediate editing commands that rub out and re-insert characters effectively constitute SciTECO's undo and redo support. As all features implemented by the immediate editing commands, undo and redo is only possible when using SciTECO interactively.

When a character is rubbed out, SciTECO 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.

Changes can be redone by typing the characters at the command line cursor or using one of the re-insertion commands — 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 ^G (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 SciTECO once you type or insert a character that is not a prefix of the rubbed out command line. This will also automatically disable the ^G modifier. The ^G modifier is disabled by default, so the corresponding commands work similar to their Unix shell counterparts.

Since SciTECO'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 SciTECO hits its configurable memory limit. It is therefore possible to terminate command lines using the $$ (double escape) command — or in other words by returning from the command line macro. Since this is a regular command respecting SciTECO's syntax, it is much less likely to accidentally terminate a command line than in classic TECOs where $$ is a special immediate editing key sequence. Command line termination will reclaim all undo-related resources without undoing any side effects, thus “persisting” or “committing” 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.

Auto Completion

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 no completion can be performed, the invocation will display a list of file names (or tokens) that begin with the token to complete in SciTECO'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.

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, SciTECO considers files and directories beginning with “.” as hidden. On Windows, the hidden file attribute is evaluated. On other platforms, SciTECO might not identify hidden files correctly.

Both forward and backslash directory separators are supported as arguments to SciTECO 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 “./”. This is useful for writing cross-platform SciTECO macros (see FILE NAMES AND DIRECTORIES).

Note that completions take place after string building and tilde-expansion is also performed by file name completions, so for instance both “~/foo” and “^EQ[$HOME]/foo” will complete a file in the user's home directory. Auto-completion also takes care of quoting string termination and string building characters, which might be relevant especially when autocompleting Q-Register names.

Colors and Theming

SciTECO supports customizing its look predominantly by setting up the current Scintilla view using Scintilla messages (see the ES 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.

The STYLE_DEFAULT (32) style defines the default foreground, background color, font etc. and is initialized to white on black with some monospaced font by SciTECO. The STYLE_DEFAULT is also accessed by SciTECO to style the info area, message area (if it is empty or when showing “user messages”) and command line area. 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 message area are currently hardcoded and cannot be customized. The command line area on the other hand will be styled with the original colors of STYLE_DEFAULT and should look similar to the current Scintilla view.

The STYLE_CALLTIP (38) style is also accessed by SciTECO to style the popup area and is initialized to black on white by SciTECO.

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 EJ command).

Scintilla styles will usually be set up in the profile macro or ED hook (for syntax highlighting). SciTECO ships with a standard library with color schemes and lexer configurations for a wide range of languages.

Gtk CSS Styling

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.

Therefore SciTECO automatically exports the following Gtk CSS variables that can be referred to by user-provided CSS files:

@sciteco_default_fg_color

The foreground color of Scintilla's STYLE_DEFAULT.

@sciteco_default_bg_color

The background color of Scintilla's STYLE_DEFAULT.

@sciteco_calltip_fg_color

The foreground color of Scintilla's STYLE_CALLTIP.

@sciteco_calltip_bg_color

The background color of Scintilla's STYLE_CALLTIP.

Furthermore, SciTECO defines named widgets for its main UI components as well as several CSS classes.

The CSS file is loaded from $SCITECOCONFIG/.teco_css if it is existing. Else, SciTECO loads the fallback CSS at /usr/local/share/sciteco/fallback.css, which can also be used as a template when writing .teco_css. The fallback CSS can also be consulted for additional documentation on SciTECO's named widgets and special CSS classes. The CSS file can be written such that it works for any SciTECO color scheme and may also be used to tweak other aspects of SciTECO's user interface. Please refer to the Gtk documentation for more details on CSS theming.

Operators

The following binary operators are supported with descending precedence, whereas borders separate operators of the same precedence:

All binary operators are left-associative, i.e. associate from left to right, in SciTECO. Round brackets may be used for grouping expressions to override operator precedence and associativity. For instance, since “^/”, “/” and “*” all have the same precedence, the expression “1 ^/ 2 / 3 * 4” is equivalent to “(((1 ^/ 2) / 3) * 4)”. 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. SciTECO currently performs minimal checking on the validity of braces (i.e. the closing brace “command”) 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 $$ 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 SciTECO.

Another construct that may be used as an argument barrier to explicitly separate arguments is the comma (“,”). It is obligatory when trying to push a sequence of number constants like in “1,2” but is optional in many contexts where it is mandatory in classic TECO, like in “.ZD”. I recommend to use it as much as possible in code where clarity matters.

The arithmetic evaluation order established by the operator precedence or braces must not be confused with the execution order of SciTECO commands which is always strictly from left to right (unless flow control commands are used).

The only unary operator currently supported is “-”. The minus-operator is special and has unique semantics. It sets the so called prefix sign which is 1 by default to -1. This prefix sign may be evaluated by commands — most often it is the default value if the argument stack is empty so that expressions like “-C” are roughly equivalent to “-1C”. However in front of opening brackets, like in “-(1+2)”, it is roughly equivalent to “-1*(1+2)” 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.

Buffer Editing Hooks

When opening or editing a file with the EB command or when closing a file with the EF 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. SciTECO thus provides user-configurable hooks into buffer editing operations. Hooks are by default disabled. To enable them, set bit 5 in the ED flags:

0,32ED

SciTECO will now execute the macro in global Q-Register “ED” whenever a relevant operation is performed. This macro must be provided if ED hooks are enabled.

The “ED” macro will receive an argument that specifies the type of operation that has just been performed or is just about to be performed. The “ED” macro is executed in a more or less isolated way by SciTECO, 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, ED hooks should not interfere with the stack-semantics of commands triggering them.

Possible arguments to the “ED” 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:

1

A file has been added to the buffer ring. It may or may not already exist in the file system. This file is SciTECO's current document when this hook executes. Scintilla lexing may be configured in this hook — it usually only has to be done once.

2

A buffer has been edited (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 “ED” macro. In this hook you may want to define language-specific auxiliary macros, for instance.

3

A buffer is about to be closed (removed from the buffer ring). The buffer that is about to be closed, is still the current document when this hook runs.

4

SciTECO is about to quit, i.e. exit normally. This is SciTECO's equivalent of atexit(3) handlers. The hook is not run when some command fails, but only when SciTECO exits normally. This is the case when control in a macro specified via --eval reaches the end, or otherwise returns (using ^C or by returning from the top-level macro via $$). Similarily the hook is executed when a munged file calls ^C or EX has been called before the top-level macro returns. It is also called after the interactive mode has shut down by calling EX$$. The quit hook will always run in batch mode (after any user interface has shut down). Errors in the hook's execution will not prevent SciTECO from exiting, but an error trace will be printed and SciTECO exit code will be a failure code. It is not possible to cancel program termination via quit hooks. The quit hook may be used to transparently save a buffer session, for instance.

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.

The SciTECO standard library contains a framework for configuring Scintilla lexing and other useful hooks (see lexer.tes).

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.

The colon (:) modifier usually prevents a command from failing and instructs it to return a condition (success/failure) boolean instead.

1000:C=

Two colons (::) can sometimes further modify a command's behavior — currently it is used by the ::S search comparison command. On all other commands it will behave like a single colon.

When put in front of a command with string arguments, the at (@) 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:

@FS/foo/bar/

@^Um{


  @FS{foo}/bar/
}

The at (@) modifier may also sometimes be supported by commands, that do not accept string arguments. For instance, @Xq cuts text into Q-Register q.

Q-Register Specifications

Q-Registers may be referred to by commands using Q-Register specifications:

c

.c

Refers to a one character Q-Register. The one character name is upper-cased. All one character names except for “.”, “^” and “#” can be referenced this way. If lead by a dot, the name refers to a local Q-Register, otherwise to a global one.

^c

.^c

Refers to a Q-Register, whose name is a single byte control code. Those can be typed with upcarets as well.

#cc

.#cc

Refers to a two character global or local Q-Register whose name is upper-cased.

[name]

.[name]

Refers to a Q-Register with an arbitrary name. The name is not upper-cased. String building characters may be used so that Q-Register names may be calculated. Curly braces can be used in name 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 “a” and “A” are equivalent to “[A]”.

Push-Down List

Another data structure supported by SciTECO 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 [q and ]q commands. For instance to search in a macro without overwriting the contents of the search register you could write:

[_ Sfoo$ ]_

To copy the string and numeric contents of register “A” to “B”, you could write “[a ]b”.

Glob Patterns

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 EN and EB commands). SciTECO glob patterns mimic the POSIX fnmatch(3) syntax, but work uniformly across all platforms. The following wildcard constructs are supported:

*

Matches an arbitary number of characters or no character at all.

?

Matches a single arbitrary character.

[set]

Matches one character in the given character set. For instance “[ch]” matches both “c” and “h”. A hyphen may be used to specify character ranges as in “[0-9]” to match all decimal digits. Within a character class, the “*” and “?” wildcards have no special meanings and represent their corresponding characters. To include a hypen in the set, write it first or last. To include a closing bracket in the set, write it first, as in “[]ch]”.

[^set]

[!set]

Matches one character which is not in the given character set. Otherwise behaves exactly like [set].

All other characters match themselves. Brackets can be used to escape wildcard characters. For instance, “[*]” may be used to match a literal asterisk. To facilitate passing filenames verbatim to commands accepting glob patterns, there is the ^ENq string building construct which automatically escapes glob pattern wildcards.

Gotos and Labels

The most basic flow control command in SciTECO 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. SciTECO may do simple unconditional and computed gotos.

Labels are symbolic and are defined with the following syntax:
!label!
Whereas label is an arbitrary string. String building is not performed on label, 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. Terminating a macro execution (or command line) fails if a label that is jumped to has not been defined. Labels also have another important role in SciTECO — they are used as comments.

Loops

Gotos may be used for looping, but SciTECO also supports a dedicated structured looping construct. Its syntax is as follows:
[n]< code >
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 ^[ command). The opening bracket takes an optional argument n. If n is omitted, -1 is implied. The loops behaviour depends on the value of n:

n > 0

Execute code exactly n times. You may break from the loop earlier though, using the semicolon (;) command.

n = 0

Skip loop. code is not executed but SciTECO parses until the loop's end before continuing execution.

n < 0

Infinite loop. The loop does not terminate automatically but you must break from it manually. Consequently, if n is omitted the loop will be an infinite one.

Additionally SciTECO supports special colon-modified “pass-through” forms of the loop start and end commands for processing the argument stack dynamically. The :> loop end command will not 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:

0Ua 5<%a:>

1,2,3,4,5,-1:<"~1;'=>

Furthermore there are a number of flow control commands that may be used in loops like F< and F>. They are described in the reference section of this manual.

Conditionals

Last but not least, SciTECO supports so called conditionals. They correspond to structured IF-THEN-ELSE statements in other imperative languages. The general syntax of conditionals is as follows:
[n]"c if [| else ] '
Whereas n is a value on the stack to test, c is a case-insignificant character identifying a condition to check for, if is a code block to execute if the condition applies and else is an optional code block to execute if the condition does not apply. The conditional pops at most one argument from the expression stack — the remaining arguments may be evaluated by the if or else blocks. Values accumulated on the expression stack by the if or else 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 n is defined optional, the conditionals described below yield an error if n is omitted:

[n]"~

Applies if n is not given (i.e. the argument stack is empty). If n is given (i.e. the stack is not empty), it is not removed from the expression stack. This construct is especially useful in macros to imply default parameter values. For instance the following macro inserts n tab characters (one by default):

@^Ut{


  "~1'<9@I//>
}
    

n"A

Applies if n is the Unicode codepoint of an alphabetic character.

n"C

Applies if n 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.

n"D

Applies if n is the Unicode codepoint of a digit character. The current radix is insignificant.

n"I

Applies if n is the code of a directory separator (e.g. “/” on UNIX, “\” or “/” on Windows). This is useful for macros that have to work with different separator styles in a portable manner. Note that, SciTECO 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.

n"S

n"T

Applies if n is a condition boolean signifying success (or truth). Therefore it is equivalent to a check for less than zero (negative).

n"F

n"U

Applies if n is a condition boolean signifying failure (or falsehood). Therefore it is equivalent to a check for greater than or equal to zero (non-negative).

n"E

n"=

Applies if n equals zero.
To check two values a and b for equality you will commonly write: a-b"=

n"G

n">

Applies if n is greater than zero (positive).
To check if a value a is greater than a value b you will commonly write: a-b">

n"L

n"<

Applies if n is less than zero (negative).
To check if a value a is less than a value b you will commonly write: a-b"<

n"N

Applies if n is not zero.
To check two values a and b for inequality you will commonly write: a-b"N

n"R

Applies if n is the Unicode codepoint of an alpha-numeric character.

n"V

Applies if n is the Unicode codepoint of a lower-case alphabetic character.

n"W

Applies if n is the Unicode codepoint of an upper-case alphabetic character.

There are also a number of flow-control commands like F' and F| 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.

Save last command line

*q

Only at the very beginning of a command-line, this command may be used to save the last command line as a string in Q-Register q

Return buffer position

. → dot

“.” pushes onto the stack, the current position (also called dot ) of the currently selected buffer or Q-Register.

dot is also available in Q-Register “:”.

Return buffer size

Z → size

Pushes onto the stack, the size of the currently selected buffer or Q-Register. This is value is also the buffer position of the document's end.

Return range for entire buffer

H → 0, Z

Pushes onto the stack the integer 0 (position of buffer beginning) and the current buffer's size. It is thus often equivalent to the expression “0,Z”, or more generally “(0,Z)”.

Insert or read ASCII numbers

n\
\ → n

Backslash pops a value from the stack, formats it according to the current radix and inserts it in the current buffer or Q-Register at dot. If n is omitted (empty stack), it does the reverse - it reads from the current buffer position an integer in the current radix and pushes it onto the stack. Dot is not changed when reading integers.

In other words, the command serializes or deserializes integers as ASCII characters.

Conditionally break from loop

[bool] ;
[bool] :;

Breaks from the current inner-most loop if bool signifies failure (non-negative value). If colon-modified, breaks from the loop if bool signifies success (negative value).

If the condition code cannot be popped from the stack, the global search register's condition integer is implied instead. This way, you may break on search success/failures without colon-modifying the search command (or at a later point).

Executing “;” outside of iterations in the current macro invocation level yields an error. It is thus not possible to let a macro break a caller's loop.

Edit command line

{
}

The opening curly bracket is a powerful command to edit command lines but has very simple semantics. It copies the current commandline into the global command line editing register (called Escape, i.e. ASCII 27) and edits this register. The curly bracket itself is not copied.

The command line may then be edited using any SciTECO command or construct. You may switch between the command line editing register and other registers or buffers. The user will then usually reapply (called update) the current command-line.

The closing curly bracket will update the current command-line with the contents of the global command line editing register. To do so it merely rubs-out the current command-line up to the first changed character and inserts all characters following from the updated command line into the command stream. To prevent the undesired rubout of the entire command-line, the replacement command ("}") is only allowed when the replacement register currently edited since it will otherwise be usually empty.

Note:

Go to position in buffer

[position] J
[position] : J → Success|Failure

Sets dot to position If position is omitted, 0 is implied and “J” will go to the beginning of the buffer.

If position is outside the range of the buffer, the command yields an error. If colon-modified, the command will instead return a condition boolean signalling whether the position could be changed or not.

Move dot <n> characters

[n] C
- C
[n] : C → Success|Failure

Adds n to dot. 1 or -1 is implied if n is omitted. Fails if n would move dot off-page. The colon modifier results in a success-boolean being returned instead.

Move dot <n> characters backwards

[n] R
- R
[n] : R → Success|Failure

Subtracts n from dot. It is equivalent to “-nC”.

Move dot <n> lines forwards

[n] L
- L
[n] : L → Success|Failure

Move dot to the beginning of the line specified relatively to the current line. Therefore a value of 0 for n goes to the beginning of the current line, 1 will go to the next line, -1 to the previous line etc. If n is omitted, 1 or -1 is implied depending on the sign prefix.

If n would move dot off-page, the command yields an error. The colon-modifer results in a condition boolean being returned instead.

Move dot <n> lines backwards

[n] B
- B
[n] : B → Success|Failure

Move dot to the beginning of the line n lines before the current one. It is equivalent to “-nL”.

Move dot by words

[n] W
- W
[n] : W → Success|Failure

Move dot n words forward.

“W” uses Scintilla's definition of a word as configurable using the SCI_SETWORDCHARS message.

Otherwise, the command's behaviour is analogous to the “C” command.

Delete words forward

[n] V
- V
[n] : V → Success|Failure

Deletes the next n words until the end of the n'th word after the current one. If n is negative, deletes up to end of the n'th word before the current one. If n is omitted, 1 or -1 is implied depending on the sign prefix.

It uses Scintilla's definition of a word as configurable using the SCI_SETWORDCHARS message.

If the words to delete extend beyond the range of the buffer, the command yields an error. If colon-modified it instead returns a condition code.

Delete word backwards

[n] Y
- Y
[n] : Y → Success|Failure

Delete n words backward. n Y is equivalent to “-nV”.

Show value as message

<n>=

Shows integer n as a message in the message line and/or on the console. It is currently always formatted as a decimal integer and shown with the user-message severity. The command fails if n is not given.

Kill lines

[n] K
- K
from,to K
[n] : K → Success|Failure
from,to: K → Success|Failure

Deletes characters up to the beginning of the line n lines after or before the current one. If n is 0, “K” will delete up to the beginning of the current line. If n is omitted, the sign prefix will be implied. So to delete the entire line regardless of the position in it, one can use “0KK”.

If the deletion is beyond the buffer's range, the command will yield an error unless it has been colon-modified so it returns a condition code.

If two arguments from and to are available, the command is synonymous to from , to D.

Delete characters

[n] D
- D
from,to D
[n] : D → Success|Failure
from,to: D → Success|Failure

If n is positive, the next n characters (up to and character .+ n ) are deleted. If n is negative, the previous n characters are deleted. If n is omitted, the sign prefix will be implied.

If two arguments can be popped from the stack, the command will delete the characters with absolute position from up to to from the current buffer.

If the character range to delete is beyond the buffer's range, the command will yield an error unless it has been colon-modified so it returns a condition code instead.

Get character code from buffer

[n] A → code
- A → code

Returns the character code of the character n relative to dot from the buffer. This can be an ASCII code or Unicode codepoint depending on Scintilla's encoding of the current buffer. Invalid Unicode byte sequences are reported as -1 or -2.

If the position of the queried character is off-page, the command will yield an error.

If the document is encoded as UTF-8 and there is an incomplete sequence at the requested position, -1 is returned. All other invalid Unicode sequences are returned as -2.

Append digit

[n] 0|1|2|3|4|5|6|7|8|9 → n*Radix+ X

Integer constants in SciTECO may be thought of and are technically sequences of single-digit commands. These commands take one argument from the stack (0 is implied), multiply it with the current radix (2, 8, 10, 16, ...), add the digit's value and return the resultant integer.

The command-like semantics of digits may be abused in macros, for instance to append digits to computed integers. It is not an error to append a digit greater than the current radix - this may be changed in the future.

Go to loop start or jump to beginning of macro

F <
: F <

Immediately jumps to the current loop's start. Also works from inside conditionals.

This command behaves exactly like > with regard to colon-modifiers.

Outside of loops — or in a macro without a loop — this jumps to the beginning of the macro.

Go to loop end or return from macro

F >
: F >

Jumps to the current loop's end. If the loop has remaining iterations or runs indefinitely, the jump is performed immediately just as if “>” had been executed. If the loop has reached its last iteration, SciTECO will parse until the loop end command has been found and control resumes after the end of the loop.

In interactive mode, if the loop is incomplete and must be exited, you can type in the loop's remaining commands without them being executed (but they are parsed).

This command behaves exactly like > with regard to colon-modifiers.

Calling F> outside of a loop at the current macro invocation level is equivalent to calling $$ (terminate command line or return from macro).

Jump to end of conditional

F ´

Jump to else-part of conditional

F |

Jump to else-part of conditional or end of conditional (only if invoked from inside the condition's else-part).

Change working directory

FG [directory] $

Changes the process' current working directory to directory which affects all subsequent operations on relative file names like tab-completions. It is also inherited by external processes spawned via EC and EG.

If directory is omitted, the working directory is changed to the current user's home directory as set by the HOME environment variable (i.e. its corresponding “$HOME” environment register). This variable is always initialized by SciTECO (see sciteco(1)). Therefore the expression “FG$” is exactly equivalent to both “FG~$” and “FG^EQ[$HOME]$”.

The current working directory is also mapped to the special global Q-Register “$” (dollar sign) which may be used retrieve the current working directory.

String-building characters are enabled on this command and directories can be tab-completed.

Binary negation

n^_ → ~n

Binary negates (complements) n and returns the result. Binary complements are often used to negate SciTECO booleans.

Exit program immediately

^ C

Lets the top-level macro return immediately regardless of the current macro invocation frame. This command is only allowed in batch mode, so it is not invoked accidentally when using the CTRL+C immediate editing command to interrupt long running operations. When using ^C in a munged file, interactive mode is never started, so it behaves effectively just like “-EX$$” (when executed in the top-level macro at least).

The quit hook is still executed.

Set radix to 8 (octal)

^ O

Set radix to 10 (decimal)

^ D

Set and get radix

radix^ R
^ R → radix

Set current radix to any value radix larger than or equal to 2. If radix is omitted, the command instead returns the current radix.

An alternative way to access the radix is via the “^R” local Q-Register. Consequently, the radix is local to the current macro invocation frame, unless the macro call was colon-modified.

Convert between lines and glyph lengths or positions

[n] ^ Q → glyphs
[position] :^ Q → line

Converts between line and glyph arguments. It returns the number of glyphs between dot and the n -th next line (or previous line if n is negative). Consequently “^QC” is equivalent to “L”, but less efficient.

If colon-modified, an absolute buffer position is converted to the line that contains this position, beginning with 1. Without arguments, “:^Q” returns the current line.

Translate between glyph and byte indexes

glyphs^ E → bytes
bytes:^ E → glyphs
^ E → bytes
:^ E → length

Translates from glyph/character to byte indexes when called without a colon. Otherwise when colon-modified, translates from byte indexes back to glyph indexes. These values can differ in documents with multi-byte encodings (of which only UTF-8 is supported). It is especially useful to translate between these indexes when manually invoking Scintilla messages (ES command), as they almost always take byte positions.

When called without arguments, ^E returns the current position (dot) in bytes. This is equivalent, but faster than “.^E”. :^E without arguments returns the length of the current document in bytes, which is equivalent but faster than “Z^E”.

When passing in indexes outside of the document's valid area, -1 is returned, so the return value can also be interpreted as a TECO boolean, signalling truth/success for invalid indexes. This provides an elegant and effective way to validate buffer addresses.

Return range of last pattern match, subexpression or text insertion

[n] ^ Y → start, end

This command returns the buffer ranges of the subpatterns of the last pattern match (search command) or of the last text insertion. n specifies the number of the subpattern from left to right. The default value 0 specifies the entire matched pattern, while higher numbers refer to ^E[...] subpatterns. ^Y can also be used to return the buffer range of the last text insertion by any SciTECO command (I, EI, ^I, Gq, \, EC, EN, etc). In this case n is only allowed to be 0 or missing.

For instance, “^YXq” copies the entire matched pattern or text insertion into register q.

Return negative length of last pattern match, subexpression or text insertion

[n] ^ S → -length
-^ S → length

Returns the negative length of the subpatterns of the last pattern match (search command) or of the last text insertion. n specifies the number of the subpattern from left to right and defaults to 0 (the entire pattern match or text insertion). “^S” is equivalent to “^YU1U0 Q0-Q1”. Without arguments, the sign prefix negates the result, i.e. returns the length of the entire matched pattern or text insertion.

A common idiom “^SC” can be used for jumping to the beginning of the matched pattern or inserted string.

Get ASCII code of character

^^c → n

Returns the ASCII code of the character c that is part of the command. Can be used in place of integer constants for improved readability. For instance ^^A will return 65.

Note that this command can be typed CTRL+Caret or Caret-Caret.

Terminate command line or return from macro

[a1,a2,...]$$
[a1,a2,...]^[$

Returns from the current macro invocation. This will pass control to the calling macro immediately and is thus faster than letting control reach the macro's end. Also, direct arguments to $$ will be left on the expression stack when the macro returns. $$ closes loops automatically and is thus safe to call from loop bodies. Furthermore, it has defined semantics when executed from within braced expressions: All braces opened in the current macro invocation will be closed and their values discarded. Only the direct arguments to $$ will be kept.

Returning from the top-level macro in batch mode will exit the program or start up interactive mode depending on whether program exit has been requested. “EX$$” is thus a common idiom to exit prematurely.

In interactive mode, returning from the top-level macro (i.e. typing $$ at the command line) has the effect of command line termination. The arguments to $$ are currently not used when terminating a command line — the new command line will always start with a clean expression stack.

The first escape of $$ may be typed either as an escape character (ASCII 27), in up-arrow mode (e.g. ^[$) or as a dollar character — the second character must be either a real escape character or a dollar character.

Discard all arguments

$
^[

Pops and discards all values from the stack that might otherwise be used as arguments to following commands. Therefore it stops popping on stack boundaries like they are introduced by arithmetic brackets or loops.

Note that ^[ is usually typed using the Escape key. CTRL+[ however is possible as well and equivalent to Escape in every manner. The up-arrow notation however is processed like any ordinary command and only works at the begining of a command. Additionally, this command may be written as a single dollar character.

Remove buffer from ring

[bool] EF
- EF

Removes buffer from buffer ring, effectively closing it. If the buffer is dirty (modified), EF will yield an error. bool may be a specified to enforce closing dirty buffers. If it is a Failure condition boolean (negative), the buffer will be closed unconditionally. If bool is absent, the sign prefix (1 or -1) will be implied, so “-EF” will always close the buffer.

It is noteworthy that EF will be executed immediately in interactive mode but can be rubbed out at a later time to reopen the file. Closed files are kept in memory until the command line is terminated.

Set and get ED-flags

flags ED
[off,]on ED
ED → flags

With arguments, the command will set the ED flags. flags is a bitmap of flags to set. Specifying one argument to set the flags is a special case of specifying two arguments that allow to control which flags to enable/disable. off is a bitmap of flags to disable (set to 0 in ED flags) and on is a bitmap of flags that is ORed into the flags variable. If off is omitted, the value 0^_ is implied. In otherwords, all flags are turned off before turning on the on flags. Without any argument ED returns the current flags.

Currently, the following flags are used by SciTECO:

The features controlled thus are discribed in other sections of this manual.

The default value of the ED flags is 16 (only automatic EOL translation enabled).

Get and set system properties

[key] EJ → value
- EJ → value
value,keyEJ
rgb,color,3 EJ

This command may be used to get and set system properties. With one argument, it retrieves a numeric property identified by key. If key is omitted, the prefix sign is implied (1 or -1). With two arguments, it sets property key to value and returns nothing. Some property keys may require more than one value. Properties may be write-only or read-only.

The following property keys are defined:

Set or get End of Line mode

0 EL
13,10: EL
1 EL
13: EL
2 EL
10: EL
EL → 0 | 1 | 2
: EL → 13,10 | 13 | 10

Sets or gets the current document's End Of Line (EOL) mode. This is a thin wrapper around Scintilla's SCI_SETEOLMODE and SCI_GETEOLMODE messages but is shorter to type and supports restoring the EOL mode upon rubout. Like the Scintilla message, EL does not change the characters in the current document. If automatic EOL translation is activated (which is the default), SciTECO will however use this information when saving files or writing to external processes.

With one argument, the EOL mode is set according to these constants:

In its colon-modified form, the EOL mode is set according to the EOL characters on the expression stack. SciTECO will only pop as many values as are necessary to determine the EOL mode.

Without arguments, the current EOL mode is returned. When colon-modified, the current EOL mode's character sequence is pushed onto the expression stack.

Edit current document's encoding (codepage/charset)

codepageEE
EE → codepage
codepage: EE
: EE → codepage

When called with an argument, it sets the current codepage, otherwise returns it. The following codepages are supported:

Displaying characters in the single-byte (non-UTF-8) codepages might be supported only with the Gtk UI. At least 77, 178, 163 and 255 are not displayed correctly on Gtk. 65001 (UTF-8) is the default for new buffers. 0 (ANSI) should be used when working with raw bytes, but is currently displayed like ISO-8859-1 (latin1).

EE does not change the buffer contents itself by default, only how it is displayed and how SciTECO interacts with it. This allows fixing up the codepage if it is not in the default UTF-8 or if codepage guessing failed.

When colon-modified the :EE command will also additionally convert the current buffer contents into the new code page, preserving the current position (dot). This will fail if the conversion would be lossy. Conversions from and to UTF-8 should always be successful.

Exit program

[bool] EX
- EX
: EX

Exits SciTECO, or rather requests program termination at the end of the top-level macro. Therefore instead of exiting immediately which could be annoying in interactive mode, EX will result in program termination only when the command line is terminated. This allows EX to be rubbed out and used in macros. The usual command to exit SciTECO in interactive mode is thus “EX$$”. In batch mode EX will exit the program if control reaches the end of the munged file — instead of starting up interactive mode.

If any buffer is dirty (modified), EX will yield an error. When specifying bool as a success/truth condition boolean, EX will not check whether there are modified buffers and will always succeed. If bool is omitted, the sign prefix is implied (1 or -1). In other words “-EX$$” is the usual interactive command sequence to discard all unsaved changes and exit.

When colon-modified, bool is ignored and EX will instead immediately try to save all modified buffers — this can of course be reversed using rubout. Saving all buffers can fail, e.g. if the unnamed file is modified or if there is an IO error. “:EX$$” is nevertheless the usual interactive command sequence to exit while saving all modified buffers.

Insert text with string building characters

[c1,c2,...] I [text] $

First inserts characters for all the values on the argument stack (interpreted as codepoints). It does so in the order of the arguments, i.e. c1 is inserted before c2 , ecetera. Secondly, the command inserts text In interactive mode, text is inserted interactively.

Unlike in classic TECO dialects, string building characters are enabled for the I command. When editing SciTECO macros, using the EI command may be better, since it has string building characters disabled.

Insert text without string building characters

[c1,c2,...] EI [text] $

Inserts text at the current position in the current document. This command is identical to the I command, except that string building characters are disabled. Therefore it may be beneficial when editing SciTECO macros.

Insert with leading indention

[char,...]^ I [text] $

^I (usually typed using the Tab key), first inserts all the chars on the stack into the buffer, then indention characters (one tab or multiple spaces) and eventually the optional text is inserted interactively. It is thus a derivate of the I (insertion) command.

SciTECO uses Scintilla settings to determine the indention characters. If tab use is enabled with the SCI_SETUSETABS message, a single tab character is inserted. Tab use is enabled by default. Otherwise, a number of spaces is inserted up to the next tab stop so that the command's text argument is inserted at the beginning of the next tab stop. The size of the tab stops is configured by the SCI_SETTABWIDTH Scintilla message (8 by default). In combination with SciTECO's use of the tab key as an immediate editing command for all insertions, this implements support for different insertion styles. The Scintilla settings apply to the current Scintilla document and are thus local to the currently edited buffer or Q-Register.

However for the same reason, the ^I command is not fully compatible with classic TECO which always inserts a single tab character and should not be used for the purpose of inserting single tabs in generic macros. To insert a single tab character reliably, the idioms “9I$” or “I^I$” may be used.

Like the I command, ^I has string building characters enabled.

Glob files or match filename and check file type

[type] EN [pattern] $ [filename] $
[type] : EN [pattern] $ [filename] $ → Success|Failure

EN is a powerful command for performing various tasks given a glob pattern. For a description of the glob pattern syntax, refer to the section Glob Patterns for details.

pattern may be omitted, in which case it defaults to the pattern saved in the search and glob register “_”. If it is specified, it overwrites the contents of the register “_” with pattern. This behaviour is similar to the search and replace commands and allows for repeated globbing/matching with the same pattern. Therefoe you should also save the “_” register on the Q-Register stack when calling EN from portable macros.

If filename is omitted (empty), EN may be used to expand a glob pattern to a list of matching file names. This is similar to globbing on UNIX but not as powerful and may be used e.g. for iterating over directory contents. E.g. “EN*.c$$” expands to all “.c” files in the current directory. The resulting file names have the exact same directory component as pattern (if any). Without filename, EN will currently only match files in the file name component of pattern, not on each component of the path name separately. In other words, EN only looks through the directory of pattern — you cannot effectively match multiple directories.

If filename is specified, pattern will only be matched against that single file name. If it matches, filename is used verbatim. In this form, pattern is matched against the entire file name, so it is possible to match directory components as well. filename does not necessarily have to exist in the file system for the match to succeed (unless a file type check is also specified). For instance, “ENf??/∗.c$foo/bar.c$” will always match and the string “foo/bar.c” will be inserted (see below).

By default, if EN is not colon-modified, the result of globbing or file name matching is inserted into the current document, at the current position. The file names will be separated by line feeds, i.e. every matching file will be on its own line.

EN may be colon-modified to avoid any text insertion. Instead, a boolean is returned that signals whether any file matched pattern. E.g. “:EN*.c$$” returns success (-1) if there is at least one “.c” file in the current directory.

The results of EN may be filtered by specifying a numeric file type check argument. This argument may be omitted (as in the examples above) and defaults to 0, i.e. no additional checking. The following file type check values are currently defined:

For instance, “3EN*$$” will expand to all subdirectories in the current directory. The following idiom may be used to check whether a given filename refers to a regular file: 1:EN*$filename$

Note that both without colon and colon modified forms of EN save the success or failure of the operation in the numeric part of the glob register “_” (i.e. the same value that the colon modified form would return). The command itself never fails because of failure in matching any files. E.g. if “EN*.c$$” does not match any files, the EN command is still successful but does not insert anything. A failure boolean would be saved in “_”, though.

String-building characters are enabled for EN and both string arguments are considered file names with regard to auto-completions.

Go to label

Olabel$
[n] Olabel1[,label2,...]$

Go to label The simple go-to command is a special case of the computed go-to command. A comma-separated list of labels may be specified in the string argument. The label to jump to is selected by n (1 is label1 , 2 is label2 , etc.). If n is omitted, 1 is implied.

If the label selected by n is does not exist in the list of labels, the command does nothing. Label definitions are cached in a table, so that if the label to go to has already been defined, the go-to command will jump immediately. Otherwise, parsing continues until the label is defined. The command will yield an error if a label has not been defined when the macro or command-line is terminated. In the latter case, the user will not be able to terminate the command-line.

Get help for topic

? [topic] $

Look up topic in the help index, opening the corresponding womanpage as a buffer and scrolling to the topic's position. The help index is built when this command is first executed, so the help system does not consume resources when not used (e.g. in a batch-mode script).

SciTECO's help documents must be installed in the directory $SCITECOPATH/women, i.e. as part of the standard library. Each document consist of at least one plain-text file with the extension “.woman”. Optionally, a SciTECO script with the extension “.woman.tec” can be installed alongside the main document to define topics covered by this document and set up styling.

The beginning of the script must be a header of the form:

!*position:topic1
position2:topic2
...
*!

The rest of the script is not read by SciTECO internally but should contain styling for the main document. It is usually read by the standard library's lexer configuration system when showing a womanpage. If the “.woman.tec” macro is missing, SciTECO will define a single topic for the document based on the “.woman” file's name.

The combination of plain-text document and script is called a “womanpage” because these files are usually generated using groff(1) with the grosciteco formatter and the sciteco.tmac GNU troff macros. When using womanpages generated by grosciteco, help topics can be defined using the SCITECO_TOPIC Troff macro. This flexible system allows SciTECO to access internal and third-party help files written in plain-text or with an arbitrary GNU troff macro package. As all GNU troff documents are processed at build-time, GNU troff is not required at runtime.

The ? command does not have string building enabled.

Save Q-Register

[q

Save Q-Register q contents on the global Q-Register push-down stack.

Restore Q-Register

]q

Restore Q-Register q by replacing its contents with the contents of the register saved on top of the Q-Register push-down stack. The stack entry is popped.

In interactive mode, the original contents of q are not immediately reclaimed but are kept in memory to support rubbing out the command. Memory is reclaimed on command-line termination.

Edit or load Q-Register

EQq$
EQq [file] $

When specified with an empty file string argument, EQ makes q the currently edited Q-Register. Otherwise, when file is specified, it is the name of a file to read into Q-Register q When loading a file, the currently edited buffer/register is not changed and the edit position of register q is reset to 0.

Undefined Q-Registers will be defined. The command fails if file could not be read.

Save Q-Register string to file

E %q<file>$

Saves the string contents of Q-Register q to file The file must always be specified, as Q-Registers have no notion of associated file names.

In interactive mode, the E% command may be rubbed out, restoring the previous state of file This follows the same rules as with the EW command.

File names may also be tab-completed and string building characters are enabled by default.

Query Q-Register existence, its integer or string characters

Qq → n
-Qq → -n
<position>Qq → character
:Qq → -1 | size

Without any arguments, get and return the integer-part of Q-Register q

With one argument, return the character code at position from the string-part of Q-Register q Positions are handled like buffer positions — they begin at 0 up to the length of the string minus 1. An error is thrown for invalid positions. If q is encoded as UTF-8 and there is an incomplete sequence at the requested position, -1 is returned. All other invalid Unicode sequences are returned as -2. Both non-colon-modified forms of Q require register q to be defined and fail otherwise.

When colon-modified, Q does not pop any arguments from the expression stack and returns the size of the string in Q-Register q if register q exists (i.e. is defined). Naturally, for empty strings, 0 is returned. When colon-modified and Q-Register q is undefined, -1 is returned instead. Therefore checking the return value :Q for values smaller 0 allows checking the existence of a register. Note that if q exists, its string part is not initialized, so :Q may be used to handle purely numeric data structures without creating Scintilla documents by accident. These semantics allow the useful idiom “:Qq">” for checking whether a Q-Register exists and has a non-empty string. Note also that the return value of :Q may be interpreted as a condition boolean that represents the non-existence of q If q is undefined, it returns success, else a failure boolean.

Set or append to Q-Register string without string building

[c1,c2,...]^Uq [string] $
[c1,c2,...]:^Uq [string] $

If not colon-modified, it first fills the Q-Register q with all the values on the expression stack (interpreted as codepoints). It does so in the order of the arguments, i.e. c1 will be the first character in q , c2 the second, etc. Eventually the string argument is appended to the register. Any existing string value in q is overwritten by this operation.

In the colon-modified form ^U does not overwrite existing contents of q but only appends to it.

If q is undefined, it will be defined.

String-building characters are disabled for ^U commands. Therefore they are especially well-suited for defining SciTECO macros, since string building characters in the desired Q-Register contents do not have to be escaped. The EU command may be used where string building is desired.

Set or append to Q-Register string with string building characters

[c1,c2,...]EUq [string] $
[c1,c2,...]:EUq [string] $

This command sets or appends to the contents of Q-Register q. It is identical to the ^U command, except that this form of the command has string building characters enabled.

Insert Q-Register string

Gq

Inserts the string of Q-Register q into the buffer at its current position. Specifying an undefined q yields an error.

Set Q-Register integer

nUq
-Uq
[n] :Uq → Success|Failure

Sets the integer-part of Q-Register q to n “-U” is equivalent to “-1U”, otherwise the command fails if n is missing.

If the command is colon-modified, it returns a success boolean if n or “-” is given. Otherwise it returns a failure boolean and does not modify q

The register is defined if it does not exist.

Increase or decrease Q-Register integer

[n] %q → q+n
-%q → q-1

Add n to the integer part of register q , returning its new value. If n is omitted, the sign prefix is implied. q will be defined if it does not exist.

Execute macro

Mq
:Mq

Execute macro stored in string of Q-Register q The command itself does not push or pop and arguments from the stack but the macro executed might well do so. The new macro invocation level will contain its own go-to label table and local Q-Register table. Except when the command is colon-modified - in this case, local Q-Registers referenced in the macro refer to the parent macro-level's local Q-Register table (or whatever level defined one last).

Errors during the macro execution will propagate to the M command. In other words if a command in the macro fails, the M command will fail and this failure propagates until the top-level macro (e.g. the command-line macro).

Note that the string of q will be copied upon macro execution, so subsequent changes to Q-Register q from inside the macro do not modify the executed code.

While M does not check the register's configured encoding (as reported by EE), its contents must be and are checked to be in valid UTF-8.

Execute macro from file

EMfile$
:EMfile$

Read the file with name file into memory and execute its contents as a macro. It is otherwise similar to the “M” command.

If file could not be read, the command yields an error.

As all SciTECO code, the contents of file must be in valid UTF-8 even if operating in the “default ANSI” mode as configured by ED.

Copy into or append or cut to Q-Register

[lines] Xq
-Xq
from,toXq
[lines] :Xq
-:Xq
from,to:Xq
[lines] @Xq
-@Xq
from,to@Xq
[lines] :@Xq
-:@Xq
from,to:@Xq

Copy the next or previous number of lines from the buffer into the Q-Register q string. If lines is omitted, the sign prefix is implied. If two arguments are specified, the characters beginning at position from up to the character at position to are copied. The semantics of the arguments is analogous to the K command's arguments.

If the command is colon-modified (:), the characters will be appended to the end of register q instead. If the command is at-modified (@), the text will be removed from the buffer after copying or appending to the Q-Register, thus performing a cut operation. The order of modifiers is as always insignificant.

Register q will be created if it is undefined.

Open or edit file

[n] EB [file] $
nEB$

Opens or edits the file with name file If file is not in the buffer ring it is opened, added to the ring and set as the currently edited buffer. If it already exists in the ring, it is merely made the current file. file may be omitted in which case the default unnamed buffer is created/edited. If an argument is specified as 0, EB will additionally display the buffer ring contents in the window's popup area. Naturally this only has any effect in interactive mode.

file may also be a glob pattern, in which case all regular files matching the pattern are opened/edited. Globbing is performed exactly the same as the EN command does. Also refer to the section called Glob Patterns for more details.

File names of buffers in the ring are normalized by making them absolute. Any comparison on file names is performed using guessed or actual absolute file paths, so that one file may be referred to in many different ways (paths).

file does not have to exist on disk. In this case, an empty buffer is created and its name is guessed from file When the newly created buffer is first saved, the file is created on disk and the buffer's name will be updated to the absolute path of the file on disk.

File names may also be tab-completed and string building characters are enabled by default.

If n is greater than zero, the string argument must be empty. Instead n selects a buffer from the ring to edit. A value of 1 denotes the first buffer, 2 the second, ecetera.

Save current buffer or Q-Register

EW $
EWfile$

Saves the current buffer to disk. If the buffer was dirty, it will be clean afterwards. If the string argument file is not empty, the buffer is saved with the specified file name and is renamed in the ring.

The EW command also works if the current document is a Q-Register, i.e. a Q-Register is edited. In this case, the string contents of the current Q-Register are saved to file Q-Registers have no notion of associated file names, so file must be always specified.

In interactive mode, EW is executed immediately and may be rubbed out. In order to support that, SciTECO creates so called save point files. It does not merely overwrite existing files when saving but moves them to save point files instead. Save point files are called “.teco-n-filename~”, where filename is the name of the saved file and n is a number that is increased with every save operation. Save point files are always created in the same directory as the original file to ensure that no copying of the file on disk is necessary but only a rename of the file. When rubbing out the EW command, SciTECO restores the latest save point file by moving (renaming) it back to its original path — also not requiring any on-disk copying. SciTECO is impossible to crash, but just in case it still does it may leave behind these save point files which must be manually deleted by the user. Otherwise save point files are deleted on command line termination.

File names may also be tab-completed and string building characters are enabled by default.

Set or get search mode flag

mode^ X
-^ X
^ X → mode

The search mode is interpreted as a TECO boolean. A true value (smaller than zero) configures case-sensitive searches, while a false value (larger than or equal to zero) configures case-insensitive searches. “-^X” is equivalent to “-1^X” and also enables case-sensitive searches. Searches are case-insensitive by default.

An alternative way to access the search mode is via the “^X” local Q-Register. Consequently, the search mode is local to the current macro invocation frame, unless the macro call was colon-modified.

Search for pattern

[n] S [pattern] $
- S [pattern] $
from,toS [pattern] $
[n] : S [pattern] $ → Success|Failure
-: S [pattern] $ → Success|Failure
from,to: S [pattern] $ → Success|Failure
[n] :: S [pattern] $ → Success|Failure
-:: S [pattern] $ → Success|Failure
from,to:: S [pattern] $ → Success|Failure

Search for pattern in the current buffer/Q-Register. Search order and range depends on the arguments given. By default without any arguments, S will search forward from dot till file end. The optional single argument specifies the occurrence to search (1 is the first occurrence, 2 the second, etc.). Negative values for n perform backward searches. If missing, the sign prefix is implied for n Therefore “-S” will search for the first occurrence of pattern before dot.

If two arguments are specified on the command, search will be bounded in the character range from up to to , and only the first occurrence will be searched. from might be larger than to in which case a backward search is performed in the selected range.

After performing the search, the search pattern is saved in the global search Q-Register “_”. A success/failure condition boolean is saved in that register's integer part. pattern may be omitted in which case the pattern of the last search or search and replace command will be implied by using the contents of register “_” (this could of course also be manually set).

After a successful search, the pointer is positioned after the found text in the buffer. An unsuccessful search will display an error message but not actually yield an error. The message displaying is suppressed when executed from loops and register “_” is the implied argument for break-commands so that a search-break idiom can be implemented as follows:

<Sfoo$; ...>

When modified with two colons, the search will be anchored in addition to returning a condition boolean, i.e. it can be used to perform a string comparison. “::S” without arguments compares the pattern against the current buffer position. With a single positive integer n , “::S” matches n repititions of the given pattern. With a negative integer n , “::S” will match the n-th last occurrence of the pattern from the beginning of the buffer (which is not really useful). With two integer arguments, “::S” compares the pattern against the corresponding part of the buffer.

In interactive mode, searching will be performed immediately (“search as you type”) highlighting matched text on the fly. Changing the pattern results in the search being reperformed from the beginning.

Search over buffer-boundaries

[n] N [pattern] $
- N [pattern] $
from,toN [pattern] $
[n] : N [pattern] $ → Success|Failure
-: N [pattern] $ → Success|Failure
from,to: N [pattern] $ → Success|Failure

Search for pattern over buffer boundaries. This command is similar to the regular search command (S) but will continue to search for occurrences of pattern when the end or beginning of the current buffer is reached. Occurrences of pattern spanning over buffer boundaries will not be found. When searching forward N will start in the current buffer at dot, continue with the next buffer in the ring searching the entire buffer until it reaches the end of the buffer ring, continue with the first buffer in the ring until reaching the current file again where it searched from the beginning of the buffer up to its current dot. Searching backwards does the reverse.

N also differs from S in the interpretation of two arguments. Using two arguments the search will be bounded between the buffer with number from , up to the buffer with number to When specifying buffer ranges, the entire buffers are searched from beginning to end. from may be greater than to in which case, searching starts at the end of buffer from and continues backwards until the beginning of buffer to has been reached. Furthermore as with all buffer numbers, the buffer ring is considered a circular structure and it is possible to search over buffer ring boundaries by specifying buffer numbers greater than the number of buffers in the ring.

Delete up to occurrence of pattern

FK [pattern] $
[n] FK [pattern] $
- FK [pattern] $
from,toFK [pattern] $
: FK [pattern] $ → Success|Failure
[n] : FK [pattern] $ → Success|Failure
-: FK [pattern] $ → Success|Failure
from,to: FK [pattern] $ → Success|Failure

FK searches for pattern just like the regular search command (S) but when found deletes all text from dot up to but not including the found text instance. When searching backwards the characters beginning after the occurrence of pattern up to dot are deleted.

In interactive mode, deletion is not performed as-you-type but only on command termination.

Delete occurrence of pattern

[n] FD [pattern] $
- FD [pattern] $
from,toFD [pattern] $
[n] : FD [pattern] $ → Success|Failure
-: FD [pattern] $ → Success|Failure
from,to: FD [pattern] $ → Success|Failure
[n] :: FD [pattern] $ → Success|Failure
-:: FD [pattern] $ → Success|Failure
from,to:: FD [pattern] $ → Success|Failure

Searches for pattern just like the regular search command (S) but when found deletes the entire occurrence.

Search and replace

[n] FS [pattern] $ [string] $
- FS [pattern] $ [string] $
from,toFS [pattern] $ [string] $
[n] : FS [pattern] $ [string] $ → Success|Failure
-: FS [pattern] $ [string] $ → Success|Failure
from,to: FS [pattern] $ [string] $ → Success|Failure
[n] :: FS [pattern] $ [string] $ → Success|Failure
-:: FS [pattern] $ [string] $ → Success|Failure
from,to:: FS [pattern] $ [string] $ → Success|Failure

Search for pattern just like the regular search command (S) does but replace it with string if found. If string is empty, the occurrence will always be deleted so “FS[pattern]$$” is similar to “FD[pattern]$”. The global replace register is not touched by the FS command.

In interactive mode, the replacement will be performed immediately and interactively.

Search and replace with default

[n] FR [pattern] $ [string] $
- FR [pattern] $ [string] $
from,toFR [pattern] $ [string] $
[n] : FR [pattern] $ [string] $ → Success|Failure
-: FR [pattern] $ [string] $ → Success|Failure
from,to: FR [pattern] $ [string] $ → Success|Failure
[n] :: FR [pattern] $ [string] $ → Success|Failure
-:: FR [pattern] $ [string] $ → Success|Failure
from,to:: FR [pattern] $ [string] $ → Success|Failure

The FR command is similar to the FS command. It searches for pattern just like the regular search command (S) and replaces the occurrence with string similar to what FS does. It differs from FS in the fact that the replacement string is saved in the global replacement register “-”. If string is empty the string in the global replacement register is implied instead.

Execute operating system command and filter buffer contents

ECcommand$
linesECcommand$
-ECcommand$
from,toECcommand$
:ECcommand$ → Success|Failure
lines:ECcommand$ → Success|Failure
-:ECcommand$ → Success|Failure
from,to:ECcommand$ → Success|Failure

The EC command allows you to interface with the operating system shell and external programs. The external program is spawned as a background process and its standard input stream is fed with data from the current document, i.e. text is piped into the external program. When automatic EOL translation is enabled, this will translate all end of line sequences according to the source document's EOL mode (see EL command). For instance when piping from a document with DOS line breaks, the receiving program will only be sent DOS line breaks. The process' standard output stream is also redirected and inserted into the current document. End of line sequences are normalized accordingly but the EOL mode guessed from the program's output is not set on the document. The process' standard error stream is discarded. If data is piped into the external program, its output replaces that data in the buffer. Dot is always left at the end of the insertion.

If invoked without parameters, no data is piped into the process (and no characters are removed) and its output is inserted at the current buffer position. This is equivalent to invoking “.,.EC”. If invoked with one parameter, the next or previous number of lines are piped from the buffer into the program and its output replaces these lines This effectively runs command as a filter over lines “-EC” may be written as a short-cut for “-1EC”. When invoked with two parameters, the characters beginning at position from up to the character at position to are piped into the program and replaced with its output. This effectively runs command as a filter over a buffer range.

Errors are thrown not only for invalid buffer ranges but also for errors during process execution. If the external command has an unsuccessful exit code, the EC command will also fail. If the EC command is colon-modified, it will instead return a TECO boolean signifying success or failure. In case of an unsuccessful exit code, a colon-modified EC will return the absolute value of the process exit code (which is also a TECO failure boolean) and 0 for all other failures. This feature may be used to take action depending on a specific process exit code.

command execution is by default platform-dependent. On DOS-like systems like Windows, command is passed to the command interpreter specified in the $COMSPEC environment variable with the “/q” and “/c” command-line arguments. On UNIX-like systems, command is passed to the interpreter specified by the $SHELL environment variable with the “-c” command-line argument. Therefore the default shell can be configured using the corresponding environment registers. The operating system restrictions on the maximum length of command-line arguments apply to command and quoting of parameters within command is somewhat platform dependent. On all other platforms, SciTECO will uniformly parse command just as an UNIX98 “/bin/sh” would, but without performing any expansions. The program specified in command is searched for in standard locations (according to the $PATH environment variable). This mode of operation can also be enforced on all platforms by enabling bit 7 in the ED flag, e.g. by executing “0,128ED”, and is recommended when writing cross-platform macros using the EC command.

When using an UNIX-compatible shell or the UNIX98 shell emulation, you might want to use the ^E@ string-building character to pass Q-Register contents reliably as single arguments to the spawned process.

The spawned process inherits both SciTECO's current working directory and its environment variables. More precisely, SciTECO uses its environment registers to construct the spawned process' environment. Therefore it is also straight forward to change the working directory or some environment variable temporarily for a spawned process.

Note that when run interactively and subsequently rubbed out, SciTECO can easily undo all changes to the editor state. It cannot however undo any other side-effects that the execution of command might have had on your system.

Note also that the EC command blocks indefinitely until the command completes, which may result in editor hangs. You may however interrupt the spawned process by sending the SIGINT signal to SciTECO, e.g. by pressing CTRL+C. The first time, this will try to kill the spawned process gracefully. The second time you press CTRL+C, it will hard kill the process.

In interactive mode, SciTECO performs TAB-completion of filenames in the command string parameter but does not attempt any escaping of shell-relevant characters like whitespaces.

Set Q-Register to output of operating system command

EGq command$
linesEGq command$
-EGq command$
from,toEGq command$
:EGq command$ → Success|Failure
lines:EGq command$ → Success|Failure
-:EGq command$ → Success|Failure
from,to:EGq command$ → Success|Failure

Runs an operating system command and set Q-Register q to the data read from its standard output stream. Data may be fed to command from the current buffer/document. The interpretation of the parameters and command as well as the colon-modification is analoguous to the EC command.

The EG command only differs from EC in not deleting any characters from the current buffer, not changing the current buffer position and writing process output to the Q-Register q In other words, the current buffer is not modified by EG. Also since EG replaces the string value of q , the register's EOL mode is set to the mode guessed from the external program's output.

The register q is defined if it does not already exist.

Send Scintilla message

[lParam,][wParam,] [message] ES [message] [,wParam]$ [lParam] $ → result

Send Scintilla message with code specified by message , wParam and lParam message and wParam may be a symbolic names when specified as part of the first string argument. If not, they are popped from the stack. lParam may be specified as a constant string whose pointer is passed to Scintilla if specified as the second string argument. It is automatically null-terminated. If the second string argument is empty, lParam is popped from the stack instead. Parameters popped from the stack may be omitted, in which case 0 is implied. The message's return value is pushed onto the stack.

All messages defined by Scintilla (as C macros in Scintilla.h) can be used by passing their name as a string to ES (e.g. ESSCI_LINESONSCREEN...). The “SCI_” prefix may be omitted and message symbols are case-insensitive. Only the Lexilla style names (SCE_...) may be used symbolically with the ES command as wParam In interactive mode, symbols may be auto-completed by pressing Tab. String-building characters are by default interpreted in the string arguments.

As a special exception, you can and must specify a Lexilla lexer name as a string argument for the SCI_SETILEXER message, i.e. in order to load a Lexilla lexer (this works similar to the old SCI_SETLEXERLANGUAGE message).

Warning: Almost all Scintilla messages may be dispatched using this command. SciTECO does not keep track of the editor state changes performed by these commands and cannot undo them. You should never use it to change the editor state (position changes, deletions, etc.) or otherwise rub out will result in an inconsistent editor state. There are however exceptions: