narrow-buffer - Hide buffer lines
n narrow-buffer [line-scheme] ["out-markup-line" |
"to-top-markup-line" "to-bottom-markup-line"] ["markup-command"]
The narrow-buffer command allows lines in a buffer to be hidden (effectively folded up) the scope of the narrow is defined by a region. A region is the text located between the point (the current cursor position) and the mark defined by set-mark.
narrow-buffer supports two types of information hiding. A simple Narrow or Narrow Out hides lines of the region from display and optionally inserts a new line, called a mark-up line. The mark-up line allows the narrow position to be annotated with a line scheme color and annotation text providing a visual representation of the narrow i.e.
Before Narrow Out After Narrow Out ________________________________________________________________ ... buffer text ... ... buffer text .. <region start> <Optional Narrow Out line mark-up> .... region text ... ... more buffer text ... <region end> ... more buffer text ...
The second narrow form is a Narrow To hides text around the region leaving the region displayed only. A Narrow Out will optionally show a mark-up line at both the top and bottom of the region. The mark-up line allows the Narrow To position to be annotated in the buffer with a line scheme color and annotation text providing a visual representation of the narrow i.e.
Before Narrow To After Narrow To ________________________________________________________________ ... buffer text ... <Optional Narrow Out top mark-up> <region start> <region start> .... region text ... .... region text ... <region end> <region end> ... more buffer text ... <Optional Narrow Out bottom mark-up>
Once a narrow has been created and information has been hidden narrow-buffer may be used to subsequently reveal the hidden text on a line or complete buffer basis.
Narrowed regions do not delete the text contained within the buffer the information is simply hidden. Saving the buffer using save-buffer(2), by default, writes both the displayed and hidden information the command may be optionally invoked to save only the visible representation.
While information is hidden in a narrow copy-region(2) and kill-region(2) operate as expected. If a narrow is copied then all of the information that is contained within the narrow is also copied to the new location. Similarly killing or deleting a narrow removes all of the information that is contained within the narrow.
narrow-region performs the low-level information hiding and is used from the macro command language, the command is not generally invoked directly by the user. Within the macro environment the location of narrows in any buffer may be determined using the line variable $line-flags(5). This variable allows the narrow state of the current line in a buffer to be determined. The narrow state of a buffer may be determined with narrow(2m). When a narrow is created the buffer mode narrow(2m) is automatically set, when the last narrow is removed the mode is deleted.
The effect of narrow-buffer depends on the given argument and is defined as follows:-
The second form of the command takes a variable number of arguments which are determined by the value of n when bits in the range 0x0ff0 are defined. These bits are interpreted as a bit-mask and determine how the narrow is to be visually displayed to the user. When these bits are set then a mark-up line is created.
0x0010 - line-scheme
0x0020 - "out-markup-line" | "to-top-markup-line" "to-bottom-markup-line"
0x0040 - "markup-command"
1 - This is a Narrow Out line.
2 - This is the top of a Narrow To.
3 - This is the bottom of a Narrow To.
When the macro is executed then the current line is the start of the narrow region, the text of the line is available to the macro via @wl(4). The markup-command aborts, using !abort(4) if the mark-up line is to be removed, otherwise returns a mark-up line in the variable $result(5).
For example, if the buffer contains the following text:
1 Richmond 2 Lafayette 3 Bloomington 4 Indianapolis 5 Gary 6
If the mark is on line 2 and the current point is on line 4, executing:-
Creates one narrow, narrowing out lines 2 and 3, line 4 becomes the narrow anchor line. When the narrow is removed lines 2 and 3 will be inserted before line 4. The buffer will become:-
1 Richmond 4 Indianapolis 5 Gary
If instead the following command was executed:-
Two narrows are created, the first narrowing out lines 4 and 5 (line 6, the last line, being the anchor line) the second narrowing out line 1 (line 2 being the anchor line). The buffer will become:-
2 Lafayette 3 Bloomington 6
Executing narrow-buffer with an argument of 2 will only work on the anchor lines, namely 4 in the first example and 2 and 6 in the second.
A pseudo line may be created by narrow-buffer which is hilighted and annotated to show that a narrow exists. This markup is used in the language templates in the collapse operations (collapse.emf) to show that a narrow exists. The narrow region is applied using the narrow-buffer command as follows:-
0x34 narrow-buffer .scheme.fold-close collapse-markup
This defines a narrow region with a color scheme mark-up. The mark-up line is annotated by the macro collapse-markup once the narrow is created. The macro is defined as follows:-
0 define-macro collapse-markup !if &les @# 0 ; no markup line modificaton !abort !endif set-variable $result &cat &trr &lef @wl 40 " ..." !emacro
The collapse-markup macro process the numeric argument @#(4) to determine the mark-up type to be applied to the buffer. When the numeric argument is negative then !abort(4) is called to remove the mark-up. When the numeric argument is positive then a mark-up line annotation is created by taking the first 40 characters of the line and appending "..." to indicate that this is a narrow. The original narrow-buffer call included a hilight(2) line scheme so the resultant mark-up line will be hilighted and show the first 40 characters of the defined followed by an ellipsis.
get-next-line(2) operates on the unnarrowed buffer and will remove any narrows hiding the 'next' line.
When copying a region containing a narrowed region(s) with copy-region(2) then the content of the narrowed region(s) is also copied. A numeric argument to copy-region(2) may be used to change the behavior to copy the visual representation only.
c-hash-eval(3) macro defined in cmacros.emf uses narrow-buffer to hide regions of source code which have been #defined out, improving readability.
!abort(4), $line-flags(5), $result(5), @#(4), @wl(4), append-buffer(2), c-hash-eval(3), collapse-all(3), collapse-current(3), copy-region(2), fold-close(3), fold-open(3), get-next-line(2), goto-alpha-mark(2), hilight(2), kill-region(2), narrow(2m), narrow-search-backward(3), narrow-search-forward(3), save-buffer(2), set-alpha-mark(2), set-mark(2), vm(3), write-buffer(2).
Copyright (c) 1998-2006 JASSPA
Last Modified: 2006/07/28
Generated On: 2006/10/07