*textobj-comment.txt*	Text objects for comments

Author: glts <676c7473@gmail.com>
License: Same terms as Vim itself (see |license|)


DESCRIPTION					*textobj-comment*

This plugin provides |text-objects| to select comments.

"ac" selects a comment including the comment delimiters, "ic" selects the
comment content without the delimiters.  This behaviour is modeled after the
built-in delimited text objects such as |a[| and |it|.  A third text object,
"aC", selects a "big" comment, including trailing or leading whitespace.

|textobj-comment| uses the filetype-specific 'comments' setting to determine
what a comment looks like for a given language.  Make sure you have enabled
filetype plugins in your configuration to make this work. |vimrc-filetype| >

	filetype plugin indent on

In order to find a target, textobj-comment looks for a comment under the
cursor, in or at the end of the cursor line, and above the cursor line.

You can see the text objects and the heuristic in action in the following
section, |textobj-comment-usage|.

Note This plugin depends on the |textobj-user| plugin, version 0.4.0.
https://github.com/kana/vim-textobj-user


USAGE						*textobj-comment-usage*

The text objects "ac", "ic", and "aC" are defined in |Visual| and
|Operator-pending| mode.  When the user enters any one of these text objects,
textobj-comment searches for a comment by using this procedure:

1.  Use any comment spanning the full line under the cursor.
2.  Use any inline comment (if the language has them) or end-of-line comment
    under or to the right of the cursor.
3.  Use the nearest comment spanning the full line above the cursor.

Note that step 3 is essentially an upwards search.  This is where a comment
relevant to the current cursor position is most likely to be found.

We'll now go on an illustrated tour of the text objects and the three steps of
the heuristic.  See also |textobj-comment-interface| below for more details.


1.  First, look for a full-line comment under the cursor.  In full-line
    context "ac" selects a comment |linewise| (the vertical bar indicates
    selected lines). >

       |    # We should probably inline
       |    # this con[s]tant
	    DOZEN = 12
<
    "ic" selects just what's inside the comment and always operates
    |characterwise| (the overline indicates selected characters). >
	       _________________________
	    %  See [t]he TeXbook, p. 352
	    \def\thinspace{\kern .16667em }
<
    The "aC" text object selects "a big comment", which is the same as "ac"
    but includes whitespace after the comment, or if there isn't any,
    whitespace before the comment. >

       |    -- Baby steps ...
       |    -- Cust[o]m "asInt'" function
       |
	    asInt' :: String -> Either ErrorMessage Int


2.  Second, look for an inline or an end-of-line comment.  Inline and
    end-of-line comments are selected characterwise.  Again, "ac" selects a
    comment including the delimiter. >
						    __________________
	    *parse_syllab[l]e = \&parse_syllables;  # deprecated alias
<
    "aC" selects the same but with trailing or leading whitespace included.
    This is especially useful when you want to delete an end-of-line comment
    and not leave any whitespace behind. >
			    __________________________
	    int tem[p] = 12;    /* core temperature */
<
    For inline comments, a match under the cursor is preferred, else one to
    the right of the cursor is selected.  With "ic": >
		   ______
	    int /* tem[p] */ temperature = 12; // renamed variable


3.  Third, if there hasn't been any success so far, search upwards for the
    nearest full-line comment.  Using "ac": >

       |    (* Let us make
       |       a singleton. *)
	    let s = SS.singleton "umb[r]ella";;
<
    Of course, the three steps always apply to all three text objects.  Here's
    a final example featuring "ic" searching upwards to find its target. >
		 _________________
	    <!-- This needs to be
	____________________
		 fixed ASAP! -->

	    <xs:complexType n[a]me="TODO" />

After this the comment search fails and nothing is selected.

Note that in order to support two styles of commenting with opening/closing
delimiters, textobj-comment tries to be smart and handles them differently.
Consider these comments in C and XML source code: >

	    /* These functions should be
	     * moved to a separate file. */
	    /* See also fileio.c and
	     * sockets.c for examples. */

	    <!-- These functions should be -->
	    <!-- moved to a separate file. -->
	    <!-- See also sources.xsl and  -->
	    <!-- nodes.xsl for examples.   -->

In the first example, two separate comments are recognized, but in the second
example, which has only single-line comments with opening/closing delimiters,
the whole commented block is treated as one big comment.

Note that even for linewise selections a sensible start and end column is set,
so that you can use "v" to switch to a useful characterwise selection. |v_v|


INTERFACE					*textobj-comment-interface*

By default, textobj-comment defines the key mappings "ac", "ic", and "aC" for
the text objects it provides.  These map to named <Plug> mappings and can be
customized easily.  For example, to use "ax" instead of "ac": >

	let g:textobj_comment_no_default_key_mappings = 1
	xmap ax <Plug>(textobj-comment-a)
	omap ax <Plug>(textobj-comment-a)

The mappings are defined in Visual and Operator-pending mode.  See the
|textobj-user| documentation for more info.

						*<Plug>(textobj-comment-a)*
ac			<Plug>(textobj-comment-a)
			"a comment", select a comment with delimiter.
			Select linewise for full-line comments, characterwise
			for inline and end-of-line comments.

						*<Plug>(textobj-comment-i)*
ic			<Plug>(textobj-comment-i)
			"inner comment", select the content inside the comment
			delimiter.
			Always characterwise.

					       *<Plug>(textobj-comment-big-a)*
aC			<Plug>(textobj-comment-big-a)
			"a big comment", select a comment with delimiter and
			whitespace after the comment, or if there isn't any,
			whitespace before the comment.
			Select linewise for full-line comments, characterwise
			for inline and end-of-line comments.

All text objects use the same simple heuristic.  See |textobj-comment-usage|.

A user command and a global variable are also installed with this plugin.

					   *:TextobjCommentDefaultKeyMappings*
:TextobjCommentDefaultKeyMappings[!]
			Restore the default key mappings.
			With the [!] overrides existing key mappings.

				   *g:textobj_comment_no_default_key_mappings*
g:textobj_comment_no_default_key_mappings
			Whether or not to define the default key mappings.
			Set this to "1" if you would like to disable the
			default key mappings.


CHANGELOG					*textobj-comment-changelog*

1.0.0	2013-05-04
	Initial release.


 vim:tw=78:ts=8:ft=help:norl:
