collapse-current(3)

NAME

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

SYNOPSIS

collapse-current
collapse-all

DESCRIPTION

MicroEmacs 2009 provides a generic, albeit coarse, 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.

collapse-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 collapse-current removes the fold marker and reveals the text.

collapse-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 collapse-all is invoked, then all folds are removed and the associated text revealed.

CONFIGURATION

In order to utilize the collapse-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, the initialization is performed within buffer-init(3). 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 XXX is the file hook base name.

.fhook-XXX-collapse-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 "^{".

.fhook-XXX-collapse-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 "^}".

.fhook-XXX-collapse-mopen


An integer value that denotes the number of lines to move in a forward or (negative n) 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.

.fhook-XXX-collapse-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.

.fhook-XXX-collapse-mnext


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

PRESENTATION

The presentation of a collapsed region takes the form:

<open line string> ... <close line string>

Where <open line string> and <close line string> are automatically extracted from the originating buffer using the search string definition. Existing collapse implementations used a simpler format:

<open line string> ...

In MicroEmacs '04 and later versions, then the <close line string> is always appended. Appending of the closing token is required to ensure that any indentation is maintained. This allows the indent processing to find both an open and close character sequence and not introduce an unwanted indentation. To ensure that indentation consistency is maintained then the .fhook-XXX.collapse-close definition should minimally match the corresponding indentation close regular expression.

EXAMPLE

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

C and C++

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

set-variable .fhook-c.collapse-open  "^{" 
set-variable .fhook-c.collapse-close "^}" 
set-variable .fhook-c.collapse-mopen  "-1" 
set-variable .fhook-c.collapse-mclose "1" 
set-variable .fhook-c.collapse-mnext "-1" 

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 collapse variables are defined in hkemf.emf as follows:-

set-variable .fhook-emf.collapse-open  "^0? ?define-macro[ \t]" 
set-variable .fhook-emf.collapse-close "^!emacro" 
set-variable .fhook-emf.collapse-mclose "1" 
set-variable .fhook-emf.collapse-mnext "-1" 

Given a macro definition:-

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

the collapsed 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 .fhook-nroff.collapse-open  "^\.S[SH]" 
set-variable .fhook-nroff.collapse-close "^\.S[SH]\|\'" 
set-variable .fhook-nroff.collapse-mnext "-1" 

Given an nroff block of text defined as:-

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

Then the collapsed version appears as:

.SH SYNOPSIS 
.SH DESCRIPTION 

tcl/tk

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

set-variable .fhook-tcl.collapse-open  "^proc " 
set-variable .fhook-tcl.collapse-close "^}" 
set-variable .fhook-tcl.collapse-mclose "1" 
set-variable .fhook-tcl.collapse-mnext "-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 collapsed version of the same section appears as:-

proc tixControl:InitWidgetRec {w} { ... } 

NOTES

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

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

HISTORY

collapse is the new name for fold appearing in MicroEmacs 2004 version. The existing commands of fold-current and fold-all have been replaced by collapse-current and collapse-all respectively. collapse now uses the private command variables.

SEE ALSO

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

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