buffer-init(3)

NAME

buffer-init - Initialize a buffer language template.
buffer-init-hooks - Initialize the buffer language template hooks.
buffer-init-fhook - Initialize the buffer file hooks.

SYNOPSIS

n buffer-init [etf]
buffer-init-hooks
buffer-init-fhook name

DESCRIPTION

The buff-init commands prepare the operating modes and binding of a buffer for the assigned major-mode. These commands operate with variables defined in the major-mode's hook and automatically configure MicroEmacs to use the template.

The commands are used in the major-mode hook files (hkXXX.emf - see File Hooks) and simply the setting up of File Language Templates by automating common actions and integrating the configuration settings made via buffer-setup(3).

The hook file is defined by a call to major-mode(2) which is typically declared in me.emf or the user start up file, binding a file extension or a content identifier to the major-mode. i.e.

5 major-mode "XXX" ".XX1 .XX2" 
13 major-mode "YYY" ".YY1 .YY2" "^#!/.*YYY" 

The first time a file is loaded that is bound to fhook-XXX via a major-mode(2) definition, the hkXXX.emf macro file is executed and then the fhook-XXX command is executed with the file's buffer current so that the file hook is applied to it. Only the execution of fhook-XXX is done on subsequent loading of files of this type.

When the fhook-XXX command is executed it's #l9 register variable is set to the matched magic string if the binding was via a file content hook, or an empty string. This can be useful as the magic string often contains configuration values such as the tab and indent width.

A basic template framework to be used with the buff-init commands may be defined as follows for a language template called XXX:

; File hook - initialize buffer on loading the file. 
define-macro fhook-XXX 
    set-variable $buffer-mask "luh1" 
    @# buffer-init "XXX" 
    buffer-init-hooks 
!emacro 

; buffer-init variables 
set-variable .fhook-XXX.name "XXX Macro" 
set-variable .fhook-XXX.setup &reg "/history/fhook/XXX" "bdfghnopx" 
set-variable .fhook-XXX.setup-mask "abdefghikmnoptux" 
; Commenting configuration -- omit if not defined. 
set-variable .fhook-XXX.comment "|#||#|# | #||" 
; Additional commands -- omit if not defined. 
set-variable .fhook-XXX.command-flag  "||" 
set-variable .fhook-XXX.command-name  "||" 
set-variable .fhook-XXX.command-nbind "||" 
set-variable .fhook-XXX.command-kbind "||" 
set-variable .fhook-XXX.command-desc  "||" 
; OR define the commands one per line uniquely numbered from 0. 
set-variable .fhook-XXX.command-0  "|bo||xxx-para|esc o||" 
set-variable .fhook-XXX.command-1  "|bo||xxx-para|esc q||" 
; Define additional buffer setup menu items -- omit if not defined 
set-variable .fhook-c.setup-flags   "|c|l|" 
set-variable .fhook-c.setup-labels  "|Option 1|Option 2|" 
; Set up collapse or folding for XXX -- omit if not defined 
set-variable .fhook-XXX.collapse-open  "^{" 
set-variable .fhook-XXX.collapse-close "^}" 
set-variable .fhook-XXX.collapse-mopen  "-1" 
set-variable .fhook-XXX.collapse-mclose "1" 
set-variable .fhook-XXX.collapse-mnext "-1" 
; setup XXX item-list -- omit if not defined 
set-variable .fhook-XXX.item-list-s1 "^[ \t]*func\\(\\w+\\)" 
set-variable .fhook-XXX.item-list-r1 "^[ \t]*end" 
; Set up hilighting 
!if &and &sin "h" .fhook-XXX.setup &band .hilight.flags 0x02 
    ; Hi-light XXX Mode 
    !if &not &exi .hilight.XXX 
        set-variable .hilight.XXX &pinc .hilight.next 1 
    !endif 

    0 hilight .hilight.XXX  2 50 
    hilight .hilight.XXX 0 "#.*"          .scheme.comment 
    hilight .hilight.XXX 1 "end"          .scheme.keyword 
    hilight .hilight.XXX 1 "^[ \t]*func" .scheme.function 
    ; ... more ... 

    ; Hilight numbers. 
    !if &band .hilight.flags 0x08 
        ; hilight constants, e.g. numbers 
        hilight .hilight.XXX 1 "[[:digit:]]+"       .scheme.constant 
        hilight .hilight.XXX 1 "-[[:digit:]]+"      .scheme.constant 
        hilight .hilight.XXX 1 "0[xX][[:xdigit:]]+" .scheme.constant 
        hilight .hilight.XXX 1 "[[:digit:]]+\.[[:digit:]]+"  .scheme.constant 
        hilight .hilight.XXX 1 "-[[:digit:]]+\.[[:digit:]]+" .scheme.constant 
        hilight .hilight.XXX 1 "[[:digit:]]+\.[[:digit:]]+f"  .scheme.constant 
        hilight .hilight.XXX 1 "-[[:digit:]]+\.[[:digit:]]+f" .scheme.constant 
    !endif 
