Permalink
Switch branches/tags
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
746 lines (578 sloc) 21.3 KB
*caw.txt* Comment plugin: Operator/Dot-repeatable/300+ filetypes
Author:
tyru <tyru.exe@gmail.com>
Version: 1.0
License:
NEW BSD LICENSE {{{
Copyright (c) 2009, tyru
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
* Neither the name of the tyru nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
}}}
==============================================================================
CONTENTS *caw-contents*
Introduction |caw-introduction|
Features |caw-features|
Supported filetypes |caw-supported-filetypes|
Interface |caw-interface|
Keymappings |caw-keymappings|
Default keymappings |caw-keymappings-default|
Prefix keymapping |caw-keymappings-prefix|
Non-operator keymappings |caw-keymappings-non-operator|
Hatpos action |caw-hatpos-action|
Zeropos action |caw-zeropos-action|
Dollarpos action |caw-dollarpos-action|
Wrap action |caw-wrap-action|
Box action |caw-box-action|
Jump action |caw-jump-action|
Operator keymappings |caw-keymappings-operator|
Hatpos operator |caw-hatpos-operator|
Zeropos operator |caw-zeropos-operator|
Dollarpos operator |caw-dollarpos-operator|
Wrap operator |caw-wrap-operator|
Box operator |caw-box-operator|
Variables |caw-variables|
Scopes |caw-variables-scopes|
Comment String |caw-variables-comments|
Hatpos |caw-variables-hatpos|
Zeropos |caw-variables-zeropos|
Dollarpos |caw-variables-dollarpos|
Wrap |caw-variables-wrap|
Box |caw-variables-box|
Others |caw-variables-others|
FAQ |caw-faq|
TODO & Bugs |caw-todo-and-bugs|
Changelog |caw-changelog|
==============================================================================
INTRODUCTION *caw-introduction* {{{
The below are the examples in "filetype=c".
caw.vim supports 300+ filetypes (see |caw-supported-filetypes|).
Type "gci" (toggle: "gcc", uncomment: "gcui")
before:
" <- inserted here"
after:
" # <- inserted here"
Type "gcI" (uncomment: "gcuI")
before:
" inserted the first column"
after:
"# inserted the first column"
Type "gca" (uncomment: "gcua")
before:
"inserted after this"
after:
"inserted after this # "
Type "gcw" (uncomment: "gcuw")
before:
" wrap!"
after:
" /* wrap! */"
Type "gcb"
before:
" box!"
after:
" /********/"
" /* box! */"
" /********/"
Type "gco"
before:
" func1();"
after:
" func1()"
" // " (now cursor is at the end and entered insert-mode)
Type "gcO"
before:
" func1();"
after:
" // " (now cursor is at the end and entered insert-mode)
" func1();"
}}}
==============================================================================
FEATURES *caw-features* {{{
* Supports 300+ filetypes (see |caw-supported-filetypes|).
* But caw.vim does not slow down your Vim startup because each comment
string are defined at ftplugin files (after/ftplugin/<filetype>/caw.vim).
* Supports operator keymappings (|caw-keymappings-operator|).
* If |g:caw_operator_keymappings| is non-zero, all default keymappings map
to operator keymappings.
* If you need operator-user.vim to use operator keymappings.
https://github.com/kana/vim-operator-user
* Supports also non-operator keymappings (|caw-keymappings-non-operator|).
* Dot-repeatable if you installed repeat.vim
https://github.com/kana/vim-repeat
* The comment behavior only depends on 'filetype' by default.
But if you have installed context_filetype.vim, caw.vim also depends on the
filetype of the context of the current cursor location.
https://github.com/Shougo/context_filetype.vim
So you can comment/uncomment JavaScript in HTML correctly.
* Well-tested powered by https://github.com/thinca/vim-themis
}}}
==============================================================================
SUPPORTED FILETYPES *caw-supported-filetypes* {{{
Most comment strings were imported from NERD Commenter.
(Thanks Martin for open-sourcing NERD Commenter as WTFPL)
http://www.vim.org/scripts/script.php?script_id=1218
https://github.com/scrooloose/nerdcommenter
And more filetypes have been added by caw.vim users (Thanks!).
See "after/ftplugin/*" in this repository for current supported filetypes.
}}}
==============================================================================
INTERFACE *caw-interface* {{{
------------------------------------------------------------------------------
KEYMAPPINGS *caw-keymappings* {{{
See |caw-introduction| for how below keymappings work.
Default keymapping *caw-keymappings-default* {{{
---------------
If |g:caw_operator_keymappings| is zero (default):
lhs rhs ~
gc |<Plug>(caw:prefix)|
gcc |<Plug>(caw:hatpos:toggle)|
gci |<Plug>(caw:hatpos:comment)|
gcui |<Plug>(caw:hatpos:uncomment)|
gcI |<Plug>(caw:zeropos:comment)|
gcuI |<Plug>(caw:zeropos:uncomment)|
gca |<Plug>(caw:dollarpos:comment)|
gcua |<Plug>(caw:dollarpos:uncomment)|
gcw |<Plug>(caw:wrap:comment)|
gcuw |<Plug>(caw:wrap:uncomment)|
gcb |<Plug>(caw:box:comment)|
gco |<Plug>(caw:jump:comment-next)|
gcO |<Plug>(caw:jump:comment-prev)|
If |g:caw_operator_keymappings| is non-zero:
lhs rhs ~
gc |<Plug>(caw:prefix)|
gcc |<Plug>(caw:hatpos:toggle:operator)|
gci |<Plug>(caw:hatpos:comment:operator)|
gcui |<Plug>(caw:hatpos:uncomment:operator)|
gcI |<Plug>(caw:zeropos:comment:operator)|
gcuI |<Plug>(caw:zeropos:uncomment:operator)|
gca |<Plug>(caw:dollarpos:comment:operator)|
gcua |<Plug>(caw:dollarpos:uncomment:operator)|
gcw |<Plug>(caw:wrap:comment:operator)|
gcuw |<Plug>(caw:wrap:uncomment:operator)|
gcb |<Plug>(caw:box:comment:operator)|
}}}
Prefix keymapping *caw-keymappings-prefix* {{{
--------------
(nx) *<Plug>(caw:prefix)*
NOTE: See |caw-faq-1| for how to change prefix keymapping.
}}}
Non-operator keymappings *caw-keymappings-non-operator* {{{
---------------------
The keymapping format is "<Plug>(caw:{action}:{method})".
Most non-operator keymappings have common behaviors described in this section.
If you want to check specified keymapping is applied to this behavior,
please check each keymapping's section.
Comment method keymappings (<Plug>(caw:{action}:comment)) change current line
in normal-mode. In visual-mode, those change selected lines.
Uncomment method keymappings (<Plug>(caw:{action}:uncomment)) remove comment strings
(in above example, "#").
In normal-mode, toggle method keymappings (<Plug>(caw:{action}:toggle)) execute
comment method keymappings if current line has a comment string. Otherwise,
those execute uncomment method keymappings.
In visual-mode, toggle method keymappings execute uncomment method keymappings
if all lines have comment strings. Otherwise, those execute comment method keymappings.
Hatpos action *caw-hatpos-action* {{{
-------------
(nx) *<Plug>(caw:hatpos:comment)*
(nx) *<Plug>(caw:hatpos:uncomment)*
(nx) *<Plug>(caw:hatpos:toggle)*
See |caw-keymappings-non-operator| for the details.
>
before:
" <- inserted here"
after:
" # <- inserted here"
<
NOTE: An old keymappings were
* *<Plug>(caw:i:comment)*
* *<Plug>(caw:i:uncomment)*
* *<Plug>(caw:i:toggle)* , *<Plug>(caw:tildepos:toggle)*
See |caw-faq-3| why I renamed the keymapping.
}}}
Zeropos action *caw-zeropos-action* {{{
--------------
(nx) *<Plug>(caw:zeropos:comment)*
(nx) *<Plug>(caw:zeropos:uncomment)*
(nx) *<Plug>(caw:zeropos:toggle)*
See |caw-keymappings-non-operator| for the details.
>
before:
" inserted the first column"
after:
"# inserted the first column"
<
NOTE: An old keymappings were
* *<Plug>(caw:I:comment)*
* *<Plug>(caw:I:uncomment)*
* *<Plug>(caw:I:toggle)*
See |caw-faq-3| why I renamed the keymapping.
}}}
Dollarpos action *caw-dollarpos-action* {{{
----------------
(nx) *<Plug>(caw:dollarpos:comment)*
(nx) *<Plug>(caw:dollarpos:uncomment)*
(nx) *<Plug>(caw:dollarpos:toggle)*
See |caw-keymappings-non-operator| for the details.
>
before:
"inserted after this"
after:
"inserted after this # "
<
NOTE: An old keymappings were
* *<Plug>(caw:a:comment)*
* *<Plug>(caw:a:uncomment)*
* *<Plug>(caw:a:toggle)*
See |caw-faq-3| why I renamed the keymapping.
}}}
Wrap action *caw-wrap-action* {{{
-----------
(nx) *<Plug>(caw:wrap:comment)*
(nx) *<Plug>(caw:wrap:uncomment)*
(nx) *<Plug>(caw:wrap:toggle)*
See |caw-keymappings-non-operator| for the details.
>
before:
" wrap!"
after:
" /* wrap! */"
<
}}}
Box action *caw-box-action* {{{
----------
(nx) *<Plug>(caw:box:comment)*
>
before:
" box!"
after:
" /********/"
" /* box! */"
" /********/"
<
}}}
Jump action *caw-jump-action* {{{
-----------
(n) *<Plug>(caw:jump:comment-next)*
>
before:
" func1();"
after:
" func1()"
" // " (now cursor is at the end and entered insert-mode)
<
(n) *<Plug>(caw:jump:comment-prev)*
>
before:
" func1();"
after:
" // " (now cursor is at the end and entered insert-mode)
" func1();"
<
}}}
}}}
Operator keymappings *caw-keymappings-operator* {{{
-----------------
The keymapping format is "<Plug>(caw:{action}:{method}:operator)".
Hatpos operator *caw-hatpos-operator* {{{
---------------
(nx) *<Plug>(caw:hatpos:comment:operator)*
(nx) *<Plug>(caw:hatpos:uncomment:operator)*
(nx) *<Plug>(caw:hatpos:toggle:operator)*
This is operator version of
* |<Plug>(caw:hatpos:comment)|
* |<Plug>(caw:hatpos:uncomment)|
* |<Plug>(caw:hatpos:toggle)|
}}}
Zeropos operator *caw-zeropos-operator* {{{
----------------
(nx) *<Plug>(caw:zeropos:comment:operator)*
(nx) *<Plug>(caw:zeropos:uncomment:operator)*
(nx) *<Plug>(caw:zeropos:toggle:operator)*
This is operator version of
* |<Plug>(caw:zeropos:comment)|
* |<Plug>(caw:zeropos:uncomment)|
* |<Plug>(caw:zeropos:toggle)|
}}}
Dollarpos operator *caw-dollarpos-operator* {{{
------------------
(nx) *<Plug>(caw:dollarpos:comment:operator)*
(nx) *<Plug>(caw:dollarpos:uncomment:operator)*
(nx) *<Plug>(caw:dollarpos:toggle:operator)*
This is operator version of
* |<Plug>(caw:dollarpos:comment)|
* |<Plug>(caw:dollarpos:uncomment)|
* |<Plug>(caw:dollarpos:toggle)|
}}}
Wrap operator *caw-wrap-operator* {{{
-------------
(nx) *<Plug>(caw:wrap:comment:operator)*
(nx) *<Plug>(caw:wrap:uncomment:operator)*
(nx) *<Plug>(caw:wrap:toggle:operator)*
This is operator version of
* |<Plug>(caw:wrap:comment)|
* |<Plug>(caw:wrap:uncomment)|
* |<Plug>(caw:wrap:toggle)|
}}}
Box operator *caw-box-operator* {{{
------------
(nx) *<Plug>(caw:box:comment:operator)*
This is operator version of
* |<Plug>(caw:box:comment)|
}}}
}}}
}}}
------------------------------------------------------------------------------
VARIABLES *caw-variables* {{{
Scopes *caw-variables-scopes* {{{
------
NOTE: You can define the following variables in every scope
for each variable below.
priority scope ~
1 buffer-local variable
2 window-local variable
3 tabpage-local variable
4 global variable
For example, you can define buffer-local variable "b:caw_hatpos_sp"
for |g:caw_hatpos_sp|. The buffer-local variable is read instead of
its global variable if it is defined.
}}}
Comment String *caw-variables-comments* {{{
--------------
Below variables are normally defined in "after/ftplugin/**/*.vim".
However, you can define them everywhere, like .vimrc.
If you define them in .vimrc, please note that you must define
in |:autocmd| command like: >
autocmd FileType sh let b:caw_oneline_comment = ':'
<
b:caw_oneline_comment *b:caw_oneline_comment*
Oneline comment string.
Example: in filetype=c, the value is "//".
b:caw_wrap_oneline_comment *b:caw_wrap_oneline_comment*
Wrap-oneline comment string.
Example: in filetype=c, the value is ["/*", "*/"].
b:caw_wrap_multiline_comment *b:caw_wrap_multiline_comment*
Wrap-multiline comment string.
Example: in filetype=c, the value is: >
{'right': '*/', 'bottom': '*', 'left': '/*', 'top': '*'}
<
}}}
Hatpos *caw-variables-hatpos* {{{
------
*g:caw_hatpos_sp* *g:caw_i_sp*
g:caw_hatpos_sp
(Default: " ")
Inserted string after comment with |<Plug>(caw:hatpos:comment)|.
NOTE: An old variable name was |g:caw_i_sp|.
See |caw-faq-3| why I renamed the keymapping.
*g:caw_hatpos_sp_blank* *g:caw_i_sp_blank*
g:caw_hatpos_sp_blank
(Default: "")
Inserted string after comment with |<Plug>(caw:hatpos:comment)|.
but applied only if a current line is blank line.
NOTE: An old variable name was |g:caw_i_sp_blank|.
See |caw-faq-3| why I renamed the keymapping.
*g:caw_hatpos_startinsert_at_blank_line*
*g:caw_i_startinsert_at_blank_line*
g:caw_hatpos_startinsert_at_blank_line
(Default: 1)
If this variable is non-zero,
if current line is blank line,
enter |Insert-mode| after |<Plug>(caw:hatpos:comment)|.
NOTE: An old variable name was |g:caw_i_startinsert_at_blank_line|.
See |caw-faq-3| why I renamed the keymapping.
*g:caw_hatpos_skip_blank_line*
*g:caw_i_skip_blank_line*
g:caw_hatpos_skip_blank_line
(Default: 0)
if this variable is non-zero,
caw does not comment out a blank line. otherwise it does.
NOTE: An old variable name was |g:caw_i_skip_blank_line|.
See |caw-faq-3| why I renamed the keymapping.
*g:caw_hatpos_align* *g:caw_i_align*
g:caw_hatpos_align
(Default: 1)
If this variable is non-zero,
Align all |<Plug>(caw:hatpos:comment)| comments' cols.
For example, if this variable is non-zero and
select the following lines: >
if 1
echo 'hi'
endif
< and execute |<Plug>(caw:hatpos:comment)| changes the above lines to: >
" if 1
" echo 'hi'
" endif
< but if this variable is zero: >
" if 1
" echo 'hi'
" endif
<
NOTE: An old variable name was |g:caw_i_align|.
See |caw-faq-3| why I renamed the keymapping.
}}}
Zeropos *caw-variables-zeropos* {{{
-------
*g:caw_zeropos_startinsert_at_blank_line*
*g:caw_I_startinsert_at_blank_line*
g:caw_zeropos_startinsert_at_blank_line
(Default: 1)
If this variable is non-zero,
if current line is blank line,
enter |Insert-mode| after |<Plug>(caw:zeropos:comment)|.
NOTE: An old variable name was |g:caw_I_startinsert_at_blank_line|.
See |caw-faq-3| why I renamed the keymapping.
*g:caw_zeropos_sp* *g:caw_I_sp*
g:caw_zeropos_sp
(Default: " ")
Inserted string after comment with |<Plug>(caw:zeropos:comment)|.
NOTE: An old variable name was |g:caw_I_sp|.
See |caw-faq-3| why I renamed the keymapping.
*g:caw_zeropos_sp_blank* *g:caw_I_sp_blank*
g:caw_zeropos_sp_blank
(Default: "")
Inserted string after comment with |<Plug>(caw:zeropos:comment)|.
but applied only if a current line is blank line.
NOTE: An old variable name was |g:caw_I_sp_blank|.
See |caw-faq-3| why I renamed the keymapping.
}}}
Dollarpos *caw-variables-dollarpos* {{{
---------
*g:caw_dollarpos_sp_left* *g:caw_a_sp_left*
g:caw_dollarpos_sp_left
(Default: " ")
Inserted string before comment with |<Plug>(caw:dollarpos:comment)|.
NOTE: An old variable name was |g:caw_a_sp_left|.
See |caw-faq-3| why I renamed the keymapping.
*g:caw_dollarpos_sp_right* *g:caw_a_sp_right*
g:caw_dollarpos_sp_right
(Default: " ")
Inserted string after comment with |<Plug>(caw:dollarpos:comment)|.
NOTE: An old variable name was |g:caw_a_sp_right|.
See |caw-faq-3| why I renamed the keymapping.
*g:caw_dollarpos_startinsert* *g:caw_a_startinsert*
g:caw_dollarpos_startinsert
(Default: 1)
If this variable is non-zero,
enter |Insert-mode| after |<Plug>(caw:dollarpos:comment)|.
NOTE: An old variable name was |g:caw_a_startinsert|.
See |caw-faq-3| why I renamed the keymapping.
}}}
Wrap *caw-variables-wrap* {{{
-----
g:caw_wrap_sp_left *g:caw_wrap_sp_left*
(Default: " ")
Inserted string before comment with |<Plug>(caw:wrap:comment)|.
g:caw_wrap_sp_right *g:caw_wrap_sp_right*
(Default: " ")
Inserted string after comment with |<Plug>(caw:wrap:comment)|.
g:caw_wrap_skip_blank_line *g:caw_wrap_skip_blank_line*
(Default: 1)
if this variable is non-zero,
caw does not comment out a blank line. otherwise it does.
g:caw_wrap_align *g:caw_wrap_align*
(Default: 1)
}}}
Jump *caw-variables-jump* {{{
-----
g:caw_jump_sp *g:caw_jump_sp*
(Default: " ")
Inserted string after comment with |<Plug>(caw:jump:comment-next)|
and |<Plug>(caw:jump:comment-prev)|.
}}}
Box *caw-variables-box* {{{
-----
g:caw_box_sp_left *g:caw_box_sp_left*
(Default: " ")
g:caw_box_sp_right *g:caw_box_sp_right*
(Default: " ")
}}}
Others *caw-variables-others* {{{
------
g:caw_no_default_keymappings *g:caw_no_default_keymappings*
(Default: 0)
If this variable is non-zero,
caw does not map default keymappings.
See |caw-keymappings| for default keymappings.
g:caw_operator_keymappings *g:caw_operator_keymappings*
(Default: 0)
If this variable is non-zero,
caw's default keymappings become operator keymappings.
NOTE: If you haven't installed kana/vim-operator-user,
this variable is forcibly set to zero.
https://github.com/kana/vim-operator-user
g:caw_find_another_action *g:caw_find_another_action*
(Default: 1)
}}}
}}}
}}}
==============================================================================
FAQ *caw-faq* {{{
*caw-faq-1*
Q. How can I change the prefix keymapping?
A. You can change prefix keymapping
by writing the following settings in your .vimrc: >
nmap <Leader>c <Plug>(caw:prefix)
xmap <Leader>c <Plug>(caw:prefix)
<
*caw-faq-2*
Q. How do I support a new filetype?
A. You have several options.
1. Set caw variables on |FileType| event
caw supports comment settings by variables.
See |caw-variables-comments| for the examples.
* Oneline comment: |b:caw_oneline_comment|
* Wrap oneline comment: |b:caw_wrap_oneline_comment|
* Wrap multiline comment: |b:caw_wrap_multiline_comment|
2. Set 'commentstring' on |FileType| event
If current filetype is not supported by default ftplugin files of caw
(after/ftplugin/<filetype>/caw.vim in this repository),
caw detects oneline / wrap oneline comment string by 'commentstring'.
I implemented this for fallback purpose because it may not be accurate,
and wrap multiline comment can't be detected by this method.
It seems tpope/vim-commentary also supports this type of settings.
3. If you are interested in sending pull request :)
3.1. Put comment string to macros/generate-ftplugins.vim
3.2. Run `vim -u NONE -i NONE -N -S macros/generate-ftplugins.vim -c quit`
3.3. Commit & Push changes and send pull request to https://github.com/tyru/caw.vim
Of course, it's welcome to report missing comment filetypes :)
https://github.com/tyru/caw.vim/issues/new
*caw-faq-3*
Q. Why you renamed keymappings and variables?
A. Because old keymappings and variables' names are hard to understand.
I changed old names like the followings:
Old New ~
i,tildepos hatpos
I zeropos
a dollarpos
e.g.:
* |<Plug>(caw:i:toggle)| and |<Plug>(caw:tildepos:toggle)| were changed
to |<Plug>(caw:hatpos:toggle)|.
* |g:caw_I_sp_blank| was changed to |g:caw_zeropos_sp_blank|.
hatpos
The keymappings do actions for the position where ^ command moves to.
zeropos
The keymappings do actions for the position where 0 command moves to.
dollarpos
The keymappings do actions for the position where $ command moves to.
See the following pull requests for the details of the changes.
https://github.com/tyru/caw.vim/pull/35
https://github.com/tyru/caw.vim/pull/48
}}}
==============================================================================
TODO & BUGS *caw-todo-and-bugs* {{{
https://github.com/tyru/caw.vim/issues
}}}
==============================================================================
CHANGELOG *caw-changelog* {{{
1.0:
- Initial upload.
See previous plugin CommentAnyWay.vim for the more old changelog
(please don't use it! very buggy...).
http://www.vim.org/scripts/script.php?script_id=2554
}}}
==============================================================================
vim:tw=78:fo=tcq2mM:ts=4:ft=help:norl:noet:fdm=marker:fen