484 lines
21 KiB
Plaintext
484 lines
21 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.
|
|
|
|
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:tcommentGuessFileType_smarty ...... |g:tcommentGuessFileType_smarty|
|
|
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()|
|
|
tcomment#GuessCommentType ........... |tcomment#GuessCommentType()|
|
|
|
|
|
|
========================================================================
|
|
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, assume 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:tcommentGuessFileType_smarty*
|
|
g:tcommentGuessFileType_smarty (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
|
|
|
|
*tcomment#GuessCommentType()*
|
|
tcomment#GuessFileType(?options={})
|
|
A function that makes the s:GuessFileType() function usable for other
|
|
library developers.
|
|
|
|
The argument is a dictionary with the following keys:
|
|
|
|
beg ................ (default = line("."))
|
|
end ................ (default = line("."))
|
|
commentMode ........ (default = "G")
|
|
filetype ........... (default = &filetype)
|
|
fallbackFiletype ... (default = "")
|
|
|
|
This function return a dictionary that contains information about how
|
|
to make comments. The information about the filetype of the text
|
|
between lines "beg" and "end" is in the "filetype" key of the return
|
|
value. It returns the first discernible filetype it encounters.
|
|
|
|
|
|
|
|
vim:tw=78:fo=tcq2:isk=!-~,^*,^|,^":ts=8:ft=help:norl:
|