major-mode(2)

NAME

major-mode - Declare or set a buffer major mode

SYNOPSIS

major-mode id
0 major-mode id
n major-mode id ["cid-label"] ["extension-list"] ["full-name"] [cid-line-count "cid-regex"] ["macro1-name" "macro2-name" ...]
16 major-mode id [cid-line-count "cid-regex"]

DESCRIPTION

The major-mode command is used to define the main content type of a buffer, such as C or HTML etc. The command changes the major-mode assignment of the current buffer, defines or modifies the major-mode properties i.e. the file extension list etc.

When the major-mode of a buffer is assigned, the buffer variables $buffer-major-mode(5) and $buffer-fhook(5) are updated and the $buffer-fhook macro is executed. The $buffer-fhook macro (and hook file that it is defined in) configure the major mode features such as hilighting, indentation rules, etc.

major-mode, with no argument n, prompts for a new major mode id and is immediately applied. If id matches the buffers current major-mode identity then the command prints the full name of the current major-mode, the content label (if enabled) and name of the hook file.

major-mode, with a positive numeric argument n modifies the major mode settings, the id argument must be supplied and the effect of the numeric argument n bits are as follows:

0x01


When set, the major-mode is created if it does not already exist. An error is returned if the bit is clear and the major-mode id does not exist.

0x02


When set, the content-ID label of the major-mode is assigned the argument value cid-label. If cid-label is an empty string (i.e. "") the feature is disabled.

When clear, the content-ID label remains unchanged unless the call is creating the major-mode, in this case, the cid-label is set to the same value as the id.

Refer to the Notes section below for more information on the use of the content-ID label.

0x04


When set, the file extensions associated with the major-mode are set to extension-list. extension-list is a space separated list of file endings (as opposed to true file extensions) and are usually specified with the extension separator. For example, the extension list ".c .h" maybe used for C major-mode to associate files ending in .c or .h.

A forward slash ('/') character at the start of an extension forces the match of the whole file name, for example, the Unix info system often has directories with a 'dir' file, an extension-list value of ".info /dir" matches any file ending in .info and a file with the name dir.

A caret ('^') character at the start of an extension matches the start of the filename with the extension.

If extension-list is the empty string then the feature is disable.

When bit 0x04 is clear, the value remains unchanged unless this is the initial creation call, in which case the value is set to ".id".

Extension-list values are not concatenated when the extension-list is redefined, the full list of extensions must always be provided. The extension comparison is always case insensitive to ensure consistent behaviour across all platforms.

0x08


When set, the full name of the major-mode is set to full-name. When this bit is clear the value remains unchanged unless the call is also creating the major-mode, when the name is set to the capitalised value of cid-label, if set, or id. The name is forced to uppercase if the value does not contain a vowel e.g. HTML.

0x10


When set, the cid-line-count and cid-regex parameters are used to define a content based identifier which recognises the file type from the contents of the file. A file to be identified must have content within the first cid-line-count non-blank lines matching the cid-regex. If the line count cid-line-count is positive the regular expression search is case sensitive, if the line count is negative, the count is negated and the search is case insensitive.

When bit 0x10 is used on its own, a special 'regex replace' form of the id can be used, see the Notes section below for more information.

The order the major-modes are defined is used when there is a conflict in assignment, for example, both C and C++ may use the .h extension. Priority is given to the last defined major-mode, i.e. the first defined major-mode has the lowest priority, ensuring that any user created major-modes have the highest priority. The order may be manipulated by simply redefining the major-mode with an argument of 1. For example, adding the following line to the end a user macro file would make the shell script major-mode the highest priority:

1 major-mode "sh" 

If a numerical argument of 0 is given to major-mode the command uses the variable $result(5) to return information about the given id major-mode in the following MicroEmacs list format:

\b<id>\b<flags>\b<cid-label>\b<extension-list>\b<full-name>\b 

Where '\b' is the list value separator character. The <flags> member is an integer interpreted as a bit flag with the following values:

0x01


If set, initialisation of the major-mode has been attempted, if bit 0x02 is also set then the attempt was successful and the major-mode would have been applied to a buffer, if bit 0x02 is clear then MicroEmacs failed to locate the major-mode fhook-<id> macro and aborted.

0x02


If set, the major-mode has been successfully initialised and the fhook-<id> macro was located.

0x04


If set, the major-mode has an ftest-<id> macro, this macro will be invoked to resolve major-mode assignment conflicts based solely on the file extension. This bit is always clear until the hook has successfully initialised.

0x08


If set, the major-mode has a bhook-<id> macro, see $buffer-bhook(5). This bit is always clear until the hook has successfully initialised.

0x10


If set, the major-mode has an ehook-<id> macro, see $buffer-ehook(5). This bit is always clear until the hook has successfully initialised.

0x20


