From 8f2c0f48264fd91477c0d2b049b964d9088bbb6c Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Mon, 18 Apr 2011 10:27:56 +0100 Subject: vim-mode/vim_mode: more changes to docs and generator. Starting to look almost readable now. --- readme_generator.pl | 43 ++++++----- vim-mode/README.md | 203 +++++++++++++++++++++++++++++++-------------------- vim-mode/vim_mode.pl | 187 ++++++++++++++++++++++++++++------------------- 3 files changed, 256 insertions(+), 177 deletions(-) diff --git a/readme_generator.pl b/readme_generator.pl index 67da7ac..2062ad1 100644 --- a/readme_generator.pl +++ b/readme_generator.pl @@ -14,6 +14,15 @@ use File::Spec; use Pod::Markdown; use feature qw/say/; use Cwd; + +my $overwrite = $ARGV[0]; +if ($overwrite =~ m/--overwrite/) { + shift @ARGV; # remove it form list of dirs. + $overwrite = 1; +} else { + $overwrite = 0; +} + my @dirs = map { File::Spec->catdir(getcwd(), $_) } @ARGV; die unless @dirs; @@ -32,25 +41,12 @@ sub read_input_file { my ($dir, $filename) = @_; my $filepath = File::Spec->catfile($dir, $filename); - - open my $rfh, '<', $filepath or die "Couldn't open $filepath for input: $!"; - _err("reading $filepath"); my $parser = Pod::Markdown->new; + $parser->parse_from_file($filepath); - $parser->parse_from_filehandle($rfh); - - close $rfh; - - my @other_files = glob($dir . "/*.pl"); - - # if (@other_files > 1) { - # $filename =~ s/\.pl$//; - # create_output_file($dir, "README-$filename.md", $parser); - # } else { - create_output_file($dir, "README.md", $parser); - # } + create_output_file($dir, "README.md", $parser); } sub create_output_file { @@ -59,20 +55,27 @@ sub create_output_file { my $filepath = File::Spec->catfile($dir, $filename); my $markdown = $parser->as_markdown; + return unless length chomp($markdown); return if $markdown =~ m/^\s*$/; - _err("Writing to $filepath"); my $sec_sep = ''; - if (-f $filepath) { - _err("$filepath already exists, going to append"); + + if (-f $filepath and not $overwrite) { + _err("$filepath already exists, going to append") unless $overwrite; $sec_sep = "\n\n* * * *\n\n"; } - open my $wfh, '>>', $filepath or die "Couldn't open $filepath for output: $!"; + my $mode = $overwrite ? '>' : '>>'; + + _err("Writing to $mode $filepath"); + + open my $wfh, $mode, $filepath + or die "Couldn't open $filepath for $mode output: $!"; + print $wfh $sec_sep; - print $wfh $parser->as_markdown; + print $wfh $parser->as_markdown; # fetch it again since we chomped $markdown. close $wfh; } diff --git a/vim-mode/README.md b/vim-mode/README.md index a59691a..593d39d 100644 --- a/vim-mode/README.md +++ b/vim-mode/README.md @@ -22,7 +22,7 @@ Uberprompt can be downloaded from: 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. +uberprompt.pl script, but it is strongly recommended that you use it. ### Irssi requirements @@ -42,12 +42,13 @@ to a script of this size and complexity. ## SETUP -Use the following command to get a statusbar item that shows which mode +Run the following command to add 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 +And the following to let `:b [str]` display a list of channels matching your +search string. `/statusbar window add vim_windows` @@ -70,34 +71,28 @@ Currently Supported ex-commands: # USAGE +The following section is divided into the different modes as supported by Vim itself: + ## 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 ^ $ 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. - +- 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) - 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` @@ -105,10 +100,14 @@ It supports most commonly used command mode features: - Switch split windows: - 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. +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. + +### REGISTERS + +- 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. ## INSERT MODE @@ -120,52 +119,98 @@ The following insert mode mappings are supported: Ex-mode (activated by `:` in command mode) supports 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 +- Command History: + +`` - cycle backwards through history + +`` - cycle forwards through 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 + +- 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 +#### Commands + +- `:map {lhs}` - display mappings starting with {lhs} +- `:map {lhs} {rhs}` - add mapping +- `:unm[ap] {lhs}` - remove custom mapping + +#### Parameters + +_{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: +(e.g. `` is _Ctrl-F_), case is ignored. + Supported `<>` keys are: - `` - ``, -- `` -- `` +- ``, `` - `` -- `<CR>` -- `<BS>` -- `` +- `` - Enter +- `` - Backspace +- `` - No-op (Do Nothing). 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}. +in _{rhs}_. Examples: @@ -174,10 +219,11 @@ Examples: - `: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 - map Ctrl-L to irssi command /clear -- `:map -- `:map > - disable , it does nothing now -- `:unmap - restore default behavior of after disabling it +- `: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 Irssi's cmdchars does __not__ work! This is necessary do differentiate between @@ -191,14 +237,11 @@ 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 '' -=item start_cmd: start every line in command mode, boolean, default off +- cmd_seq: char that when double-pressed simulates ``, string, default '' (disabled) +- 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 +- 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. @@ -217,14 +260,14 @@ 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) +[http://github.com/shabble/irssi-scripts/issues/new](http://github.com/shabble/irssi-scripts/issues/new) or contact rudi_s or shabble on irc.freenode.net (#irssi and #irssi_vim) # AUTHORS Copyright © 2010-2011 Tom Feist `` and -Copyright © 2010-2011 Simon Ruderich ` +Copyright © 2010-2011 Simon Ruderich `` # THANKS diff --git a/vim-mode/vim_mode.pl b/vim-mode/vim_mode.pl index 3e844e5..4c63bf1 100644 --- a/vim-mode/vim_mode.pl +++ b/vim-mode/vim_mode.pl @@ -24,7 +24,7 @@ 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. +uberprompt.pl script, but it is strongly recommended that you use it. =head3 Irssi requirements @@ -49,12 +49,13 @@ to a script of this size and complexity. =head2 SETUP -Use the following command to get a statusbar item that shows which mode +Run the following command to add 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 +And the following to let C<:b [str]> display a list of channels matching your +search string. C @@ -80,22 +81,21 @@ Currently Supported ex-commands: =head1 USAGE +The following section is divided into the different modes as supported by Vim itself: + =head2 COMMAND MODE It supports most commonly used command mode features: -=over 4 +=over 2 -=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 Insert/Command mode. C and C enter command mode. C allows to use C as Escape (any other character can be used as well). -=item Cursor motion: h l 0 ^ $ f t F T +=item Cursor motion: CSpaceE EBSE 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 History motion: C C moves to the oldest (first) history +line. C without a count moves to the current input line, with a count it goes to the I history line (1 is the oldest). =item Cursor word motion: C @@ -119,18 +119,6 @@ It supports most commonly used command mode features: =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 @@ -145,10 +133,21 @@ It supports most commonly used command mode features: =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. +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. + +=head3 REGISTERS + +=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 =head2 INSERT MODE @@ -166,80 +165,115 @@ 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 Command History: + +CuparrowE> - cycle backwards through history + +CdownarrowE> - cycle forwards through history + +C<:eh> - show ex history + +=item Switching buffers: + +C<:[N]b [N]> - switch to channel number -=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 +C<:b#> - switch to last channel -=item Close window: C<:[N]bd[elete] [N]> +C<:b> Epartial-channel-nameE -=item Display windows: C<:ls>, C<:buffers> +C<:b> / -=item Display registers: C<:reg[isters] {args}>, C<:di[splay] {args}> +C<:buffer {args}> (same as C<:b>) -=item Display undolist: C<:undol[ist]> (mostly used for debugging) +C<:[N]bn[ext] [N]> - switch to next window -=item Source files C<:so[urce]> - only sources vim_moderc at the moment, +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: + +<: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 +=item Mappings: -=over 4 +C<:map> - display custom mappings -=item C<:map {lhs}> - display mappings starting with {lhs} +=item Save mappings: -=item C<:map {lhs} {rhs}> - add mapping +C<:mkv[imrc][!]> - like in Vim, but [file] not supported -=item C<:unm[ap] {lhs}> - remove custom mapping +=item Substitute: -=back +C<:s///> - I and I are supported as flags, only /// can be used as + separator, uses Perl regex instead of Vim regex -=item Save mappings: C<:mkv[imrc][!]> - like in Vim, but [file] not supported +=item Settings: -=item Substitute: C<:s///> - I and I are supported as flags, only /// can - be used as separator, uses Perl regex instead of - Vim regex +C<:se[t]> - display all options -=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 +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 +=head4 Commands + +=over 4 + +=item C<:map {lhs}> - display mappings starting with {lhs} + +=item C<:map {lhs} {rhs}> - add mapping -(e.g. CC-FE> is Ctrl-F), case is ignored. Supported CE> keys: +=item C<:unm[ap] {lhs}> - remove custom mapping + +=back + +=head4 Parameters + +I<{lhs}> is the key combination to be mapped, I<{rhs}> the target. The +CE> notation is used + +(e.g. CC-FE> is I), case is ignored. + Supported CE> keys are: =over 4 =item CC-AE> - CC-ZE>, -=item CC-^E> - -=item CC-6E> +=item CC-^E>, CC-6E> =item CSpaceE> -=item CCRE> +=item CCRE> - Enter -=item CBSE> +=item CBSE> - Backspace -=item CNopE> +=item CNopE> - No-op (Do Nothing). =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}. +in I<{rhs}>. Examples: @@ -255,13 +289,14 @@ Examples: =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 EC-LE /clear> - map Ctrl-L to irssi command /clear -=item C<:map /window goto 1> +=item C<:map EC-GE /window goto 1> -=item C<:map > - disable , it does nothing now +=item C<:map EC-EE > - disable , it does nothing now -=item C<:unmap > - restore default behavior of after disabling it +=item C<:unmap EC-EE> - restore default behavior of CC-EE> +after disabling it =back @@ -281,17 +316,15 @@ following settings are available: =item debug: enable debug output, boolean, default off -=item cmd_seq: char that when double-pressed simulates , - string, default '' +=item cmd_seq: char that when double-pressed simulates CEscE>, string, default '' (disabled) + =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 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 +=item prompt_leading_space: determines whether ex mode prepends a space to the displayed input. Boolean, default on =back @@ -312,14 +345,14 @@ 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 +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> +Copyright E 2010-2011 Simon Ruderich Csimon@ruderich.orgE> =head1 THANKS -- cgit v1.2.3