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