!endif 

; End the initialisation - call user extensions i.e. myXXX.emf 
buffer-init-fhook "XXX" 

buffer-init is invoked from the buffer file hook fhook and is invoked with the numerical argument passed to the fhook macro (specified as $#). The call takes two arguments, the first is the name of the template or hook, in the example this is XXX. The second argument is the etf template name (see etf(8)). The command initializes the buffer, using the .fhook-XXX variable information defined in the file.

buffer-init-hooks is invoked from the buffer file hook fhook typically following the buffer-init call this macro invokes any user defined file hooks of the form my-fhook-XXX. User defined my-bhook-XXX and my-ehook-XXX are configured into the buffer space ready for execution.

buffer-init-hooks must be placed in all fhook-XXX macros to correctly initialize the file hooks. If this is not added then the "my-*hook-always" macros may not be called correctly for buffers where the fhook-XXX has not been configured correctly.

buffer-init-fhook is placed at the end of the hook file definition and retrieves additional configuration information from the registry and the user settings, it will also locate and load any user additions to the template by loading the file myXXX.emf.

A set of global default file hooks may be defined of the form my-fhook-always, my-bhook-always, my-ehook-always and my-dhook-always. These file hooks are global and invoked after the

Execution Sequence

It is important to understand the execution sequence of the buffer hook files. On identifying a new file hook then the hkXXX.emf file is fetched from the file system and executed. Execution causes all of the variables to be defined and finally, when all definitions have been made, buffer-init-fhook is executed to load in any user defined extensions. At this point then the macro fhook-XXX has ONLY been defined it has NOT been executed. This load operation is performed once only and is on demand.

The fhook-XXX macro must be defined BEFORE any of the variables associated with the hook as all subsequent variables are command variables and are defined in the context of the macro definition. See Variables(4) for more information on macro variables.

fhook-XXX is invoked to apply hilighting, buffer key bindings, indentation etc. to a new buffer which has just been created.

ehook-XXX is invoked when a buffer is swapped out. This may be used to save global variables that have been modified in the context of the buffer.

bhook-XXX is invoked when a buffer is swapped in. This may be used to restore variables that are specific to a buffer to global variables.

dhook-XXX is invoked before a buffer is deleted. This may be used to clean up a buffer before it is destroyed.

Extended file hooks
The buffer hooks [fbed]hook-XXX may be extended by user specific configuration in the form my-[fbed]hook-any, these are invoked after the primary hook as been invoked and operate on all buffers rather than a specific buffer type. The my-*hook-always mechanism is provided by the buffer-init macros of buffinit.emf rather than from the base command set of MicroEmacs.

Configuration Masks

Buffer initialization is controlled by the settings of the variables .fhook-XXX.setup and fhook-XXX.setup-mask:

set-variable .fhook-XXX.setup &reg "/history/fhook/XXX" "bdfghnopx" 
set-variable .fhook-XXX.setup-mask "abdefghikmnoptux" 

The variables use an ASCII configuration string that identifies the modes of operation that are required. Upper and lower case alternatives are presented, an uppercase flag disables the mode, lower case enables. Where the flag is not specified then the mode is not changed.

a - Auto mode


Configure auto(2m) mode for automatic source file line type detection. Typically enabled for text files.

b - Abbreviation mode


Configures the abbreviation mode using buffer-abbrev-file(2) for the buffer.

c - View / Author mode


Configure view(2m) mode for read only or authoring.

d - Auto indentation operation.


Automatic indent is enabled using indent(2).

Where indent(2m) mode is required then omit the d flag and use flag i instead.

e - Exact or case sensitivity operation


Configure exact(2m) case sensitive mode. e enable exact, E disable exact.

f - Folding/Collapsing operation


Configures folding support, if enabled then the variables .fhook-XXX.collapse-OPERATION, should be defined to declare the folding points.

g - Fence matching operation


Configure fence matching mode with fence(2m). Note that fence matching is now typically performed in the macro environment using display-matching-fence(3) rather than the in-built fence matching. This colorizes the fences that are matched. g enable fence matching, G disable fence matching.

h - Hilighting


Support syntax hilighting, when defined then the hilighting scheme defined by .hilight.XXX is attached to the buffer.

i - Automatic indentation


Support indentation using indent(2m). Automatic indentation (see indent(2)) is defined with the d flag. i enables indent, I disables indent.

j - Justify


Configure paragraph justification using justify(2m). j enable justify, J disable justify.

k - Backup mode


Configure backups with backup(2m) mode. k enable backup, K disable backup.

m - Magic mode


Configure regular expression magic(2m) mode. m enable magic, M disable magic.

n - New buffer header


Enable the insertion of a buffer header from the etf(8) template file.

o - Tool menu


Enable the tool menu for the buffer.

p - Help page


Produce a help page for the buffer describing the bindings.

s - Auto spell


Configure automatic spelling for the buffer using auto-spell(3).

t - Tab mode


Configure insertion of literal tabs by enabling tab(2m) mode. t enable tab, T disable tab.

u - Undo


Configure the undo/redo history using undo(2m) mode. u enable undo, U disable undo.

w - Wrap


Configure wrapping using wrap(2m) mode. w enable wrap, W disable wrap.

x - Time stamping


Configure time stamping as defined by time(2m).

1 - Reformatting hilighting


A special internal flag indicating that hilighting is used for reformatting purposes, i.e. to make readable and hide control text.

# - Commenting


Special flag used to indicate commenting is supported. The comment format should be defined with the .fhook-XXX.comment variable within the template.

.fhook-XXX.setup is the current set-up, this is normally defined to take settings from the registry providing a default when not defined. This is the only mask that is allowed to include the uppercase flags. All values defined in .fhook-XXX.setup are explicitly enabled or disabled by default. The setup set should contain the configuration flags that are required to make the template operate correctly, but should not include modes that the user may set up i.e. exact or magic etc.

.fhook-XXX.setup-mask defines the set of flags that are allowed with the template. The configuration defined in buffer-setup(3) is tested against the mask, if the mask allows it then the mode is enabled. .fhook-XXX.setup is generally a subset of .fhook-XXX.setup-mask.

buffer-setup(3) operates with the values defined by .fhook-XXX.setup and .fhook-XXX.setup-mask. The initialization of .fhook-XXX.setup is performed using the registry as follows:

set-variable .fhook-XXX.setup &reg "/history/fhook/XXX" "bdfghnopx" 

This allows the user to configure over-ridding modes via buffer-setup(3). The user configuration is saved to the Registry and restored using &reg(4), when the variable is defined. The flags that are defined by buffer-setup(3) include a, b, c, d, e, f, g, h, i, j, k, m, n, o, p, s, t, u, w, and x.

Tags

The buffer setup may be configured to add a tags generator to the language template, this is added to the menu. The tags generation is declared in the template by assigning the variable .fhook-XXX.tags with a command line to run tags utility. The command line string should commence with a ! character to tell MicroEmacs to execute an external command, for example to use the GNU ctags(2) utility is defined as:

set-variable .fhook-c.tags "!ctags *.c *.h" 

When the value starts with a '!' then rest of the line is spawned as a process, no additional interface is provided to the command.

Some language templates include a macro tags facility to generate a tags file (See emftags(3f) - emftags.emf, ctags(3f) - ctags.emf, ntags(3f) - ntags.emf). .fhook-XXX.tags may be defined to use an internal macro based tags generator rather than an external command. Without the '!' character the command line is assumed to be an MicroEmacs macro based and runs the command

me @<.tags-var-value> -v%tag-options=<options> 

A macros based command line for the 'C' Programming Language is defined as:

set-variable .fhook-c.tags "ctags" 

The presence of a tags generator is not flagged in the setup flags, declaration of the .fhook-XXX.tags variable is sufficient to declare that a tags generator exists.

Private Configuration Extensions

The .fhook-XXX.setup may be extended to include local configuration items that are private to a specific buffer. The extensions are added to the buffer-setup(3) menu and provide an on/off check-box control to enable and disable specific buffer features. Feature examples include: Enable or disable Doxygen highlighting in a buffer, control hidden file names in a directory listing etc.

The configuration extensions are defined using two additional hook variables, these variables are normally omitted and only defined if the extensions are required.

.fhook-XXX.setup-flags


Defines the alphabetic [a-z] setup characters that are used to enable or disable a feature. These are defined as MicroEmacs list variables (see &lfind(4), &lget(4), etc. for the full syntax definition). The characters that may be used are those that are not used by buffer setup i.e. "clqrvyz"

.fhook-XXX.setup-labels


Defines the text labels that are added to the setup menu, the label is associated with the enable button.

To add a new feature switch then the the character flags to hold the state are are defined with the .fhook-XXX.setup-flags and .fhook-XXX.setup-labels. The characters defined with the setup-flags should be added to .fhook-XXX.setup-mask. If the option is to be enabled by default then the enabling character is added to .fhook-XXX.setup.

To enable/disable the features then buffer-setup(3) when invoked modifies the state of the variable .fhook-XXX.setup and then executes the buffer hook again causing the new state to be processed and applied. The modified .fhook-XXX.setup value is stored in the user registry and is applied thereafter when the specified buffer type is loaded.

Within the template definition then the additional flags are checked by testing the state of the .fhook-XXX.setup variable. An example is shown below.

; Add the extra variable to the buffer-init variables 
; Option 1 is disabled and Option 2 is enabled by default here. 
set-variable .fhook-XXX.setup &reg "/history/fhook/XXX" "bdfghnopxl" 
set-variable .fhook-XXX.setup-mask "abdefghikmnoptuxcl" 

; Define the additional options. 
set-variable .fhook-XXX.setup-flags   "|c|l|" 
set-variable .fhook-XXX.setup-labels  "|Option 1|Option 2|" 

; Test for the Option 1 being enabled. 
!if &sin "c" .fhook-XXX.setup 
    ; Do Option 1 configuration. 
!endif 

; Test for the Option 2 being enabled. 
!if &sin "l" .fhook-XXX.setup 
    ; Do Option 2 configuration. 
!endif 

The templates hkc.emf, hkcpp.emf and hkjava.emf include private extensions which may be used as examples.

Comments

The format of comments may be defined in the template using the .fhook-XXX.comment variable. Definition of the comment form allows the comment formatting to be automatically set up. Where the comment format is defined then the following key bindings are automatically added to the template:

C-c C-s comment-start - start a new comment.
C-c C-c comment-line - comment out the current line.
C-c C-d uncomment-line - remove commenting from current line.
C-c C-e comment-to-end-of-line - comment to end of line.
C-c C-r comment-restyle - format/re-style comment.

Help information is automatically added to the buffer to describe the key bindings if help information is enabled.

The default comment format is defined with the variable .fhook-XXX.comment with an argument string in the form "| <comment-start> | <comment-end> | <comment-pad> | <mid-box-left> | <mid-box-right> | <comment-flags> |". Where a language supports multiple comment types, or styles, then additional comment styles may be specified with a comment definition of the form .fhook-XXX.comment-N where N is an integer from 1 to n. Each definition defines an different comment style. Additional comment definitions should be ordered such that the longest or most definitive comment definition appears before other comment definitions which have less definitive features. The comment matching searches each of the comment definitions in the order 1 to n to determine the comment style, as soon as a positive match is located then the comment is used without searching the remaining comments.

The fields of the comment definition are defined as follows:

<comment-start>


The format of the start of the comment or comment open syntax.

<comment-end>


The format of the closing comment, where the comment exists to the end of the line then the field is defined as empty. Leading white space should be included where this affects the horizontal positioning of the comment, white leading space is ignored in any match i.e. " */" for C type comments.

<comment-pad>


The character to use to pad a comment between the <comment-start> and <comment-end> characters when creating a line or a box formation.

<mid-box-left>


The start of a comment continuation line when creating a box comment.

<mid-box-right>


The end of a comment continuation line when creating a box comment and the comment is not closed and continues on the next line.

<comment-flags>


The comment flags define how the comment should be formatted when re-styled. The flags are defined as single characters that describe the attributes. Re-styling may include the following attributes:

b


Box format required, create a left and right edge for the comment.

f


A footer line is required, a new line is created following the comment text to contain the with a closing comment <comment-end> string. The end of comment is not padded.

F


As f except the footer line is left padded with <comment-pad> strings.

h


A header line is required, a new line is created before the comment text to contain the opening comment <comment-start> string. The end of comment is not padded.

H


As h except the header line is right padded with <comment-pad> strings.

j


Enable justification mode in the *comment* buffer and re-style.

r


A restyle key binding is added to the buffer "esc o" and "esc q" buffer key bindings are added and bound to comment-restyle(3). The r flag is only processed from the

Examples of the comments format are shown below.

'C' Programming language


Format: /* ... */

set-variable .fhook-c.comment "|/*| */|*| * | * |f|" 

The comment output is defined as:

/*************************************************************** 
 * This is a box comment                                       * 
 ***************************************************************/ 

/* Comment to end of line **************************************/ 

C++ Programming language


Format: // ... <EOL>

set-variable .fhook-cpp.comment "|//||/|// | //||" 

The comment output is defined as:

///////////////////////////////////////////////////////////////// 
// This is a box comment                                       // 
///////////////////////////////////////////////////////////////// 

// Comment to end of line /////////////////////////////////////// 

C++ supports both C and C++ comment styles, both styles may be defined in the language template. For C++ then // is assumed to be the default style.

set-variable .fhook-cpp.comment   "|//||/|// | //||" 
set-variable .fhook-cpp.comment-1 "|/*| */|*| * | * |f|" 

MicroEmacs macro language


Format: ; ... <EOL>

set-variable .fhook-emf.comment "|;||;|; | ;||" 

The comment output is defined as:

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 
; Box Comment                                                   ; 
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 

; Comment to end of line ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 

Shell script


Format: # ... <EOL>

set-variable .fhook-shell.comment "|#||#|# | #||" 

The comment output is defined as:

################################################################# 
# Box Comment                                                   # 
################################################################# 

# Comment to end of line ######################################## 

MS-DOS Batch file


Format: rem ... <EOL>

set-variable .fhook-dos.comment "|rem |||rem |||" 

The comment output is defined as:

rem 
rem Box Comment 
rem 

rem Comment to end of line 

Commands and Key Bindings

Local buffer commands and key bindings for over-riding key definitions used within the buffer are defined with the fhook-XXX.command-* variables. These are defined as MicroEmacs list variables (see &lfind(4), &lget(4), etc. for the full syntax definition) and define a list of keys, commands and bindings. Each command is typically separated by the '|' character. The field order in all of the fhook-XXX.command-* variables MUST be consistent, so if a command is defined in field 5, then all definitions associated with that command MUST be defined in field 5 for all variables.

To make the command definitions easier then the syntax fhook-XXX.command-n may be used where n is an integer from 0..n-1. The fhook-XXX.command-n statements are used to construct the fhook-XXX.command-* lists, the advantage being that the command and key bindings etc. are defined together. Once the command-n variables are processed then they are deleted from the environment. The general syntax of the command-n variable is defined as a list:

|command-flag|command-nbind|command-name|command-kbind|command-desc|

The command variables are defined as follows:

.fhook-c.command-flag


A configuration flag that defines the components to use for the command. The flags are set as individual characters and are defined as follows:

t - Toolbar


Show the command in the toolbar. The .fhook-XXX.command-desc variable should contain a readable name for the command to display in the menu. An optional hot key for selection in any osd is specified by prefixing the character in the string with \H.

h - Help Screen


Show the command in the help screen. The .fhook-XXX.command-desc variable should contain a readable name for the command to display in the menu. An optional hot key for selection in any osd is specified by prefixing the character in the string with \H.

b - Key binding


Create a buffer key binding for the command, the key to bind is defined by the variable fhook-XXX.command-kbind, if the command requires a numerical argument then this is defined in the variable fhook-XXX.command-nbind. The binding is only created if the key buffer binding does not already exist, the binding may be forced by using the o flag. Where a key binding is only to be created if hilighting is enabled then the b flag should be qualified with the H flag.

o - Forced key binding


Optionally used with the b and forces the binding to over-write any existing binding.

i - Emulated key binding


Used with the b flag, ignores key bindings that are emulation mappings.

H - Hilighting key binding


Used with the b flag, only performs the key binding if hilighting is enabled.

.fhook-XXX.command-name


Specifies the name of the command to execute, this may be a built in command of a macro. Typically the command is a local macro defined in the hook file.

.fhook-XXX.command-nbind


The value of the numeric argument to pass to the command defined in the .fhook-XXX.command-name field. This field may be empty if no numeric argument is required.

.fhook-XXX.command-kbind


The local key binding to bind to the command, this field is only interpreted if the b is specified, otherwise the field may be empty. Where multiple key bindings are required to the same command then a field definition is required for each binding.

.fhook-c.command-desc


A short description of the command that is used for the help page (h) and toolbar (t). The field may be empty if the field is not specified for insertion into the toolbar or help page.

As an example, two new commands or bindings may be defined for a template, the first field is bound to key A-q which executes macro XXX-comp with a numerical argument of 2. The second field binds a new key to comment-restyle(3).

..... 

set-variable .fhook-XXX.command-flag  "|th|bo|" 
set-variable .fhook-XXX.command-name  "|XXX-comp|comment-restyle|" 
set-variable .fhook-XXX.command-nbind "|2||" 
set-variable .fhook-XXX.command-kbind "|A-q|esc o|" 
set-variable .fhook-XXX.command-desc  "|Complete command||" 

..... 

; Local macro definition to perform command completion 
define-macro XXX-comp 
    set-variable #l1 @# 
    ..... 
!emacro 

The alternative form of definition using the command-n syntax is defined as:

..... 

set-variable .fhook-XXX.command-0 "|th|2|XXX-comp|A-q|Complete command|" 
set-variable .fhook-XXX.command-1 "|bo||comment-restyle|esc o||" 

..... 

; Local macro definition to perform command completion 
define-macro XXX-comp 
    set-variable #l1 @# 
    ..... 
!emacro 

The key bindings sometimes need to be protected where they have been redefined to perform some other operation for example when emulation modes are used (i.e. nedit, me3.8). The buffer initialisation uses the command buffer-bind-create and the variables .buffer-bind-create.map-from and .buffer-bind-create.map-to which define replacement keys for bindings. As an example the nedit emulation mode uses key binding C-c C-c and provides a buffer binding mapping to translate any key buffer binding to a different key. i.e.

; reconfigure the buffer bindings 
set-variable .buffer-bind-key.map-from "|C-c C-c|C-c C-d|" 
set-variable .buffer-bind-key.map-to   "|C-b|C-u|" 

Information Hiding with Collapse

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

Note: collapse was called fold in earlier releases but the name was changed when real fold editing support was added, see fold.emf for more information.

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.

The language template defines the syntax of blocks of information that may be collapsed and hidden with narrow. In order to utilize the collapse-current(3) and collapse-all(3) commands within a buffer, the start and end markers have to be initialized for the syntactical contents of the buffer. The buffer specific variables are defined as follows, where XXX is the file hook base name. The .fhook-XXX.collapse-* variables define the regular expression search pattern and line positioning.

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

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} { ... } 

