Added draft for the completion framework

[iomenu.git] / iocomplete.1

.Dd $Mdocdate: September 28 2016 $
.Dt IOCOMPLETE 1
.Os
.Sh NAME
.
.Nm iocomplete
.Nd a command line completion backend for iomenu
.
.Sh SYNOPSIS
.
.Nm
.Op


.Op Ic +command
.Op Ar files Fl
.
.Sh DESCRIPTION
.
.Nm vis
is a highly efficient vim like text editor.
.Bl -tag
.It Fl v
Print version information and exit.
.
.It Fl -
Denotes  the  end  of the options. Arguments after this will be handled as a
file name.
.El
.
.Ss Modes
.
Vis implements more or less functional normal, operator-pending, insert,
replace and visual (in both line and character wise variants) modes.
.Pp
Visual block mode is not implemented and there exists no immediate plan
to do so. Instead vis has built in support for multiple cursors.
.Pp
Command mode is implemented as a regular file. Use the full power of
the editor to edit your commands / search terms.
.Pp
Ex mode is deliberately not implemented, instead a variant of the
structural regular expression based command language of `sam(1)`
is supported.
.
.Ss Undo/Redo and Repeat
.
The text is currently snapshotted whenever an operator is completed as
well as when insert or replace mode is left. Additionally a snapshot is
also taken if in insert or replace mode a certain idle time elapses.
.Pp
Another idea is to snapshot based on the distance between two consecutive
editing operations (as they are likely unrelated and thus should be
individually reversible).
.Pp
Besides the regular undo functionality, the key bindings 
.Ql g+
and
.Ql g-
traverse the history in chronological order. Further more the
.Iq :earlier
and
.Iq :later
commands provide means to restore the text to an arbitrary
state.
.Pp
The repeat command
.Ql \&.
works for all operators and is able to repeat
the last insertion or replacement.
.
.Ss Tab <-> Space conversion and Line endings \n vs \r\n
.
Tabs can optionally be expanded to a configurable number of spaces.
The first line ending in the file determines what will be inserted upon
a line break (defaults to \n).
.
.Ss Jump list and change list
.
A per window, file local jump list (navigate with `CTRL+O` and `CTRL+I`)
and change list (navigate with `g;` and `g,`) is supported. The jump
list is implemented as a fixed sized ring buffer.
.
.Ss Macros
.
The general purpose registers
.Ql [a-z]
can be used to record macros. Use
one of
.Ql [A-Z]
to append to an existing macro.
.Ql q
starts a recording,
.Ql @
plays it back.
.Ql @@
refers to the least recently recorded macro.
.Ql @:
repeats the last :-command.
.Ql @/
is equivalent to
.Ql n
in normal mode.
.
.Ss Structural Regular Expression based Command Language
.
.Nm vis
supports
.Xr sam 1
structural regular expression based command language.
.
.Ss Mouse support
.
.
.Sh KEY BINDINGS
.
.Ss Operators
.
.Bl -tag
.It c
change
.
.It d
delete
.
.It !
filter
.
.It =
indent, currently an alias for gq
.
.It gq
format using fmt(1)
.
.It gu
make lowercase
.
.It gU
make uppercase
.
.It J
join
.
.It p
put
.
.It <
shift-left
.
.It >
shift-right
.
.It ~
swap case
.
.It y
yank
.El
.
.Ss Movements
.
.Bl -tag
.It 0
start of line
.
.It b
previous start of a word
.
.It B
previous start of a WORD
.
.It $
end of line
.
.It e
next end of a word
.
.It E
next end of a WORD
.
.It F char
to next occurrence of char to the left
.
.It f char
to next occurrence of char to the right
.
.It ^
first non-blank of line
.
.It g0
begin of display line
.
.It g$
end of display line
.
.It ge
previous end of a word
.
.It gE
previous end of a WORD
.
.It gg
begin of file
.
.It G
goto line or end of file
.
.It gj
display line down
.
.It gk
display line up
.
.It g_
last non-blank of line
.
.It gm
middle of display line
.
.It |
goto column
.
.It h
char left
.
.It H
goto top/home line of window
.
.It j
line down
.
.It k
line up
.
.It l
char right
.
.It L
goto bottom/last line of window
.
.It ` mark
go to mark
.
.It ' mark
go to start of line containing mark
.
.It %
match bracket
.
.It M
goto middle line of window
.
.It ]]
next end of C-like function
.
.It }
next paragraph
.
.It )
next sentence
.
.It ][
next start of C-like function
.
.It N
repeat last search backwards
.
.It n
repeat last search forward
.
.It []
previous end of C-like function
.
.It [{
previous start of block
.
.It ]}
next start of block
.
.It [(
previous start of parenthese pair
.
.It ])
next start of parenthese pair
.
.It {
previous paragraph
.
.It (
previous sentence
.
.It [[
previous start of C-like function
.
.It ;
repeat last to/till movement
.
.It ,
repeat last to/till movement but in opposite direction
.
.It #
search word under cursor backwards
.
.It *
search word under cursor forwards
.
.It T char
till before next occurrence of char to the left
.
.It t char
till before next occurrence of char to the right
.
.It ? text
to next match of text in backward direction
.
.It / text
to next match of text in forward direction
.
.It w
next start of a word
.
.It W
next start of a WORD
.El
.Pp
An empty line is currently neither a word nor a WORD.
.Pp
Some of these commands do not work as in vim when prefixed with a
digit i.e. a multiplier. As an example in vim
.Ql 3$
moves to the end
of the 3rd line down. However vis treats it as a move to the end of
current line which is repeated 3 times where the last two have no
effect.
.
.Ss Text objects
.
All of the following text objects are implemented in an inner variant
(prefixed with
.Ql i`) and a normal variant (prefixed with
.Ql a`):
.Bl -tag
.
.It w
word
.
.It W
WORD
.
.It s
sentence
.
.It p
paragraph
.
.It [,], (,), {,}, <,>, ", ', `
block enclosed by these symbols
.El
.Pp
For sentence and paragraph there is no difference between the inner and
normal variants.
.Bl -tag
.
.It gn
matches the last used search term in forward direction
.
.It gN
matches the last used search term in backward direction
.El
.Pp
Additionally the following text objects, which are not part of stock
vim are also supported:
.Bl -tag
.
.It ae
entire file content
.
.It ie
entire file content except for leading and trailing empty lines
.
.It af
C-like function definition including immediately preceding comments
.
.It if
C-like function definition only function body
.
.It al
current line
.
.It il
current line without leading and trailing white spaces
.El
.
.Ss Multiple Cursors / Selections
.
.Nm vis
supports multiple cursors with immediate visual feedback (unlike in the
visual block mode of vim where for example inserts only become visible
upon exit). There always exists one primary cursor located within the
current view port. Additional cursors ones can be created as needed. If
more than one cursor exists, the primary one is styled differently
(yellow by default).
.Pp
To manipulate multiple cursors use in normal mode:
.Bl -tag
.
.It Ctrl-K
create count new cursors on the lines above
.
.It Ctrl-Meta-K
create count new cursors on the lines above the first cursor
.
.It Ctrl-J
create count new cursors on the lines below
.
.It Ctrl-Meta-J
create count new cursors on the lines below the last cursor
.
.It Ctrl-P
remove primary cursor
.
.It Ctrl-N
select word the cursor is currently over, switch to visual mode
.
.It Ctrl-U
make the count previous cursor primary
.
.It Ctrl-D
make the count next cursor primary
.
.It Ctrl-C
remove the count cursor column
.
.It Ctrl-L
remove all but the count cursor column
.
.It Tab
try to align all cursor on the same column
.
.It Esc
dispose all but the primary cursor
.El
.Pp
Visual mode was enhanced to recognize:
.Bl -tag
.
.It I
create a cursor at the start of every selected line
.
.It A
create a cursor at the end of every selected line
.
.It Tab
left align selections by inserting spaces
.
.It Shift-Tab
right align selections by inserting spaces
.
.It Ctrl-N
create new cursor and select next word matching current selection
.
.It Ctrl-X
clear (skip) current selection, but select next matching word
.
.It Ctrl-P
remove primary cursor
.
.It Ctrl-U/K
make the count previous cursor primary
.
.It Ctrl-D/J
make the count next cursor primary
.
.It Ctrl-C
remove the count cursor column
.
.It Ctrl-L
remove all but the count cursor column
.
.It +
rotates selections rightwards count times
.
.It -
rotates selections leftwards count times
.
.It \e
trim selections, remove leading and trailing white space
.
.It Esc
clear all selections, switch to normal mode
.El
.Pp
In insert/replace mode:
.Bl -tag
.
.It Shift-Tab
align all cursors by inserting spaces
.El
.
.Ss Marks
.
.Bl -tag
.
.It [a-z]
general purpose marks
.
.It <
start of the last selected visual area in current buffer
.
.It >
end of the last selected visual area in current buffer
.El
.
.Ss Registers
.
Supported registers include:
.Bl -tag
.
.It "a-"z
general purpose registers
.
.It "A-"Z
append to corresponding general purpose register
.
.It "*,
"+  system clipboard integration via shell script vis-clipboard
.
.It "0
yank register
.
.It "/
search register
.
.It ":
command register
.
.It "_
black hole (/dev/null) register
.El
.Pp
If no explicit register is specified a default register is used.
.
.Sh COMMANDS
.
.Pp
Besides the sam command language the following commands are also recognized at
the `:`-command prompt. Any unique prefix can be used.
.Bl -tag
.Iq :bdelete
close all windows which display the same file as the current one
.Iq :earlier
revert to older text state
.Iq :e
replace current file with a new one or reload it from disk
.Iq :langmap
set key equivalents for layout specific key mappings
.Iq :later
revert to newer text state
.Iq :!
launch external command, redirect keyboard input to it
.Iq :map
add a global key mapping
.Iq :map-window
add a window local key mapping
.Iq :new
open an empty window, arrange horizontally
.Iq :open
open a new window
.Iq :qall
close all windows, exit editor
.Iq :q
close currently focused window
.
.It :r
insert content of another file at current cursor position
.
.It :set
set the options below
.
.It :split
split window horizontally
.
.It :s
search and replace currently implemented in terms of `sed(1)`
.
.It :unmap
remove a global key mapping
.
.It :unmap-window
remove a window local key mapping
.
.It :vnew
open an empty window, arrange vertically
.
.It :vsplit
split window vertically
.
.It :wq
write changes then close window
.
.It :w
write current buffer content to file
.
.It  tabwidth  [1-8]           default 8
set display width of a tab and number of spaces to use if expandtab is enabled
.
.It  expandtab  (yes|no)        default no
whether typed in tabs should be expanded to tabwidth spaces
.
.It  autoindent (yes|no)        default no
replicate spaces and tabs at the beginning of the line when
.
.It  number         (yes|no)    default no
.
.It  relativenumber (yes|no)    default no
whether absolute or relative line numbers are printed alongside
.
.It  syntax      name           default yes
use syntax definition given (e.g. "c") or disable syntax
.
.It  show
show/hide special white space replacement symbols
.Bl -bullet
.
.It
newlines = [0|1]         default 0
.
.It
tabs     = [0|1]         default 0
.
.It
spaces   = [0|1]         default 0
.El
.
.It  cursorline (yes|no)        default no
highlight the line on which the cursor currently resides
.
.It  colorcolumn number         default 0
highlight the given column
.
.It  horizon    number          default 32768 (32K)
how far back the lexer will look to synchronize parsing
.
.It  theme      name            default dark-16.lua | solarized.lua (16 | 256 color)
use the given theme / color scheme for syntax highlighting
.El
.Pp
Commands taking a file name will use a simple file open dialog based on
the included `vis-open` shell script and `vis-menu` utility, if given
a file pattern or directory.
.Ic :e *.c
opens a menu with all C files
.Ic :e \&.
opens a menu with all files of the current directory
.
.Ss Runtime Configurable Key Bindings
.
Vis supports run time key bindings via the
.Ic :{un,}map{,-window}
set of commands. The basic syntax is
.Ic :map <mode> <lhs> <rhs>
where mode is one of 
.Ql normal
,
.Ql insert
,
.Ql replace
,
.Ql visual
,
.Ql visual-line
or
.Ql operator-pending
.
.Ql lhs
refers to the key to map,
.Ql rhs
is a key action or alias. An existing mapping can be overridden by appending
.Ql !
to the map command.
.Pp
Key mappings are always recursive, this means doing something like
.Ic :map! normal j 2j
will not work because it will enter an endless loop. Instead vis uses
pseudo keys referred to as key actions which can be used to invoke a set
of available (see
.Ic :help
or
.Ic F1
for a list) editor functions. Hence the correct thing to do would be
.Ic :map! normal j 2<cursor-line-down>
.Pp
Unmapping works as follows:
.Ic :unmap <mode> <lhs>
.Pp
The commands suffixed with `-window` only affect the currently active window.
.
.Ss Layout Specific Key Bindings
.
Vis allows to set key equivalents for non-latin keyboard layouts. This
facilitates editing non-latin texts. The defined mappings take effect
in all non-input modes, i.e. everywhere except in insert and replace mode.
.Pp
For example, the following maps the movement keys in Russian layout:
.Ic :langmap ролд hjkl
.Pp
More generally the syntax of the `:langmap` command is:
.Ic :langmap <keys in your layout> <equivalent keys in latin layout>
.Pp
If the key sequences have not the same length, the rest of the longer
sequence will be discarded.
.
.Ss Runtime Configurable Key Bindings
.
Vis supports run time key bindings via the
.Ic :{un,}map{,-window}
set of commands. The basic syntax is
.Ic :map <mode> <lhs> <rhs>
where mode is one of 
.Ql normal
,
.Ql insert
,
.Ql replace
,
.Ql visual
,
.Ql visual-line
or
.Ql operator-pending
.
.Ql lhs
refers to the key to map,
.Ql rhs
is a key action or alias. An existing mapping can be overridden by appending
.Ql !
to the map command.
.Pp
Key mappings are always recursive, this means doing something like
.Ic :map! normal j 2j
will not work because it will enter an endless loop. Instead vis uses
pseudo keys referred to as key actions which can be used to invoke a set
of available (see
.Ic :help
or
.Ic F1
for a list) editor functions. Hence the correct thing to do would be
.Ic :map! normal j 2<cursor-line-down>
.Pp
Unmapping works as follows:
.Ic :unmap <mode> <lhs>
.Pp
The commands suffixed with `-window` only affect the currently active window.
.
.Ss Layout Specific Key Bindings
.
Vis allows to set key equivalents for non-latin keyboard layouts. This
facilitates editing non-latin texts. The defined mappings take effect
in all non-input modes, i.e. everywhere except in insert and replace mode.
.Pp
For example, the following maps the movement keys in Russian layout:
.Ic :langmap ролд hjkl
.Pp
More generally the syntax of the `:langmap` command is:
.Ic :langmap <keys in your layout> <equivalent keys in latin layout>
.Pp
If the key sequences have not the same length, the rest of the longer
sequence will be discarded.
.
.Sh ENVIRONMENT
.
.Bl -tag
.Ev VIS_PATH
Override path to look for Lua support files as used for  syntax  highlighting.
Defaults (in this order) to:
.Bl -bullet
.
.It
The location of the vis binary
.
.It
.Pa $XDG_CONFIG_HOME/vis
where
.Ev $XDG_CONFIG_HOME
refers to
.Pa $HOME/.config
if unset
.
.It
.Pa /usr/local/share/vis
.
.It
.Pa /usr/share/vis
.El
.Ev VIS_THEME
Override syntax highlighting theme to use.
.El
.
.Sh FILES
.
.Pp
Settings and keymaps can be specified in a
.Pa visrc.lua
file, which will
be read by
.Pa vis
at runtime. An example
.Pa visrc.lua
file is installed in
.Pa /usr/local/share/vis
by default. This file can be copied to
.Pa $XDG_CONFIG_HOME/vis
(which defaults to
.Pa $HOME/.config/vis
) for further configuration.
.Pp
The environment variable
.Pa VIS_PATH
can be set to override the path that
.Pa vis
will look for Lua support files as used for syntax highlighting.
.Pa VIS_PATH
defaults (in this order) to:
.Bl -bullet
.
.It
The location of the
.Nm vis
binary
.
.It
.Pa $XDG_CONFIG_HOME/vis
where
.Pa $XDG_CONFIG_HOME
refers to
.Pa $HOME/.config
if unset.
.
.It
.Pa /usr/local/share/vis
.
.It
.Pa /usr/share/vis
.El
.Pp
The environment variable
.Ev VIS_THEME
can be set to specify the theme used by
.Nm vis
:
.Bd -literal
VIS_THEME=/path/to/your/theme.lua
export VIS_THEME
.Ed
.
.Sh SEE ALSO
.
.Xr vis-menu 1
.Xr vis-open 1
.Xr vis-clipboard 1
.Xr vis-complete 1
.
.Sh AUTHORS
.
.Nm vis
is written by
.An Marc André Tanner Aq mat at brain-dump.org