Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
tree: 3ad639fcd8
Fetching contributors…

Cannot retrieve contributors at this time

461 lines (365 sloc) 20.435 kb
*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.
tcomment favours the use of line-wise comment styles. This implies that usually
whole line will be commented out. tcomment also knows block-style and inline
comments that can be used via special maps (see below) or the |:TCommentAs|
command.
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 ;-).
*tcomment-operator*
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)
gc<Count>c{motion} :: Toggle comment text with count argument
(see |tcomment#Comment()|)
gcc :: Toggle comment for the current line
gC{motion} :: Comment region
gCc :: Comment the current line
In visual mode:
gc :: Toggle comments
gC :: Comment selected text
CAVEAT: If you visually select text within a line, the visual mode map will
comment out the selected text. If you selected text across several lines, the
visual mode map will assume though that you wanted to comment out lines --
since this is how many vim maps work. In order to make tcomment use e.g. inline
comments anyway, use the <c-_>i map -- see below.
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 for normal and insert mode:
<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 (in normal and insert mode, this map will
create an empty inline comment, which isn't suitable for
all filetypes though)
<c-_>r :: :TCommentRight
<c-_>p :: Comment the current inner paragraph
<c-_><Count> :: :TComment with count argument (a number from 1 to 9)
(see |tcomment#Comment()|)
Primary key maps for visual mode:
<c-_><c-_> :: :TComment
<c-_>i :: :TCommentInline
<c-_><Count> :: :TComment with count argument (a number from 1 to 9)
(see |tcomment#Comment()|)
A secondary set of key maps is defined for normal and insert 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>
... and for select mode:
<Leader>__ :: :TComment
<Leader>_i :: :TCommentInline
-----------------------------------------------------------------------
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~
g:tcommentMapLeader1 ................ |g:tcommentMapLeader1|
g:tcommentMapLeader2 ................ |g:tcommentMapLeader2|
g:tcommentMapLeaderOp1 .............. |g:tcommentMapLeaderOp1|
g:tcommentMapLeaderOp2 .............. |g:tcommentMapLeaderOp2|
:TComment ........................... |:TComment|
:TCommentAs ......................... |:TCommentAs|
:TCommentRight ...................... |:TCommentRight|
:TCommentBlock ...................... |:TCommentBlock|
:TCommentInline ..................... |:TCommentInline|
:TCommentMaybeInline ................ |:TCommentMaybeInline|
g:tcommentBlankLines ................ |g:tcommentBlankLines|
g:tcommentModeExtra ................. |g:tcommentModeExtra|
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:tcommentGuessFileType_eruby ....... |g:tcommentGuessFileType_eruby|
g:tcommentIgnoreTypes_php ........... |g:tcommentIgnoreTypes_php|
g:tcomment#syntax_substitute ........ |g:tcomment#syntax_substitute|
g:tcommentSyntaxMap ................. |g:tcommentSyntaxMap|
g:tcomment#replacements_c ........... |g:tcomment#replacements_c|
g:tcommentBlockC .................... |g:tcommentBlockC|
g:tcommentBlockC2 ................... |g:tcommentBlockC2|
g:tcommentInlineC ................... |g:tcommentInlineC|
g:tcommentBlockXML .................. |g:tcommentBlockXML|
g:tcommentInlineXML ................. |g:tcommentInlineXML|
tcomment#DefineType ................. |tcomment#DefineType()|
g:tcomment_types .................... |g:tcomment_types|
tcomment#Comment .................... |tcomment#Comment()|
tcomment#SetOption .................. |tcomment#SetOption()|
tcomment#Operator ................... |tcomment#Operator()|
tcomment#OperatorLine ............... |tcomment#OperatorLine()|
tcomment#OperatorAnyway ............. |tcomment#OperatorAnyway()|
tcomment#OperatorLineAnyway ......... |tcomment#OperatorLineAnyway()|
tcomment#CommentAs .................. |tcomment#CommentAs()|
========================================================================
plugin/tcomment.vim~
*g:tcommentMapLeader1*
g:tcommentMapLeader1 (default: '<c-_>')
g:tcommentMapLeader1 should be a shortcut that can be used with
map, imap, vmap.
*g:tcommentMapLeader2*
g:tcommentMapLeader2 (default: '<Leader>_')
g:tcommentMapLeader2 should be a shortcut that can be used with
map, xmap.
*g:tcommentMapLeaderOp1*
g:tcommentMapLeaderOp1 (default: 'gc')
See |tcomment-operator|.
*g:tcommentMapLeaderOp2*
g:tcommentMapLeaderOp2 (default: 'gC')
See |tcomment-operator|.
*: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:tcommentModeExtra*
g:tcommentModeExtra (default: '')
Modifies how commenting works.
> ... Move the cursor to the end of the comment
>> ... Like above but move the cursor to the next line
# ... Move the cursor to the position of the commented text
(NOTE: this only works when creating empty comments using
|:TCommentInline| from normal or insert mode and should
not be set here as a global option.)
*g:tcommentOpModeExtra*
g:tcommentOpModeExtra (default: '')
Modifies how the operator works.
See |g:tcommentModeExtra| for a list of possible values.
*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:tcommentGuessFileType_eruby*
g:tcommentGuessFileType_eruby (default: 1)
*g:tcommentIgnoreTypes_php*
g:tcommentIgnoreTypes_php (default: 'sql')
In php files, some syntax regions are wrongly 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:tcomment#replacements_c*
g:tcomment#replacements_c (default: {...})
Replacements for c 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: g:tcommentLineC)
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.
NAME usually is a 'filetype'. You can use special suffixes to define
special comment types. E.g. the name "FILETYPE_block" is used for
block comments for 'filetype'. The name "FILETYPE_inline" is used for
inline comments. If no specialized comment definition exists, the
normal one with name "FILETYPE" is used.
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.
Example: If the string is "--%s--\n-- ", lines will be commented as
"--%s--" but the middle lines in block comments will be commented as
"--%s".
If it is a dictionary:
See the help on the args argument of |tcomment#Comment| (see item 1,
args is a list of key=value pairs) to find out which fields can be
used.
*g:tcomment_types*
g:tcomment_types (default: {})
A dictionary of NAME => COMMENT DEFINITION (see |tcomment#DefineType|)
that can be set in vimrc to override tcomment's default comment
styles.
*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
count=N ... Repeat the comment string N times
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 multiplied 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#SetOption()*
tcomment#SetOption(name, arg)
*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:
Jump to Line
Something went wrong with that request. Please try again.