NAME
INTRODUCTION AND PHILOSOPHY
KEY TRANSLATION
Key Macros
COMMANDLINE EDITING
Immediate Editing Commands
Undo and Redo
Auto Completion
USER INTERFACE
Colors and Theming
Gtk CSS Styling
ARITHMETICS AND EXPRESSIONS
Operators
BUFFER RING
Buffer Editing Hooks
COMMAND SYNTAX
Modifiers
Q-REGISTERS
Q-Register Specifications
Push-Down List
STRING-BUILDING CHARACTERS
PATTERN MATCH CHARACTERS
FILE NAMES AND DIRECTORIES
Glob Patterns
FLOW CONTROL
Gotos and Labels
Loops
Conditionals
COMMAND REFERENCE
Save last command line
Return buffer position
Return buffer size
Return range for entire buffer
Insert or read ASCII numbers
Conditionally break from loop
Edit command line
Go to position in buffer
Move dot <n> characters
Move dot <n> characters backwards
Move dot <n> lines forwards
Move dot <n> lines backwards
Move dot by words
Delete words forward
Delete word backwards
Show value as message
Kill lines
Delete characters
Get character code from buffer
Append digit
Go to loop start or jump to beginning of macro
Go to loop end or return from macro
Jump to end of conditional
Jump to else-part of conditional
Change working directory
Binary negation
Exit program immediately
Set radix to 8 (octal)
Set radix to 10 (decimal)
Set and get radix
Translate between glyph and byte indexes
Get ASCII code of character
Terminate command line or return from macro
Discard all arguments
Remove buffer from ring
Set and get ED-flags
Get and set system properties
Set or get End of Line mode
Edit current document’s encoding (codepage/charset)
Exit program
Insert text with string building characters
Insert text without string building characters
Insert with leading indention
Glob files or match filename and check file type
Go to label
Get help for topic
Save Q-Register
Restore Q-Register
Edit or load Q-Register
Save Q-Register string to file
Query Q-Register existence, its integer or string characters
Set or append to Q-Register string without string building
Set or append to Q-Register string with string building characters
Insert Q-Register string
Set Q-Register integer
Increase or decrease Q-Register integer
Execute macro
Execute macro from file
Copy into or append to Q-Register
Open or edit file
Save current buffer or Q-Register
Set or get search mode flag
Search for pattern
Search over buffer-boundaries
Delete up to occurrence of pattern
Delete occurrence of pattern
Search and replace
Search and replace with default
Execute operating system command and filter buffer contents
Set Q-Register to output of operating system command
Send Scintilla message
COMPATIBILITY
SEE ALSO
AUTHOR

---

NAME

sciteco −− Language reference for the SciTECO text editor and language

INTRODUCTION AND PHILOSOPHY

SciTECO is a powerful editor and interactive programming language following an unique paradigm of text editing. It is both different from popular screen editors like ex and traditional command-based editors like ed. 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 Vi or emacs 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), SciTECO represents a synthesis. In SciTECO the screen-editing and command languages are the same! The SciTECO 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, SciTECO 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.

SciTECO 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. SciTECO is not the first attempt to devise a TECO-based interactive screen editor. It is very similar to Video TECO, a little known editor that pioneered the concept. When Video TECO wanted to “outdo classic TECOs in every way”, SciTECO wants to outdo Video TECO in every way.

When using SciTECO in interactive mode, it is important to know exactly how SciTECO 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 SciTECO’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, SciTECO 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 — albeit limited — language for screen editing, SciTECO also supports regular commands for command-line editing.

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:

	1.		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, SciTECO 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.
	2.		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. SciTECO will always use latin letters regardless of the current keyboard layout. SciTECO 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 — typed CTRL+B — will be echoed “ˆB”. SciTECO also treats Caret-letter combinations equivalent to control codes under most circumstances.
	3.		A few keys with non-printable representation are translated to control codes as well. The most prominent is the Escape key — 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. “ˆI”).
	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.
	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.
	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 COMMANDLINE EDITING). By default they are inserted into the command line macro and are immediately executed.

