Elisp: Major Mode Names
Quick Guide on Naming Your Major Mode
Here's a quick guide on how to name your own major mode.
First, think of a prefix name. Let's say “xx”.
- For ALL Symbols in your source code, they should start with “xx-”
- The file name should be “xx-mode.el”
- The command name to start the mode should be “xx-mode”
- The package's feature name should be “xx”. That is,
(provide 'xx)
.
Names Associated with Major Mode
There are several names associated with a major mode:
- The command name to start the mode (e.g.
dired
,emacs-lisp-mode
) - Buffer Local Variable major-mode.
- Buffer Local Variable mode-name.
- Feature name, e.g. the xx in
(provide 'xx)
and(require 'xx)
. - File name of the source code. e.g. “xx-mode.el”.
Value of Variable “major-mode”
major-mode is a built-in Buffer Local Variable .
This is most important.
This value is usually the same as the command name user types to activate the mode, but not always.
(e.g.
the command to invoke dired-mode
is dired
.)
- This variable is automatically set when you use
define-derived-mode
to define a major mode. Emacs use the first argument as the value. - Its value is a Lisp Symbol.
- This value is used to check what's current major mode by emacs lisp code. 〔see Emacs: Show Variable 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.
when you write a major mode, typically at the bottom you add:
(provide 'my-mode)
where my-mode is the command name to invoke the mode. (but technically it can be any)
A major mode package usually add one such feature name, but may be more, or none.
There is no technical relation between the feature name and the variable major-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:
- in html-mode, the value is “HTML”.
- In perl-mode, the value is “Perl”.
- In cperl-mode, the value is “CPerl”.
- In nxml-mode, the value “nXML”.
If you use define-derived-mode
, the 3rd arg will automatically be set as the mode-name. 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, you can have your mode named “xx-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 “xx-mode”, then the file can be “xx-mode.el”. This is how majority of major mode package's files are named.
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.
- Do not name it like “david-mode”, or “great-mode”, because user won't be able to tell what it is for.
- Do not name it generic like html-mode or ruby-mode, since a lot other lisp programers might also wrote those modes. Only modes distributed with GNU Emacs might want to use such a generic name.
Here are some example names from existing modes for consideration:
- For Perl, there are modes named perl-mode, cperl-mode.
- For XML, there are modes named xml-mode and nxml-mode.
- For HTML, there are html-mode, html-helper-mode, nxhtml-mode.
- For JavaScript: javascript-mode, js-mode, js2-mode, espresso-mode.
- For IRC, there are rcirc-mode, erc-mode.
- For email, there's rmail, vm, gnus.
If you are out of ideas, you can simply name it with your name plus the language's name, such as “dv-html-mode”.
emacs package system
Emacs lisp, writing a major mode. Essentials
- Elisp: Write a Major Mode for Syntax Coloring
- Elisp: Font Lock Mode
- Elisp: Syntax Color Comments
- Elisp: Write Comment/Uncomment Command
- Elisp: Keyword Completion
- Elisp: Create Keymap (keybinding)
- Elisp: Create Function Templates
- Elisp: Command to Lookup Doc
- Elisp: Create a Hook
- Elisp: Major Mode Names
- Elisp: provide, require, features
- Elisp: load, load-file, autoload
- Elisp: Syntax Table