# [`readline-vim`][]
 

 Upgrade [Readline][] from [vi][] to [Vim][].

 [`readline-vim`][] is a [Python][] script that generates [Readline][] macros
 (4658 of them) that provide [Vim][] [motions][], [operators][] and [text
 objects][] (the ones that are useful on a single line) as well as functionality
 from the popular [`vim-surround`][].

 
 [`readline-vim`]: https://git.rcrnstn.net/rcrnstn/readline-vim
 [Readline]: https://en.wikipedia.org/wiki/Readline

 [vi]: https://en.wikipedia.org/wiki/vi
 [Vim]: https://en.wikipedia.org/wiki/Vim_(text_editor)
 [Python]: https://www.python.org

 [motions]: https://vimhelp.org/motion.txt.html
 [operators]: https://vimhelp.org/motion.txt.html#operator
 [text objects]: https://vimhelp.org/motion.txt.html#text-objects

 [`vim-surround`]: https://github.com/tpope/vim-surround

 ## Background
 
 [Readline][] is a library that provides line-editing for interactive
 command-line programs. It is used in a great many places, including shells such

 as [Bash][] (where it originated) and [REPL][]s such as [Python][]'s or
 [Octave][]'s. Using [`rlwrap`][], Readline can even be used with programs that
 don't have built-in support for it, such as [MATLAB][] (as in `rlwrap -a matlab
 -nodesktop -nosplash`). There are bindings in many languages, so if you're a
 developer you can easily use it in your own projects. These factors make it
 fairly ubiquitous.

 Readline can be configured with an [`inputrc`][] file, usually placed at
 [`~/.inputrc`][], which supports an [`$include`][] directive useful for
 including other files, e.g. from `~/.inputrc.d/`.

 
 Readline uses [Emacs][]-like key bindings by default. If you're a Vim fan

 though, you probably use its vi mode, activated by `set editing-mode vi` in the
 configuration or through some mechanism in the containing program, such as

 Bash's `set -o vi`.
 
 If you *are* a Vim fan though, this has the potential of landing you in a sort

 of [uncanny valley][] since (Readline's) vi (mode) does not include the many

 improvements contained in Vim that you have come to rely on, mainly [text

 objects][] and the related plugins. This is especially bad if you're using
 Readline inside Vim's own [`:terminal`][]. [`readline-vim`][] aims to fix this.
 
 [Bash]: https://en.wikipedia.org/wiki/Bash_(Unix_shell)
 [REPL]: https://en.wikipedia.org/wiki/Read-eval-print_loop
 [Octave]: https://en.wikipedia.org/wiki/GNU_Octave
 [`rlwrap`]: https://manpages.debian.org/rlwrap/rlwrap.1.html
 [MATLAB]: https://en.wikipedia.org/wiki/MATLAB
 [`inputrc`]: https://www.mankier.com/3/readline#Initialization_File
 [`~/.inputrc`]: https://www.mankier.com/3/readline#Files-~/.inputrc
 [`$include`]: https://www.mankier.com/3/readline#Initialization_File-Conditional_Constructs
 [Emacs]: https://en.wikipedia.org/wiki/Emacs
 [uncanny valley]: https://en.wikipedia.org/wiki/Uncanny_valley
 [`:terminal`]: https://vimhelp.org/terminal.txt.html#:terminal

 ## Usage
 
 Clone the repository
 
 ```sh
 git clone https://git.rcrnstn.net/rcrnstn/readline-vim
 cd readline-vim
 ```
 

 and either append the output to your `~/.inputrc`

 
 ```sh
 ./readline-vim >> ~/.inputrc
 ```
 

 or use a separate file and include it (recommended)
 
 ```sh
 mkdir -p ~/.inputrc.d
 ./readline-vim >| ~/.inputrc.d/readline-vim.inputrc
 ```
 
 ```sh
 cat >> ~/.inputrc << 'EOF'
 
 ## `readline-vim`
 $include ~/.inputrc.d/readline-vim.inputrc
 EOF
 ```
 
 ### Use vi mode by default
 
 ```sh
 cat >> ~/.inputrc << 'EOF'
 
 ## Use vi editing mode
 set editing-mode vi
 EOF
 ```
 
 ### Indicate mode with cursor shape
 
 ```sh
 cat >> ~/.inputrc << 'EOF'
 
 ## Indicate mode with cursor shape
 set show-mode-in-prompt On
 $if term=linux
     # https://www.kernel.org/doc/Documentation/admin-guide/vga-softcursor.rst
     set vi-cmd-mode-string \1\e[?8c\2
     set vi-ins-mode-string \1\e[?0c\2
     set emacs-mode-string  \1\e[?0c\2
 $else
     # https://vt100.net/docs/vt510-rm/DECSCUSR
     # http://invisible-island.net/xterm/ctlseqs/ctlseqs.html
     set vi-cmd-mode-string \1\e[1 q\2
     set vi-ins-mode-string \1\e[5 q\2
     set emacs-mode-string  \1\e[5 q\2
 $endif
 EOF
 ```
 
 ## Features
 
 -   Motions
     -   vi (built-in)
         -   Word (upper and lower case versions)
             -   `w` *word beginning, forwards*
             -   `e` *word end, forwards*
             -   `b` *word beginning, backwards*
         -   Other
             -   `h`, `l` *left, right*
             -   `0`, `^`, `$` *line beginning, first non-whitespace character,
                 end*.
             -   `|` *(first) column*
             -   `;`, `,` *next, previous searched character*
             -   `%` *matching pair character*
     -   Vim
         -   Word (upper and lower case versions)
             -   `ge` *word end, backwards*
         -   Other
             -   `g_` *last non-whitespace character*
             -   `)`, `(` *sentence, forwards, backwards* (only works with
                 sentences after ".")
 -   Operators
     -   vi
         -   `d` *delete*
         -   `c` *change*
         -   `y` *[yank][]*
     -   [`vim-surround`][]
         -   `ds` *delete surroundings*
         -   `cs` *change surroundings*
         -   `ys` *add surroundings ("you surround")*
 -   Text objects
     -   Motions (vi and Vim)
     -   Implicit line (repeat last character of operator)
     -   Vim words (`a` *an* and `i` *inner*, upper and lower case versions)
         -   `w` *word*
     -   Vim pairs (`a` *an* and `i` *inner* versions)
         -   Distinct
             -   Matching
                 -   `(`, `)`, `b`
                 -   `{`, `}`, `B`
                 -   `[`, `]`
             -   Other
                 -   `<`, `>`
         -   Nondistinct
             -   Quotes
                 -   `"`, `'`, `` ` ``
             -   Punctuation
                 -   `#`, `$`, `%`, `&`, `@`, `\\`, `^` `_`, `|`, `~`
                 -   `.`, `,`, `:`, `;`, `!`, `?`
                 -   `+`, `-`, `*`, `/`, `=`
 
 [yank]: https://en.wiktionary.org/wiki/yank
 
 ## Bugs
 
 Some macros clobber the `a`, `b` and/or `c` marks.
 
 Only forward motions work as expected with the surround operators.
 
 Most known bugs exhibit themselves at the end, and sometimes the beginning, of
 line. This is sometimes unavoidable, sometimes a trade-off to produce correct
 behavior elsewhere, mostly single-character words and/or whitespace:
 
 -   `ge`/`gE` motions: Jumps past last word on line, does not jump past first
     word on line.
 -   word/WORD text objects: Always excludes the last character on line.
 -   Implicit line text object (as used in e.g. `yss)`): Includes whitespace at
     the beginning and end of line.
 
 ## Implementation notes
 
 This is an honest attempt to solve this problem "optimally". However, Readline
 macros are not [Turing complete][Turing completeness] (in contrast to e.g.
 VimScript) which makes this kind of hard (and more fun :smile:).

 Testing suggests that marks are not supported by all applications when combined
 with operators in macros. No workaround has been found.
 
 Counts used in macros have to come before the operator. That is, `2cl` works
 but `c2l` does not.
 
 Macros are what Vim calls recursive, i.e. they can make use of other macros in
 their expansion. To use Readline commands (such as `upcase-word`) they need to
 be bound to a key sequence (if no binding exists already) before being used in
 macros.
 
 [Turing completeness]: https://en.wikipedia.org/wiki/Turing_completeness
 
 ## Related projects
 
 -   [`bash-surround`][]

 
     Defines the macros manually and therefore "only" provides 234 of them,
     missing some functionality.
 
     The instructions are Bash centric, although it uses general Readline
     macros.
 

 -   [Athame][]

 
     Patches Readline to route keystrokes through an actual Vim process. Also
     provides patches for [Zsh][]. This means that whatever your local Vim
     supports, Athame supports (including plugins)!
 
     Can be a little unreliable if your local Vim has a ton of plugins,
     especially if they interact with the terminal in non-obvious ways.
 

 -   [Zsh][]
 
     Has built-in [text objects][Zsh text objects] and [surround][Zsh surround]
     support. It even has a Vim-like [Visual mode][Zsh Visual mode]. The popular
     [Oh My Zsh][] Zsh configuration framework extends this with its
     [`vi-mode`][Oh My Zsh `vi-mode`] plugin. There are also several other
     plugins:
 
     -   [`softmoth/zsh-vim-mode`][]
     -   [`jeffreytse/zsh-vi-mode`][]
 
 -   [`thlorenz/readline-vim`][]

 
     Exclusive to [Node.js][] [`readline`][Node.js `readline`] and only defines

     vi bindings, not Vim bindings.

 [`bash-surround`]: https://github.com/liloman/bash-surround
 [Athame]: https://github.com/ardagnir/athame
 [Zsh]: https://en.wikipedia.org/wiki/Zsh
 [Zsh text objects]: http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#Text-Objects
 [Zsh surround]: https://sourceforge.net/p/zsh/code/ci/master/tree/Functions/Zle/surround
 [Zsh Visual mode]: http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#index-visual_002dmode
 [Oh My Zsh]: https://ohmyz.sh
 [Oh My Zsh `vi-mode`]: https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/vi-mode
 [`softmoth/zsh-vim-mode`]: https://github.com/softmoth/zsh-vim-mode
 [`jeffreytse/zsh-vi-mode`]: https://github.com/jeffreytse/zsh-vi-mode
 [`thlorenz/readline-vim`]: https://github.com/thlorenz/readline-vim

 [Node.js]: https://nodejs.org
 [Node.js `readline`]: https://nodejs.org/api/readline.html#readline_readline
 

 ## License
 
 Licensed under the [ISC License][], see the [`LICENSE`](LICENSE) file.
 
 [ISC License]: https://choosealicense.com/licenses/isc/