While SciTECO handles keys with arbitrary Unicode representations, all immediate editing commands and regular SciTECO commands operate on a language based solely on ASCII codes, which is a subset of Unicode. Since the SciTECO parser is Unicode-aware, this does not exclude using Unicode glyphs wherever a single character is expected, i.e. ˆˆx and Uq works with arbitrary Unicode glyphs. All SciTECO macros must be in valid UTF-8.

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.

COMMANDLINE EDITING

After all key presses have been translated to characters SciTECO 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.

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.

Name	Code	Mnemonics	Context	Description
Toggle modifier	7	^G	Everywhere	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 ˆG (CTRL+G) effectively switches between undo and redo modes. The modifier also influences the behaviour of the TAB key.
Case insensitive command character	—	Any letter	Beginning of case-insensitive commands (automatic case folding enabled)	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 ED flags is set, e.g. by executing: 0,8ED
Insert end of line sequence	10	^J, Return, Enter	Everywhere (no automatic EOL translation)	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 SCI_GETEOLMODE Scintilla message. In auto-EOL-translation mode, the return key will always insert a line feed.
Rub out character	8	^H, Backspace	Everywhere (modifier disabled)	Rubs out the command line’s last character.
Re-insert character	8	^H, Backspace	Everywhere (modifier enabled)	Inserts the next character from the rubbed out part of the command line.
Rub out word/command	23	^W	Non-empty file name arguments (modifier disabled)	Rub out directory separator at end of filename and the last filename component up to but not inluding the preceding directory separator.
			Non-empty string arguments (modifier disabled)	Rub out last word according to Scintilla’s definition of a word as set by SCI_SETWORDCHARS.
			Miscelleaneous (modifier disabled)	Rub out last command, i.e. rub out at least one character until a new command could begin.
Re-insert word/command	23	^W	File name arguments (modifier enabled)	Re-insert next file name component up to and including the next directory separator from the rubbed-out command line.
			String arguments (modifier enabled)	Re-insert next word from the rubbed-out command line according to Scintilla’s definition of a word as set by SCI_SETWORDCHARS.
			Miscelleaneous (modifier enabled)	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.
