From baeb1f7beb2a80179fb79e1e38518c99845988ef Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Mon, 18 Apr 2011 09:29:35 +0100 Subject: vim-mode/vim_mode: podified help --- vim-mode/vim_mode.pl | 656 ++++++++++++++++++++++++++++++++------------------- 1 file changed, 412 insertions(+), 244 deletions(-) (limited to 'vim-mode') diff --git a/vim-mode/vim_mode.pl b/vim-mode/vim_mode.pl index b279790..3e844e5 100644 --- a/vim-mode/vim_mode.pl +++ b/vim-mode/vim_mode.pl @@ -1,247 +1,415 @@ -# A script to emulate some of the vi(m) features for the Irssi inputline. -# -# It should work fine with at least 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. -# -# 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 -# -# or contact rudi_s or shabble on irc.freenode.net (#irssi and #irssi_vim) -# -# -# Features: -# -# 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 ^ $ 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 "* "+ contain both irssi's 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. 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. -# -# The following insert mode mappings are supported: -# -# * Insert register content: Ctrl-R x (where x is the register to insert) -# -# Ex-mode supports (activated by : in command mode) the following commands: -# -# * Command History: , -# :eh - show ex history -# * Switching buffers: :[N]b [N] - switch to channel number -# :b# - switch to last channel -# :b -# :b / -# :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. is Ctrl-F), case is ignored. Supported <> keys: -# -, , , , , , . Mapping ex-mode and -# irssi commands is supported. When mapping ex-mode commands the trailing -# 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 /clear - map Ctrl-L to irssi command /clear -# :map /window goto 1 -# :map - disable , it does nothing now -# :unmap - restore default behavior of after disabling it -# -# Note that you must use / for irssi commands (like /clear), the current value -# of 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 , -# string, default '' -# * 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 -# -# -# The following statusbar items are available: -# -# * vim_mode: displays current mode -# * vim_windows: displays windows selected with :b -# -# -# Configuration -# -# Additionally to the irssi settings described above 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. It's syntax is similar to "vimrc". To (re)load -# it while vim_mode is running use :so[urce]. -# -# Supported ex-commands: -# -# * :map -# -# -# Installation: -# -# As always, copy the script into .irssi/scripts and load it with -# /script load vim_mode.pl -# -# 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 -# -# -# Dependencies: -# -# For proper :ex mode support, vim-mode requires the installation of uberprompt.pl -# Uberprompt can be downloaded from: -# -# http://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 -# -# -# Known 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) -# * undo/redo positions are mostly wrong -# -# -# TODO: -# * History: -# * /,?,n,N to search through history (like history_search.pl) -# * Window switching (:b) -# * Tab completion of window(-item) names -# * non-sequential matches(?) -# -# WONTFIX - things we're not ever likely to do -# * Macros -# -# THANKS: -# -# * estragib: a lot of testing and many bug reports and feature requests -# * iaj: testing -# * tmr: explaining how various bits of vim work -# -# LICENCE: -# -# Copyright (c) 2010 Tom Feist & Simon Ruderich -# -# 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. -# -# -# Have fun! +=pod + +=head1 NAME + +vim_mode.pl + +=head1 DESCRIPTION + +An Irssi script to emulate some of the vi(m) features for the Irssi inputline. + +=head1 INSTALLATION + +Copy into your F<~/.irssi/scripts/> directory and load with +C. You may wish to have it autoload in one of the +L. + +=head2 DEPENDENCIES + +For proper :ex mode support, vim-mode requires the installation of F +Uberprompt can be downloaded from: + +L + +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. + +=head3 Irssi requirements + +0.8.12 and above should work fine. However the following features are +disabled in irssi < 0.8.13: + +=over 4 + +=item C C (only with count, they work fine without count in older versions) + +=item C, C + +=back + +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. + +=head2 SETUP + +Use the following command to get a statusbar item that shows which mode +you're in. + +C + +And the following to let C<:b I> display a list of matching channels + +C + +B Remember to C after adding these statusbar items to make them +permanent. + + +=head3 FILE-BASED CONFIGURATION + +Additionally to the irssi settings described in L, vim_mode +can be configured through an external configuration file named "vim_moderc" +located in F<~/.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 C<:so[urce]>. + +Currently Supported ex-commands: + +=over 4 + +=item C<:map> + +=back + +=head1 USAGE + +=head2 COMMAND MODE + +It supports most commonly used command mode features: + +=over 4 + +=item 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). + +=item Cursor motion: h l 0 ^ $ f t F T + +=item 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). + +=item Cursor word motion: C + +=item Word objects (only the following work yet): C + +=item Yank and paste: C + +=item Change and delete: C + +=item Delete at cursor: C + +=item Replace at cursor: C + +=item Insert mode: C + +=item Switch case: C<~> + +=item Repeat change: C<.> + +=item Repeat C + +=item Registers: C<"a-"z "" "0 "* "+ "_> (black hole) + +=over 4 + +=item Appending to register with C<"A-"Z> + +=item C<""> is the default yank/delete register. + +=item C<"0> contains the last yank (if no register was specified). + +=item The special registers C<"* "+> both contain irssi's internal cut-buffer. + +=back + +=item Line-wise shortcuts: C
+ +=item Shortcuts: C + +=item Scroll the scrollback buffer: C + +=item Switch to last active window: C + +=item Switch split windows: + +=item Undo/Redo: C + +=back + +Counts and combinations work as well, e.g. C or C<3iabcEescE>. +Counts also work with mapped ex-commands (see below), e.g. if you map C to do +C<:bn>, then C<2gb> will switch to the second next buffer. Repeat also supports +counts. + +=head2 INSERT MODE + +The following insert mode mappings are supported: + +=over 4 + +=item Insert register content: Ctrl-R x (where x is the register to insert) + +=back + +=head2 EX-MODE + +Ex-mode (activated by C<:> in command mode) supports the following commands: + +=over 4 + +=item Command History: CuparrowE>, C> + C<:eh> - show ex history + +=item Switching buffers: C<:[N]b [N]> - switch to channel number + C<:b#> - switch to last channel + C<:b> Epartial-channel-nameE + C<:b> / + C<:buffer {args}> (same as C<:b>) + C<:[N]bn[ext] [N]> - switch to next window + C<:[N]bp[rev] [N]> - switch to previous window + +=item Close window: C<:[N]bd[elete] [N]> + +=item Display windows: C<:ls>, C<:buffers> + +=item Display registers: C<:reg[isters] {args}>, C<:di[splay] {args}> + +=item Display undolist: C<:undol[ist]> (mostly used for debugging) + +=item Source files C<:so[urce]> - only sources vim_moderc at the moment, + F<{file}> not supported + +=item Mappings: C<:map> - display custom mappings + +=over 4 + +=item C<:map {lhs}> - display mappings starting with {lhs} + +=item C<:map {lhs} {rhs}> - add mapping + +=item C<:unm[ap] {lhs}> - remove custom mapping + +=back + +=item Save mappings: C<:mkv[imrc][!]> - like in Vim, but [file] not supported + +=item Substitute: C<:s///> - I and I are supported as flags, only /// can + be used as separator, uses Perl regex instead of + Vim regex + +=item Settings: C<:se[t]> - display all options + C<:se[t] {option}> - display all matching options + C<:se[t] {option} {value}> - change option to value + +=back + +=head3 MAPPINGS + +C<{lhs}> is the key combination to be mapped, C<{rhs}> the target. The +CE>> notation is used + +(e.g. CC-FE> is Ctrl-F), case is ignored. Supported CE> keys: + +=over 4 + +=item CC-AE> - CC-ZE>, + +=item CC-^E> + +=item CC-6E> + +=item CSpaceE> + +=item CCRE> + +=item CBSE> + +=item CNopE> + +=back + +Mapping ex-mode and irssi commands is supported. When mapping ex-mode commands +the trailing CCrE> is not necessary. Only default mappings can be used +in {rhs}. + +Examples: + +=over 4 + +=item C<:map w W> - to remap w to work like W + +=item C<:map gb :bnext> - to map gb to call :bnext + +=item C<:map gB :bprev> + +=item C<:map g1 :b 1> - to map g1 to switch to buffer 1 + +=item C<:map gb :b> - to map gb to :b, 1gb switches to buffer 1, 5gb to 5 + +=item C<:map /clear> - map Ctrl-L to irssi command /clear + +=item C<:map /window goto 1> + +=item C<:map > - disable , it does nothing now + +=item C<:unmap > - restore default behavior of after disabling it + +=back + +Note that you must use C for irssi commands (like C), the current value +of Irssi's cmdchars does B work! This is necessary do differentiate between +ex-commands and irssi commands. + +=head2 SETTINGS + +The settings are stored as irssi settings and can be set using C as usual +(prepend C to setting name) or using the C<:set> ex-command. The +following settings are available: + +=over 4 + +=item utf8: support UTF-8 characters, boolean, default on + +=item debug: enable debug output, boolean, default off + +=item cmd_seq: char that when double-pressed simulates , + string, default '' +=item start_cmd: start every line in command mode, boolean, default off + +=item max_undo_lines: size of the undo buffer. Integer, default 50 items. + +=item ex_history_size: number of items stored in the ex-mode history. + Integer, default 100. + +=item prompt_leading_space: determines whether ex mode prepends a space to the + displayed input. Boolean, default on + +=back + +In contrast to irssi's settings, C<: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 + +=head1 SUPPORT + +Any behavior different from Vim (unless explicitly documented) should be +considered a bug and reported. + +B This script is still under heavy development, and there may be bugs. +Please submit reproducible sequences to the bug-tracker at: +L + +or contact rudi_s or shabble on irc.freenode.net (#irssi and #irssi_vim) + +=head1 AUTHORS + +Copyright E 2010-2011 Tom Feist Cshabble+irssi@metavore.orgE> and +Copyright E 2010-2011 Simon Ruderich Csimon@ruderich.org> + +=head1 THANKS + +Particular thanks go to + +=over 4 + +=item estragib: a lot of testing and many bug reports and feature requests + +=item iaj: testing + +=item tmr: explaining how various bits of vim work + +=back + +as well as the rest of C<#irssi> and C<#irssi_vim> on Freenode IRC. + +=head1 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. + +=head1 BUGS + +=over 4 + +=item count before register doesn't work: e.g. 3"ap doesn't work, but "a3p does + +=item mapping an incomplete ex-command doesn't open the ex-mode with the partial + command (e.g. C<:map gb :b> causes an error instead of opening the ex-mode and + displaying C<:bEcursorE>) + +=item undo/redo cursor positions are mostly wrong + +=back + +=head1 TODO + +=over 4 + +=item History: + +=over 4 + +=item C< * /,?,n,N> to search through history (like rl_history_search.pl) + +=back + +=item Window switching (C<:b>) + +=over 4 + +=item Tab completion of window(-item) names + +=item non-sequential matches(?) + +=back + +=back + +See also the TODO file at +L for +many many more things. + +=head2 WONTFIX + +Things we're not ever likely to do: + +=over 4 + +=item Macros + +=back + +=cut use strict; use warnings; -- cgit v1.2.3