1 *NrrwRgn.txt* A Narrow Region Plugin (similar to Emacs)
3 Author: Christian Brabandt <cb@256bit.org>
4 Version: 0.31 Sat, 16 Feb 2013 22:28:31 +0100
5 Copyright: (c) 2009, 2010, 2011, 2012 by Christian Brabandt
6 The VIM LICENSE applies to NrrwRgnPlugin.vim and NrrwRgnPlugin.txt
7 (see |copyright|) except use NrrwRgnPlugin instead of "Vim".
8 NO WARRANTY, EXPRESS OR IMPLIED. USE AT-YOUR-OWN-RISK.
11 ==============================================================================
12 1. Contents *NarrowRegion* *NrrwRgnPlugin*
14 1. Contents.....................................: |NrrwRgnPlugin|
15 2. NrrwRgn Manual...............................: |NrrwRgn-manual|
16 2.1 NrrwRgn Howto..............................: |NR-HowTo|
17 2.2 NrrwRgn Multi..............................: |NR-multi-example|
18 2.3 NrrwRgn Configuration......................: |NrrwRgn-config|
19 3. NrrwRgn Feedback.............................: |NrrwRgn-feedback|
20 4. NrrwRgn History..............................: |NrrwRgn-history|
22 ==============================================================================
23 2. NrrwRgn Manual *NrrwRgn-manual*
27 This plugin is based on a discussion in comp.editors (see the thread at
28 http://groups.google.com/group/comp.editors/browse_frm/thread/0f562d97f80dde13)
30 Narrowing means focussing on a region and making the rest inaccessible. You
31 simply select the region, call |:NarrowRegion| and the selected part will open
32 in a new scratch buffer. The rest of the file will be protected, so you won't
33 accidentally modify that buffer. In the new buffer, you can do a global
34 replace, search or anything else to modify that part. When you are finished,
35 simply write that buffer (e.g. by |:w|) and your modifications will be put in
36 the original buffer making it accessible again.
38 NrrwRgn allows you to either select a line based selection using an Ex-command
39 or you can simply use any visual selected region and press your preferred key
40 combination to open that selection in a new buffer.
42 This plugin defines the following commands:
46 :[range]NarrowRegion[!] When [range] is omitted, select only the current
47 line, else use the lines in the range given and
48 open it in a new Scratch Window.
49 If the current line is selected and is on a folded
50 region, select the whole folded text.
51 Whenever you are finished modifying that region
52 simply write the buffer.
53 If ! is given, open the narrowed buffer not in a
54 split buffer but in the current window.
58 :NarrowWindow[!] Select only the range that is visible the current
59 window and open it in a new Scratch Window.
60 Whenever you are finished modifying that region
61 simply write the buffer.
62 If ! is given, open the narrowed buffer not in a
63 split buffer but in the current window (works best
67 :WidenRegion[!] This command is only available in the narrowed
68 scratch window. If the buffer has been modified,
69 the contents will be put back on the original
70 buffer. If ! is specified, the window will be
71 closed, otherwise it will remain open.
74 :NRV[!] Opened the narrowed window for the region that was
75 last selected in visual mode
76 If ! is given, open the narrowed buffer not in a
77 split buffer but in the current window (works best
82 :NUD When viewing unified diffs, this command opens
83 the current chunk in 2 Narrowed Windows in
84 |diff-mode| The current chunk is determined as the
85 one, that the cursor is at. This command does not
86 make sense if editing a different file format (or
87 even different diff format)
91 :[range]NRP[!] You can use this command, to mark several lines
92 that will later be put into a Narrowed Window
94 If the ! is used, all earlier selected lines will
99 :NRM[!] This command takes all lines, that have been
100 marked by |:NRP| and puts them together in a new
102 When you write your changes back, all separate
103 lines will be put back at their origin.
104 This command also clears the list of marked lines,
105 that was created with |NRP|.
106 See also |NR-multi-example|.
107 If ! is given, open the narrowed buffer not in a
108 split buffer but in the current window (works best
111 *:NRSyncOnWrite* *:NRS*
113 :NRS Enable synching the buffer content back to the
114 original buffer when writing.
115 (this is the default).
117 *:NRNoSyncOnWrite* *:NRN*
119 :NRN Disable synching the buffer content back to the
120 original buffer when writing. When set, the
121 narrowed buffer behaves like an ordinary buffer
122 that you can write in the filesystem.
123 (this is the default).
127 :NRL[!] Reselect the last selected region again and open
128 in a narrowed window.
129 If ! is given, open the narrowed buffer not in a
130 split buffer but in the current window (works best
134 2.1 NrrwRgn HowTo *NR-HowTo*
137 Use the commands provided above to select a certain region to narrow. You can
138 also start visual mode and have the selected region being narrowed. In this
139 mode, NarrowRegion allows you to block select |CTRL-V| , character select |v|
140 or linewise select |V| a region. Then press <Leader>nr where <Leader> by
141 default is set to '\', unless you have set it to something different (see
142 |<Leader>| for information how to change this) and the selected range will
143 open in a new scratch buffer. This key combination only works in |Visual-mode|
145 When finished, simply write that Narrowed Region window, from which you want
146 to take the modifications in your original file.
148 It is possible, to recursively open a Narrowed Window on top of an already
149 narrowed window. This sounds a little bit silly, but this makes it possible,
150 to have several narrowed windows, which you can use for several different
151 things, e.g. If you have 2 different buffers opened and you want to diff a
152 certain region of each of those 2 buffers, simply open a Narrowed Window for
153 each buffer, and execute |:diffthis| in each narrowed window.
155 You can then interactively merge those 2 windows. And when you are finished,
156 simply write the narrowed window and the changes will be taken back into the
159 When viewing unified diffs, you can use the provided |:NUD| command to open 2
160 Narrowed Windows side by side viewing the current chunk in |diff-mode|. Those
161 2 Narrowed windows will be marked 'modified', since there was some post
162 processing involved when opening the narrowed windows. Be careful, when
163 quitting the windows, not to write unwanted changes into your patch file! In
164 the window that contains the unified buffer, you can move to a different
165 chunk, run |:NUD| and the 2 Narrowed Windows in diff mode will update.
167 2.2 NrrwRgn Multi *NR-multi-example*
170 Using the commands |:NRP| and |:NRM| allows to select a range of lines, that
171 will be put into a narrowed buffer together. This might sound confusing, but
172 this allows to apply a filter before making changes. For example before
173 editing your config file, you decide to strip all comments for making big
174 changes but when you write your changes back, these comments will stay in your
175 file. You would do it like this: >
179 Now a Narrowed Window will open, that contains only the configuration lines.
180 Each block of independent region will be separated by a string like
182 # Start NarrowRegion1
186 This is needed, so the plugin later knows, which region belongs where in the
187 original place. Blocks you don't want to change, you can safely delete, they
188 won't be written back into your original file. But other than that, you
189 shouldn't change those separating lines.
191 When you are finished, simply write your changes back.
193 ==============================================================================
195 2.3 NrrwRgn Configuration *NrrwRgn-config*
196 -------------------------
198 NarrowRegion can be customized by setting some global variables. If you'd
199 like to open the narrowed window as a vertical split buffer, simply set the
200 variable g:nrrw_rgn_vert to 1 in your |.vimrc| >
202 let g:nrrw_rgn_vert = 1
204 ------------------------------------------------------------------------------
206 If you'd like to specify a certain width/height for you scratch buffer, then
207 set the variable g:nrrw_rgn_wdth in your |.vimrc| . This variable defines the
208 width or the nr of columns, if you have also set g:nrrw_rgn_vert. >
210 let g:nrrw_rgn_wdth = 30
212 ------------------------------------------------------------------------------
214 By default, NarrowRegion highlights the region that has been selected
215 using the WildMenu highlighting (see |hl-WildMenu|). If you'd like to use a
216 different highlighting, set the variable g:nrrw_rgn_hl to your preferred
217 highlighting Group. For example to have the region highlighted like a search
218 result, you could put that in your |.vimrc| >
220 let g:nrrw_rgn_hl = 'Search'
222 If you want to turn off the highlighting (because this can be distracting), you
223 can set the global variable g:nrrw_rgn_nohl to 1 in your |.vimrc| >
225 let g:nrrw_rgn_nohl = 1
227 ------------------------------------------------------------------------------
229 If you'd like to change the key combination that starts the Narrowed Window
230 for your selected range, you could put this in your |.vimrc| >
232 xmap <F3> <Plug>NrrwrgnDo
234 This will let <F3> open the Narrow-Window, but only if you have pressed it in
235 Visual Mode. It doesn't really make sense to map this combination to any other
236 mode, unless you want it to Narrow your last visually selected range.
238 ------------------------------------------------------------------------------
240 If you'd like to specify the options that you want to have set for the
241 narrowed window, you can set the g:nrrw_custom_options setting, in your
244 let g:nrrw_custom_options={}
245 let g:nrrw_custom_options['filetype'] = 'python'
247 This will only apply those options to the narrowed buffer. You need to take
248 care that all options you need will apply.
250 ------------------------------------------------------------------------------
252 If you don't like that your narrowed window opens above the current window,
253 define the g:nrrw_topbot_leftright variable to your taste, e.g. >
255 let g:nrrw_topbot_leftright = 'botright'
257 Now, all narrowed windows will appear below the original window. If not
258 specified, the narrowed window will appear above/left of the original window.
260 ------------------------------------------------------------------------------
262 If you want to use several independent narrowed regions of the same buffer
263 that you want to write at the same time, protecting the original buffer is not
264 really useful. Therefore, set the g:nrrw_rgn_protect variable, e.g. in your
267 let g:nrrw_rgn_protect = 'n'
269 This can be useful if you diff different regions of the same file, and want
270 to be able to put back the changes at different positions. Please note that
271 you should take care not to change any part that will later be influenced
272 when writing the narrowed region back.
274 Note: Don't use overlapping regions! Your changes will probably not be put
275 back correctly and there is no guard against losing data accidentally. NrrwRgn
276 tries hard to adjust the highlighting and regions as you write your changes
277 back into the original buffer, but it can't guarantee that this will work and
278 might fail silently. Therefore, this feature is experimental!
280 ------------------------------------------------------------------------------
283 NarrowRegion can execute certain commands, when creating the narrowed window
284 and when closing the narrowed window. For this, you can set 2 buffer-local
285 variables that specify what commands to execute, which will hook into the
286 execution of the Narrow Region plugin.
288 For example, suppose you have a file, containing columns separated data (CSV
289 format) which you want to modify and you also have the CSV filetype plugin
290 (http://www.vim.org/scripts/script.php?script_id=2830) installed and you want
291 to modify the CSV data which should be visually arranged like a table in the
294 Therefore you want the command |:ArrangeColumn| to be executed in the new
295 narrowed window upon entering it, and when writing the changes back, you want
296 the command |:UnArrangeColumn| to be executed just before putting the
297 changes back. So you set those two variables in your original buffer: >
299 let b:nrrw_aucmd_create = "set ft=csv|%ArrangeCol"
300 let b:nrrw_aucmd_close = "%UnArrangeColumn"
302 This will execute the commands in the narrowed window: >
307 and before writing the changes back, it'll execute: >
311 ==============================================================================
312 3. NrrwRgn Feedback *NrrwRgn-feedback*
314 Feedback is always welcome. If you like the plugin, please rate it at the
316 http://www.vim.org/scripts/script.php?script_id=3075
318 You can also follow the development of the plugin at github:
319 http://github.com/chrisbra/NrrwRgn
321 Please don't hesitate to report any bugs to the maintainer, mentioned in the
322 third line of this document.
324 If you like the plugin, write me an email (look in the third line for my mail
325 address). And if you are really happy, vote for the plugin and consider
326 looking at my Amazon whishlist: http://www.amazon.de/wishlist/2BKAHE8J7Z6UW
328 ==============================================================================
329 4. NrrwRgn History *NrrwRgn-history*
333 - NRM threw some errors (reported by pydave in
334 https://github.com/chrisbra/NrrwRgn/issues/17, thanks!)
335 - don't create swapfiles (reported by ping, thanks!)
337 0.30: Jan 25, 2013 {{{1
338 - |NRL| throws erros, when used without having first narrowed a region
339 - |NRV!| not allowed (reported by ping, thanks!)
340 - when using single window narrowing, :w would jump back to the original
341 window. Only do this, when 'hidden' is not set (reported by ping, thanks!)
342 - when narrowing a region, the last visual selected region wasn't correctly
343 restored (reported by ping, thanks!)
345 - recursive narrowing was broken, fix it (reported by ping, thanks!)
347 0.29: Aug 20, 2012 {{{1
348 - Use ! to have the narrowed buffer not opened in a new window (suggested by
349 Greg Sexton thanks!, issue #8
350 https://github.com/chrisbra/NrrwRgn/issues/8)
351 - Fix mappings for visual mode (https://github.com/chrisbra/NrrwRgn/issues/9,
352 reported by Sung Pae, thanks!)
353 - Fix problem with setting the filetype
354 (https://github.com/chrisbra/NrrwRgn/issues/10, reported by Hong Xu,
356 - Fix some minor problems, when using ! mode
357 0.28: Jun 03, 2012 {{{1
358 - Plugin did not store last narrowed region when narrowed window was moved to
359 another tabpage (reported by Ben Fritz, thanks!)
361 0.27: May 17, 2012 {{{1
362 - When using |:NR| on a line that is folded, include the whole folded region
363 in the Narrowed window.
364 - Better filetype detection for comments
365 - Error handling, when doing |:NRM| without doing |:NRP| first
366 - Use |:NRP!| to clear the old selection
367 - Don't load the autoload script when sourcing the plugin script
368 (reported by Sergey Khorev, thanks!)
369 - Vim 7.3.449 introduced E855, prevent this error.
371 - |NRM| did not correctly parse the list of lines provided by |:NRP|
372 - highlighted pattern for blockwise visual narrowed regions was wrong
373 - Saving blockwise visual selected regions back, could corrupt the contents
375 0.26: Jan 02, 2012 {{{1
377 - Fix issue https://github.com/chrisbra/NrrwRgn/issues/7
378 (reported by Alessio B., thanks!)
381 0.25: Nov 08, 2011 {{{1
383 - updated documentation (patch by Jean, thanks!)
384 - make it possible, to not sync the narrowed buffer back by disabling
385 it using |:NRSyncOnWrite| |:NRNoSyncOnWrite|
387 0.24: Oct 24, 2011 {{{1
389 - error on vim.org page, reuploaded version 0.22 as 0.24
391 0.23: Oct 24, 2011 {{{1
393 - (wrongly uploaded to vim.org)
395 0.22: Oct 24, 2011 {{{1
397 - Allow customization via the use of hooks (|NR-hooks|)
399 0.21: July 26, 2011 {{{1
401 - Fix undefined variable adjust_line_numbers
402 https://github.com/chrisbra/NrrwRgn/issues/5 (reported by jmcantrell,
405 0.20: July 25, 2011 {{{1
406 - allow customization via the g:nrrw_topbot_leftright variable (Thanks Herbert
408 - allow what options will be applied using the g:nrrw_custom_options dict
409 (suggested by Herbert Sitz. Thanks!)
410 - NRV didn't hightlight the region that was selected (reported by Herbert
412 - use the g:nrrw_rgn_protect variable, to prevent that the original buffer
413 will be protected. This is useful, if you narrow several regions of the same
414 buffer and want to write those changes indepentently (reported by kolyuchiy
415 in https://github.com/chrisbra/NrrwRgn/issues/3, Thanks!)
416 - fix an error with not correctly deleting the highlighted region, that was
417 discovered when reporting issue 3 (see above). (Reported by kolyuchiy,
419 - Catch errors, when setting window local options. (Patch by Sung Pae,
422 0.19: May 22, 2011 {{{1
423 - fix issue 2 from github https://github.com/chrisbra/NrrwRgn/issues/2
424 (Widening does not work, if the narrowed windows have been moved to a new
425 tabspace). Reported by vanschelven, thanks!
427 0.18: December 10, 2010 {{{1
428 - experimental feature: Allow to Narrow several different regions at once
429 using :g/pattern/NRP and afterwards calling :NRM
430 (This only works linewise. Should that be made possible for any reagion?)
431 - disable folds, before writing changes back, otherwise chances are, you'll
432 lose more data then wanted
435 0.17: November 23, 2010 {{{1
436 - cache the options, that will be set (instead of parsing
437 $VIMRUNTIME/doc/options.txt every time) in the Narrowed Window
438 - getting the options didn't work, when using an autocommand like this:
439 autocmd BufEnter * cd %:p:h
440 (reported by Xu Hong, Thanks!)
441 - :q didn't clean up the Narrowed Buffer correctly. Fix this
444 0.16: November 16, 2010 {{{1
445 - Bugfix: copy all local options to the narrowed window (reported by Xu Hong,
448 0.15: August 26, 2010 {{{1
449 - Bugfix: minor documentation update (reported by Hong Xu, Thanks!)
451 0.14: August 26, 2010 {{{1
452 - Bugfix: :only in the original buffer resulted in errors (reported by Adam
455 0.13: August 22, 2010 {{{1
456 - Unified Diff Handling (experimental feature)
458 0.12: July 29, 2010 {{{1
460 - Version 0.11, wasn't packaged correctly and the vimball file
461 contained some garbage. (Thanks Dennis Hostetler!)
463 0.11: July 28, 2010 {{{1
465 - Don't set 'winfixwidth' and 'winfixheight' (suggested by Charles Campbell)
467 0.10: May 20, 2010 {{{1
469 - Restore cursor position using winrestview() and winsaveview()
470 - fix a bug, that prevented the use of visual narrowing
471 - Make sure when closing the narrowed buffer, the content will be written to
472 the right original region
473 - use topleft for opening the Narrowed window
474 - check, that the original buffer is still available
475 - If you Narrow the complete buffer using :NRV and write the changes back, an
476 additional trailing line is inserted. Remove that line.
477 - When writing the changes back, update the highlighting.
479 0.9: May 20, 2010 {{{1
481 - It is now possible to Narrow a window recursively. This allows to have
482 several narrowed windows, and allows for example to only diff certain
483 regions (as was suggested in a recent thread at the vim_use mailinglist:
484 http://groups.google.com/group/vim_use/msg/05d7fd9bd1556f0e) therefore, the
485 use for the g:nrrw_rgn_sepwin variable isn't necessary anymore.
486 - Small documentation updates
488 0.8: May 18, 2010 {{{1
490 - the g:nrrw_rgn_sepwin variable can be used to force separate Narrowed
491 Windows, so you could easily diff those windows.
492 - make the separating of several windows a little bit safer (look at the
493 bufnr(), so it should work without problems for several buffers)
494 - switch from script local variables to buffer local variables, so narrowing
495 for several buffers should work.
496 - set 'winfixheight' for narrowed window
497 - Added command :NRV (suggested by Charles Campbell, thanks!)
498 - added error handling, in case :NRV is called, without a selected region
499 - take care of beeps, when calling :NRV
502 0.7: May 17, 2010 {{{1
504 - really use the black hole register for deleting the old buffer contents in
505 the narrowed buffer (suggestion by esquifit in
506 http://groups.google.com/group/comp.editors/msg/3eb3e3a7c68597db)
507 - make autocommand nesting, so the highlighting will be removed when writing
509 - Use g:nrrw_rgn_nohl variable to disable highlighting (as this can be
512 0.6: May 04, 2010 {{{1
514 - the previous version had problems restoring the orig buffer, this version
515 fixes it (highlighting and setl ma did not work correctly)
517 0.5: May 04, 2010 {{{1
519 - The mapping that allows for narrowing a visually selected range, did not
521 - Make :WidenRegion work as expected (close the widened window) (unreleased)
523 0.4: Apr 28, 2010 {{{1
525 - Highlight narrowed region in the original buffer
526 - Save and Restore search-register
527 - Provide shortcut commands |:NR|
528 - Provide command |:NW| and |:NarrowWindow|
529 - Make plugin autoloadable
530 - Enable GLVS (see |:GLVS|)
531 - Provide Documenation (:h NarrowRegion)
532 - Distribute Plugin as vimball |pi_vimball.txt|
534 0.3: Apr 28, 2010 {{{1
537 - development versions are available at the github repository
538 - put plugin on a public repository (http://github.com/chrisbra/NrrwRgn)
542 ==============================================================================
544 vim:tw=78:ts=8:ft=help:et:fdm=marker:fdl=0:norl