pafcu / vimsplain

Explain Vim command sequences

Vimsplain takes an sequence of vim commands and attempts to explain the meaning of the commands. Note that there are some Unicode-related problems with Python 2 so it's better to use a Python 3.x interpreter (often installed as python3).

Usage:

python3 vimsplain.py commands

e.g.

> python3 vimsplain.py qa3jYpJDq2@aZZ

qa      record typed characters into named register {0-9a-zA-Z"} (uppercase to append)
3j      cursor 3 lines downward
Y       yank 1 lines [into buffer x]; synonym for "yy"
p       put the text [from register x] after the cursor 1 times
J       Join 2 lines; default is 2
D       delete the characters under the cursor until the end of the line and 1-1 more lines [into buffer x]; synonym for "d$"
q       (while recording) stops recording
2@a     execute the contents of register {a-z} 2 times
ZZ      store current file if modified, and exit

Normally escape sequences are noted by ^, e.g. ^C,^[. This introduces potential ambiguity, e.g. it is not possible to know wheter ^V means

^	cursor to the first CHAR of the line
V	start linewise Visual mode

or:

^V	start blockwise Visual mode.

Therefore, the non-standard approch of using § is used, since that character is not used as a command in Vim, and is easy to type on most keyboards. A drawback is that § can not be entered in Insert mode since it will be interpreted as CTRL. Escape, or CTRL-[, is denoted by §[.

Vim documentation often uses <C-x> to denote Ctrl+x (where x is some character). If the program is invoked with the --convert_special switch, <C-x> will be converted to §x and <CR> will be converted to §M in the input. The reason this is only enabled when the switch is used is that it makes it impossible to enter some Vim commands (since these would be interpreted as a special character instead of commands).

A more compex example:

> python vimsplain.py "4JD=Gjwci(*a§[jcfda.join(',')§[ZZ"

4J      Join 4 lines; default is 2
D       delete the characters under the cursor until the end of the line and 1-1 more lines [into buffer x]; synonym for "d$"
=G      filter 1 lines through "indent" with motion cursor to line 1, default last line
j       cursor 1 lines downward
w       cursor 1 words forward
ci(     delete 1 text [into buffer x] and start insert with motion "inner block" from "[(" to "])"
                Text: *a
                Command: §[     end insert mode (unless 'insertmode' set)
j       cursor 1 lines downward
cfd     delete 1 text [into buffer x] and start insert with motion cursor to 1 occurrence of d to the right
                Text: a.join(',')
                Command: §[     end insert mode (unless 'insertmode' set)
ZZ      store current file if modified, and exit

There are still many features missing, most importantly support for arrow keys, mouse buttons, backspace and command line editing mode.

The file index.txt is a slightly modified version of the same file as included in Vim 7.3. It is licensed under the Vim license, see LICENSE.vim. Eveything else is licensed under the ISC license, see LICENSE.

vimsplain's Issues

command mode not implemented

Track mode changes in macros and mappings

Mode changes are only accounted for when they are explicit, the mode is not updated when called implicitly via macros of mappings

Register names are not replaced in descriptions

e.g.

"vimsplain qa" should give
record typed characters into named register a (uppercase to append)
intead of the current
record typed characters into named register {0-9a-zA-Z"} (uppercase to append)

The Flattr link in readme doesn't work

Probably the link has changed or the project was removed

Missing mode changes

gQ should switch to Ex mode

Select mode is not implemented

Select mode is not implemented yet

v should exit Visual mode when already in characterwise Visual mode

v should exit Visual mode when already in characterwise Visual mode

0 is incorrectly being identified as the number of times the next input will be used

0 in normal mode, in vim brings you to the beginning of the line (like ^)

$ python3 vimsplain.py 0j
0j	cursor 0 lines downward

but should output something like

0	cursor to the first CHAR of the line
j	cursor 1 lines downward

Missing control characters

Arrow keys, mouse keys and backspace do not work

Giving a non-motion command should exit Visual mode

Giving a non-motion command should exit Visual mode

re.error: nothing to repeat at position 0

When running the script like so:
python vimsplain.py ciw

the program throws the following error:

PS Z:\Documents\Git\vimsplain> python .\vimsplain.py ciw
Traceback (most recent call last):
  File "Z:\Documents\Git\vimsplain\vimsplain.py", line 288, in <module>
    commands = parse_commands(fix_help(open('index.txt')))
  File "Z:\Documents\Git\vimsplain\vimsplain.py", line 277, in parse_commands
    tup2 = (tup[0], re.compile(tup[1].pattern[2:]), tup[2], tup[3], tup[4], tup[5]) # Recompile expresison but with leading '\:' removed
  File "C:\Python39\lib\re.py", line 252, in compile
    return _compile(pattern, flags)
  File "C:\Python39\lib\re.py", line 304, in _compile
    p = sre_compile.compile(pattern, flags)
  File "C:\Python39\lib\sre_compile.py", line 764, in compile
    p = sre_parse.parse(p, flags)
  File "C:\Python39\lib\sre_parse.py", line 948, in parse
    p = _parse_sub(source, state, flags & SRE_FLAG_VERBOSE, 0)
  File "C:\Python39\lib\sre_parse.py", line 443, in _parse_sub
    itemsappend(_parse(source, state, verbose, nested + 1,
  File "C:\Python39\lib\sre_parse.py", line 668, in _parse
    raise source.error("nothing to repeat",
re.error: nothing to repeat at position 0

This happens after a fresh clone, using Python version 3.9.1