git.r.bdr.sh - rbdr/dotfiles/blob - vim/doc/indent-object.txt

   1 *indent-object.txt*         Text objects based on indent levels.
   2
   3            Copyright (c) 2010 Michael Smith
   4
   5 Indent Text Objects
   6
   7 INTRODUCTION                      |idntobj-introduction|
   8 TEXT OBJECTS                      |idntobj-objects|
   9 BLANK LINES                       |idntobj-blanklines|
  10 ABOUT                             |idntobj-about|
  11
  12
  13 ==============================================================================
  14 INTRODUCTION                                            *idntobj-introduction*
  15
  16 Vim text objects provide a convenient way to select and operate on various
  17 types of objects. These objects include regions surrounded by various types of
  18 brackets and various parts of language (ie sentences, paragraphs, etc).
  19
  20 This plugin defines a new text object, based on indentation levels. This is
  21 very useful in languages such as Python, in which the syntax defines scope in
  22 terms of indentation. Using the objects defined in this plugin, an entire if
  23 structure can be quickly selected, for example.
  24
  25
  26 ==============================================================================
  27 TEXT OBJECTS                          *ai* *ii* *aI* *iI*     *idntobj-objects*
  28
  29 This plugin defines two new text objects. These are very similar - they differ
  30 only in whether they include the line below the block or not.
  31
  32         Key Mapping       Description     ~
  33 >
  34         <count>ai         (A)n (I)ndentation level and line above.
  35         <count>ii         (I)nner (I)ndentation level (no line above).
  36         <count>aI         (A)n (I)ndentation level and lines above/below.
  37         <count>iI         (I)nner (I)ndentation level (no lines above/below).
  38 <
  39
  40 Note that the iI mapping is mostly included simply for completeness, it is
  41 effectively a synonym for ii.
  42
  43 Just like regular text objects, these mappings can be used either with
  44 operators expecting a motion, such as 'd' or 'c', as well as in visual mode.
  45 In visual mode the mapping can be repeated, which has the effect of
  46 iteratively increasing the scope of indentation block selected. Specifying a
  47 count can be used to achieve the same effect.
  48
  49 The difference between |ai| and |aI| is that |ai| includes the line
  50 immediately above the indentation block, whereas aI includes not only that,
  51 but also the line below. Which of these is most useful largely depends on the
  52 structure of the language being edited.
  53
  54 For example, when editing the Python code, |ai| is generally more useful, as
  55 the line above the indentation block is usually related to it. For example, in
  56 the following code (* is used to indicate the cursor position):
  57 >
  58       if foo > 3:
  59          log("foo is big") *
  60          foo = 3
  61       do_something_else()
  62 <
  63 the if clause is logically related to the code block, whereas the function
  64 call below is not. It is unlikely we would want to select the line below when
  65 we are interested in the if block.
  66
  67 However, in other languages, such as Vim scripts, control structures are
  68 usually terminated with something like 'endif'. Therefore, in this example:
  69 >
  70       if foo > 3
  71          echo "foo is big" *
  72          let foo = 3
  73       endif
  74       call do_something_else()
  75 <
  76 we would more likely want to include the endif when we select the if
  77 structure.
  78
  79
  80 ==============================================================================
  81 BLANK LINES                                               *idntobj-blanklines*
  82
  83 When scanning code blocks, the plugin usually ignores blank lines. There is an
  84 exception to this, however, when the block being selected is not indented. In
  85 this case if blank lines are ignored, then the entire file would be selected.
  86 Instead when code at the top level is being indented blank lines are
  87 considered to delimit the block.
  88
  89
  90 ==============================================================================
  91 ABOUT                                                          *idntobj-about*
  92
  93 vim-indent-object was written by Michael Smith <msmith@msmith.id.au>. The
  94 project repository is kept at:
  95
  96 http://github.com/michaeljsmith/vim-indent-object
  97
  98 Any feedback or criticism is welcome, and can be mailed to the author at the
  99 above email address. Alternatively issues can be raised on the project
 100 website.
 101
 102 Licence:
 103
 104 Permission is hereby granted, free of charge, to any person obtaining a copy
 105 of this software and associated documentation files (the "Software"), to
 106 deal in the Software without restriction, including without limitation the
 107 rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 108 sell copies of the Software, and to permit persons to whom the Software is
 109 furnished to do so, subject to the following conditions:
 110
 111 The above copyright notice and this permission notice shall be included in
 112 all copies or substantial portions of the Software.
 113
 114 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 115 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 116 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 117 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 118 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 119 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 120 IN THE SOFTWARE.