Rub out string	21	^U	String arguments (modifier disabled)	Rub out the entire current string argument.
Re-insert string	21	^U	String arguments (modifier enabled)	Re-insert the entire current string argument from previously rubbed-out part of the command line, stopping at the string’s terminating character.
Auto complete Q-Register name	9	^I, Tab	Q-Register specifications	In all Q-Register specifications — either after a command with a Q-Register argument like M or as part of a string building construct like ˆEQ (of course including string building constructs within Q-Register specifications) — auto complete the local or global register name beginning at the start of the specification. In the case of one or two-letter specifications (#xy), only one or two-letter register names are considered for auto-completion. In the case of long specifications ([name]), fully completed names are terminated with a closing bracket, thus ending the specification.
Auto complete filename	9	^I, Tab	String arguments (modifier enabled)	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 ˆG modifier is enabled.
			Operating system command arguments
			File name arguments	Auto complete filename beginning at the start of the argument. Fully completed filenames terminate the string argument, except if the “{” terminator is used.
Auto complete directory	9	^I, Tab	Directory arguments	Auto complete directory beginning at the start of the argument.
Auto complete symbol	9	^I, Tab	Scintilla symbol arguments	In Scintilla Symbol arguments (ES commands), complete beginning with the symbol, terminating fully completed symbols with a comma.
Auto complete Goto label	9	^I, Tab	Goto command arguments	In Goto label arguments (O command), complete beginning with the current label, terminating fully completed labels with a comma.
Auto complete help topic	9	^I, Tab	Help topic arguments	In help topic arguments (? command), complete beginning at the start of the command. Fully completed topics terminate the string argument, effectively opening the corresponding womanpage, except if the “{” terminator is used.
Indent to next tab stop	9	^I, Tab	Text insertion arguments	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 ˆI command.
Suspend process	26	^Z	Everywhere	Suspends process using 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 — this will also work if SciTECO 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.
Interrupt	3	^C	SciTECO is busy	Not a real immediate editing command. Will interrupt the current operation (character processing), yielding a SciTECO error. On some GUIs it depends on asynchronous delivery of the SIGINT signal and is useful to interrupt infinite loops. Since not all user interfaces support interruptions via ˆC, it may be necessary to deliver the signal by pressing ˆC on the attached console or by explicitly sending it. If SciTECO is not busy, ˆC is self-inserting and might be typed as part of regular commands. The ˆC command itself is disallowed in interactive mode, though.

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.

USER INTERFACE

SciTECO can be built with support for different textual and graphical user interfaces. In SciTECO’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 SciTECO 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:

	•		The info area identifying the currently edited buffer or Q-Register. This area is currently sometimes omitted. If technically possible, SciTECO will include the same information in the window’s title.
	•		The Scintilla area displaying the current document’s contents. This corresponds to a Scintilla view (see section BUFFER RING) and can be customized extensively using Scintilla messages (see the ES command).
	•		The message area which will show the last SciTECO message that occurred. This area will show errors, warnings, “user messages” and other notes and tries to highlight them appropriately.
	•		The auto-completion popup area which is only shown when presenting the user with a choice of auto-completions. This area will overlap the Scintilla and message areas.
	•		The command line area, 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.

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 (light) blue 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.

ARITHMETICS AND EXPRESSIONS

SciTECO 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 n arguments and return n arguments. This is done using an integer value stack. The stack is used for passing arguments and for arithmetics. SciTECO 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 SciTECO 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 SciTECO build time however. In this specific build, integers are 64-bit.

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 SciTECO negative values (smaller than zero) represent success and non-negative values (larger than or equal to zero) represent failure. Therefore SciTECO booleans may be negated by performing a binary (bit by bit) negation for instance using the ˆ_ command.

Operators

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

base ^* power	Raise base to power.
a ^/ b	Remainder of a divided by b. It is actually a modulo operation conforming to the host C compiler’s modulo semantics.
a / b	Divide a by b. Naturally it is a division without remainder.
a * b	Multiply a by b.
a - b	Subtract b from a.
a + b	Add b to a.
a & b	Binary AND.
a ^# b	Binary exclusive OR (XOR).
a # b	Binary OR.

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 RING

SciTECO 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 SciTECO’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 “/” when accessing the current buffer’s file name with the “*” Q-Register. File names are always tried to be normalized to absolute paths to make them independant of SciTECO’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.

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 ES 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, ED hooks should be used (see below). Note that Q-Registers behave differently — they can also be edited like regular buffers but share one Scintilla instance for performance reasons.

SciTECO 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 “.” 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 EE command). The ˆE 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.

Currently, SciTECO supports buffers in UTF-8 and single-byte ANSI encodings, that can also be used for editing raw binary files. UTF-8 is the default codepage for new buffers and Q-Registers unless the 2nd ED flag bit is set. You can also specify --8bit to optimize SciTECO for 8-bit cleanliness. While navigation in documents with single-byte encodings takes place in constant time, SciTECO uses heuristics in UTF-8 documents for translating between byte and character offsets which are slower especially when “jumping” into very large lines.

To simplify working with files using different end of line sequences (combinations of carriage return and line feed), SciTECO implements an automatic EOL translation feature. When loading files with the EB and EQ commands — or when reading from an external process with the EC and EG commands — SciTECO 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 SciTECO is still saved as the corresponding Scintilla document’s EOL mode (see SCI_SETEOLMODE and the EL 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 EW and E% commands or when writing to an external process with the EC and EG 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 ED flag setting. It can be turned off by executing:
16,0ED
This may be beneficial when working with very large files — as the EOL translation imposes a performance penalty — 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.

For more details, please refer to this manual’s command reference.

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

COMMAND SYNTAX

SciTECO’s command syntax is quite flexible and diverse but may be categorized into some base command types.

	C
	EF		A simple command consists of one or more printable or control characters whose case is insignificant. Only at the beginning 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. “ˆJ”) are reserved for future use as operational commands. The command is executed as soon as it has been completely specified.
	Qq		A command identifier may be followed by a Q-Register specification q. It specifies a Q-Register to be accessed by the command (e.g. to query, set, increase).

Istring$
FSstring1$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.

Modifiers

A command’s behaviour or syntax may be influenced by so called modifiers written in front of commands. 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=
For instance if “1000C” would fail, “1000:C” will return 0 instead.

The at (@) modifier allows the string termination character to be changed for individual commands. The alternative termination character must be specified just before the first string argument. For instance:
@FS/foo/bar/
Any character may be used as an alternative termination character. There is one special case, though. If specified as the opening curly brace ({), a string argument will continue until the closing curly brace (}). 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:
@ˆUm{
@FS{foo}/bar/
}
The termination character can be quoted if you want to handle it like any regular character. For instance, you could write “SˆQ$$” to search for the escape character itself.

Q-REGISTERS

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

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. SciTECO 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. SciTECO initializes the Q-Registers “A” to “Z” and “0” to “9” in every Q-Register table.

There are global Q-Registers with special significance for SciTECO because they may be accessed by commands opaquely. Some of these registers represent information beyond their textual and numeric cells — they overwrite default operations with custom side-effects in order to support unique idioms. Some of the registers with special significance are initialized by SciTECO while others must be manually defined. The following list is an overview of all special global registers:
_ (underscore)

Search string and search condition register. Also used by the globbing command EN, so it is also the glob string and condition register. It is initialized automatically on startup.

- (minus)

Replacement string register. Its integer part is currently unused. It is initialized automatically on startup.

: (colon)

The current document’s position (dot). This changes dot when set as with the J and other movement commands. This allows you to change dot temporarily with the following idiom:
[: ! ...change dot... ! ]:
The string part of this register is currently unused.

* (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 tried to be made absolute paths by SciTECO, but this might not always be possible. Also, file names accessed with the “*” register will always have forward-slash directory separators even if they are displayed differently in the user interface. The “*” 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 “*” register is unsupported. Setting the numeric part of the “*” register, as in “1U*”, is equivalent to editing a buffer by id (e.g. “1EB$”) but is shorter since there is no string parameter. This allows the useful idioms of changing to the previous buffer with “-%*$”, changing to the next buffer with “%*$” and changing the current buffer temporarily:
[* ! ...change current buffer... ! ]*
The register is initialized automatically on startup.

$ (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 ˆU or EU commands which will change the current working directory in a manner similar to the FG command. This allows you to change the current directory temporarily with the following idiom:
[$ ! ...change current directory... ! ]$
As with FG, relative directories may be specified but querying “$” will still return an absolute path. The “$” register may also be edited but changing its string contents this way has no effect on the current working directory. Appending to the “$” register is unsupported. The register is initialized automatically on startup.

$ (Escape)

Command-line replacement register. Its integer part is unused. It is initialized automatically on startup.

$variable

Global Q-Registers beginning with a dollar sign that do not contain any “=” represent the process environment (the environment variables). The register “$” does not 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 SciTECO 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 sciteco(1).

˜clipboard

These registers constitute SciTECO’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. SciTECO thus initializes registers beginning with “˜” for every available clipboard either on startup or only when entering interactive mode. The register “˜” refers to the default clipboard which will always exist if clipboards are supported. Other commonly used clipboard registers are “˜P” for the primary selection, “˜S” for the secondary selection and “˜C” 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.
SciTECO does not generally support clipboards on ncurses, but has special support for OSC-52 escape sequences, as were introduced by sufficiently recent versions of 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 ED flags if and only if their terminal emulator is properly configured. xterm(1) for instance must be configured for allowing the SetSelection and GetSelection window operations. If running under xterm(1), SciTECO will still check whether the XTerm version is sufficient. Other terminal emulators like Kitty may ask for permission to read the clipboard (read-clipboard-ask). This is not supported by SciTECO and must be disabled (use read-clipboard instead). If native clipboard support is unavailable, users may still fall back to using external tools like xclip(1) with the EC command.
Setting the string part of a clipboard register will set that clipboard. SciTECO 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, SciTECO 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 not be guessed from the original clipboard contents, though. The numeric parts of the clipboard registers are currently not used by SciTECO.

ˆKkey

Key macro registers as documented in section 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.

ED

The ED hook Q-Register. Its string-content is called as a macro when bit 5 is set in the ED flags (see subsection Buffer Editing Hooks). The numeric part of register ED is currently unused and the register is not automatically initialized on startup.

Furthermore, SciTECO 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 local registers:
ˆR (CTRL+R)

The current radix as reported and configurable with the ˆR, ˆO and ˆD commands (10 by default). The string part of this register is currently unused.

ˆX (CTRL+X)

The current search mode flag as set and reported by the ˆ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.

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.

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

STRING-BUILDING CHARACTERS

As alluded to earlier SciTECO 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:

	1.		Carets followed by characters are translated to control codes, so “ˆa” and “ˆA” are equivalent to CTRL+A (code 1). A double caret “ˆˆ” 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.
	2.		String building characters are processed, resulting in expansions or translations of subsequent characters.
	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).

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:

	ˆQc
	ˆRc		Escape character c. The character is not handled as a string building or string termination character, so for instance “ˆQˆQ” translates to “ˆQ”. Furthermore, some immediate editing commands are inhibited right after ˆQ, so you can type “ˆQˆU” and “ˆQˆW”, which translate to control codes 21 and 23.
	ˆVˆV
	ˆVc		Translates all following characters, including the expansions of ˆEQ, ˆEU etc., into lower case. When ˆV is not followed by ˆV, a single character c is lower-cased.
	ˆWˆW
	ˆWc		Analogous to ˆV, but upper-cases characters. Since ˆW is an immediate editing command, this can practically be typed only with upcarets in interactive mode.
	ˆE\q		Expands to the formatted number stored in the numeric part of Q-Register q. The number is formatted according to the current radix and exactly the same as the backslash (\) 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.
	ˆEUq		Expands to the character whose code is stored in the numeric part of Q-Register q. For instance if register “A” contains the code 66, “ˆEUa” expands to the character “B”. The interpretation of this code depends on the context. Within inserts and searches (I, S, etc.) bytes or Unicode codepoints are expected depending on the buffer’s encoding. Operations on registers (EU) similarily consult the register’s encoding. Everything else expects Unicode codepoints.
	ˆEQq		Expands to the string contents of the Q-Register specified by q.
	ˆE@q		Expands to the shell-quoted string contents of the Q-Register specified by q. The quoting will be such that an UNIX98 “/bin/sh” will interpret the quoted string like the original contents of q. This is useful when generating UNIX shell code or when passing registers with unknown contents as parameters to external commands using the EC command.
	ˆENq		Expands to the string contents of the Q-Register specified by q 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 “*” or other special characters).
	ˆEc		All remaining ˆE combinations are passed down unmodified. Therefore ˆE pattern match characters do not have to be escaped.

PATTERN MATCH CHARACTERS

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

The following pattern match constructs are supported for matching one character in different character classes (caret-notations refer to the corresponding control characters):

	ˆQc
	ˆRc		Escape character c. Since these are interpreted as string building characters as well, you may have to type two or three ˆQ in a row to escape a pattern match character.
	ˆS
	ˆEB		Matches all non-alpha-numeric characters.
	ˆEA		Matches all alphabetic characters.
	ˆEC		Matches all symbol constituents. These are currently defined as alpha-numeric characters, dot (.) and dollar ($) signs.
	ˆED		Matches all digits.
	ˆEGq		Matches all characters in the string of the Q-Register specified by q, i.e. one of the characters in the register.
	ˆEL		Matches all line break characters. These are defined as carriage return, line-feed, vertial tab and form feed.
	ˆER		Matches all alpha-numeric characters.
	ˆEV		Matches all lower-case alphabetic characters.
	ˆEW		Matches all upper-case alphabetic characters.
	c		All other (non-magic) characters represent a class that contains only the character itself.

The following additional pattern match constructs are supported (caret-notations refer to the corresponding control characters):

	ˆX
	ˆEX		Matches any character.

ˆNclass

Matches any character not in class. All constructs listed above for matching classes may be used.

ˆEMpattern

Matches many occurrences (at least one) of pattern. Any pattern match construct and non-magic character may be used.

ˆES

Matches any sequence of whitespace characters (at least one). Whitespace characters are defined as line-break characters, the space and horizontal tab characters.

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

All non-pattern-match-characters match themselves. Note however that currently, all pattern matching is performed case-insensitive.

FILE NAMES AND DIRECTORIES

One class of SciTECO commands accepts file names or directory path arguments. The most prominent is the EB 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 FG command). Nevertheless, SciTECO will function properly after changing the working directory as SciTECO canonicalizes relative paths to absolute paths if necessary. Both buffer file names and some special Q-Registers corresponding to environment variables documented in sciteco(1) are canonicalized in this way.

The directory separator style (forward or backslash) accepted by SciTECO 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 SciTECO macros. File names queried via some SciTECO 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.

Currently all path name arguments also support string building characters. Therefore it is possible to refer to environment variables in path arguments. For instance, “ˆEQ[$HOME]/.teco_ini” will refer to the SciTECO profile on UNIX by default.

Even though the “HOME” environment variable is initialized to a sane value by SciTECO, it is cumbersome to type in frequently used commands. Therefore, SciTECO also supports UNIX-shell-like tilde-expansions. So for instance, the file name “˜/.teco_ini” also expands to the SciTECO profile on UNIX by default and is roughly equivalent to “ˆEQ[$HOME]/.teco_ini”. It is important to note that “˜” is not part of the file name proper (not even on UNIX) but a token that needs to be expanded first. In SciTECO this expansion takes place after processing string building characters. Unlike the UNIX-shell, SciTECO will only expand the current user’s home directory using the value of the “$HOME” environment register. Thus the “˜username” syntax is not supported.

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 COMMANDLINE EDITING.

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.

FLOW CONTROL

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

It is important to note that in contrast to classic TECOs and Video TECO, SciTECO 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, SciTECO 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. SciTECO will never ever jump into string arguments! Also SciTECO caches program counters in tables and dedicated stacks so that flow-control statements are generally faster than in classic TECOs.

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:>
The command can be understood as equivalent to the expressions “(%a)(%a)(%a)(%a)(%a)” or “(%a,%a,%a,%a,%a)”. Consequently, the colon-modified loop start command will not 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):
1,2,3,4,5,-1:<"˜1;’=>
If the loop start is colon-modified, the colon in front of the loop end command is ignored if present.

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.

