Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tomtom/tcomment_vim

An extensible & universal comment vim-plugin that also handles embedded filetypes
https://github.com/tomtom/tcomment_vim

vim vim-plugin

Last synced: about 17 hours ago
JSON representation

An extensible & universal comment vim-plugin that also handles embedded filetypes

Awesome Lists containing this project

README 

        
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#type#Define()| 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:tcomment_opleader1|):



    gc{motion}   :: Toggle comments (for small comments within one line 

                    the &filetype_inline style will be used, if 

                    defined)

    gcc{motion} :: Toggle comment with count argument 

                    (see |tcomment#Comment()|)

    gcc          :: Toggle comment for the current line



Force line-wise operation:

    gC{motion}   :: Toggle comments by line

    gCc{motion} :: Toggle comment by line with count argument 

                    (see |tcomment#Comment()|)



Explicit commenting/uncommenting:



    g<{motion}   :: Uncomment region

    g{motion}   :: Comment region

    g>c          :: Comment the current line

    g>b          :: Comment the current region as block



In visual mode:



    gc           :: Toggle comments

    g>           :: 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 i map -- see below.



By default the cursor stays put. If you want the cursor to the end of 

the commented text, set |g:tcomment#operator#mode_extra| to '>' (but this may not 

work properly with exclusive motions).



Primary key maps for normal and insert mode (see also |g:tcomment_mapleader1|):



       :: :TComment

     :: :TComment 

    b       :: :TCommentBlock

                    In insert mode, the cursor will be positioned inside 

                    the comment. In normal mode, the cursor will stay 

                    put.

    a       :: :TCommentAs 

    n       :: :TCommentAs &filetype 

    s       :: :TCommentAs &filetype_

    i       :: :TCommentInline (in normal and insert mode, this map will 

                    create an empty inline comment, which isn't suitable for 

                    all filetypes though)

                    In insert mode, the cursor will be positioned inside 

                    the comment. In normal mode, the cursor will stay 

                    put.

    r       :: :TCommentRight

    p       :: Comment the current inner paragraph

     :: Set the count argument (a number from 1 to 9) for use with 

                    the subsequent tcomment map/command (see 

                    |tcomment#Comment()|)

                    E.g. in JavaScript, in order to get an empty /** */ 

                    comment for documentation purposes, in insert mode type 

                    2i

                    In order to get an empty block comment like >

                      /**

                       *

                       */

<                   type 2b



Most of the above maps are also available in visual mode.



A secondary set of key maps is defined for normal and insert mode (see also 

|g:tcomment_mapleader2|):



    __       :: :TComment

    _p       :: Comment the current inner paragraph

    _ :: :TComment 

    _i       :: :TCommentInline

    _r       :: :TCommentRight

    _b       :: :TCommentBlock

    _a       :: :TCommentAs 

    _n       :: :TCommentAs &filetype 

    _s       :: :TCommentAs &filetype_



... and for select mode:



    __       :: :TComment

    _i       :: :TCommentInline



-----------------------------------------------------------------------

                            *tcomment-new-filetype* *tcomment-debug*

Adding a new filetype~



If tcomment doesn't know a filetype, it makes use of 'commentstring' or 

'comments'. If the result still does not satisfy your needs, you might have to 

add a custom filetype definition. This could be done in a file like 

`autoload/tcomment/types/mytypes.vim` somewhere in your 'runtimepath', which 

will be loaded on startup.



New comment types can be defined via the |tcomment#type#Define()| function. If 

the file may contain embedded code of another filetype, you might also want to 

set `g:tcomment#filetype#guess_{FILETYPE}` to 1 or the name of a default 

fallback filetype.



If nothing helps:



1. Make sure 'filetype' is set correctly.

2. Place the cursor at an appropriate position -- e.g. the first non-blank 

   character of a line of code.

3. Call |tcomment#debug#CollectInfo()|.

4. File an issue on github and post the output of `:call 

   tcomment#debug#CollectInfo()`. The output will also be copied to the 

   clipboard.



If this still doesn't help, please install tlib 

(https://github.com/tomtom/tlib_vim), please try:



    Tlibtraceset --file=tcomment.log +tcomment



Then comment out the text in question and send me the log file.



-----------------------------------------------------------------------

Install~



Either use the zip archive:



- Download the zip archive

- Extract it to `~/.vim/pack/tml/start/tcomment`



or install from github:



- Start a terminal

- Change the working directory to `~/.vim/pack/tml/start/`

- Type: `git clone https://github.com/tomtom/tcomment_vim`



NOTE: If you don't want to run this plugin on startup, use 

`~/.vim/pack/tml/opt/`.



NOTE: On Windows, ~/.vim might be ~/vimfiles. Please see 'runtimepath' for 

details.



License: GPLv3 or later