Editor

Editor

syn-edit is SynapseOS's text editor. It is one engine behind three front ends — a terminal editor, a graphical window, and a scripting mode with no terminal at all — so an edit means the same thing whichever one you are using.

The engine is modal, and so is the terminal editor. The window is not: it stays in insert and takes the keys every other program on the desktop takes.

Front-end	Command
Terminal editor	syn-edit file.txt (the default), or syn-edit tui file.txt
The window	Editor in the start menu, or syn-edit gui file.txt
No terminal at all	syn-edit run -k KEYS file, syn-edit ex -c CMD file

It depends on nothing but libc.

---

The terminal editor is modal

Press i to start typing, Escape to stop, :w to write and :q to quit — vim's arrangement, because it is the one a text editor on a Unix system is expected to have and the one the scripting mode needs in order to be a scripting mode at all.

If you have never used a modal editor: the keys do different things depending on which mode you are in. In normal mode d deletes and i starts inserting; in insert mode they type a d and an i. Escape always takes you back to normal mode, and :q! always leaves without saving.

This is the terminal editor and the scripting mode. The window works the other way round — see In the window.

Syntax highlighting

The language is guessed from the file, and --lang NAME forces it.

syn-edit langs                    # every language that is highlighted
syn-edit highlight main.c         # the spans it found, without opening anything

Editing without a terminal

This is the part worth knowing about even if you use another editor. run applies a key sequence to a file and prints the result; ex does the same with ex commands only. Nothing is written unless you ask with -w.

syn-edit run -k 'ggdG' notes.md              # delete every line, print the result
syn-edit run -k 'ciwfoo<Esc>' file.c         # change a word
syn-edit ex  -c '%s/foo/bar/g' -w *.c        # substitute, and write it back
syn-edit run -k 'gg' --status file.c         # cursor, mode and message as records

Keys use vim notation, with <Esc>, <CR>, <Tab>, <BS>, <C-r> and the arrow keys spelled inside angle brackets; a literal < is <lt>.

This is how the editor's own test suite drives it, which is the reason it exists and the reason to trust it: the keys the window sends and the keys a script sends go through one engine, so they cannot come to mean different things.

Patterns

Patterns are POSIX basic regular expressions — the closest thing in libc to vim's default. \( \) group, \| alternates, \+ and \? repeat, and \< \> anchor to word boundaries. A pattern starting with \v is read as an extended regular expression instead, which is what vim's very-magic mode is.

syn-edit ex -c '%s/\<log\>/trace/g' -w app.c      # whole word
syn-edit ex -c '%s/\v(foo|bar)/baz/g'  -w app.c   # very-magic alternation

In the window

The window is not modal. It is always ready to type, and the keys are the ones every other program on the desktop uses:

Key	What it does
Ctrl+C / Ctrl+X / Ctrl+V	Copy, cut, paste. The desktop clipboard, and the whole line when nothing is selected
Ctrl+Z / Ctrl+Shift+Z	Undo, redo. Ctrl+Y redoes as well
Ctrl+A	Select all
Ctrl+F / Ctrl+R	Find, replace
Ctrl+S / Ctrl+O / Ctrl+N	Save, open, new
Shift+arrows	Extend the selection
Click and drag, double click	Select, and select a word
Escape	Drop the selection
Insert	Overwrite instead of inserting

Typing with something selected replaces it, and Backspace at the start of a line joins it onto the one above. Every one of those is the engine's own operation with the engine's own undo — the window holds no text, no selection and no undo stack of its own, which is why an edit made with the mouse and an edit made by a script cannot come to mean different things.

The document list

Down the left, full height, with a header of its own. Every open document is a row carrying its name and the folder it is in — which is what tells config.json in one project from config.json in another — with the current one marked by an accent bar, an amber dot for unsaved changes, and an ✕ on hover to close it.

Closing something with unsaved changes asks rather than refusing: save and close, discard, or cancel. If the write then fails — a read-only file, a full disk — it says so and keeps the document open, rather than closing it or reporting the wrong problem.

Drag the panel's right edge to size it. The width is written down, so a panel sized once stays sized; the Documents button in the toolbar hides it altogether. Closing the last document is not offered — that is what the window's own close button is for.

syn-edit config set treewidth 300     # the same width, typed
syn-edit config set tree false        # start with the panel hidden

A setting changed with a button or a drag in the window is written down. A :set typed at the command line is not — that is vim's, and vim's answer is "this session".

The rest of it

A scrollbar you can drag, a right-click menu, tabs above the text, and a task-list panel for - [ ] lines. Scrolling moves the caret first and the view second — an editor whose view can drift away from its cursor is an editor that types in the wrong place.

Vim keys are the terminal editor's. The window does not take them: Ctrl+V pastes here rather than starting a block selection, and Escape drops the selection rather than leaving insert.

Settings

syn-edit config list              # every setting and its value
syn-edit config set tabwidth 4
syn-edit config reset
syn-edit about                    # version, licence, and what works on this machine

For front-ends

serve runs the engine on stdin/stdout — it is what the window drives — and --rec prints the machine-readable records a front-end parses.

Every field of --rec output is percent-encoded, including the ones that look like plain words. A line of source code can contain a tab and a file name can contain any byte at all. Decode for display only.

Exit status: 0 success, 1 failure, 2 a usage problem.

See also

Commands · Files · Settings · Development Notes