COMMAND REFERENCE

This section documents all of the commands supported by SciTECO. The command reference adheres to a few typographic conventions:

	•		The first lines in each command subsection descibes the command’s syntax. Each line corresponds to one alternative.
	•		[...] denotes an optional value or construct.
	•		Alternatives are separated by “|”.
	•		Italic (or underlined) words refer to variable values or characters.
	•		Bold characters are of syntactic significance.
	•		A right arrow (→) is followed by the command’s return values (i.e. values pushed onto the expression stack).
	•		$ separates string arguments since the default string terminator Escape (code 27) is echoed as a dollar sign by SciTECO.

The same conventions are used elsewhere in this manual.

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:

	•		Command line editing only works on command lines, but not arbitrary macros. It is therefore not available in batch mode and will yield an error if used.
	•		Command line editing commands may be safely used from macro invocations. Such macros are called command line editing macros.
	•		A command line update from a macro invocation will always yield to the outer-most macro level (i.e. the command line macro). Code following the update command in the macro will thus never be executed.
	•		As a safe-guard against command line trashing due to erroneous changes at the beginning of command lines, a backup mechanism is implemented: If the updated command line yields an error at any command during the update, the original command line will be restored with an algorithm similar to command line updating and the update command will fail instead. That way it behaves like any other command that yields an error: The character resulting in the update is rejected by the command line input subsystem.
	•		In the rare case that an aforementioned command line backup fails, the commands following the erroneous character will not be inserted again (will be lost).

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.

	•		If n is positive, dot is positioned at the beginning of the word n words after the current one.
	•		If n is negative, dot is positioned at the end of the word n words before the current one.
	•		If n is zero, dot is not moved.

