fold-current(3)

NAME

fold-current - (un)Fold a region in the current buffer
fold-all - (Un)Fold all regions in the current buffer

SYNOPSIS

fold-current
fold-all

DESCRIPTION

MicroEmacs '02 provides a generic, albeit course, folding mechanism which is applied to some of the well known file modes. The folding mechanism allows parts of the buffer to be scrolled up and hidden, leaving a residue hilighting marker within the buffer indicating a folded region. A folded buffer typically allows a summary of the buffer contents to be viewed within several windows, hiding the detail of the buffer.

The folding mechanism uses well defined start and end markers which form part of the syntax of the well known file mode. i.e. in 'C' this is the open and closed braces that appear on the left-hand margin ({ .. }). The intention is that the natural syntax of the text is used to determine the fold positions, requiring no additional text formating or special text tags to be inserted by the user.

fold-current opens and closes a folded region within the buffer. If the current cursor position lies between a start and end marker then the region between the start and end is folded out and hidden from view, leaving a highlight marker in the buffer. If the fold already exists then, moving the cursor to the folded line and invoking fold-current removes the fold marker and reveals the text.

fold-all opens and closes all folded regions within the buffer, if the current state is unfolded then all of the start/end markers are located and their regions folded. Conversely, if the buffer is currently folded and fold-all is invoked, then all folds are removed and the associated text revealed.

CONFIGURATION

In order to utilize the fold-current/all commands within a buffer, the start and end markers have to be initialized for the syntactical contents of the buffer. This is performed within the hook function for the buffer, using the hook-name. Buffer specific variables are defined within the context of the buffer to configure that start and end fold handling. The buffer specific variables are defined as follows, where xxxx is the file hook base name.

xxxx-fold-open


A regular expression search string used to locate the start of the string. For speed the search string should include a regular expression start or end of line character whenever possible. i.e. in C the open is defined as "^{".

xxxx-fold-close


A regular expression search string used to locate the end of the string. For speed the search string should include a regular expression start or end line character whenever possible. i.e. in C the close is defined as "^}".

xxxx-fold-mopen


An integer value that denotes the number of lines to move in a forward or (-ve) backward direction from the start line located by the search string to the position in the buffer to be folded. If default value when mopen is omitted is 0, starting the fold from the search string line.

xxxx-fold-mclose


The relative displacement from the close fold line to the fold position, this is a positive or negative displacement depending on where the fold is to be positioned.

xxxx-fold-mnext


Specifies the number of lines to advance before the next search is continued on the fold operation. This is only used by fold-all.

EXAMPLE

The following examples show how the fold variables are set up in each of the buffer modes.

C and C++

C and C++ fold on the open and close brace appearing in the left-hand margin. The fold variables are defined in hkc/hkcpp.emf as follows:-

set-variable %c-fold-open  "^{" 
set-variable %c-fold-close "^}" 

Given a 'C' function definition:-

static void 
myfunc (int a, int b) 
{ 
    /* Function body */ 
} 

the folded version appears as follows:-

static void 
myfunc (int a, int b) 
} 

emf

MicroEmacs macro files emf support folding of macro definitions, the fold variables are defined in hkemf.emf as follows:-

set-variable %emf-fold-open  "^0? ?define-macro" 
set-variable %emf-fold-close "^!emacro" 
set-variable %emf-fold-mopen "1" 

Given a macro definition:-

0 define-macro mymacro 
; This is the body of the macro 
; ... and some more ... 
!emacro 

the folded version of the macro is defined as:-

0 define-macro mymacro 
!emacro 

nroff

nroff is configured for manual pages only and folds between .SH and .SS sections, the hook variables are defined as follows:-

set-variable %nroff-fold-open  "^\.S[SH]" 
set-variable %nroff-fold-close "^\.S[SH]" 
set-variable %nroff-fold-mopen "1" 
set-variable %nroff-fold-mnext "-1" 

Given an nroff block of text defined as:-

.SH SYNOPSIS 
.\" Some text 
.\" Some more text 
.SH DESCRIPTION 

Then the folded version appears as:

.SH SYNOPSIS 
.SH DESCRIPTION 

tcl/tk

tcl/tk is configured to fold procedures. The fold variables are defined as:-

set-variable %tcl-fold-open  "^proc " 
set-variable %tcl-fold-close "^}" 
set-variable %tcl-fold-mopen "1" 

Given a tcl procedure definition:-

proc tixControl:InitWidgetRec {w} { 
    upvar #0 $w data 

    tixChainMethod $w InitWidgetRec 

    set data(varInited)	  0 
    set data(serial)	0 
} 

The folded version of the same section appears as:-

proc tixControl:InitWidgetRec {w} { 
} 

NOTES

fold-current and fold-all are macros implemented in fold.emf. The folding is performed using the narrow-buffer(2) command.

fold-current may also be bound to the mouse using the user-setup(3). The typical binding is C-mouse-drop-1.

SEE ALSO

File Hooks, user-setup(3), narrow-buffer(2).

(c) Copyright JASSPA 2002
Last Modified: 2001/12/18
Generated On: 2002/01/06