Emacs Lisp: How to Name Your Major Mode

By Xah Lee. Date: . Last updated: .

This page is a tutorial on how to name your own major mode.

First, here's a quick summary.

There are several names associated with a major mode:

Here's a quick guide.

First, think of a prefix name. Let's say “mymath” for a math oriented programing language.

  1. For ALL symbols in your source code (that is, variable names and function names), they should start with “mymath-”
  2. The file name should be “mymath-mode.el”
  3. The command name to invoke the mode should be “mymath-mode”
  4. The package's feature name should be “mymath”. That is, (provide 'mymath).

If you follow the above guide, it'd be much easier to submit your package to package repo such as MELPA. 〔►see Emacs: How to Install Packages Using ELPA, MELPA

Value of Variable “major-mode”

major-mode is a built-in buffer local variable.

For example, call describe-variable then type “major-mode”, and emacs will show the variable's value of the current buffer's major mode.

This variable is the most important, technical, name for a major mode. This value is usually the same as the command name user types to activate the mode, but not always. (for example, the command to invoke dired-mode is dired.)

This variable is automatically set when you use define-derived-mode. Emacs will use the first argument as the value.

Value of Feature Name

This is also a important technical name. Feature symbol is most similar to other language's package/module name for import/load.

See: Emacs Lisp: What's “feature”?

Choosing Your Mode's Name

When choosing a name, try to come up with a name so that user can tell what it is for, but also unique from other modes for the same language. For example, if your mode is for HTML, you don't want just name it html-mode, because many other people probably have created a mode of the same name, causing confusion and name conflict.

Here are some example names from existing modes for consideration:

If you are out of ideas, you can simply name it with your name plus the language's name, such as “dv-html-mode”.

Prefix Mode Name to All Names

Emacs lisp does not have namespace. Basically, all variables and functions are all in a global namespace, stored in the variable obarray.

The symbols in your package should have unique names to avoid multiple packages having the same name that can override each other. The conventional practice is that all your symbol's names in your mode should be prefixed by your mode name, or a abbreviation of your mode name.

This is also important reason that you should choose a unique name for your mode.

For example, if you look at the source code of cperl-mode, all their names starts with “cperl-”. For python-mode, all names starts with “python-”.

Value of Variable “mode-name”

mode-name is a built-in buffer local variable. When in a major mode, the value of the variable mode-name is displayed in the status bar (the “mode line”). This name is intended to be human friendly indication of what language they are working with.

For example:

If you use define-derived-mode, the 3rd arg will automatically be set as the mode-name.

(define-derived-mode dv-html-mode fundamental-mode "dvHTML"
  …
)

Else, you can set it yourself. (setq mode-name "HTML")

The Elisp File Name

Emacs and Elisp does not enforce a relation of your mode's name and the file name. For example, your can have your mode named “mymath-mode”, while the file name can be “math_mode_by_David.el” or “math_mode_v1.4.el”.

Normally, you just name your file the same as the value of the variable major-mode defined in your package. So, for example, if you have “mymath-mode”, then the file can be “mymath-mode.el”. This is how majority of major mode package's files are named.

Elisp file's name can be a little flexible. A version number in the file name is common. If your package has more than one file, you can name them anything appropriate to the file's purpose.

What's the difference between library, package, features? And what's the difference between load-file, load, require, autoload?

See: Emacs Lisp's Library System.

Like it? Buy Xah Emacs Tutorial. Thanks.

or, buy something from Best Keyboard for Emacs