“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 n is 0, return the code of the character pointed to by dot.
	•		If n is 1, return the code of the character immediately after dot.
	•		If n is -1, return the code of the character immediately preceding dot, ecetera.
	•		If n is omitted, the sign prefix is implied.

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.

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.

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:

	•		4: If enabled, prefer raw single-byte ANSI encoding for all new buffers and registers. This does not change the encoding of any existing buffers and any initialized default register when set via ED, so you might want to launch SciTECO with --8bit.
	•		8: Enable/disable automatic folding of case-insensitive command characters during interactive key translation. The case of letter keys is inverted, so one or two character commands will typically be inserted upper-case, but you can still press Shift to insert lower-case letters. Case-insensitive Q-Register specifications are not case folded. This is thought to improve the readability of the command line macro.
	•		16: Enable/disable automatic translation of end of line sequences to and from line feed. Disabling this flag allows 8-bit clean loading and saving of files.
	•		32: Enable/Disable buffer editing hooks (via execution of macro in global Q-Register “ED”)
	•		128: Enable/Disable enforcement of UNIX98 “/bin/sh” emulation for operating system command executions
	•		256: Enable/Disable OSC-52 clipboard support. Must only be enabled if the terminal emulator is configured properly.
	•		512: Enable/Disable Unicode icons in the Curses UI. This requires a capable font, like the ones provided by the “Nerd Fonts” project. Changes to this flag in interactive mode may not become effective immediately.

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:

	0		The current user interface: 1 for Curses, 2 for GTK (read-only)
	1		The current numbfer of buffers: Also the numeric id of the last buffer in the ring. This is implied if no argument is given, so “EJ” returns the number of buffers in the ring. (read-only)
	2		The current memory limit in bytes. This limit helps to prevent dangerous out-of-memory conditions (e.g. resulting from infinite loops) by constantly sampling the memory requirements of SciTECO. Note that not all platforms support precise measurements of the current memory usage — SciTECO will fall back to an approximation which might be less than the actual usage on those platforms. Memory limiting is effective in batch and interactive mode. Commands which would exceed that limit will fail instead allowing users to recover in interactive mode, e.g. by terminating the command line. When getting, a zero value indicates that memory limiting is disabled. Setting a value less than or equal to 0 as in “0,2EJ” disables the limit. Warning: Disabling memory limiting may provoke out-of-memory errors in long running or infinite loops (interactive mode) that result in abnormal program termination. Setting a new limit may fail if the current memory requirements are too large for the new limit — if this happens you may have to clear your command-line first. Memory limiting is enabled by default.
	3		This write-only property allows redefining the first 16 entries of the terminal color palette — a feature required by some color schemes when using the Curses user interface. When setting this property, you are making a request to define the terminal color as the Scintilla-compatible RGB color value given in the rgb parameter. color must be a value between 0 and 15 corresponding to black, red, green, yellow, blue, magenta, cyan, white, bright black, bright red, etc. in that order. The rgb value has the format 0xBBGGRR, i.e. the red component is the least-significant byte and all other bytes are ignored. Note that on curses, RGB color values sent to Scintilla are actually mapped to these 16 colors by the Scinterm port and may represent colors with no resemblance to the “RGB” value used (depending on the current palette) — they should instead be viewed as placeholders for 16 standard terminal color codes. Please refer to the Scinterm manual for details on the allowed “RGB” values and how they map to terminal colors. This command provides a crude way to request exact RGB colors for the first 16 terminal colors. The color definition may be queued or be completely ignored on other user interfaces and no feedback is given if it fails. In fact feedback cannot be given reliably anyway. Note that on 8 color terminals, only the first 8 colors can be redefined (if you are lucky). Note that due to restrictions of most terminal emulators and some curses implementations, this command simply will not restore the original palette entry or request when rubbed out and should generally only be used in batch-mode — typically when loading a color scheme. For the same reasons — even though SciTECO tries hard to restore the original palette on exit — palette changes may persist after SciTECO terminates on most terminal emulators on Unix. The only emulator which will restore their default palette on exit the author is aware of is xterm(1) and the Linux console driver. You have been warned. Good luck.
	4		The column after the last horizontal movement. This is only used by fnkeys.tes and is similar to the Scintilla-internal setting SCI_CHOOSECARETX. Unless most other settings, this is on purpose not restored on rubout, so it "survives" command line replacements.

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:

	0		Carriage return (ASCII 13), followed by line feed (ASCII 10). This is the default EOL mode on DOS/Windows.
	1		Carriage return (ASCII 13). The default EOL mode on old Mac OS systems.
	2		Line feed (ASCII 10). The default EOL mode on POSIX/UNIX systems.

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:

	•		0: ANSI (raw bytes)
	•		1: ISO-8859-1 (latin1)
	•		77: Macintosh Latin encoding
	•		161: ISO-8859-7
	•		162: ISO-8859-9 (latin5)
	•		163: CP1258
	•		177: ISO-8859-8
	•		178: ISO-8859-6
	•		186: ISO-8859-13 (latin7)
	•		204: KOI8-R
	•		222: ISO-8859-11
	•		238: ISO-8859-2 (latin2)
	•		255: CP437
	•		866: CP866
	•		1000: ISO-8859-15 (latin9)
	•		1251: CP1251
	•		65001: UTF-8

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:

	0		No file type checking is performed. Note however, that when globbing only directory contents (of any type) are used, so without the filename argument, the value 0 is equivalent to 5.
	1		Only match regular files (no directories). Will also match symlinks to regular files (on platforms supporting symlinks).
	2		Only match symlinks. On platforms without symlinks (non-UNIX), this will never match anything.
	3		Only match directories.
	4		Only match executables. On UNIX, the executable flag is evaluated, while on Windows only the file name is checked.
	5		Only match existing files or directories. When globbing, this check makes no sense and is equivalent to no check at all. It may however be used to test that a filename refers to an existing file.

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
...
*!
In other words it must be a SciTECO comment followed by an asterisk sign, followed by the first topic which is a buffer position in bytes, followed by a colon and the topic string. The topic string is terminated by the end of the line. The end of the header is marked by a single “*!”. Topic terms should be specified with printable characters only (e.g. use Caret+A instead of CTRL+A). When looking up a help term, control characters are canonicalized to their printable form, so the term “ˆA” is found both by Caret+A and CTRL+A. Also, while topic terms are not case folded, lookup is case insensitive.

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
<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 to Q-Register