Where folding is required using fold-open(3) then the collapse methods above are not enacted when folding is enabled. Folding may be enabled as defined by the File Hooks, alternatively the folding may be explicitly defined using the variable .fhook-XXX.fold. The .fhook-XXX.fold variable argument is defined as "| <literal-open> | <literal-close> | <comment-termination> | <regex-find-open> | <regex-find-close> |. Where the fields are defined as follows:

<literal-open>


The literal fold open string.

<literal-close>


The literal fold close string.

<comment-termination>


The comment termination string.

<regex-find-open>


The regular expression to find an open fold.

<regex-find-close>


The regular expression to find a close string.

As an example, a language may have the following syntax for defining folds:

/* {{{ This is an example fold. */ 
This is 
the body 
of the fold 
/* }}} */ 

The fold is defined as follows:

set-variable fhook-XXX.fold "|/\\* {{{|/\\* }}}|\\*/|/\\*[ \t]*{{{|/\\*[ \t]*}}}|" 

Item Lists

Item Lists perform a regular expression search of a buffer, presenting a list of the located text and associated types in a separate window which is presented to the left of the buffer window or more typically in the toolbar. The command item-list(3) is a generic command that interacts with the buffer environment variables to present abbreviated buffer information to the user.

The regular expression search strings are predefined in the language templates, using the variables .fhook-XXX-item-list-sY and .fhook-XXX-item-list-rY and are described more fully in item-list(3).

