EDIT(1) General Commands Manual EDIT(1)
NAME
edit - simple text editor
SYNOPSIS
edit file
DESCRIPTION
edit is a modal, terminal-based text editor. It aims to provide a
simple yet powerful editing model, in a suckless-style codebase.
edit uses a selection-centric, selection-then-action model inspired by
kakoune, where a selection is a set of contiguous characters on a given
line. Indeed, most commands act on a list of selections: on saved
selections if any, otherwise on running selections.
By default, the running selections list contains only the cursor,
making the selection abstraction invisible for simple editing. It is
also possible to drop an anchor below the cursor, making running
selections contain all characters between the anchor and the cursor.
For more elaborate editing, such as multi-cursor or column editing,
there are several ways to save selections.
OPTIONS
-v prints version information to stderr, then exits.
USAGE
The default mode is the normal mode, in which most keys are associated
to an edition command.
For some commands, it makes sense to execute them multiple times. Enter
a multiplier m before these commands to get the expected result. If no
multiplier is specified, the default value of 1 is assumed.
Editor interaction
? display an help message
q/Q quit/force quit
s change a run-time setting (see subsection "Run-time settings")
e/E execute make/a shell command and get back to edit
File management
w/W write/write as
R reload
Entering insert mode
i enter insert mode (see subsection "Insert mode")
It is also possible to enter insert mode at a specific location.
However, these commands do not combine well when applied to one than
one selection, therefore they empty the saved selections list and
unanchor the anchor before entering insert mode.
I/A at the start/end of the cursor line
o/O on an empty line created below/above the cursor line
Navigation
l/h, Right/Left
move to m -th next/previous character
j/k, Down/Up
move to m -th next/previous line
g/G move to m -th/last line of the file
m move to matching bracket
0/^/$ move to start/first non-blank character/end of line
t/T move to m -th next/previous word
}/{ move to m -th next/previous block
n/N move to m -th next/previous selection
J jump to m -th next match for prompted pattern (useful to navigate
quickly through the file without changing selections)
Selections management
Escape forget saved selections, unanchor, reset multiplier
c display number of saved selections
v anchor/unanchor
a add running selections to saved selections, unanchor
z duplicate the running selection on the next m lines (designed
for easy block/column editing)
./%/b select cursor line/all lines/ m blocks
: select custom range of lines
Custom ranges must be formatted min,max where min / max is either empty
(meaning 1/last line number), a dot (meaning cursor line number) or an
integer.
f, / search for pattern (see subsection "Search pattern syntax")
* search for the word that is currently under the cursor
Searching will create a new saved selections list containing all
substrings of previously saved selections matching the given pattern.
Edition commands
u/U switch to lowercase/uppercase
K comment/uncomment line
>/<, Tab/Shift-Tab
m increase/decrease line indent
x, Delete/Backspace
suppress selection content if any, else m characters
after/before
r replace (see subsection "Replace pattern syntax")
Control-A
autocomplete with longest common prefix
Lines management
edit has a line-centric clipboard. The following commands do not act on
selections but directly on lines.
y/Y yank m lines/blocks, starting at cursor
d/D delete m lines/blocks, starting at cursor
p/P paste after/before cursor line m times
Shift-Down/Shift-Up
move lines of running selections m lines down/up
Insert mode
In insert mode, most keys insert their character before the selections.
Right, Left, Down, Up, Delete, Backspace, Control-A, Shift-Down
Shift-Up
like in normal mode
Escape get back to normal mode
Dialog mode
When the editor need additionnal user input, it switches to dialog
mode. In this mode, the user is prompted something on the bottom line
of the screen.
Left, Right, Control-A, Control-E
navigate the input
Up recover the last input associated with the prompt
Down clear the input
Delete/Backspace
suppress character after/before the cursor
Enter validate input, get back to normal mode
Escape cancel, get back to normal mode
Run-time settings
Setting assignements must be formatted name=value where name is in the
following list and value of the according type. Any integer value is
considered a boolean, 0 meaning FALSE and any other value meaning TRUE.
c case sensitive (boolean, default: TRUE)
fs field separator (character, default: ',')
h highlight selections (boolean, default: TRUE)
l language extension (string, default: deduced from filename)
sh syntax highlight (boolean, default: TRUE)
tw tab width (integer, default: 4)
Search pattern syntax
<character> ::= <regular_char> # character (not <esc_char>)
| "\" <esc_char> # escaped character
| "." # any character
| "\d" | "\D" # any [non] digit
| "\w" | "\W" # any [non] word character
| "[" <set> "]" # any character in <set>
| "[^" <set> "]" # any character not in <set>
<esc_char> ::= "\" | "^" | "$" | "|" | "(" | ")"
| "*" | "+" | "?" | "{" | "[" | "."
<set> ::= <items> # <item> characters
| "-" <items> # "-" and <items> characters
| <items> "-" # "-" and <items> characters
| "-" <items> "-" # "-" and <items> characters
<items> ::= <non_minus> # character (not "-")
| <non_minus> "-" <non_minus> # range (inclusive)
| <items> <items> # characters in either <items>
<repeater> ::= "" # exactly 1
| "+" # 1 or more (at least once)
| "?" # 0 or 1 (at most once)
| "*" | "{}" # 0 or more (any number)
| "{" <int> "}" # exactly <int>
| "{" <int> ",}" # at least <int>
| "{," <int> "}" # at most <int>
| "{" <int> "," <int> "}" # range (inclusive)
<int> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
| <int> <int>
<assertion> ::= "^" | "$" # start/end of line
| "\A" | "\Z" # start/end of selection
| "\b" | "\B" # [non] words boundary
<atom> ::= <assertion> | <character> <repeater>
<OR_atom> ::= <atom> | <OR_atom> "|" <atom>
<group> ::= "" | <group> <OR_atom>
<block> ::= <atom> | "(" <group> ")" <repeater>
<OR_block> ::= <block> | <OR_block> "|" <block>
<pattern> ::= "" | <pattern> <OR_block>
Replace pattern syntax
<pattern> ::= <regular_char> # character (not "\" or "$")
| "\\" | "\$" # escaped "\" and "$"
| "\0" | "$0" # whole initial selection
| "\" <pos_digit> # <pos_digit>-th subpattern
| "$" <pos_digit> # <pos_digit>-th field
| <pattern> <pattern> # concatenation
<pos_digit> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
NOTES
Search and replace engine
The search and replace engine is home-grown. While it has some caveats
(see section "ISSUES"), it is quite capable: the search is incremental
and supports regular expressions, and the replace supports the reuse of
subpatterns and fields from the to-be-replaced string.
Using the engine should feel pretty straightforward as it can be used
in a typical sed fashion:
(1) Choose a line range with % or b or : or .
(2) Specify a search pattern with f or /
(3) Specify a replace pattern with r
But there is more to it than a sed imitation. Using a home-grown engine
allows for better integration with the editor. Indeed, as all these
steps make sense individually, one can use any combination of these.
Syntaxes are described in a Backus-Naur form notation in subsections
"Search pattern syntax" and "Replace pattern syntax".
Syntax highlighting system
Designing a syntax highlighting system capable enough to perform
exhaustive, semantically correct syntax highlighting for many languages
is very challenging. In the context of a tiny, autonomous codebase,
this goal is soon forgotten.
edit syntax highlighting system try to balance capability and
simplicity. Its semantic understanding is limited, and is designed to
process lines individually. Its simplicity makes it really easy to add
language support, and easy to compute at runtime.
It works well for keywords, numbers, monoline strings/comments, and
markup languages where a line break is significant (Markdown or Gemtext
for example); but not so much for multilines strings/comments or some
other markup languages (XML for example).
The commenting command use single line comments: the user is encouraged
to use it over ranges of lines instead of using multiline comments.
Encoding
edit only works with UTF-8 encoded text.
Tabulations
edit is designed to work with spaces, not tabs. When opening a file,
tabs are converted to spaces (according to the TAB_WIDTH value).
Unfortunately, some languages recquire tabs (makefiles are an example).
To accomodate these, the language-level CONVERT_LEADING_SPACES flag can
be set so that leading spaces are converted back to tabs when saving.
Trailing spaces
By default, the SUPPRESS_TRAILING_SPACES option is set, which has the
effect of ignoring trailing spaces when saving.
Multiples selections on a given line
Selections can not overlap.
Indenting and commenting is performed at most once per line, no matter
how much selections a line contains.
Undo/redo
There is no undo/redo mechanism. Instead, the user is advised to save
frequently and reload the file when a set of actions is to be reverted.
Arbitrary yanking
It is not possible to yank only a part of a given line. The clipboard
is designed to work with ranges of lines, not arbitrary text sequences.
Lines wrapping
It is not possible to wrap lines.
CUSTOMIZATION
edit is customized by creating a custom config.h and (re)compiling the
source code. This keeps it fast, secure and simple.
Languages support
Supported languages are defined in languages.h with two #ifdef LANGUAGE
enclosed parts (one for language declaration, one for inclusion in the
languages array). Mimicking other languages is advised when adding
support for a new anguage.
SEE ALSO
kakoune(1), vis(1)
ISSUES
Repeaters in regular expressions
Repeaters always match as much as possible, potentially eating too much
characters and invalidating a valid match.
For example, ".*." never matches anything because the leading ".*" eats
all the selection, leaving no more characters to be matched by the
trailing ".".
BUGS
Send all bug reports with a patch to arthur@jacquin.xyz.