[lines] Xq
-Xq
from,toXq
[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.

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

S [pattern] $
[n] S [pattern] $
- S [pattern] $
from,toS [pattern] $
: 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$; ...>
Alternatively, S may be colon-modified in which case it returns a condition boolean that may be directly evaluated by a conditional or break-command.

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

FD [pattern] $
[n] FD [pattern] $
- FD [pattern] $
from,toFD [pattern] $
: 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

FS [pattern] $ [string] $
[n] FS [pattern] $ [string] $
- FS [pattern] $ [string] $
from,toFS [pattern] $ [string] $
: 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

FR [pattern] $ [string] $
[n] FR [pattern] $ [string] $
- FR [pattern] $ [string] $
from,toFR [pattern] $ [string] $
: 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:

	•		In the editor profile and batch mode in general, the ES command may be used freely.
	•		In the ED hook macro (register “ED”), when a file is added to the ring, most destructive operations can be performed since rubbing out the EB command responsible for the hook execution also removes the buffer from the ring again.
	•		As part of function key macros that immediately terminate the command line.

COMPATIBILITY

SciTECO is not compatible to any particular TECO dialect but is quite similar to Video TECO. Most Video TECO and many Standard TECO programs should be portable with little to no changes. This manual mentions differences on several occasions.

SEE ALSO

Program invocation and options:

sciteco(1)

Scintilla messages and other documentation:

Scintilla

Scinterm manual, documenting the mapping of “RGB” values to terminal
colors on curses user interfaces:

Scinterm manual

Suitable terminal fonts for icon support in Curses (see ED flags):

Nerd Fonts

Gtk+ 3 documentation, containg details about its CSS support and
syntax:

Overview of CSS in GTK

AUTHOR

This manpage and the SciTECO program was written by Robin Haberkorn.

---

*

IThis page was made with SciTECO.$-EX$$