If set, the major-mode has a dhook-<id> macro, see $buffer-dhook(5). This bit is always clear until the hook has successfully initialised.

When major-mode is called with a numeric argument of 16, a special 'regex replace' style of id may be used, for example:

16 major-mode "\\1" -2 "-[*!]- *\\(\\m+\\).*?-[*!]-" 

In this form the id string must be a '\' character followed by a digit between 0 and 7 which must refer to a group within the cid-regex. When a match is found, the value of the group is compared with all major-mode content-id labels (cid-label) and if a match is found that mode is applied. This has the major advantage of being able to support all major-modes in a single regex search, greatly reducing the performance impact of content based identification.

NOTES

The major-mode has a very specific order of event execution which is defined in the following paragraphs:

The common major-modes must be defined first and this occurs in the main me.emf macro file, user and company created major-modes are typically defined in the user and company macro files. The definitions at this stage are minimal to enable MicroEmacs to start-up as quickly as possible, a single call to major-mode will usually suffice.

When the user loads a file MicroEmacs loops through all of the major-modes, in order, checking every defined content-id from the start of the first non-blank line of the loading file. If a match is found in the buffer then the major-mode is initialised (if not already initialised - see below) and assigned to the buffer.

If no content-id based match was found, MicroEmacs loops through all major-modes, in order, checking every defined extension list. If a match is found the major-mode is initialised, if required, and checked for the existence of a ftest-<id> macro. If the macro exists it is executed and the return status assessed, if there was no match then the buffer is assigned the major mode of the file extension. If the buffer content matches the ftest-<id> type the major-mode is immediately assigned and the search halted, otherwise the probability of the buffer being of that type is stored and the search is continued. If, by the end of the search, no definitive match has been found, the most likely major-mode is assigned, or the default major-mode where no match was found.

If a major-mode has been assigned, the major-modes $buffer-fhook(5) function (named fhook-<id>) is executed within the current buffer. The hook macros configure settings such as the hilighting, indentation schemes, buffer based binding and modes etc.

A major-mode is deemed initialised if the main fhook-<id> macro is defined, if it is not, MicroEmacs attempts to locate and execute the associated hook file, hk<id>.emf. If the file is not found or, having executed the file, the main fhook-<id> macro is still not defined the initialisation is considered failed and the major-mode becomes unusable.

Migration

In January 2026 the existing command add-file-hook was replaced with major-mode with the aim to consolidating the major-mode concept and improving compatibility with Emacs. As a result, all existing calls to add-file-hook need to be migrated to major-mode.

Calls to add-file-hook take one of two different forms:

File Extension Recognition


Calls without a numeric argument were used to bind a list of extensions to a file-hook macro. To migrate these definitions, first determine if the hook is a standard system hook by locating the hk<id>.emf file and if so whether the extensions are now supported by checking the relevant call to major-mode in the current me.emf. If the hook is a system one and all extensions are listed then the existing call to add-file-hook maybe removed.

If the hook is a system one but not all extensions are listed, replace the add-file-hook line with one like the following:

4 major-mode "<id>" "<combined-full-extension-list>" 

Where <id> is taken from the hook macro name which should have the form fhook-<id>. If it is not a system hook, replace the line with one like the following:

5 major-mode "<id>" "<extension-list>" 

If the hook file contains a user friendly name for the hook, e.g. contains a line like the following:

set-variable .fhook-<id>.name "<File-type-name>" 

Then remove this line from the hook file and change the call to major-mode to:

13 major-mode "<id>" "<extension-list>" "<File-type-name>" 

File Content Recognition


Calls with a numeric argument to add-file-hook were used to define a content based identifier, given in the form of a regex search pattern. Many of these content-IDs take the form of "-*- <id> -*-" or "-!- <id> -!-", these are generally no longer required as the new major-mode cid-label feature automatically performs the same function. If the label used in the content-ID is something other than <id> then the call to add-file-line can usually be replaced with:

3 major-mode "<id>" "<cid-label>" 

If this is not a system hook then this can be combined with an extension-based major-mode definition, i.e. a single call to major-mode like one of the following:

7  major-mode "<id>" "<cid-label>" "<extension-list>" 
15 major-mode "<id>" "<cid-label>" "<extension-list>" "<File-type-name>" 

However, if there is more than one label or the content-ID does not take this form then replace the call to add-file-hook with a line of the following form:

17 major-mode "<id>" n "<regex>" 

Where <id> is taken from the hook macro name which should have the form fhook-<id>, n is the numeric argument given and <regex> is the first argument given. Again, if this is not a system hook this line can be combined with the major-mode definition call unless there are more than one.

SEE ALSO

File Hooks, Language Templates, $buffer-major-mode(5), $buffer-fhook(5), define-macro-file(2).

(c) Copyright JASSPA 2026
Last Modified: 2026/02/17
Generated On: 2026/03/01