Options

Vixen edits path, or a new buffer if no path is given. If path is a directory, nothing is read.

-d debug

Print debug messages to standard error. Each character in debug enables debug printing for functionality associated with that character ( `a-z' only). See the source code for the mapping of character to functionality. As a special case, `+' enables all debug printing.

-c macro

After startup, before giving control to the user, macro is executed.

-i

Reads initial buffer from standard input instead of from file. This can be used to start vixen with a directory as filename and pipe the output of a command to it.

Modes

Vixen is a modeful text editor. It starts in command mode, interpreting key strokes as commands. Commands can move the insertion cursor, modify the buffer, change the mode, and more. Many commands that modify the buffer expect to be followed by a motion commands, causing the command to operate on text from the insertion cursor to the position after the motion. Insert mode, entered by i (among others), inserts further keys at the insertion cursor and advances it. Replace mode, started by r, is similar but overwrites text instead of inserting it. Visual mode, started by v, accepts commands just as command mode, but commands operate on the selection (indicated by reverse colors), and motion commands change the selection. Visual line mode only allows whole lines to be selected. Ex commands can be entered by typing a colon, though this is not considered a separate mode. Pressing escape in any mode switches back to command mode.

User interface

The main text window is a view of the current buffer. The title contains the name ``vixen'' and the absolute path of the file being edited. Vixen makes sure the insertion cursor is always visible, unless the view is scrolled by the scrollbar. Under the window is the status bar, it contains the current mode, the buffer's file name (or that none has been set yet), the number of lines and characters in the file, the current insertion position, the characters that have been collected as a command, and optionally an error message. When entering line-based commands, such as ex commands and searches, the status bar is temporarily replaced by a text entry widget. The end of the buffer is indicated by an EOT character in blue color on white background color. The insertion cursor is shown before the character it is positioned at. The visual selection is indicated in reverse colors. A text search match is indicated with black text on a yellow background, after a change of the text the colors are removed. After an incoming plumb message, the added text or addressed line is indicated by white text on a blue background. The colors are removed on the first key stroke or command. The edit entry, for ex commands and searches, has file name completion and a history. Pressing tab interprets the word before the cursor as a filename completes it to the largest common prefix of the matches. If the word is already the largest common prefix, each tab fills in the next match. History is accessed with the up and down arrow keys. Up selects the previous line that prefix-matches the text typed so far, down the next.

Buffer

The buffer is the data that commands operate on. All data is utf-8, arbitrary binary files cannot be edited. Vixen always has exactly one buffer The buffer can be in `modified' state, i.e. not yet flushed to disk. A file name may be associated with a buffer, either because the buffer was read from that file or because the buffer has previously been written to it.

Insertion cursor and positions

The buffer always has a insertion cursor (or just `cursor'), where text in insert or replace mode will be inserted, and commands will operate from. The position of the insertion cursor is represented as a line (starting at 1) and column (starting at 0) within that line. Positions always represent a character with one exception: it can be positioned after the last character in the buffer, at the end of file. Different from most vi clones, the insertion cursor can be positioned at a newline. In an empty buffer, e.g. when starting vixen without parameters, the only valid position is ``1.0''.

Selection

The selection is indicated by reverse colors, and only present while in one of the visual modes. On entering the visual mode, the start and end of the selection is set to the cursor position. On entering the visual line mode, the selection is set from start of the cursor's line to the end of the cursor's line (including newline). Motion commands are interpreted from the end of the selection, even if its position is before the start of the selection (possible due to backwards motions).

Registers and macro's

Registers can hold textual data. They are useful to temporarily store text, for later use. Special registers exist too, automatically updated. Some commands, especially those that delete or insert text, modify a register. This register can be changed by prefixing the command with the <reg> command. The same applies to commands that use a register, e.g. yank. The contents of a register can also be executed with the @<reg> command, as a macro. Macro's can also be recorded by the q<reg> command, and ended by a subsequent q command. <reg>.

Registers:

Holds text removed during last deletion.

.

Holds last insertion with insert or replace mode.

%

Current filename, may be empty. Read-only.

/

Pattern of last text search.

*

Contents of snarf buffer.

!

Command last executed by ex command :b command.

a-z

Registers available to user.

A-Z

Aliases for registers a-z. Writes to these registers append to the lower cased registers, instead of writing them.

Marks

Marks are positions in the file. They can be set by the m<mark> command and jumped to by `<mark> and '<mark> commands (the first jumps to the exact position, the second to the first non-blank character of the position's line). Some marks are automatically set when navigating the buffer, some cannot be modified by the user, see the table below. A mark is automatically deleted when the text at its position is deleted. Marks always point to the same character, and are automatically adjusted on insertions and deletions before them. The following marks are available:

<

First character of visual selection (regardless of direction of selection, so not necessarily the start of the selection). Set automatically when changing the visual selection, read-only. m-command.

>

Last character of visual selection.

` and '

Many non-trivial motion commands are considered jumps. These identical marks contain the position of the insertion cursor before the last jump.

.

Location of last change, insertion or deletion. Read-only.

^

Location of last insertion of text. Read-only.

a-z

No special meaning. Note that marks A-Z and 0-9 are not available.

Changes and undo/redo

Each modification of the buffer, e.g. by a command or an insertion through insert mode, is recorded as a change. It can be undone by the u command. Undone commands can be redone by the ^r command.

Inserting text

Text can be inserted in the buffer while in an editing mode, insert or replace mode. The last typed character can be removed by ^h, the last typed word by ^w, the last typed line by ^u. Only text typed after switching to the current editing mode can be removed with the commands above. Commands have to be used for other deletions. When in replace mode, text is overwritten. Newlines are never overwritting though, so when the cursor is at the end of a line, replace mode is effectively the same as insert mode. Erasing overwritten text reveals the original text again.

Plumbing

Plumbing is supported through the non-visual gP,gpp and gp<motion> commands, and the (identical) visual commands gp and gP. Quick write and compile cycles are supported by the gb and ex' :b [command] commands. Vixen uses a helper program vixenplumb (not otherwise documented) to keep track of which files are being edited, and routes plumb requests accordingly or starts a new vixen.

Motion commands

Motion commands set the insertion cursor. While in visual select, they change the selection. As modifier in commands, they indicate the range of text for the command to operate on. Many motion commands can be prefixed by a repeat count (not starting with zero). For example j moves the cursor down one line, while 3j moves the cursor down three lines.

The table below lists the motion commands and their cursor destination when a repeat has not been specified. Commands prefixed with <n> interpret a repeat count, but all commands accept them.

0 or Home

Column 0 of line.

<n>h or <n>Left

Character to the left, stopping at column 0.

<n>l or <n>Right

Character to the right, stopping at the newline.

<n>space

Character to the right, not stopping at newlines.

<n>w

Start of next word, stopping at interpunction.

<n>W

Start of next word, not stopping at interpunction.

<n>e

End of next word, stopping at interpunction.

<n>E

End of next word, not stopping at interpunction.

<n>b

To start of previous word, stopping at interpunction.

<n>G

If <n> was not specified, moves to the end of the file. Otherwise, interprets <n> as line number and moves to first non-blank character on the line.

$ or End

End of current line (at newline if any).

^

First non-blank character on line.

<n>-

First non-blank character on previous line.

<n>+ or <n><newline>

First non-blank character on next line.

<n>_

First non-blank on current line or <n>-1 lines relative from cursor.

<n>[fFtT]<char>

Find next (for f and t) or previous (for F and T) char on current line. f and F place the cursor at the character, t on the character before it, T on the character after it.

<n>;

Repeat last character find command ( [fFtT])

<n>,

Repeat last character find command, but in reverse direction (effectively executing the command with swapped case).

<n>/ or <n>?

Search forward or backward. The regex(6) pattern to search for must entered in the edit entry at the bottom of the window.

<n>* or <n>#

Search for the word under the cursor, # searches in reverse. This sets the last search string used by commands n and N.

<n>n or <n>N

Repeat last search, N reverse the search direction.

<n>%

If n was given it is interpreted as a percentage of the lines in the file, and the cursor is moved to that line, to the first non-blank character. Otherwise, jump to the counterpart of the nearest (forward) character in (){}[], taking nesting into account.

<n>|

Column n on current line, or column 0 by default.

<n>( or <n>) or <n>{ or <n>}

Next/previous sentence ( ) and () or next/previous paragraph ( } and {). In other vi implementations, the { and } commands also stop at troff paragraph commands, vixen does not.

`<mark> or '<mark>

To mark.

TP <n>H or M or <n>L Move relative to currently visible part of buffer. If n was not specified, it defaults to 0. H jumps to the first+nth visible line. L jumps to the last-nth visible line. M jumps to the middle, between the first and last.

<n>gg

Like G, but jump to first line if n was not specified.

<n>go

To character nth character of file, 1 by default (the first character in the file).

^e and ^y

Scroll visible window up/down by one line. This is not really a motion command because it only scrolls the window, however the insertion cursor is always kept in view and so may change as a side effect. The same applies to ^u, ^d, ^b and ^f.

^u and ^d

Scroll visible window up/down by half a window.

^b and ^f

Scroll visible window up/down by one window.

Visual commands

Visual commands operate on the current text selection and can only be executed while in one of the visual modes. Some commands operate on whole lines, even if lines are partially selected. The cursor is usually left at the first character of the affected range after an execution. The commands are very similar to the non-visual commands. Visual commands:

d

Delete text.

y

Yank text, i.e. copy text to the register.

J

Join lines, i.e. replace newlines by a space.

< or >

Unindent/indent text, removing or inserting tabs. Empty lines are kept empty.

r<char>

Replace all selected characters by as many char's.

!

Start ex command with visual registers and execute command preset as range, i.e. :'<,'>!.

:

Start ex command with visual registers as range, i.e. :'<,'>.

~ or g~

Swap case (of ascii characters only).

gJ

Join, but remove newlines altogether, don't replace them by a space.

gu or gU

Change to lower/upper case (ascii characters only).

q<reg> or q

Start (with reg) or stop (without) recording a macro to register reg.

o

Swap start and end of visual selection, changing the cursor.

<reg>

Use register reg for next command.

c or s

Change (substitute) selected text: delete it and switch to insert mode.

C or S or R

Change (substitute, replace) all lines that are part of the selection: Delete them and switch to insert mode.

p or P

Plumb text.

Commands

Non-visual commands are very similar to the visual commands. Instead of operating on visually selected text, they often operate on the line with the insertion cursor. Many of the commands accept a motion command as modifier, the text range to operate on is then from the cursor to where the motion command moves (the motion command is interpreted relative to the cursor). Just like motion commands, most modification commands also accept a repeat count. This allows for two repeat counts in a combined modification and motion command, e.g. 3d4w. This means "delete 4 words and do it 3 times". This is interpreted as "delete twelve words". Commands that delete text put it in register . The register can be overridden by prefixing the command with the <reg> command, e.g. a3d4w .

i

Switch to insert mode, at the cursor.

I

switch to insert mode, at the first non-blank character on the line.

a

Move to next position on the line and switch to insert mode.

A

Move to end of line and switch to insert mode.

o

Insert empty line after current, move to it and switch to insert mode.

O

Like o, but inserts empty line before current line.

R

Switch to replace mode.

<n>r<char>

Replace n (1 by default) characters by occurrences of char.

gi

To insert mode at the end of the last text insertion.

gI

To insert mode at the first column of the line.

<n>cc or c<motion>

Change n lines or by motion range. I.e. delete the text and switch to insert mode.

<n>C

Change from cursor to end of current+n-1th line.

<n>s

Substitute n characters, i.e. delete them and switch to insert mode.

<n>S

Substitute the entire current and following n-1 lines.

v

Switch to visual mode, setting start and end of visual selection to current cursor.

V

switch to visual line mode, setting start of visual selection to start of current line, and end of selection to end of current line (including newline).

<n>x

Delete character at cursor, on same line.

<n>X

Delete character before cursor, on same line.

<n>dd or <n>d<motion>"

Delete line or motion range.

<n>D

Delete end of current+n-1th line.

<n>yy or <n>y<motion>

Yank text (copy to register, by default) line or motion range.

<n>Y

Yank entire current line.

<n>p

Paste from register to after cursor. If the register ( by default) ends with a newline, the text is inserted on a new line after the current cursor.

<n>P

Like p but if register ends with a newline place the text on a new line before the current cursor.

[n]<< or [n]<[motion] or [n]>> or [n]>[motion] or

Unindent or indent line or motion range.

<n>J

Join current and next n lines.

<n>gJ

Join n lines, remove newlines altogether, don't replace them by a space.

m<mark>

Set mark to current position.

<n>!! or !<motion>

Start ex command for n lines or motion range.

ZZ

Quit, but first write the buffer if it has unwritten changes.

~

Change case of character under cursor, on same line.

<n>g~~ or g~<motion>

Change case of n lines, or up to motion range.

<n>guu or <n>gUU or g[uU]<motion>

Change n lines to lower/upper case, or by motion range.

^g

Update status bar.

^l

Redraw screen.

u

Undo last change.

^r

Redo last change.

@<reg> or @@

Execute register reg as macro, or execute same macro as last @ command.

: or Q

Start ex command.

.

Repeat last modification command. E.g. if last command was d3w that same command is executed again, interpreted from the current cursor.

q<reg> or q

Start recording macro into register reg, or stop recording.

<reg>

Use register reg for the next command.

gP

Plumb pattern under cursor. Pattern is path optionally followed by a semicolon and an ex address, e.g. a line number. The start of the pattern is looked for before the cursor too.

gpp or <n>gp<motion>

Plumb line or motion range.

gb

Equivalent to ex command b: execute the command in register ! and plumb the standard output and standard error as message kind `newtext'.

Ex commands operate on whole lines of text. By default they operate on dot, the line of the cursor. Most commands can be prefixed with an address expression. And many of those commands accept a range expression to instead operate an multiple range. A range is specified as two addresses, separated by a comma or semicolon. The semicolon causes the second address to be interpreted relative to the first address, instead of to the start of the file. An address is one or more (optionally whitespace separated) components, evaluated after each other, starting with the current cursor:

.

Dot, the current location. Initially the cursor.

$

Last line of the file.

0-9+

Number, absolute line number in file.

+0-9* or -0-9*

Moves number lines relative to dot. If the number is absent, it defaults to 1.

/pattern/ or ?pattern?

Line that contains pattern.

'<mark>

Line that contains mark.

Supported commands:

[range]!command

Execute command. If no range is given, just execute command. Otherwise, pass the text range to command and replace it with its output.

[range]s/pattern/repl/[g]

For each line in range, match against pattern and replace the matching text with repl. References to matching groups from the regular expression can be made in repl by a backslash followed by a digit. Digit `0' is the whole match, groups are counted from 1. If g was specified, perform the replacement for every match on the line, instead of on only the first. See regex(6) for valid values for pattern. The separator can be any non-alphanumeric besides whitespace, double quote and pipe.

[range]r [!]arg

If ! is specified, arg is executed as command. Otherwise it is read as a file. The text reads is inserted either instead of range, or on a newline after the cursor when range was not specified.

[range]w[q!] [>>]filename or q[!]"

Write and/or quite. If w is specified, the current buffer is written to disk. If a file name has previously been set for the file, the filename parameter may be left out. If filename is specified and different from the current file name, and filename already exists, the write will fail unless ! was also specified. If filename starts with >>, the text is appended to the file. If range is specified, only that range is written. Appending and writing a range never clears the modified status from the buffer. Then, if q is specified, vixen quits. If the buffer still has unwritten modifications, vixen will not quit unless ! was also specified.

x

Same as the ZZ command: quit, but first write the buffer if it has unwritten modifications.

cd <path>

Change working directory to path.

f [filename]

If filename is absent, prints the current file name associated with the buffer. Otherwise sets the current filename for the buffer to filename.

D<chars>

Toggle debug settings for chars, which must be one or more chars of: a-z, or - (disable all) or + (enable all).

b [command]

Build by executing command. The output (both standard output and standard error) are plumbed with kind `newtext', with only the current working directory set. This the text to be sent to a vixen that gathers output for that directory, a mechanism similar to that in acme(1). If command is absent, the command previously executed with b is executed again. This command is available in register ! and is set to `mk' by default. Also see non-ex command gb.

Commands zz, zt, and zb, for scrolling the window to place the cursor at the middle, top and bottom of the window.

Other implementations treat some motion commands differently based on the command they are executed with, e.g. cw is actually interpreted as ``delete to end of word'', i.e. more like ce. Vixen always interprets motion commands in one single way.

Key mappings for commands, through ex' :map command is not supported, :ab for abbreviations in insert mode is not supported either.

Vixen does not have a full ex mode, where consecutive commands are interpreted as ex commands. Commands to print multiple lines of text have not been implemented.

The full command names of ex commands are not supported. E.g. only :q is supported, not :quit.

Some featurse that likely won't be supported:
• Multiple editing windows within on instance of vixen.
• Text folding (hiding parts of the text).
• Visual block mode, where any rectangular block of text (over multiple lines) can be selected.
• Spell checking, text completion.
• Editing non-utf-8 (e.g. binary) files.

Vixen will not implement all commands and features found in the various vi clones, or the original vi. The behaviour of some commands may be different, that could be a bug. Vixen also has features that the vi clones and the original vi do not have, such as plumbing.

Entire file is kept in memory twice: in vixen and in Tk.