diff options
| -rw-r--r-- | vim-mode/README.md | 284 |
1 files changed, 284 insertions, 0 deletions
diff --git a/vim-mode/README.md b/vim-mode/README.md new file mode 100644 index 0000000..a59691a --- /dev/null +++ b/vim-mode/README.md @@ -0,0 +1,284 @@ +# NAME + +vim_mode.pl + +# DESCRIPTION + +An Irssi script to emulate some of the vi(m) features for the Irssi inputline. + +# INSTALLATION + +Copy into your `~/.irssi/scripts/` directory and load with +`/SCRIPT LOAD vim_mode.pl`. You may wish to have it autoload in one of the +[usual ways](https://github.com/shabble/irssi-docs/wiki/Guide#Autorunning_Scripts). + +## DEPENDENCIES + +For proper :ex mode support, vim-mode requires the installation of `uberprompt.pl` +Uberprompt can be downloaded from: + +[https://github.com/shabble/irssi-scripts/raw/master/prompt_info/uberprompt.pl](https://github.com/shabble/irssi-scripts/raw/master/prompt_info/uberprompt.pl) + +and follow the instructions at the top of that file for installation. + +If you don't need Ex-mode, you can run vim_mode.pl without the +uberprompt.pl script, but it is recommended. + +### Irssi requirements + +0.8.12 and above should work fine. However the following features are +disabled in irssi < 0.8.13: + +- `j` `k` (only with count, they work fine without count in older versions) +- `gg`, `G` + +It is intended to work with at Irssi 0.8.12 and later versions. However some +features are disabled in older versions (see below for details). + +Perl >= 5.8.1 is recommended for UTF-8 support (which can be disabled if +necessary). Please report bugs in older versions as well, we'll try to fix +them. Later versions of Perl are also faster, which is probably beneficial +to a script of this size and complexity. + +## SETUP + +Use the following command to get a statusbar item that shows which mode +you're in. + +`/statusbar window add vim_mode` + +And the following to let `:b _name_` display a list of matching channels + +`/statusbar window add vim_windows` + +__Note:__ Remember to `/save` after adding these statusbar items to make them +permanent. + + + +### FILE-BASED CONFIGURATION + +Additionally to the irssi settings described in [SETTINGS](#pod_SETTINGS), vim_mode +can be configured through an external configuration file named "vim_moderc" +located in `~/.irssi/vim_moderc`. If available it's loaded on startup and every +supported ex-command is run. Its syntax is similar to "vimrc". To (re)load it +while vim_mode is running use `:so[urce]`. + +Currently Supported ex-commands: + +- `:map` + +# USAGE + +## COMMAND MODE + +It supports most commonly used command mode features: + + - Insert/Command mode. Escape and Ctrl-C enter command mode. + /set vim_mode_cmd_seq j allows to use jj as Escape (any other character + can be used as well). + - Cursor motion: h l 0 ^ $ <Space> <BS> f t F T + - History motion: j k gg G + gg moves to the oldest (first) history line. + G without a count moves to the current input line, with a count it goes to + the count-th history line (1 is the oldest). + - Cursor word motion: `w b ge e W gE B E` + - Word objects (only the following work yet): `aw aW` + - Yank and paste: `y p P` + - Change and delete: `c d` + - Delete at cursor: `x X` + - Replace at cursor: `r` + - Insert mode: `i a I A` + - Switch case: `~` + - Repeat change: `.` + - Repeat `ftFT: ; ,` + - Registers: `"a-"z "" "0 "* "+ "_` (black hole) + - Appending to register with `"A-"Z` + - `""` is the default yank/delete register. + - `"0` contains the last yank (if no register was specified). + - The special registers `"* "+` both contain irssi's internal cut-buffer. + +- Line-wise shortcuts: `dd cc yy` +- Shortcuts: `s S C D` +- Scroll the scrollback buffer: `Ctrl-E Ctrl-D Ctrl-Y Ctrl-U Ctrl-F Ctrl-B` +- Switch to last active window: `Ctrl-6/Ctrl-^` +- Switch split windows: <Ctrl-W j Ctrl-W k> +- Undo/Redo: `u Ctrl-R` + +Counts and combinations work as well, e.g. `d5fx` or `3iabc<esc>`. +Counts also work with mapped ex-commands (see below), e.g. if you map `gb` to do +`:bn`, then `2gb` will switch to the second next buffer. Repeat also supports +counts. + +## INSERT MODE + +The following insert mode mappings are supported: + +- Insert register content: Ctrl-R x (where x is the register to insert) + +## EX-MODE + +Ex-mode (activated by `:` in command mode) supports the following commands: + + - Command History: `<uparrow>`, `<<downarrow>` + `:eh` - show ex history + - Switching buffers: `:[N]b [N]` - switch to channel number + `:b#` - switch to last channel + `:b` <partial-channel-name> + `:b` <partial-server>/<partial-channel> + `:buffer {args}` (same as `:b`) + `:[N]bn[ext] [N]` - switch to next window + `:[N]bp[rev] [N]` - switch to previous window + - Close window: `:[N]bd[elete] [N]` + - Display windows: `:ls`, `:buffers` + - Display registers: `:reg[isters] {args}`, `:di[splay] {args}` + - Display undolist: `:undol[ist]` (mostly used for debugging) + - Source files `:so[urce]` - only sources vim_moderc at the moment, + `{file}` not supported + - Mappings: `:map` - display custom mappings + - `:map {lhs}` - display mappings starting with {lhs} + - `:map {lhs} {rhs}` - add mapping + - `:unm[ap] {lhs}` - remove custom mapping + +- Save mappings: `:mkv[imrc][!]` - like in Vim, but [file] not supported +- Substitute: `:s///` - _i_ and _g_ are supported as flags, only /// can + be used as separator, uses Perl regex instead of + Vim regex +- Settings: `:se[t]` - display all options + `:se[t] {option}` - display all matching options + `:se[t] {option} {value}` - change option to value + +### MAPPINGS + +`{lhs}` is the key combination to be mapped, `{rhs}` the target. The +`<>`> notation is used + +(e.g. `<C-F>` is Ctrl-F), case is ignored. Supported `<>` keys: + +- `<C-A>` - `<C-Z>`, +- `<C-^>` +- `<C-6>` +- `<Space>` +- `<CR>` +- `<BS>` +- `<Nop>` + +Mapping ex-mode and irssi commands is supported. When mapping ex-mode commands +the trailing `<Cr>` is not necessary. Only default mappings can be used +in {rhs}. + +Examples: + +- `:map w W` - to remap w to work like W +- `:map gb :bnext` - to map gb to call :bnext +- `:map gB :bprev` +- `:map g1 :b 1` - to map g1 to switch to buffer 1 +- `:map gb :b` - to map gb to :b, 1gb switches to buffer 1, 5gb to 5 +- `:map <C-L` /clear> - map Ctrl-L to irssi command /clear +- `:map <C-G` /window goto 1> +- `:map <C-E` <Nop>> - disable <C-E>, it does nothing now +- `:unmap <C-E`> - restore default behavior of <C-E> after disabling it + +Note that you must use `/` for irssi commands (like `/clear`), the current value +of Irssi's cmdchars does __not__ work! This is necessary do differentiate between +ex-commands and irssi commands. + +## SETTINGS + +The settings are stored as irssi settings and can be set using `/set` as usual +(prepend `vim_mode_` to setting name) or using the `:set` ex-command. The +following settings are available: + +- utf8: support UTF-8 characters, boolean, default on +- debug: enable debug output, boolean, default off +- cmd_seq: char that when double-pressed simulates <esc>, + string, default '' +=item start_cmd: start every line in command mode, boolean, default off +- max_undo_lines: size of the undo buffer. Integer, default 50 items. +- ex_history_size: number of items stored in the ex-mode history. + Integer, default 100. +- prompt_leading_space: determines whether ex mode prepends a space to the + displayed input. Boolean, default on + +In contrast to irssi's settings, `:set` accepts 0 and 1 as values for boolean +settings, but only vim_mode's settings can be set/displayed. + +Examples: + + :set cmd_seq=j # set cmd_seq to j + :set cmd_seq= # disable cmd_seq + :set debug=on # enable debug + :set debug=off # disable debug + +# SUPPORT + +Any behavior different from Vim (unless explicitly documented) should be +considered a bug and reported. + +__NOTE:__ This script is still under heavy development, and there may be bugs. +Please submit reproducible sequences to the bug-tracker at: +[http://github.com/shabble/irssi-scripts/issues](http://github.com/shabble/irssi-scripts/issues) + +or contact rudi_s or shabble on irc.freenode.net (#irssi and #irssi_vim) + +# AUTHORS + +Copyright © 2010-2011 Tom Feist `<shabble+irssi@metavore.org>` and +Copyright © 2010-2011 Simon Ruderich `<simon@ruderich.org<gt`> + +# THANKS + +Particular thanks go to + +- estragib: a lot of testing and many bug reports and feature requests +- iaj: testing +- tmr: explaining how various bits of vim work + +as well as the rest of `#irssi` and `#irssi_vim` on Freenode IRC. + +# LICENCE + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. + +# BUGS + +- count before register doesn't work: e.g. 3"ap doesn't work, but "a3p does +- mapping an incomplete ex-command doesn't open the ex-mode with the partial + command (e.g. `:map gb :b` causes an error instead of opening the ex-mode and + displaying `:b<cursor>`) +- undo/redo cursor positions are mostly wrong + +# TODO + + - History: + - ` * /,?,n,N` to search through history (like rl_history_search.pl) + + - Window switching (`:b`) + - Tab completion of window(-item) names + - non-sequential matches(?) + +See also the TODO file at +[github](https://github.com/shabble/irssi-scripts/blob/master/vim-mode/TODO) for +many many more things. + +## WONTFIX + +Things we're not ever likely to do: + +- Macros
\ No newline at end of file |