360 lines
16 KiB
Plaintext
360 lines
16 KiB
Plaintext
*tcomment.txt* An easily extensible & universal comment plugin
|
|
Author: Thomas Link, micathom AT gmail com?subject=vim
|
|
|
|
tcomment provides easy to use, file-type sensible comments for Vim. It
|
|
can handle embedded syntax.
|
|
|
|
TComment works like a toggle, i.e., it will comment out text that
|
|
contains uncommented lines, and it will remove comment markup for
|
|
already commented text (i.e. text that contains no uncommented lines).
|
|
|
|
If the file-type is properly defined, TComment will figure out which
|
|
comment string to use. Otherwise you use |tcomment#DefineType()| to
|
|
override the default choice.
|
|
|
|
TComment can properly handle an embedded syntax, e.g., ruby/python/perl
|
|
regions in vim scripts, HTML or JavaScript in php code etc.
|
|
|
|
Demo:
|
|
http://vimsomnia.blogspot.com/2010/11/tcomment-vim-plugin.html
|
|
|
|
|
|
*tcomment-maps*
|
|
Key bindings~
|
|
|
|
Most of the time the default toggle keys will do what you want (or to be
|
|
more precise: what I think you want it to do ;-).
|
|
|
|
*g:tcommentMapLeaderOp1*
|
|
*g:tcommentMapLeaderOp2*
|
|
As operator (the prefix can be customized via g:tcommentMapLeaderOp1
|
|
and g:tcommentMapLeaderOp2):
|
|
|
|
gc{motion} :: Toggle comments (for small comments within one line
|
|
the &filetype_inline style will be used, if
|
|
defined)
|
|
gcc :: Toggle comment for the current line
|
|
gC{motion} :: Comment region
|
|
gCc :: Comment the current line
|
|
|
|
By default the cursor stays put. If you want the cursor to the end of
|
|
the commented text, set |g:tcommentOpModeExtra| to '>' (but this may not
|
|
work properly with exclusive motions).
|
|
|
|
Primary key maps:
|
|
|
|
<c-_><c-_> :: :TComment
|
|
<c-_><space> :: :TComment <QUERY COMMENT-BEGIN ?COMMENT-END>
|
|
<c-_>b :: :TCommentBlock
|
|
<c-_>a :: :TCommentAs <QUERY COMMENT TYPE>
|
|
<c-_>n :: :TCommentAs &filetype <QUERY COUNT>
|
|
<c-_>s :: :TCommentAs &filetype_<QUERY COMMENT SUBTYPE>
|
|
<c-_>i :: :TCommentInline
|
|
<c-_>r :: :TCommentRight
|
|
<c-_>p :: Comment the current inner paragraph
|
|
|
|
A secondary set of key maps is defined for normal mode.
|
|
|
|
<Leader>__ :: :TComment
|
|
<Leader>_p :: Comment the current inner paragraph
|
|
<Leader>_<space> :: :TComment <QUERY COMMENT-BEGIN ?COMMENT-END>
|
|
<Leader>_i :: :TCommentInline
|
|
<Leader>_r :: :TCommentRight
|
|
<Leader>_b :: :TCommentBlock
|
|
<Leader>_a :: :TCommentAs <QUERY COMMENT TYPE>
|
|
<Leader>_n :: :TCommentAs &filetype <QUERY COUNT>
|
|
<Leader>_s :: :TCommentAs &filetype_<QUERY COMMENT SUBTYPE>
|
|
|
|
|
|
-----------------------------------------------------------------------
|
|
Install~
|
|
|
|
Edit the vba file and type: >
|
|
|
|
:so %
|
|
|
|
See :help vimball for details. If you have difficulties or use vim 7.0,
|
|
please make sure, you have the current version of vimball (vimscript
|
|
#1502) installed or update your runtime.
|
|
|
|
|
|
========================================================================
|
|
Contents~
|
|
|
|
:TComment ........................... |:TComment|
|
|
:TCommentAs ......................... |:TCommentAs|
|
|
:TCommentRight ...................... |:TCommentRight|
|
|
:TCommentBlock ...................... |:TCommentBlock|
|
|
:TCommentInline ..................... |:TCommentInline|
|
|
:TCommentMaybeInline ................ |:TCommentMaybeInline|
|
|
g:tcommentBlankLines ................ |g:tcommentBlankLines|
|
|
g:tcommentOpModeExtra ............... |g:tcommentOpModeExtra|
|
|
g:tcommentOptions ................... |g:tcommentOptions|
|
|
g:tcomment#ignore_char_type ......... |g:tcomment#ignore_char_type|
|
|
g:tcommentGuessFileType ............. |g:tcommentGuessFileType|
|
|
g:tcommentGuessFileType_dsl ......... |g:tcommentGuessFileType_dsl|
|
|
g:tcommentGuessFileType_php ......... |g:tcommentGuessFileType_php|
|
|
g:tcommentGuessFileType_html ........ |g:tcommentGuessFileType_html|
|
|
g:tcommentGuessFileType_tskeleton ... |g:tcommentGuessFileType_tskeleton|
|
|
g:tcommentGuessFileType_vim ......... |g:tcommentGuessFileType_vim|
|
|
g:tcommentGuessFileType_django ...... |g:tcommentGuessFileType_django|
|
|
g:tcommentIgnoreTypes_php ........... |g:tcommentIgnoreTypes_php|
|
|
g:tcomment#syntax_substitute ........ |g:tcomment#syntax_substitute|
|
|
g:tcommentSyntaxMap ................. |g:tcommentSyntaxMap|
|
|
g:tcommentBlockC .................... |g:tcommentBlockC|
|
|
g:tcommentBlockC2 ................... |g:tcommentBlockC2|
|
|
g:tcommentInlineC ................... |g:tcommentInlineC|
|
|
g:tcommentBlockXML .................. |g:tcommentBlockXML|
|
|
g:tcommentInlineXML ................. |g:tcommentInlineXML|
|
|
tcomment#DefineType ................. |tcomment#DefineType()|
|
|
tcomment#Comment .................... |tcomment#Comment()|
|
|
tcomment#Operator ................... |tcomment#Operator()|
|
|
tcomment#OperatorLine ............... |tcomment#OperatorLine()|
|
|
tcomment#OperatorAnyway ............. |tcomment#OperatorAnyway()|
|
|
tcomment#OperatorLineAnyway ......... |tcomment#OperatorLineAnyway()|
|
|
tcomment#CommentAs .................. |tcomment#CommentAs()|
|
|
|
|
|
|
========================================================================
|
|
plugin/tcomment.vim~
|
|
|
|
*:TComment*
|
|
:[range]TComment[!] ?ARGS...
|
|
If there is a visual selection that begins and ends in the same line,
|
|
then |:TCommentInline| is used instead.
|
|
The optional range defaults to the current line. With a bang '!',
|
|
always comment the line.
|
|
|
|
ARGS... are either (see also |tcomment#Comment()|):
|
|
1. a list of key=value pairs
|
|
2. 1-2 values for: ?commentBegin, ?commentEnd
|
|
|
|
*:TCommentAs*
|
|
:[range]TCommentAs[!] commenttype ?ARGS...
|
|
TCommentAs requires g:tcomment_{filetype} to be defined.
|
|
With a bang '!', always comment the line.
|
|
|
|
ARGS... are either (see also |tcomment#Comment()|):
|
|
1. a list of key=value pairs
|
|
2. 1-2 values for: ?commentBegin, ?commentEnd
|
|
|
|
*:TCommentRight*
|
|
:[range]TCommentRight[!] ?ARGS...
|
|
Comment the text to the right of the cursor. If a visual selection was
|
|
made (be it block-wise or not), all lines are commented out at from
|
|
the current cursor position downwards.
|
|
With a bang '!', always comment the line.
|
|
|
|
ARGS... are either (see also |tcomment#Comment()|):
|
|
1. a list of key=value pairs
|
|
2. 1-2 values for: ?commentBegin, ?commentEnd
|
|
|
|
*:TCommentBlock*
|
|
:[range]TCommentBlock[!] ?ARGS...
|
|
Comment as "block", e.g. use the {&ft}_block comment style. The
|
|
commented text isn't indented or reformated.
|
|
With a bang '!', always comment the line.
|
|
|
|
ARGS... are either (see also |tcomment#Comment()|):
|
|
1. a list of key=value pairs
|
|
2. 1-2 values for: ?commentBegin, ?commentEnd
|
|
|
|
*:TCommentInline*
|
|
:[range]TCommentInline[!] ?ARGS...
|
|
Use the {&ft}_inline comment style.
|
|
With a bang '!', always comment the line.
|
|
|
|
ARGS... are either (see also |tcomment#Comment()|):
|
|
1. a list of key=value pairs
|
|
2. 1-2 values for: ?commentBegin, ?commentEnd
|
|
|
|
*:TCommentMaybeInline*
|
|
:[range]TCommentMaybeInline[!] ?ARGS...
|
|
With a bang '!', always comment the line.
|
|
|
|
ARGS... are either (see also |tcomment#Comment()|):
|
|
1. a list of key=value pairs
|
|
2. 1-2 values for: ?commentBegin, ?commentEnd
|
|
|
|
|
|
========================================================================
|
|
autoload/tcomment.vim~
|
|
|
|
*g:tcommentBlankLines*
|
|
g:tcommentBlankLines (default: 1)
|
|
If true, comment blank lines too
|
|
|
|
*g:tcommentOpModeExtra*
|
|
g:tcommentOpModeExtra (default: '')
|
|
Modifies how the operator works.
|
|
> ... Move the cursor to the end of the comment
|
|
|
|
*g:tcommentOptions*
|
|
g:tcommentOptions (default: {})
|
|
Other key-value options used by |tcomment#Comment()|.
|
|
|
|
Example: If you want to put the opening comment marker always in
|
|
the first column regardless of the block's indentation, put this
|
|
into your |vimrc| file: >
|
|
let g:tcommentOptions = {'col': 1}
|
|
<
|
|
|
|
*g:tcomment#ignore_char_type*
|
|
g:tcomment#ignore_char_type (default: 1)
|
|
|text-objects| for use with |tcomment#Operator| can have different
|
|
types: line, block, char etc. Text objects like aB, it, at etc.
|
|
have type char but this may not work reliably. By default,
|
|
tcomment handles those text objects most often as if they were of
|
|
type line. Set this variable to 0 in order to change this
|
|
behaviour. Be prepared that the result may not always match your
|
|
intentions.
|
|
|
|
*g:tcommentGuessFileType*
|
|
g:tcommentGuessFileType (default: 0)
|
|
Guess the file type based on syntax names always or for some fileformat only
|
|
If non-zero, try to guess filetypes.
|
|
tcomment also checks g:tcommentGuessFileType_{&filetype} for
|
|
filetype specific values.
|
|
|
|
Values:
|
|
0 ... don't guess
|
|
1 ... guess
|
|
FILETYPE ... assume this filetype
|
|
|
|
*g:tcommentGuessFileType_dsl*
|
|
g:tcommentGuessFileType_dsl (default: 'xml')
|
|
For dsl documents, assumet filetype = xml.
|
|
|
|
*g:tcommentGuessFileType_php*
|
|
g:tcommentGuessFileType_php (default: 'html')
|
|
In php documents, the php part is usually marked as phpRegion. We
|
|
thus assume that the buffers default comment style isn't php but
|
|
html.
|
|
|
|
*g:tcommentGuessFileType_html*
|
|
g:tcommentGuessFileType_html (default: 1)
|
|
|
|
*g:tcommentGuessFileType_tskeleton*
|
|
g:tcommentGuessFileType_tskeleton (default: 1)
|
|
|
|
*g:tcommentGuessFileType_vim*
|
|
g:tcommentGuessFileType_vim (default: 1)
|
|
|
|
*g:tcommentGuessFileType_django*
|
|
g:tcommentGuessFileType_django (default: 1)
|
|
|
|
*g:tcommentIgnoreTypes_php*
|
|
g:tcommentIgnoreTypes_php (default: 'sql')
|
|
In php files, some syntax regions are wongly highlighted as sql
|
|
markup. We thus ignore sql syntax when guessing the filetype in
|
|
php files.
|
|
|
|
*g:tcomment#syntax_substitute*
|
|
g:tcomment#syntax_substitute (default: {...})
|
|
|
|
*g:tcommentSyntaxMap*
|
|
g:tcommentSyntaxMap (default: {...})
|
|
tcomment guesses filetypes based on the name of the current syntax
|
|
region. This works well if the syntax names match
|
|
/filetypeSomeName/. Other syntax names have to be explicitly
|
|
mapped onto the corresponding filetype.
|
|
|
|
*g:tcommentBlockC*
|
|
g:tcommentBlockC (default: {...})
|
|
Generic c-like block comments.
|
|
|
|
*g:tcommentBlockC2*
|
|
g:tcommentBlockC2 (default: {...})
|
|
Generic c-like block comments (alternative markup).
|
|
|
|
*g:tcommentInlineC*
|
|
g:tcommentInlineC (default: "/* %s */")
|
|
Generic c-like comments.
|
|
|
|
*g:tcommentBlockXML*
|
|
g:tcommentBlockXML (default: "<!--%s-->\n ")
|
|
Generic xml-like block comments.
|
|
|
|
*g:tcommentInlineXML*
|
|
g:tcommentInlineXML (default: "<!-- %s -->")
|
|
Generic xml-like comments.
|
|
|
|
*tcomment#DefineType()*
|
|
tcomment#DefineType(name, commentdef)
|
|
If you don't explicitly define a comment style, |:TComment| will use
|
|
'commentstring' instead. We override the default values here in order
|
|
to have a blank after the comment marker. Block comments work only if
|
|
we explicitly define the markup.
|
|
|
|
The comment definition can be either a string or a dictionary.
|
|
|
|
If it is a string:
|
|
The format for block comments is similar to 'commentstrings' with the
|
|
exception that the format strings for blocks can contain a second line
|
|
that defines how "middle lines" (see :h format-comments) should be
|
|
displayed.
|
|
|
|
If it is a dictionary:
|
|
See the help on the args argument of |tcomment#Comment|.
|
|
|
|
*tcomment#Comment()*
|
|
tcomment#Comment(beg, end, ...)
|
|
tcomment#Comment(line1, line2, ?commentMode, ?commentAnyway, ?args...)
|
|
args... are either:
|
|
1. a list of key=value pairs where known keys are (see also
|
|
|g:tcommentOptions|):
|
|
as=STRING ... Use a specific comment definition
|
|
col=N ... Start the comment at column N (in block
|
|
mode; must be smaller than |indent()|)
|
|
mode=STRING ... See the notes below on the "commentMode" argument
|
|
begin=STRING ... Comment prefix
|
|
end=STRING ... Comment postfix
|
|
middle=STRING ... Middle line comments in block mode
|
|
rxbeg=N ... Regexp to find the substring of "begin"
|
|
that should be multipied by "count"
|
|
rxend=N ... The above for "end"
|
|
rxmid=N ... The above for "middle"
|
|
commentstring_rx ... A regexp format string that matches
|
|
commented lines (no new groups may be
|
|
introduced, the |regexp| is |\V|; % have
|
|
to be doubled); "commentstring", "begin"
|
|
and optionally "end" must be defined or
|
|
deducible.
|
|
2. 1-2 values for: ?commentPrefix, ?commentPostfix
|
|
3. a dictionary (internal use only)
|
|
|
|
commentMode:
|
|
G ... guess the value of commentMode
|
|
B ... block (use extra lines for the comment markers)
|
|
i ... maybe inline, guess
|
|
I ... inline
|
|
R ... right (comment the line right of the cursor)
|
|
v ... visual
|
|
o ... operator
|
|
By default, each line in range will be commented by adding the comment
|
|
prefix and postfix.
|
|
|
|
*tcomment#Operator()*
|
|
tcomment#Operator(type, ...)
|
|
|
|
*tcomment#OperatorLine()*
|
|
tcomment#OperatorLine(type)
|
|
|
|
*tcomment#OperatorAnyway()*
|
|
tcomment#OperatorAnyway(type)
|
|
|
|
*tcomment#OperatorLineAnyway()*
|
|
tcomment#OperatorLineAnyway(type)
|
|
|
|
*tcomment#CommentAs()*
|
|
tcomment#CommentAs(beg, end, commentAnyway, filetype, ?args...)
|
|
Where args is either:
|
|
1. A count NUMBER
|
|
2. An args list (see the notes on the "args" argument of
|
|
|tcomment#Comment()|)
|
|
comment text as if it were of a specific filetype
|
|
|
|
|
|
|
|
vim:tw=78:fo=tcq2:isk=!-~,^*,^|,^":ts=8:ft=help:norl:
|