vis.1 (33323B)
- .Dd January 14, 2017
- .Dt VIS 1
- .Os Vis v0.9
- .
- .Sh NAME
- .
- .Nm vis
- .Nd a highly efficient text editor
- .
- .Sh SYNOPSIS
- .
- .Nm
- .Op Fl v
- .Op Cm + Ns Ar command
- .Op Fl -
- .Op Ar files ...
- .
- .Sh DESCRIPTION
- .
- .Nm
- is a highly efficient screen-oriented text editor combining the strengths of
- both
- .Nm vi(m)
- and
- .Nm sam .
- .
- This manual page is intended for users already familiar with
- .Nm vi Ns / Ns Nm sam .
- Anyone else should almost certainly read a good tutorial on either editor
- before this manual page.
- The following options are available:
- .Bl -tag -width indent
- .It Fl v
- Print version information and exit.
- .It Cm + Ns Ar command
- Execute
- .Ar command
- after loading file.
- .
- .It Fl -
- Denotes the end of the options.
- Arguments after this will be handled as a
- file name.
- .El
- .Pp
- The special file
- .Cm -
- instructs
- .Nm
- to read from standard input in which case
- .Ic :wq
- will write to standard output, thereby enabling usage as an interactive filter.
- .Pp
- If standard input is redirected and all input is consumed,
- .Nm
- will open
- .Pa /dev/tty
- to gather further commands.
- Failure to do so results in program termination.
- .
- .Ss Selections
- .
- .Nm
- uses selections as core editing primitives.
- A selection is a non-empty, directed range with two endpoints called
- .Em cursor
- and
- .Em anchor .
- A selection can be anchored in which case the anchor remains fixed while
- only the position of the cursor is adjusted.
- For non-anchored selections both endpoints are updated.
- A singleton selection covers one character on which both cursor and
- anchor reside.
- There always exists a primary selection which remains visible
- (i.e. changes to its position will adjust the viewport).
- .
- .Ss Modes
- .
- .Nm
- employs the same
- .Em modal
- editing approach as
- .Nm vi .
- It supports a
- .Sq normal ,
- .Sq operator pending ,
- .Sq insert ,
- .Sq replace
- and
- .Sq visual
- (in both line and character wise variants) mode.
- The visual block and ex modes are deliberately not implemented,
- instead
- .Nm
- has built in support for multiple selections and an
- .Em interactive
- variant of the structural regular expression based command language of
- .Nm sam .
- .Pp
- In normal mode all selections are non-anchored and reduced to a single character.
- .
- .Ss Undo/Redo
- .
- .Nm
- uses an undo tree to keep track of text revisions.
- The
- .Ic u
- .Pq undo
- and
- .Aq Ic C-r
- .Pq redo
- commands can be used to traverse the tree along the main branch.
- .Ic g+
- and
- .Ic g-
- traverse the history in chronological order.
- The
- .Ic :earlier
- and
- .Ic :later
- commands provide means to restore the text to an arbitrary state.
- .
- .Ss Marks
- .
- A mark associates a symbolic name to a set of selections.
- A stored selection becomes invalid when its delimiting boundaries change
- in the underlying buffer.
- If said changes are later undone the mark becomes valid again.
- .Ic m
- sets a mark,
- .Ic M
- restores it.
- For example,
- .Ic ' Ns Ar a Ns Ic m
- sets the mark
- .Ar a
- while
- .Ic ' Ns Ar a Ns Ic M
- restores it.
- Use of
- .Ic m
- or
- .Ic M
- without specifying a mark uses the default mark.
- .Pp
- Available marks are:
- .Bl -tag -width indent
- .It Ic ''
- default mark
- .It Ic '^
- active selections when leaving visual mode
- .It Ic 'a Ns \(en Ns Ic 'z
- general purpose marks
- .El
- .Pp
- No marks across files are supported.
- Marks are not preserved over editing sessions.
- .
- .Ss Jump list
- .
- A per window, fixed sized file local jump list exists which stores marks
- (i.e. set of selections).
- .Bl -tag -width indent
- .It Ic g<
- jump backward
- .It Ic g>
- jump forward
- .It Ic gs
- save currently active selections
- .El
- .
- .Ss Registers
- .
- Registers are named lists of text.
- Uninitialized register slots default to the empty string.
- Available registers are:
- .Bl -tag -width indent
- .It Ic \(dq\(dq
- default register
- .It Ic \(dqa Ns \(en Ns Ic \(dqz
- general purpose registers
- .It Ic \(dqA Ns \(en Ns Ic \(dqZ
- append to corresponding general purpose register
- .It Ic \(dq* , Ic \(dq+
- system clipboard integration via shell script
- .Xr vis-clipboard 1
- .It Ic \(dq0
- yank register, most recently yanked range
- .It Ic \(dq1 Ns \(en Ns Ic \(dq9
- .It Ic \(dq&
- sub expression matches of most recent
- .Ic x
- or
- .Ic y
- command
- .It Ic \(dq/
- search register, most recently used search pattern
- .It Ic \(dq\&:
- command register, most recently executed command
- .It Ic \(dq_
- black hole
- .Pq Pa /dev/null
- register, ignore content is always empty
- .It Ic \(dq#
- selection number (readonly)
- .El
- .Pp
- If no explicit register is specified the default register is used.
- .
- .Ss Macros
- .
- The general purpose registers
- .Ic \(dqa Ns \(en Ns Ic \(dqz
- can be used to record macros.
- Use one of
- .Ic \(dqA Ns \(en Ns Ic \(dqZ
- to append to an existing macro.
- .Ic q
- starts a recording,
- .Ic @
- plays it back.
- .Ic @@
- refers to the most recently recorded macro.
- .Ic @:
- repeats the last
- .Ic \&: Ns -command.
- .Ic @/
- is equivalent to
- .Ic n
- in normal mode.
- .
- These operations always use the first register slot.
- .
- .Ss Encoding, Tab and Newline handling
- .
- .Nm
- always assumes the input file to be UTF-8 encoded with
- .Li \[rs]n
- line endings.
- If you wish to edit files with legacy encodings or non-Unix line endings,
- use
- .Xr iconv 1
- and
- .Xr dos2unix 1
- to convert them as needed.
- .Aq Ic Tab
- can optionally be expanded to a configurable number of spaces (see
- .Sx "SET OPTIONS" ) .
- .
- .Ss Mouse support
- .
- The mouse is currently not used at all.
- .
- .Sh SAM COMMANDS
- .
- .Nm
- supports an interactive variant of the structural regular expression based
- command language introduced by
- .Xr sam 1 .
- .
- .Ss Regular expressions
- .
- .Nm
- currently defers regular expression matching to the underlying C library.
- It uses what POSIX refers to as
- .Dq Extended Regular Expressions
- as described in
- .Xr regex 7 .
- The anchors
- .Ic ^
- and
- .Ic $
- match the beginning / end of the range they are applied to.
- Additionally
- .Li \[rs]n
- and
- .Li \[rs]t
- may be used to refer to newlines and tabs,
- respectively.
- The
- .Ic \&.
- atom matches any character except newline.
- The empty regular expression stands for the last complete expression
- encountered.
- .
- .Ss Addresses
- .
- An address identifies a substring (or range) in a file.
- In the following
- .Do
- character
- .Ar n
- .Dc
- means the null string after the
- .Ar n Ns -th
- character in the file, with 1 the first character in the file.
- .Do
- Line
- .Ar n
- .Dc
- means the
- .Ar n Ns -th
- match, starting at the beginning of the file, of the regular expression
- .Dq Li .*\[rs]n\&? .
- .Pp
- All windows always have at least one current substring which is the default
- address.
- In sam this is referred to as
- .Sy dot .
- In
- .Nm
- multiple
- .Dq dots
- (or selections) can exist at the same time.
- .
- .Ss Simple addresses
- .
- .Bl -tag -width indent
- .It Ic # Ns Ar n
- The empty string after character
- .Ar n ;
- .Ic #0
- is the beginning of the file.
- .It Ar n
- Line
- .Ar n .
- .It Ic / Ns Ar regexp Ns Ic /
- .It Ic \&? Ns Ar regexp Ns Ic \&?
- The substring that matches the regular expression, found by looking
- towards the end
- .Pq Ic /
- or beginning
- .Pq Ic \&?
- of the file.
- The search does not wrap around when hitting the end
- .Pq start
- of the file.
- .It Ic 0
- The string before the first full line.
- This is not necessarily the null string; see
- .Ic +
- and
- .Ic -
- below.
- .It Ic $
- The null string at the end of the file.
- .It Ic \&.
- Dot, the current range.
- .It Ic ' Ns Ar m
- The mark
- .Ar m
- in the file.
- .El
- .
- .Ss Compound addresses
- .
- In the following,
- .Ar a1
- and
- .Ar a2
- are addresses.
- .Bl -tag -width indent
- .It Ar a1 Ns Ic + Ns Ar a2
- The address
- .Ar a2
- evaluated starting at the end of
- .Ar a1 .
- .It Ar a1 Ns Ic - Ns Ar a2
- The address
- .Ar a2
- evaluated looking the reverse direction starting at the beginning of
- .Ar a1 .
- .It Ar a1 Ns Ic \&, Ns Ar a2
- The substring from the beginning of
- .Ar a1
- to the end of
- .Ar a2 .
- If
- .Ar a1
- is missing,
- .Ic 0
- is substituted.
- If
- .Ar a2
- is missing,
- .Ic $
- is substituted.
- .It Ar a1 Ns Ic \&; Ns Ar a2
- Like
- .Ar a1 Ns Ic \&, Ns Ar a2
- but with
- .Ar a2
- evaluated at the end of, and range set to,
- .Ar a1 .
- .El
- .Pp
- The operators
- .Ic +
- and
- .Ic -
- are high precedence, while
- .Ic \&,
- and
- .Ic \&;
- are low precedence.
- .Pp
- In both
- .Ic +
- and
- .Ic -
- forms, if
- .Ar a2
- is a line or character address with a missing number, the number defaults to 1.
- If
- .Ar a1
- is missing,
- .Ic \&.
- is substituted.
- If both
- .Ar a1
- and
- .Ar a2
- are present and distinguishable,
- .Ic +
- may be elided.
- .Ar a2
- may be a regular expression; if it is delimited by
- .Li \&?
- characters, the effect of the
- .Ic +
- or
- .Ic -
- is reversed.
- .
- The
- .Ic %
- sign is an alias for
- .Ic \&,
- and hence
- .Ic 0,$ .
- .
- It is an error for a compound address to represent a malformed substring.
- .
- .Ss Commands
- .
- In the following, text demarcated by slashes represents text delimited
- by any printable ASCII character except alphanumerics.
- Any number of trailing delimiters may be elided, with multiple elisions then
- representing null strings, but the first delimiter must always be present.
- In any delimited text, newline may not appear literally;
- .Li \[rs]n
- and
- .Li \[rs]t
- may be typed for newline and tab;
- .Li \[rs]/
- quotes the delimiter, here
- .Li / .
- An ampersand
- .Li &
- and
- .Li \[rs] Ns Ar n ,
- where
- .Ar n
- is a digit (1\(en9) are replaced by the corresponding register.
- Backslash is otherwise interpreted literally.
- .Pp
- Most commands may be prefixed with an address to indicate their range of
- operation.
- If a command takes an address and none is supplied, a default address is used.
- In normal mode this equates to the character the selection is currently over.
- If only one selection exists
- .Ic x
- and
- .Ic y
- default to the whole file
- .Ic 0,$ .
- In normal mode the write commands
- .Ic w
- and
- .Ic wq
- always apply to the whole file.
- Commands are executed once for every selection.
- In visual mode the commands are applied to every selection
- as if an implicit
- .Ic x
- command, matching the existing selections, was present.
- .
- .Pp
- In the description,
- .Dq range
- is used to represent whatever address is supplied.
- .Pp
- Many commands create new selections as a side effect when issued from a visual
- mode.
- If so, it is always to the “result” of the change: the new text for an
- insertion, the empty string for a deletion, the command output of a filter etc.
- If after a successful command execution no selections remain,
- the editor will switch to normal mode, otherwise it remains in
- visual mode.
- This allows
- .Em interactive
- refinements of ranges.
- .
- .\" Many commands set the value of dot as a side effect.
- .\" If so, it is always to the
- .\" .Dq result
- .\" of the change: the empty string for a deletion, the new text for an
- .\" insertion, etc.
- .\" .Po
- .\" but see the
- .\" .Sy s
- .\" and
- .\" .Sy e
- .\" commands
- .\" .Pc .
- .
- .Ss Text commands
- .
- .Bl -tag -width indent
- .It Ic a Ns [ Ar count ] Ns / Ns Ar text Ns Ic /
- Insert the
- .Ar text
- .Ar count
- times into the file after the range.
- .\" Set dot.
- .Pp
- May also be written as
- .Bd -literal -offset indent
- a
- lines
- of
- text
- .
- .Ed
- .
- .It Ic c No or Ic i
- Same as
- .Ic a ,
- but
- .Ic c
- replaces the text, while
- .Ic i
- inserts
- .Em before
- the range.
- .
- .It Ic d
- Delete the text in range.
- .\" Set dot.
- .El
- .
- .Ss Display commands
- .
- .Bl -tag -width Ds
- .It Ic p
- Create a new selection for the range.
- .El
- .
- .Ss I/O commands
- .
- .Bl -tag -width indent
- .It Ic e Ns Oo Cm \&! Oc Op Pa file name
- Replace the file by the contents of the named external file.
- If no file name is given, reload file from disk.
- .
- .It Ic r Ar file name
- Replace the text in the range by the contents of the named external file.
- .\" Set dot.
- .
- .It Ic w Ns Oo Cm \&! Oc Op Ar file name
- Write the range
- .Po
- default
- .Ic 0,$
- .Pc
- to the named external file.
- .
- .It Ic wq Ns Oo Cm \&! Oc Op Ar file name
- Same as
- .Ic w ,
- but close file afterwards.
- .El
- .Pp
- If the file name argument is absent from any of these, the current file name is
- used.
- .
- .Ic e
- always sets the file name,
- .Ic w
- will do so if the file has no name.
- Forcing the
- .Ic e
- command with
- .Cm \&!
- will discard any unsaved changes.
- Forcing
- .Ic w
- will overwrite the file on disk even if it has been externally modified
- since loading it.
- Write commands with a non-default addresses and no file name are destructive
- and need always to be forced.
- .Bl -tag -width indent
- .
- .It Ic < Ar shell command
- Replace the range by the standard output of the shell command.
- .
- .It Ic > Ar shell command
- Sends the range to the standard input of the shell command.
- .
- .It Ic \&| Ar shell command
- Send the range to the standard input, and replace it by the standard output, of
- the shell command.
- .
- .It Ic \&! Ar shell command
- Run interactive shell command, redirect keyboard input to it.
- .
- .It Ic cd Ar directory
- Change working directory.
- If no directory is specified,
- .Ev "$HOME"
- is used.
- .El
- .Pp
- In any of
- .Ic < ,
- .Ic > ,
- .Ic \&| ,
- or
- .Ic \&! ,
- if the shell command is omitted, the last shell command
- .Pq of any type
- is substituted.
- Unless the file being edited is unnamed, all these external commands
- can refer to its absolute path and file name through the
- .Ev vis_filepath
- and
- .Ev vis_filename
- environment variables.
- .
- .Ss Loops and conditionals
- .
- .Bl -tag -width indent
- .It Ic x/ Ns Ar regexp Ns Ic / Op Ar command
- For each match of the regular expression in the range, run the command with
- range set to the match.
- If the regular expression and its slashes are omitted,
- .Ar "/.*\[rs]n/"
- is assumed.
- Null string matches potentially occur before every character of the range and
- at the end of the range.
- .Pp
- The
- .Ic \(dq1 Ns \(en Ns Ic \(dq9
- and
- .Ic \(dq&
- registers are updated with the (sub) expression matches of the pattern.
- .
- .It Ic y/ Ns Ar regexp Ns Ic / Op Ar command
- Like
- .Ic x ,
- but run the command for each substring that lies before, between, or after the
- matches that would be generated by
- .Ic x .
- There is no default behavior.
- Null substrings potentially occur before every character in the range.
- .
- .It Ic X/ Ns Ar regexp Ns Ic "/" Ar command
- For each file whose file name matches the regular expression, make that the
- current file and run the command.
- If the expression is omitted, the command is run in every file.
- .
- .It Ic Y/ Ns Ar regexp Ns Ic / Ar command
- Same as
- .Ic X ,
- but for files that do not match the regular expression, and the expression is
- required.
- .\" TODO improve markup, use Op macro, make it actually understandable :/
- .It Ic g Ns [ Ar count ] Ns [ Ar /regexp/ ] Ar command
- .It Ic v Ns [ Ar count ] Ns [ Ar /regexp/ ] Ar command
- If the
- .Ar count
- range contains
- .Po
- .Ic g
- .Pc
- or does not contain
- .Po
- .Ic v
- .Pc
- a match for the expression, run command on the range.
- .Pp
- The
- .Ar count
- specifier has the following format, where
- .Ar n
- and
- .Ar m
- are integers denoting the ranges.
- .Bl -tag -width indent
- .It Ar n Ns Ic \&, Ns Ar m
- The closed interval from
- .Ar n
- to
- .Ar m .
- If
- .Ar n
- is missing,
- .Ic 1
- is substituted.
- If
- .Ar m
- is missing,
- .Ic ∞
- is substituted.
- Negative values are interpreted relative to the last range.
- .It Ic % Ns Ar n
- Matches every
- .Ar n Ns -th
- range.
- .El
- .
- .El
- .Pp
- These may be nested arbitrarily deeply.
- An empty command in an
- .Ic x
- or
- .Ic y
- defaults to
- .Ic p .
- .Ic X ,
- .Ic Y ,
- .Ic g
- and
- .Ic v
- do not have defaults.
- .
- .Ss Grouping and multiple changes
- .
- Commands may be grouped by enclosing them in curly braces.
- Semantically, the opening brace is like a command: it takes an
- .Pq optional
- address and runs each sub-command on the range.
- Commands within the braces are executed sequentially, but changes
- made by one command are not visible to other commands.
- .Pp
- When a command makes a number of changes to a file, as in
- .Ic x/ Ns Ar re Ns Ic / Ic c/ Ns Ar text Ns Ic / ,
- the addresses of all changes are computed based on the initial state.
- If the changes are non-overlapping, they are applied in the specified
- order.
- Conflicting changes are rejected.
- .Pp
- Braces may be nested arbitrarily.
- .
- .Sh VI(M) KEY BINDINGS
- .
- In the following sections angle brackets are used to denote special keys.
- The prefixes
- .Ic C- ,
- .Ic S- ,
- and
- .Ic M-
- are used to refer to the
- .Aq Ctrl ,
- .Aq Shift
- and
- .Aq Alt
- modifiers, respectively.
- .Pp
- All active key bindings can be listed at runtime using the
- .Ic :help
- command.
- .
- .Ss Operators
- .
- Operators perform a certain operation on a text range indicated by either a
- motion, a text object or an existing selection.
- .Pp
- When used in normal mode, the following operators wait for a motion, putting
- vis into operator pending mode.
- .Bl -tag -width XXXXXXXXXX -compact
- .It Ic c
- change, delete range and enter insert mode
- .
- .It Ic d
- delete, cut range to register
- .
- .It Ic <
- shift-left, decrease indent
- .
- .It Ic >
- shift-right, increase indent
- .
- .It Ic y
- yank, copy range to register
- .El
- .Pp
- When used in normal mode, the following actions take effect immediately.
- .Bl -tag -width XXXXXXXXXX -compact
- .It Ic =
- format, filter range through
- .Xr fmt 1
- .
- .It Ic gu
- make lowercase
- .
- .It Ic gU
- make uppercase
- .
- .It Ic g~
- swap case
- .
- .It Ic J
- join lines, insert spaces in between
- .
- .It Ic gJ
- join lines remove any delimiting white spaces
- .
- .It Ic p
- put register content after cursor
- .
- .It Ic P
- put register content before cursor
- .
- .El
- .
- .Ss Motions
- .
- .\" TODO? more formal definition: pos -> [min(pos, f(pos)), max(pos, f(pos))]
- Motions take an initial file position and transform it to a destination file
- position,
- thereby defining a range.
- .\" TODO define word/WORD
- .Pp
- .Bl -tag -width XXXXXXXXXX -compact
- .It Ic 0
- start of line
- .
- .It Ic b
- previous start of a word
- .
- .It Ic B
- previous start of a WORD
- .
- .It Ic $
- end of line
- .
- .It Ic e
- next end of a word
- .
- .It Ic E
- next end of a WORD
- .
- .It Ic F Ns Aq Ar char
- to next occurrence of
- .Aq Ar char
- to the left
- .
- .It Ic f Ns Aq Ar char
- to next occurrence of
- .Aq Ar char
- to the right
- .
- .It Ic ^
- first non-blank of line
- .
- .It Ic g0
- begin of display line
- .
- .It Ic g$
- end of display line
- .
- .It Ic ge
- previous end of a word
- .
- .It Ic gE
- previous end of a WORD
- .
- .It Ic gg
- begin of file
- .
- .It Ic G
- goto line or end of file
- .
- .It Ic gj
- display line down
- .
- .It Ic gk
- display line up
- .
- .It Ic gh
- codepoint left
- .
- .It Ic gl
- codepoint right
- .
- .It Ic gH
- byte left
- .
- .It Ic gL
- byte right
- .It Ic g_
- last non-blank of line
- .
- .It Ic gm
- middle of display line
- .
- .It Ic g\&|
- goto column
- .
- .It Ic h
- char left
- .
- .It Ic H
- goto top/home line of window
- .
- .It Ic j
- line down
- .
- .It Ic k
- line up
- .
- .It Ic l
- char right
- .
- .It Ic L
- goto bottom/last line of window
- .
- .It Ic %
- match bracket, quote or backtick
- .
- .It Ic }
- next paragraph
- .
- .It Ic \&)
- next sentence
- .
- .It Ic N
- repeat last search backwards
- .
- .It Ic n
- repeat last search forward
- .
- .It Ic [{
- previous start of block
- .
- .It Ic ]}
- next start of block
- .
- .It Ic [(
- previous start of parentheses pair
- .
- .It Ic ])
- next start of parentheses pair
- .
- .It Ic {
- previous paragraph
- .
- .It Ic \&(
- previous sentence
- .
- .It Ic \&;
- repeat last to/till movement
- .
- .It Ic \&,
- repeat last to/till movement but in opposite direction
- .
- .It Ic #
- search word under selection backwards
- .
- .It Ic *
- search word under selection forwards
- .
- .It Ic T Ns Aq Ar char
- till before next occurrence of
- .Aq Ar char
- to the left
- .
- .It Ic t Ns Aq Ar char
- till before next occurrence of
- .Aq Ar char
- to the right
- .
- .It Ic \&? Ns Ar pattern
- to next match of
- .Ar pattern
- in backward direction
- .
- .It Ic / Ns Ar pattern
- to next match of
- .Ar pattern
- in forward direction
- .
- .It Ic w
- next start of a word
- .
- .It Ic W
- next start of a WORD
- .El
- .
- .Ss Text objects
- .
- .\" TODO? more formal definition: text-object: pos -> [a, b]
- Text objects take an initial file position and transform it to a range
- where the former does not necessarily have to be contained in the latter.
- .
- All of the following text objects are implemented in an inner variant
- (prefixed with
- .Ic i )
- where the surrounding white space or delimiting characters are not part
- of the resulting range and a normal variant (prefixed with
- .Ic a )
- where they are.
- .Pp
- .Bl -tag -width XXXXXXXXXX -compact
- .
- .It Ic w
- word
- .
- .It Ic W
- WORD
- .
- .It Ic s
- sentence
- .
- .It Ic p
- paragraph
- .
- .It Ic [, ], (, ), {, }, <, >, \(dq, ', `
- block enclosed by these symbols
- .El
- .Pp
- Further available text objects include:
- .Bl -tag -width XXXXXXXXXX -compact
- .
- .It Ic gn
- matches the last used search term in forward direction
- .
- .It Ic gN
- matches the last used search term in backward direction
- .
- .It Ic al
- current line
- .
- .It Ic il
- current line without leading and trailing white spaces
- .El
- .
- .Ss Multiple Selections
- .
- .Nm
- supports multiple selections with immediate visual feedback.
- There always exists one primary selection located within the current
- view port.
- Additional selections can be created as needed.
- If more than one selection exists, the primary one is styled differently.
- .Pp
- To manipulate selections use in normal mode:
- .Pp
- .Bl -tag -width XXXXXXXXXX -compact
- .It Aq Ic C-k
- create count new selections on the lines above
- .
- .It Aq Ic C-M-k
- create count new selections on the lines above the first selection
- .
- .It Aq Ic C-j
- create count new selections on the lines below
- .
- .It Aq Ic C-M-j
- create count new selections on the lines below the last selection
- .
- .It Aq Ic C-p
- remove primary selection
- .
- .It Aq Ic C-n
- select word the selection is currently over, switch to visual mode
- .
- .It Aq Ic C-u
- make the count previous selection primary
- .
- .It Aq Ic C-d
- make the count next selection primary
- .
- .It Aq Ic C-c
- remove the count selection column
- .
- .It Aq Ic C-l
- remove all but the count selection column
- .
- .It Aq Ic Tab
- try to align all selections on the same column
- .
- .It Aq Ic Escape
- dispose all but the primary selection
- .El
- .Pp
- The visual modes were enhanced to recognize:
- .Pp
- .Bl -tag -width XXXXXXXXXX -compact
- .It Ic I
- create a selection at the start of every selected line
- .
- .It Ic A
- create a selection at the end of every selected line
- .
- .It Aq Ic Tab
- left align selections by inserting spaces
- .
- .It Aq Ic S-Tab
- right align selections by inserting spaces
- .
- .It Aq Ic C-a
- create new selections everywhere matching current word or selection
- .
- .It Aq Ic C-n
- create new selection and select next word matching current selection
- .
- .It Aq Ic C-x
- clear (skip) current selection, but select next matching word
- .
- .It Aq Ic C-p
- remove primary selection
- .
- .It Ao Ic C-u Ac Ao Ic C-k Ac
- make the count previous selection primary
- .
- .It Ao Ic C-d Ac Ao Ic C-j Ac
- make the count next selection primary
- .
- .It Aq Ic C-c
- remove the count selection column
- .
- .It Aq Ic C-l
- remove all but the count selection column
- .
- .It Ic +
- rotate selections rightwards count times
- .
- .It Ic -
- rotate selections leftwards count times
- .
- .It Ic _
- trim selections, remove leading and trailing white space
- .
- .It Ic o
- flip selection direction, swap cursor and anchor
- .
- .It Aq Ic Escape
- clear all selections, switch to normal mode
- .El
- .Pp
- In insert and replace mode:
- .Pp
- .Bl -tag -width XXXXXXXXXX -compact
- .It Aq Ic S-Tab
- align all selections by inserting spaces
- .El
- .Pp
- Selections can be manipulated using set operations.
- The first operand is the currently active selections while the second
- can be specified as a mark.
- For example,
- .Ic ' Ns Ar a Ns Ic \&|
- produces the union of the mark
- .Ar a
- and the current selection.
- Use of set operations without specifying a mark use the default mark as
- the first operand.
- .Pp
- .Bl -tag -width XXXXXXXXXX -compact
- .It Ic \&|
- set union
- .It Ic &
- set intersection
- .It Ic \e
- set minus
- .It Ic ~
- set complement
- .El
- .
- .Sh VI(M) COMMANDS
- .
- Any unique prefix can be used to abbreviate a command.
- .
- .Ss File and Window management
- .
- A file must be opened in at least one window.
- If the last window displaying a certain file is closed all unsaved changes are
- discarded.
- Windows are equally sized and can be displayed in rows (horizontally)
- or in columns (vertically).
- The
- .Aq Ic C-w
- .Ic h ,
- .Aq Ic C-w
- .Ic j ,
- .Aq Ic C-w
- .Ic k
- and
- .Aq Ic C-w
- .Ic l
- key mappings can be used to switch between windows.
- .Bl -tag -width indent
- .It Ic :new
- open an empty window, arranged as a new row (horizontally)
- .
- .It Ic :vnew
- open an empty window, arranged as a new column (vertically)
- .
- .It Ic :open Ns Oo Cm \&! Oc Op Ar file name
- open a new window, displaying file name if given
- .
- .It Ic :split Op Ar file name
- split window into rows (horizontally)
- .
- .It Ic :vsplit Op Ar file name
- split window into columns (vertically)
- .
- .It Ic :q Ns Oo Cm \&! Oc Op Ar exit code
- close currently focused window
- .
- .It Ic :qall Ns Oo Cm \&! Oc Op Ar exit code
- close all windows, terminate editor with exit code (defaults to 0)
- .El
- .Pp
- Commands taking a file name will invoke the
- .Xr vis-open 1
- utility, if given a file pattern or directory.
- .
- .Ss Runtime key mappings
- .
- .Nm
- supports global as well as window local run time key mappings which are
- always evaluated recursively.
- .
- .Bl -tag -width indent
- .It Ic :map Ns Oo Cm \&! Oc Ar mode Ar lhs Ar rhs
- add a global key mapping
- .
- .It Ic :map-window Ns Oo Cm \&! Oc Ar mode Ar lhs Ar rhs
- add a window local key mapping
- .
- .It Ic :unmap Ar mode Ar lhs
- remove a global key mapping
- .
- .It Ic :unmap-window Ar mode Ar lhs
- remove a window local key mapping
- .El
- .Pp
- In the above
- .Ar mode
- refers to one of
- .Ql normal ,
- .Ql insert ,
- .Ql replace ,
- .Ql visual ,
- .Ql visual-line
- or
- .Ql operator-pending ;
- .Ar lhs
- refers to the key to map and
- .Ar rhs
- is a key action or alias.
- An existing mapping may be overridden by forcing the map command by specifying
- .Cm \&! .
- .Pp
- Because key mappings are always recursive, doing something like:
- .Pp
- .Dl :map! normal j 2j
- .Pp
- will not work because it would enter an endless loop.
- Instead,
- .Nm
- uses pseudo keys referred to as key actions which can be used to invoke
- a set of available editor functions.
- .Ic :help
- lists all currently active key bindings as well as all available symbolic
- keys.
- .
- .Ss Keyboard Layout Specific Mappings
- .
- In order to facilitate usage of non-latin keyboard layouts,
- .Nm
- allows one to map locale specific keys to their latin equivalents by means of the
- .Pp
- .D1 Ic :langmap Ar locale-keys Ar latin-keys
- .Pp
- command.
- As an example, the following maps the movement keys in Russian layout:
- .Pp
- .Dl :langmap ролд hjkl
- .Pp
- If the key sequences have not the same length, the remainder of the longer
- sequence will be discarded.
- .Pp
- The defined mappings take effect
- in all non-input modes, i.e. everywhere except in insert and replace mode.
- .
- .Ss Undo/Redo
- .
- .Bl -tag -width indent
- .It Ic :earlier Op Ar count
- revert to older text state
- .It Ic :later Op Ar count
- revert to newer text state
- .El
- .Pp
- If count is suffixed by either of
- .Sy d
- .Pq days ,
- .Sy h
- .Pq hours ,
- .Sy m
- .Pq minutes
- or
- .Sy s
- .Pq seconds
- it is interpreted as an offset from the current system time and the closest
- available text state is restored.
- .
- .Sh SET OPTIONS
- .
- There are a small number of options that may be set
- .Pq or unset
- to change the editor's behavior using the
- .Ic :set
- command.
- This section describes the options, their abbreviations and their
- default values.
- Boolean options can be toggled by appending
- .Sy \&!
- to the option name.
- .Pp
- In each entry below, the first part of the tag line is the full name
- of the option, followed by any equivalent abbreviations.
- The part in square brackets is the default value of the option.
- .Bl -tag -width indent
- .It Ic shell Op Dq Pa /bin/sh
- User shell to use for external commands, overrides
- .Ev SHELL
- and shell field of password database
- .Pa /etc/passwd
- .
- .It Ic escdelay Op Ar 50
- Milliseconds to wait before deciding whether an escape sequence should
- be treated as an
- .Aq Cm Escape
- key.
- .
- .It Ic tabwidth , Ic tw Op Ar 8
- Display width of a tab and number of spaces to use if
- .Ic expandtab
- is enabled.
- .
- .It Ic autoindent , Cm ai Op Cm off
- Automatically indent new lines by copying white space from previous line.
- .
- .It Ic expandtab , Ic et Op Cm off
- Whether
- .Aq Ic Tab
- should be expanded to
- .Ic tabwidth
- spaces.
- .
- .It Ic number , Ic nu Op Cm off
- Display absolute line numbers.
- .
- .It Ic relativenumbers , Ic rnu Op Cm off
- Display relative line numbers.
- .
- .It Ic cursorline , Ic cul Op Cm off
- Highlight line primary cursor resides on.
- .
- .It Ic colorcolumn , Ic cc Op Ar 0
- Highlight a fixed column.
- .
- .It Ic horizon Op Ar 32768
- How many bytes back the lexer will look to synchronize parsing.
- .
- .It Ic theme Op Do default-16 Dc or Do default-256 Dc
- Color theme to use, name without file extension.
- Loaded from a
- .Pa themes/
- sub directory of the paths listed in the
- .Sx FILES
- section.
- .
- .It Cm syntax Op Cm auto
- Syntax highlighting lexer to use, name without file extension.
- .
- .It Cm showtabs Op Cm off
- Whether to display replacement symbol instead of tabs.
- .
- .It Cm shownewlines Op Cm off
- Whether to display replacement symbol instead of newlines.
- .
- .It Cm showspaces Op Cm off
- Whether to display replacement symbol instead of blank cells.
- .
- .It Cm showeof Op Cm on
- Whether to display replacement symbol for lines after the end of the file.
- .
- .It Cm savemethod Op Ar auto
- How the current file should be saved,
- .Ar atomic
- which uses
- .Xr rename 2
- to atomically replace the file,
- .Ar inplace
- which truncates the file and then rewrites it or
- .Ar auto
- which tries the former before falling back to the latter.
- The rename method fails for symlinks, hardlinks, in case of insufficient
- directory permissions or when either the file owner, group, POSIX ACL or
- SELinux labels can not be restored.
- .It Cm loadmethod Op Ar auto
- How existing files should be loaded,
- .Ar read
- which copies the file content to an independent in-memory buffer,
- .Ar mmap
- which memory maps the file from disk and uses OS capabilities as
- caching layer or
- .Ar auto
- which tries the former for files smaller than 8Mb and the latter for
- lager ones.
- WARNING: modifying a memory mapped file in-place will cause data loss.
- .It Ic layout Op Do v Dc or Do h Dc
- Whether to use vertical or horizontal layout.
- .It Cm ignorecase , Cm ic Op Cm off
- Whether to ignore case when searching.
- .It Ic wrapcolumn , Ic wc Op Ar 0
- Wrap lines at minimum of window width and wrapcolumn.
- .
- .It Ic breakat , brk Op Dq Pa ""
- Characters which might cause a word wrap.
- .El
- .
- .Sh COMMAND and SEARCH PROMPT
- .
- The command and search prompt as opened by
- .Ic \&: ,
- .Ic / ,
- or
- .Ic \&?
- is implemented as a single line height window, displaying a regular file
- whose editing starts in insert mode.
- .Aq Ic Escape
- switches to normal mode, a second
- .Aq Ic Escape
- cancels the prompt.
- .Aq Ic Up
- enlarges the window, giving access to the command history.
- .Aq Ic C-v
- .Aq Ic Enter
- inserts a literal new line thus enabling multiline commands.
- .Aq Ic Enter
- executes the visual selection if present, or else everything in the
- region spawned by the selection position and the delimiting prompt symbols
- at the start of adjacent lines.
- .
- .Sh CONFIGURATION
- .
- .Nm
- uses Lua for configuration and scripting purposes.
- During startup
- .Pa visrc.lua
- (see the
- .Sx FILES
- section) is sourced which can be used to set personal configuration options.
- As an example the following will enable the display of line numbers:
- .Pp
- .Dl vis:command('set number')
- .
- .Sh ENVIRONMENT
- .
- .Bl -tag -width indent
- .It Ev VIS_PATH
- The default path to use to load Lua support files.
- .It Ev HOME
- The home directory used for the
- .Ic cd
- command if no argument is given.
- .It Ev TERM
- The terminal type to use to initialize the curses interface, defaults to
- .Sy xterm
- if unset.
- .It Ev SHELL
- The command shell to use for I/O related commands like
- .Ic \&! ,
- .Ic > ,
- .Ic <
- and
- .Ic \&| .
- .It Ev XDG_CONFIG_HOME
- The configuration directory to use, defaults to
- .Pa $HOME/.config
- if unset.
- .El
- .
- .Sh ASYNCHRONOUS EVENTS
- .
- .Bl -tag -width indent
- .It Dv SIGSTOP
- Suspend editor.
- .It Dv SIGCONT
- Resume editor.
- .It Dv SIGBUS
- An
- .Xr mmap 2
- ed file got truncated, unsaved file contents will be lost.
- .It Dv SIGHUP
- .It Dv SIGTERM
- Restore initial terminal state.
- Unsaved file contents will be lost.
- .It Dv SIGINT
- When an interrupt occurs while an external command is being run it is terminated.
- .It Dv SIGWINCH
- The screen is resized.
- .El
- .
- .Sh FILES
- .
- Upon startup
- .Nm
- will source the first
- .Pa visrc.lua
- configuration file found from these locations.
- All actively used paths can be listed at runtime using the
- .Cm :help
- command.
- .Bl -bullet
- .It
- .Pa $VIS_PATH
- .It
- The location of the
- .Nm
- binary (on systems where
- .Pa /proc/self/exe
- is available).
- .It
- .Pa $XDG_CONFIG_HOME/vis
- where
- .Ev XDG_CONFIG_HOME
- refers to
- .Pa $HOME/.config
- if unset.
- .
- .It
- .Pa /etc/vis
- for a system-wide configuration provided by administrator.
- .It
- .Pa /usr/local/share/vis
- or
- .Pa /usr/share/vis
- depending on the build configuration.
- .
- .Pp
- When creating a new
- .Pa visrc.lua
- be sure to copy the structure from here.
- .El
- .
- .Sh EXIT STATUS
- .
- .Ex -std
- .
- .Sh EXAMPLES
- .
- Use
- .Nm
- as an interactive filter.
- .Pp
- .Dl $ { echo Pick your number; seq 1 10; } | vis - > choice
- .Pp
- Use the
- .Xr vis-open 1
- based file browser to list all C language source files:
- .Pp
- .Dl :e *.c
- .Pp
- Spawn background process and pipe range to its standard input:
- .Pp
- .Dl :> { plumber <&3 3<&- & } 3<&0 1>&- 2>&-
- .
- .Sh SEE ALSO
- .
- .Xr sam 1 ,
- .Xr vi 1 ,
- .Xr vis-clipboard 1 ,
- .Xr vis-complete 1 ,
- .Xr vis-digraph 1 ,
- .Xr vis-menu 1 ,
- .Xr vis-open 1
- .Pp
- .Lk http://doc.cat-v.org/bell_labs/sam_lang_tutorial/sam_tut.pdf "A Tutorial for the Sam Command Language"
- by
- .An Rob Pike
- .Pp
- .Lk http://doc.cat-v.org/plan_9/4th_edition/papers/sam/ "The Text Editor sam"
- by
- .An Rob Pike
- .Pp
- .Lk http://man.cat-v.org/plan_9/1/sam "Plan 9 manual page for sam(1)"
- .Pp
- .Lk http://doc.cat-v.org/bell_labs/structural_regexps/se.pdf "Structural Regular Expressions"
- by
- .An Rob Pike
- .Pp
- .Lk http://pubs.opengroup.org/onlinepubs/9699919799/utilities/vi.html "vi - screen-oriented (visual) display editor"
- .St -p1003.1
- .
- .Sh STANDARDS
- .
- .Nm
- does not strive to be
- .St -p1003.1
- compatible, but shares obvious similarities with the
- .Nm vi
- utility.
- .
- .\" .Sh HISTORY
- .\" TODO something about vi(m) and sam history
- .
- .Sh AUTHORS
- .
- .Nm
- is written by
- .An Marc André Tanner Aq mat at brain-dump.org
- .
- .Sh BUGS
- .
- On some systems there already exists a
- .Nm
- binary, thus causing a name conflict.