major-mode(2)

NAME

major-mode - Declare or set a buffer major mode
add-file-hook - Depreciated, update to 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 new major modes, the main 'type' of a buffer or file, such as C or HTML etc. The command can be used to configure or reconfigure the base properties of a major-mode, such as its supported extension list, and it can be used to change the major-mode of the current buffer.

When the major-mode of a buffer is assigned, the buffer's $buffer-major-mode(5) and $buffer-fhook(5) variables are assigned and the macro pointed to by the $buffer-fhook variable is executed, this macro, and the hook file it is defined in, are responsible for setting up features such as hilighting and indentation rules for the major-mode and ultimately for the buffer.

When no argument n is given to the command, major-mode prompts the user for the current buffer's new mode. If a new mode id is entered, the major-mode is immediately applied, if the buffer's current major-mode ID is given the command prints the full name of the current major-mode, its content label (if enabled) and the name of the hook file.

If a positive numeric argument n is given to the command the major-mode id must be given and the effect of the bits of the numeric argument are defined as follows:

0x01


When set the major-mode will be created if it does not already; an error is returned if the bit is clear and the given major-mode id does not exist.

0x02


When set the content-ID label of the major-mode is assigned the value of cid-label, if the value is an empty string (i.e. "") the feature is disabled. See the notes section below for more information on the use of the content-ID label. When this bit is clear the value remains unchanged unless this call is also creating the major-mode, in which case the cid-label is set to the same value as the id.

0x04


When set the file extensions associated with the major-mode is set to extension-list. The argument is a space separated list of file endings (as opposed to true extensions) and is 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 '/' character at the start of an extension can be used to force the match of the whole file name, for example the Unix info system often have directories with a 'dir' file, an extension-list value of ".info /dir" will match any file ending in .info and a file with the name dir. Similarly, if the extension starts with a '^' character the start of the file name is matched instead, the difference to '/' is that the file name only has to start with the extension. If extension-list is an empty string the feature is disable. If 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 concatenation when the extension-list is redefined, the full list of extensions must be give. Note also that the 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 this call is also creating the major-mode, in which case the name is set to the capitalised value of cid-label or id if not set. The name is uppercased 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, to be identified a file must have content within the first cid-line-count non-blank lines which matches the given cid-regex. If the given line count is positive the id regex search will be case sensitive, if negative the search is case insensitive and the count is negated. 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.

Optionally, when bit 0x01 is set a list of macro definitions ("macro1-name" "macro2-name" ...) can also be given, see Notes section below.

The order in which the major-modes are defined can be important when there is a conflict in assignment, for example, both C nd C++ can use the .h extension. Priority is given to the last defined major-mode, i.e. the first defined has the lowest priority, to ensure that any user created major-modes will have the highest priority. However, this order can be manipulated by simply redefining the major-mode if an argument of 1, i.e. adding the following line to the end of your 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 a bit based integer with the following flags:

0x01


If set, the 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's fhook-<id> macro and aborted.

0x02


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

0x04


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

0x08


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

0x10


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

0x20


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

Order of Events

The major-modes must be defined first, this typically happens in the main me.emf macro file, user and company created major-modes are typically defined in the user and company macro file. The definition at this stage is 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 major-modes, in order, checking every defined content-id from the start of the first non-blank line. If a match is in the buffer the major-mode is initialised if not already (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 does exists it is executed and the return assessed, if it does not exist the buffer is simply assumed to be of that type. If the buffer is found to be definitely of that 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, no definite match has been found, the most likely major-mode is assigned, or the default major-mode if no possible match was found.

If a major-mode has been assigned, the major-modes $buffer-fhook(5) function (anemd fhook-<id>) will be executed with the buffer current so that the hook macro can configure settings such as the hilighting & indentation schemes, buffer based binding and modes etc.

NOTES

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.

When major-mode is called with a numeric argument of 16, a special 'regex replace' style of id can 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.

Optionally major-mode can be given a list of macros, "macro1-name" etc., when bit 0x01 is set. These macros must be defined within the hook file hk<id>.emf, the command will define the macros in the same way as command define-macro-file(2). Only macros useful before a file of the given type is created or loaded should be defined as loading the hook will define all macros within it.

The numeric argument given when the $buffer-fhook macro is executed is a bit based flag where the bits have the following meaning:

0x01


When this bit is set the buffer is for a file that already exists, when clear the buffer is for a new file so the fhook should handle the insertion of any required file templates etc.

0x02


If this bit is set a file content hook was used to identify the file type and registry variable #l9 will be set to the matched magic string. This can be useful as the magic string often contains configuration values such as the tab and indent width.

Extending a standard hook definition

The standard file hook files hkXXX.emf should not be modified. The standard file hooks may be extended with local definitions by defining a file myXXX.emf, which is an extension to the hook file hkXXX.emf. This is automatically executed after hkXXX.emf. Refer to sections Language Templates and File Hooks for details.

File Extensions

The file extensions are specified as a space separated list of file name endings. Back-up file endings such as tilde (~) are not classed as correct file endings and are skipped by the file hook search, hence a file ending ".c~" invokes the same hook function as a ".c" file. It is therefore not necessary to add the backup and auto-save endings to the major mode definition.

The extension separator, usually dot (.), is typically added to the extensions list, they may be omitted with effect where a file always ends in the same set of characters. A notable example is "makefile" which includes no extension, as such, MicroEmacs applies the same hook function to a file called Imakefile as the endings are the same. This can be avoided by defining the extension as "/makefile" which only matches files whose whole name is "makefile".

Binary Files

It is sometimes useful to associate file types as binary files, so that they are immediately loaded in binary. In this case, both file extension and content recognition methods (i.e. of a magic string) are applicable. In both cases the file is bound to the well known hook fhook-binary which automatically loads the file in a binary mode.

Note, that for binary major-mode recognition, via extension or content-ID, the file must be loaded twice, initially in the default text mode, then it must be reloaded in binary mode once identified. For this reason it is better to load the file directly into binary mode using find-bfile(3) or find-hfile(3).

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 took 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. If migrating such a call, first determine if the hook is a standard system hook by locating the hk<id>.emf 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 call to add-file-hook can be 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 giving 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), $major-mode-ids(5), find-bfile(3), find-hfile(3), define-macro-file(2).

(c) Copyright JASSPA 2026
Last Modified: 2026/01/30
Generated On: 2026/01/31