126 lines
5.4 KiB
Text
126 lines
5.4 KiB
Text
*indent-object.txt* Text objects based on indent levels.
|
|
|
|
Copyright (c) 2010 Michael Smith
|
|
|
|
Indent Text Objects
|
|
|
|
INTRODUCTION |indtobj-introduction|
|
|
TEXT OBJECTS |indtobj-objects|
|
|
BLANK LINES |indtobj-blanklines|
|
|
ABOUT |indtobj-about|
|
|
|
|
|
|
==============================================================================
|
|
INTRODUCTION *indtobj-introduction*
|
|
|
|
Vim text objects provide a convenient way to select and operate on various
|
|
types of objects. These objects include regions surrounded by various types of
|
|
brackets and various parts of language (ie sentences, paragraphs, etc).
|
|
|
|
This plugin defines a new text object, based on indentation levels. This is
|
|
very useful in languages such as Python, in which the syntax defines scope in
|
|
terms of indentation. Using the objects defined in this plugin, an entire if
|
|
structure can be quickly selected, for example.
|
|
|
|
|
|
==============================================================================
|
|
TEXT OBJECTS *ai* *ii* *aI* *iI* *indtobj-objects*
|
|
|
|
This plugin defines two new text objects. These are very similar - they differ
|
|
only in whether they include the line below the block or not.
|
|
|
|
Key Mapping Description ~
|
|
>
|
|
<count>ai (A)n (I)ndentation level and line above.
|
|
<count>ii (I)nner (I)ndentation level (no line above).
|
|
<count>aI (A)n (I)ndentation level and lines above/below.
|
|
<count>iI (I)nner (I)ndentation level (no lines above/below).
|
|
<
|
|
|
|
Note that the iI mapping is mostly included simply for completeness, it is
|
|
effectively a synonym for ii.
|
|
|
|
Just like regular text objects, these mappings can be used either with
|
|
operators expecting a motion, such as 'd' or 'c', as well as in visual mode.
|
|
In visual mode the mapping can be repeated, which has the effect of
|
|
iteratively increasing the scope of indentation block selected. Specifying a
|
|
count can be used to achieve the same effect.
|
|
|
|
The difference between |ai| and |aI| is that |ai| includes the line
|
|
immediately above the indentation block, whereas aI includes not only that,
|
|
but also the line below. Which of these is most useful largely depends on the
|
|
structure of the language being edited.
|
|
|
|
For example, when editing the Python code, |ai| is generally more useful, as
|
|
the line above the indentation block is usually related to it. For example, in
|
|
the following code (* is used to indicate the cursor position):
|
|
>
|
|
if foo > 3:
|
|
log("foo is big") *
|
|
foo = 3
|
|
do_something_else()
|
|
<
|
|
the if clause is logically related to the code block, whereas the function
|
|
call below is not. It is unlikely we would want to select the line below when
|
|
we are interested in the if block.
|
|
|
|
However, in other languages, such as Vim scripts, control structures are
|
|
usually terminated with something like 'endif'. Therefore, in this example:
|
|
>
|
|
if foo > 3
|
|
echo "foo is big" *
|
|
let foo = 3
|
|
endif
|
|
call do_something_else()
|
|
<
|
|
we would more likely want to include the endif when we select the if
|
|
structure.
|
|
|
|
|
|
==============================================================================
|
|
BLANK LINES *indtobj-blanklines*
|
|
|
|
When scanning code blocks, the plugin usually ignores blank lines. There is an
|
|
exception to this, however, when the block being selected is not indented. In
|
|
this case if blank lines are ignored, then the entire file would be selected.
|
|
Instead when code at the top level is being indented blank lines are
|
|
considered to delimit the block.
|
|
|
|
This exceptional behaviour can be disabled by executing the following line
|
|
>
|
|
:let g:indent_object_except_first_level = 0
|
|
<
|
|
(default is 1)
|
|
|
|
|
|
==============================================================================
|
|
ABOUT *indtobj-about*
|
|
|
|
vim-indent-object was written by Michael Smith <msmith@msmith.id.au>. The
|
|
project repository is kept at:
|
|
|
|
http://github.com/michaeljsmith/vim-indent-object
|
|
|
|
Any feedback or criticism is welcome, and can be mailed to the author at the
|
|
above email address. Alternatively issues can be raised on the project
|
|
website.
|
|
|
|
Licence:
|
|
|
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
of this software and associated documentation files (the "Software"), to
|
|
deal in the Software without restriction, including without limitation the
|
|
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
|
|
sell copies of the Software, and to permit persons to whom the Software is
|
|
furnished to do so, subject to the following conditions:
|
|
|
|
The above copyright notice and this permission notice shall be included in
|
|
all copies or substantial portions of the Software.
|
|
|
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
|
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
|
|
IN THE SOFTWARE.
|