narrow-buffer(2)

NAME

narrow-buffer - Hide buffer lines

SYNOPSIS

n narrow-buffer
n narrow-buffer [line-scheme] ["out-markup-line" |
     "to-top-markup-line" "to-bottom-markup-line"] ["markup-command"]

DESCRIPTION

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:-

1


Removes all narrows in the current buffer (the default), it aborts if there are no narrows in the buffer.

2


Removes the current line's narrow, it aborts if there is no narrow at the current line.

3


Narrow to region hides all but the lines of text in the current buffer from the mark position to the current cursor position, effectively 'narrowing' the buffer to the remaining text.

4


Narrow out region hides the lines of text in the current buffer from the mark position to the current cursor position. This is the inverse effect of argument 3.

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


Bit 0x0010 specifies the line hilight(2) color scheme to be used on the narrow line when it is an open or closed narrow. The scheme colors used are defined by the scheme variables scheme.fold-open and scheme.fold-closed.

0x0020 - "out-markup-line" | "to-top-markup-line" "to-bottom-markup-line"


Bit 0x0020 specifies that mark-up text is used, the text mark up is passed into the call. The number of arguments is determined by the type of markup operation (to/out). The arguments are placed on the mark-up lines.

0x0040 - "markup-command"


Bit 0x0040 specifies that a mark-up line is used to represent the narrow region. When the narrow region is created then the markup-command macro is executed to annotate the narrowed region. The macro is invoked when the narrow is created and is passed a numeric argument n which identifies the operation of the narrow. The numeric argument to the mark-up macro is defined below, generally a positive argument means that a narrow is being added and negative means that the narrow is being removed.

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).

EXAMPLE

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:-

4 narrow-buffer 

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:-

3 narrow-buffer 

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.

Marking Up

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.

NOTES

Alpha mark set by set-alpha-mark(2) in text which is subsequently narrowed out will automatically remove the narrow if the user returns to the mark using goto-alpha-mark(2).

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.

FURTHER EXAMPLES

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.

vm(3) defined in vm.emf uses narrow-buffer with appropriate arguments to append-buffer(2) and write-buffer(2) to write out only parts of the current buffer.

SEE ALSO

!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).

(c) Copyright JASSPA 2009
Last Modified: 2009/08/29
Generated On: 2009/10/12