File hooks provide a mechanism to automatically invoke a set of macros for a given buffer type when the following events occur:
The file hook selection (see below) is performed on the file name / extension and on the textual content of the buffer using add-file-hook.
Refer to Language Templates for a description of how the file hooks are used to define a new template for a new text format.
The hook macros allow buffer modes and highlighting, applicable to the text type of the file, to be applied to the buffer. In addition, the associated hook macros may be located in a separate file and are loaded on demand when the file reading determines that a set of hook macros are required.
Consider a file hook definition of the form;
add-file-hook ".c .h" "fhook-c"
which binds the file hook fhook-c to any files that are loaded with the extension .c and .h. The operations undertaken by MicroEmacs '06 are defined as follows when a file foo.c is loaded:-
The name of the file hook macro name is important, hook commands must commence with the text fhook-mode where mode is an identifier for the operating mode. The name space is decomposed as follows:-
The fhook- nomenclature may be omitted provided that the name is less than 6 characters, however the file, begin and end hook macros MUST commence with f, b and e respectively. In addition the macros must be defined as no auto file loading is performed.
The macros bound to a buffer may be interrogated, the variables $buffer-fhook(5), $buffer-bhook(5), $buffer-ehook(5) and $buffer-dhook(5) contain the names of any associated macro attached as a macro hooks, defining the file, begin, end and delete hooks respectively. If a macro is not bound then the empty string "" is returned. Setting the variables has the effect of defining the hook and is a method by which the buffer hooks may be affected after the buffer has been loaded.
The file hook fhook-XXX numeric argument may be used to determine if the file associated with a buffer is a new file created by the user, or an existing file. Typically this distinction is used to determine whether a boiler template is added to the file or not. The macro argument @# is defined as zero (0) if this is a new file that has been created, or non-zero otherwise.
The macro argument status is typically tested on entry to the macro as follows:-
define-macro fhook-mode !if ¬ @# ; This is a new file. Do new file things !else ; This is an existing file !endif ; Set up bindings !emacro
An example of a generic hook file is given at the end of this section which elaborates on the file hooks.
The begin and end hooks are usually used to save and restore global states which require special settings for a particular buffer type. This typically involves saving and restoring global variables which are used by other buffers in a different configuration. For example the following is used to reformat the time stamp string; the time stamp is a global variable $timestamp(5) and if it is changed in one buffer, it must be restored ready for another. In this case the old time stamp is retained in a local buffer variable whenever the buffer is entered, the time stamp is then modified for the buffers requirements. On exit from the buffer the old time stamp format is restored to it's former state.
0 define-macro bhook-foo set-variable .timestamp $timestamp ; Save old time stamp. set-variable $timestamp "19%Y/%M/%D %h:%m:%s" !emacro 0 define-macro ehook-foo set-variable $timestamp .bhook-foo.timestamp !emacro
Note that in both cases the define-macro(2) invocation is defined as zero, this merely hides the macro from the command line since both are private macros not normally invoked by the user.
MicroEmacs '06 may be reconfigured to operate in different modes (referred to a Major Modes in GNU emacs(1)) using the macro file hooks. The file hooks allow the working environment to be customized for the editing of text of a particular sort, by importing text specific macros, key rebinding and highlighting.
MicroEmacs '06, by default, loads a file into a buffer with default global modes with no highlighting. There are no mode specific key bindings, variable settings, macros or highlights, buffer interaction behaves in it's default state. The state of the buffer interaction may be modified through the use of the buffer modes (see Operating Modes), for example the 'C' programming language automatic indent indent(2) changes the characteristics of the tab character and performs language specific indentation of statements. When a text specific set of highlighting rules are applied to the buffer, the text becomes emphasized through the use of color applied selectively to the text i.e. comments, keywords, strings are shown in different colors, allowing them to be differentiated without studying the content.
Setting the operating mode of the buffer would be tedious to perform from the command line, instead MicroEmacs '06 uses three different prioritized criteria to endeavor to select the correct operating mode. The operating mode is applied to the buffer by execution of a set of file specific macros, referred to a hook commands. The selection criteria of the hook commands is performed as follows, ordered in lowest to highest priority:-
The space separated list of names are interpreted as either file extensions or filenames. In this case any file with the extension .c, .cpp is bound to a file hook called fhook-cmode e.g. foo.c. Similarly files with the extension .doc or .txt are interpreted as plain text documents and are bound to fhook-doc. e.g. foo.txt. The entry README that exists in the documentation hook list may refer to a file README and also foo.README, both cases invoke the document hook.
The file selection is the lowest priority selection criteria but usually satisfies most mode selection requirements.
In this case, any file that commences with "#!/bin/sh" is interpreted as a shell script and invokes the shell hook fhook-shell. Where the identifier does not appear on the first non-blank line, the argument may be increased to the number of lines to be searched. Also it the magic sting should be search for without exact(2m) mode then the argument should be negated, e.g.
-4 add-file-hook "<html>" "fhook-html"
invokes fhook-html whenever "<html>", "<HTML>" etc. is found in the first 4 lines of a file header, e.g.:
<!-- Comment line --> <HtMl>
A match on a string identifier is assigned a higher priority than the file extension. It is recommended that magic strings are only used where there are no predefined file extensions, or conflicts exist between files with the same extension containing data interpreted in a different context.
-*- mode -*-
Where mode represents the major mode within GNU Emacs. The same format as used by Magic Strings can be used to find and extract the mode, e.g.:
-1 add-file-hook "-[*!]-[ \t]nroff.*-[*!]-" "fhook-nroff"
The definition would detect the GNU Emacs mode defined in an Nroff file e.g.
.\" -*- nroff -*- "
.TH man 1
It should be stressed that the -*- syntax belongs to GNU Emacs and NOT MicroEmacs '06, MicroEmacs '06 provides a mechanism to locate, extract and interpret the string. The -*- syntax should only be applied to files if it is known that the mode is a GNU mode.
A MicroEmacs '06 specific string is also provided, defined as:
-!- mode -!-
where mode is an arbitrary string defined by add-file-hook. User defined modes may be created and assigned to files with this syntax, this does not conflict with the GNU Emacs command. For example to assign a new mode mymode to a file we would define the following:-
-1 add-file-hook "-!-[ \t]mymode.*-!-" "fhook-mymode"
Files containing a the following identifier would be loaded with mymode hook:
# -!- mymode -!-
# Last Modified: <120683.1014>
The buffer hook files hkname.emf typically follow a standard layout, and are generally associated with hi-lighting as follows, mode in this case is the name of the file mode associated with the file:-
!if &seq .hilight.mode "ERROR" set-variable .hilight.mode &pinc .hilight.next 1 !endif ; ; Define the hilighting ; 0 hilight .hilight.mode 1 $global-scheme hilight .hilight.mode 2 "\*\*" .scheme.comment hilight .hilight.mode 4 "\"" "\"" "\\" .scheme.string hilight .hilight.mode 0 "'.'" .scheme.quote hilight .hilight.mode 1 "if" .scheme.keyword hilight .hilight.mode 1 "elif" .scheme.keyword hilight .hilight.mode 1 "else" .scheme.keyword ... ; Reset the hilighting printer format and define the color bindings. 0 hilight-print .hilight.mode hilight-print .hilight.mode "i" .scheme.comment hilight-print .hilight.mode "b" .scheme.keyword .scheme.variable hilight-print .hilight.mode "bi" .scheme.string .scheme.quote ... ; Define the indentation tokens 0 indent .hilight.mode 2 10 indent .hilight.mode n "if" 4 indent .hilight.mode s "elif" -4 indent .hilight.mode s "else" -4 indent .hilight.mode o "endif" -4 indent .hilight.mode n "while" 4 ... define-macro fhook-mode ; if arg is 0 this is a new file so add template !if ¬ @# etfinsrt "mode" !endif set-variable $buffer-hilight .hilight.mode set-variable $buffer-indent .hilight.mode 1 buffer-mode "time" 1 buffer-mode "indent" buffer-abbrev-file "mode" !emacro
The previous example shows how the fhook-mode numeric argument is used to determine if this is a new file. If the argument @# is zero then this is interpreted as a new file, in this case a standard template is inserted (from file mode.etf) and the generic strings such as $YEAR$ replaced with construction information. The template is generally used for standard headers and skeleton text body.
In addition an abbreviation file mode.eaf (see eaf(8)) is bound to the buffer using the buffer-abbrev-file(2) command and the buffer hi-lighting enabled by assignment of the $buffer-hilight(5) variable.
The standard hook files supplied with MicroEmacs '06 should not be modified, changes to the file hooks may be applied using a separate macro file called myXXX.emf, this is automatically executed after the hkXXX.emf file is executed.
The extended hook functions may be defined company wide, or by the user, to over-ride some of the standard hook functions, or to extend the syntax of the base files with locally defined extensions. As an example, consider the following file myc.emf which extends the basic hkc.emf file set of hi-lighting tokens for the 'C' Language.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; ; Created By : Steven Phillips ; Created : Thu Jun 18 15:34:05 1998 ; Last Modified : <230798.0854> ; ; Description Extension hilighting for the 'C' language. ; ; Notes Define the locally defined 'C' library types and definitions ; as extensions to the 'C' programming language. ; ; History ; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; MicroEmacs specific tokens hilight .hilight.c 1 "LINE" .scheme.type hilight .hilight.c 1 "BUFFER" .scheme.type hilight .hilight.c 1 "WINDOW" .scheme.type hilight .hilight.c 1 "REGION" .scheme.type hilight .hilight.c 1 "KEYTAB" .scheme.type hilight .hilight.c 1 "KILL" .scheme.type hilight .hilight.c 1 "KLIST" .scheme.type hilight .hilight.c 1 "HILNODE" .scheme.type hilight .hilight.c 1 "HILNODEPTR" .scheme.type hilight .hilight.c 1 "HILCOLOR" .scheme.type hilight .hilight.c 1 "SELHILIGHT" .scheme.type hilight .hilight.c 1 "VIDEO" .scheme.type hilight .hilight.c 1 "VVIDEO" .scheme.type hilight .hilight.c 1 "FRAMELINE" .scheme.type hilight .hilight.c 1 "IPIPEBUF" .scheme.type hilight .hilight.c 1 "DIRNODE" .scheme.type hilight .hilight.c 1 "UNDOND" .scheme.type hilight .hilight.c 1 "meVARLIST" .scheme.type hilight .hilight.c 1 "meVARIABLE" .scheme.type hilight .hilight.c 1 "meCMD" .scheme.type hilight .hilight.c 1 "meAMARK" .scheme.type hilight .hilight.c 1 "meABREV" .scheme.type hilight .hilight.c 1 "meMACRO" .scheme.type hilight .hilight.c 1 "meNARROW" .scheme.type hilight .hilight.c 1 "meREGISTERS" .scheme.type hilight .hilight.c 1 "meSTAT" .scheme.type hilight .hilight.c 1 "osdITEM" .scheme.type hilight .hilight.c 1 "osdDIALOG" .scheme.type hilight .hilight.c 1 "osdCHILD" .scheme.type hilight .hilight.c 1 "meSCROLLBAR" .scheme.type hilight .hilight.c 1 "osdCONTEXT" .scheme.type hilight .hilight.c 1 "osdDISPLAY" .scheme.type hilight .hilight.c 1 "RNODE" .scheme.type hilight .hilight.c 1 "REGHANDLE" .scheme.type hilight .hilight.c 1 "meDIRLIST" .scheme.type hilight .hilight.c 1 "meNAMESVAR" .scheme.type hilight .hilight.c 1 "meDICTADDR" .scheme.type hilight .hilight.c 1 "meSPELLRULE" .scheme.type hilight .hilight.c 1 "meDICTWORD" .scheme.type hilight .hilight.c 1 "meDICTIONARY" .scheme.type hilight .hilight.c 1 "meMODE" .scheme.type
Copyright (c) 1998-2006 JASSPA
Last Modified: 2005/01/16
Generated On: 2006/10/07