@@ -1,41 +1,59 @@

 # [`readline-vim`][]

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

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

-[`readline-vim`][] is a Python program that generates [Readline][] macros that

-provide [Vim][] [motions][], [operators][] and [text objects][] (that are

-useful on a single line).

+[`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

-[Python]: https://www.python.org

 [Readline]: https://en.wikipedia.org/wiki/Readline

-[`vi`]: https://en.wikipedia.org/wiki/vi

-[Vim]: https://en.wikipedia.org/wiki/Vim

+[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][] or

-[Octave][]. Using [`rlwrap`][], Readline can even be used with programs that

-doesn't have built in support for it, such as Matlab (as in `lrwrap -a matlab

--nodesktop -nosplash`). These factors make it fairly ubiquitous.

+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`.

+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

+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

+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][].

+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

@@ -46,15 +64,151 @@ git clone https://git.rcrnstn.net/rcrnstn/readline-vim

 cd readline-vim

 ```

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

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

 ```sh

 ./readline-vim >> ~/.inputrc

 ```

-## Similar projects

+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:).

--   [`bash-surround`](https://github.com/liloman/bash-surround)

+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.

@@ -62,7 +216,7 @@ and append the output to your `~/.inputrc`

     The instructions are Bash centric, although it uses general Readline

     macros.

--   [Athame](https://github.com/ardagnir/athame)

+-   [Athame][]

     Patches Readline to route keystrokes through an actual Vim process. Also

     provides patches for [Zsh][]. This means that whatever your local Vim

@@ -71,14 +225,35 @@ and append the output to your `~/.inputrc`

     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.

--   [`readline-vim`](https://github.com/thlorenz/readline-vim)

+-   [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.

+    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

-[Zsh]: https://en.wikipedia.org/wiki/Zsh

 ## License

@@ -2,11 +2,12 @@

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

-[`readline-vim`][] generates [Readline][] macros that provide [Vim][]

-[motions][], [operators][] and [text objects][] (that are useful on a single

-line).

+[`readline-vim`][] is a Python program that generates [Readline][] macros that

+provide [Vim][] [motions][], [operators][] and [text objects][] (that are

+useful on a single line).

 [`readline-vim`]: https://git.rcrnstn.net/rcrnstn/readline-vim

+[Python]: https://www.python.org

 [Readline]: https://en.wikipedia.org/wiki/Readline

 [`vi`]: https://en.wikipedia.org/wiki/vi

 [Vim]: https://en.wikipedia.org/wiki/Vim

@@ -36,6 +36,21 @@ 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][].

+## Usage

+

+Clone the repository

+

+```sh

+git clone https://git.rcrnstn.net/rcrnstn/readline-vim

+cd readline-vim

+```

+

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

+

+```sh

+./readline-vim >> ~/.inputrc

+```

+

 ## Similar projects

 -   [`bash-surround`](https://github.com/liloman/bash-surround)

@@ -36,6 +36,34 @@ 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][].

+## Similar projects

+

+-   [`bash-surround`](https://github.com/liloman/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](https://github.com/ardagnir/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.

+

+-   [`readline-vim`](https://github.com/thlorenz/readline-vim)

+

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

+    `vi` bindings, not Vim.

+

+[Node.js]: https://nodejs.org

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

+[Zsh]: https://en.wikipedia.org/wiki/Zsh

+

 ## License

 Licensed under the [ISC License][], see the [`LICENSE`](LICENSE) file.

@@ -14,6 +14,28 @@ line).

 [operators]: https://vimhelp.org/motion.txt.html#operator

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

+## 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][] or

+[Octave][]. Using [`rlwrap`][], Readline can even be used with programs that

+doesn't have built in support for it, such as Matlab (as in `lrwrap -a matlab

+-nodesktop -nosplash`). These factors make it fairly ubiquitous.

+

+Readline can be configured with an `inputrc` file, usually placed at

+`~/.inputrc`.

+

+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][].

+

 ## License

 Licensed under the [ISC License][], see the [`LICENSE`](LICENSE) file.

@@ -13,3 +13,9 @@ line).

 [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

+

+## License

+

+Licensed under the [ISC License][], see the [`LICENSE`](LICENSE) file.

+

+[ISC License]: https://choosealicense.com/licenses/isc/

new file mode 100644

@@ -0,0 +1,15 @@

+# [`readline-vim`][]

+

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

+

+[`readline-vim`][] generates [Readline][] macros that provide [Vim][]

+[motions][], [operators][] and [text objects][] (that are useful on a single

+line).

+

+[`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

+[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