Hilighting

Buffer hilighting is defined by the hilight(2) command. Within the context of buffer-init then the standard definitions and name space conventions should be adhered to:

!if &not &exist .hilight.XXX 
    set-variable .hilight.XXX &pinc .hilight.next 1 
!endif 
!if &and &sin "h" .fhook-XXX.setup &band .hilight.flags 0x02 
    ; High-light XXX Mode 
    0 hilight    .hilight.XXX 0                    $global-scheme 
    ..... 
    ; Variable hilighting 
    !if &band .hilight.flags 0x08 
        ; hilight constants, e.g. numbers 
        hilight .hilight.XXX 1 "[[:digit:]]+"       .scheme.constant 
        ...... 
    !endif 
!endif 

Indentation

Buffer indentation is defined by the indent(2) command. Within the context of buffer-init then the standard definitions and name space conventions should be adhered to. The buffer indentation scheme uses the hilighting variable, if hilighting is not defined then the variable allocation of .hilight.XXX should be performed as defined in the previous Hilighting section.

!if &sin "d" .fhook-XXX.setup 
    0 indent  .hilight.XXX 0 10 
    indent .hilight.XXX n "{"  4 
    indent .hilight.XXX o "}" -4 
    ..... 
!endif 

HISTORY

The January 2005 version of MicroEmacs introduced the following changes:

• The my-*hook-always introduced allowing global file hooks to manipulate operate on any buffer.
• The Electric-C indentation previously flagged as > was removed, as was cmode(2m). Indentation configuration for C mode is now performed by the indent(2) command.
• Private template configuration using .fhook-XXX.setup-flags and .fhook-XXX.setup-labels.
• The fhook-XXX.command-n syntax was introduced in June 2005 to simplify the command list definitions.

SEE ALSO

$buffer-hilight(5), $buffer-indent(5), major-mode(2), buffer-abbrev-file(2), buffer-setup(3), collapse-all(3), collapse-current(3), ctags(3f), eaf(8), emftags(3f), etf(8), insert-template(3), execute-buffer(2), expand-abbrev(2), global-abbrev-file(2), hilight(2), indent(2), indent(2m), item-list(3), narrow-buffer(2), ntags(3f), restyle-buffer(3), restyle-region(3), scheme-editor(3), time(2m),
File Hooks,
File Language Templates.

Ref: buffer-init(3) File: m3mac064.3 Date: 2026/02/17

(c) Copyright JASSPA 2026