|
DataMuseum.dkPresents historical artifacts from the history of: DKUUG/EUUG Conference tapes |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about DKUUG/EUUG Conference tapes Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - metrics - downloadIndex: T l
Length: 51302 (0xc866)
Types: TextFile
Names: »lispref-10«
└─⟦a05ed705a⟧ Bits:30007078 DKUUG GNU 2/12/89
└─⟦c06c473ab⟧ »./UNRELEASED/lispref.tar.Z«
└─⟦1b57a2ffe⟧
└─⟦this⟧ »lispref-10«
Info file: lispref, -*-Text-*-
produced by texinfo-format-buffer
from file: lispref.texinfo
This file documents GNU Emacs Lisp.
This is Edition 0.1 Beta of the GNU Emacs Lisp Reference Manual, for
Emacs Version 18, with some references to Emacs Version 19.
Please read this document for review purposes.
Published by the Free Software Foundation, 675 Massachusetts Avenue,
Cambridge, MA 02139 USA
Copyright (C) 1989 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Foundation.
▶1f◀
File: lispref Node: Changing Key Bindings, Prev: Global and Local Keymaps, Up: Keymaps
Changing Key Bindings
=====================
The way to rebind a key is to change its binding in a keymap. You can
change the global keymap, in which case the change is effective in all
buffers (except those that have their own overriding local definitions
for the same key). Or you can change the current buffer's local map,
which usually affects the local keymap for all buffers using the same
major mode. In addition, you can change bindings in any map that you
can access.
The `global-set-key' and `local-set-key' functions are easiest to use.
People often use `global-set-key' in their `.emacs' file for simple
customization.
``(global-set-key KEY CMD)''
Defines KEY globally to run CMD.
``(local-set-key KEY CMD)''
Defines KEY locally (in the major mode now in effect) to run CMD.
For example,
(global-set-key "\C-x\C-\\" 'next-line)
redefines `C-x C-\' to move down a line.
A special read syntax is provided to represent control and meta
characters (*Note String Type::). In a string, the syntax `\C-' means
that the following character is a control character and `\M-' means that
the following character is a META character. Thus, the string `"\M-x"'
is read as `M-x', `"\C-f"' is read as `C-f', and `"\M-\C-x"' and
`"\C-\M-x"' are both read as `C-M-x'.
However, the most general way to modify a keymap is to use the
`define-key' function. `define-key' takes three arguments: the keymap,
the key to modify in it, and the new definition. (`global-set-key' is
equivalent to `define-key' with `current-global-map' as its first
argument.)
For the functions below, it is an error if an argument named KEYMAP is
not a keymap or if an argument named KEY is not a string representing
characters to be typed.
* Function: define-key KEYMAP KEY DEFINITION
This function adds a binding for KEY in KEYMAP. If KEY is more
than one character long, the change is actually made in another
keymap reached from KEYMAP. The DEFINITION can be any Lisp object,
but only certain types are meaningful. (To see a list of these
objects, *Note Key Lookup::.) The value returned by `define-key'
is DEFINITION.
Every prefix of KEY must be a prefix key (i.e., bound to a
keymap) or undefined; otherwise an error is signalled (with data
`(error "Key sequence KEY uses invalid prefix characters")'). If
some prefix of KEY is undefined, then DEFINE-KEY automatically
defines it as a prefix key so that the rest of KEY may be defined
as specified.
In the following example, a sparse keymap is created and a number
of bindings are added to it.
(setq map (make-sparse-keymap))
=> (keymap)
(define-key map "\C-f" 'forward-char)
=> forward-char
map
=> (keymap (6 . forward-char))
;; Build sparse map for `C-x' and bind `f' in that.
(define-key map "\C-xf" 'forward-word)
=> forward-word
map
=> (keymap
(24 keymap ; `C-x'
(102 . forward-word)) ; `f'
(6 . forward-char)) ; `C-f'
;; Bind `C-p' to the `ctl-x-map'.
(define-key map "\C-p" ctl-x-map)
=> [nil ... find-file ... backward-kill-sentence] ; `ctl-x-map'
;; Bind `C-f' to `foo' in the `ctl-x-map'.
(define-key map "\C-p\C-f" 'foo)
=> 'foo
map
=> (keymap ; Note `foo' in `ctl-x-map'.
(16 . [nil ... foo ... backward-kill-sentence])
(24 keymap
(102 . forward-word))
(6 . forward-char))
In this example, `C-x C-f' has been changed in the default global
map as a result of this change in `ctl-x-map'.
Note also that typing `C-p C-f' will execute the function `foo'
as will `C-x C-f', since `ctl-x-map' was changed.
* Command: global-set-key KEY DEFINITION
This function gives KEY a definition of DEFINITION in the global
keymap.
(global-set-key KEY DEFINITION)
==
(define-key (current-global-map) KEY DEFINITION)
* Command: global-unset-key KEY
This function removes the definition of KEY from the current
global map. One use of this function is to unset a key so that a
longer key may use the first key as a prefix---which would not be
allowed otherwise.
(global-unset-key KEY)
==
(define-key (current-global-map) KEY nil)
For example:
(global-unset-key "\C-l")
=> nil
(global-set-key "\C-l\C-l" 'redraw-display)
=> nil
* Command: local-set-key KEY DEFINITION
This function gives KEY a definition of DEFINITION in the local
keymap.
(local-set-key KEY DEFINITION)
==
(define-key (current-local-map) KEY DEFINITION)
* Command: local-unset-key KEY
This function removes the definition of KEY from the current
local map.
(local-unset-key KEY)
==
(define-key (current-local-map) KEY nil)
* Function: substitute-key-definition OLDDEF NEWDEF KEYMAP
This function replaces OLDDEF with NEWDEF for any keys in KEYMAP
that were bound to OLDDEF. In other words, OLDDEF is replaced with
NEWDEF wherever it appears.
It returns `nil'.
Prefix keymaps that appear within KEYMAP are not checked
recursively for keys bound to OLDDEF; they are not changed at all.
Perhaps they ought to be checked recursively.
(setq map '(keymap
(?1 . olddef-1)
(?2 . olddef-2)
(?3 . olddef-1)))
=> (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
(substitute-key-definition 'olddef-1 'newdef map)
=> nil
map
=> (keymap (49 . newdef) (50 . olddef-2) (51 . newdef))
;; The following will redefine `C-x C-f', if you do it in an
;; Emacs with standard bindings.
(substitute-key-definition
'find-file 'find-file-read-only (current-global-map))
* Function: suppress-keymap KEYMAP &optional NODIGITS
This function changes the contents of the full keymap KEYMAP by
replacing the self insertion commands for numbers with the
`digit-argument' function, unless NODIGITS is non-`nil', and by
replacing the functions for the rest of the printing characters
with `undefined'. This means that you are unable to type text into
a buffer after calling `suppress-keymap'.
The function returns `nil'.
Since this function does change KEYMAP, you probably wish to use
it either with a new keymap or with a copy of a keymap, and use the
modified map locally. Suppressing `global-map' would make it
impossible to use most of Emacs.
In `emacs/lisp/dired.el', for example, a keymap is made for Dired
mode. The beginning of the `define-key' sequence looks like this:
...
(setq dired-mode-map (make-keymap))
(suppress-keymap dired-mode-map)
(define-key dired-mode-map "r" 'dired-rename-file)
(define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
(define-key dired-mode-map "d" 'dired-flag-file-deleted)
(define-key dired-mode-map "v" 'dired-view-file)
(define-key dired-mode-map "e" 'dired-find-file)
(define-key dired-mode-map "f" 'dired-find-file)
...
The `suppress-keymap' function does not make it impossible to
modify a buffer, as it does not suppress commands such as `yank'
and `quote-insert'. (To prevent any modification of a buffer, make
it read-only. (*Note Read Only Buffers::.)
The `suppress-keymap' function changes a keymap by replacing the
self insertion commands for numbers with the `digit-argument'
function and by replacing the functions for the rest of the
printing characters with `undefined'.
In the following illustration, the first three lines containing
`self-insert-command' represent the ten digits. The following line
represents all of the other printing characters. The
`suppress-keymap' function replaces the `self-insert-command'
function with `digit-argument' and `undefined'.
(setq map (copy-keymap (current-global-map)))
=> [set-mark-command ... ; `C-a'
self-insert-command ... ; SPC
self-insert-command ; 0
self-insert-command ; 1
self-insert-command ... ; 2
self-insert-command ... ; other printing characters
delete-backward-char] ; DEL
(suppress-keymap map)
=> nil
map
=> [set-mark-command ... ; `C-a'
undefined ... ; SPC
digit-argument ; 0
digit-argument ; 1
digit-argument ... ; 2
undefined ; what were
undefined ... ; other printing characters
delete-backward-char] ; DEL
▶1f◀
File: lispref Node: Major and Minor Modes, Prev: Keymaps, Up: Top, Next: Documentation
Major and Minor Modes
*********************
A "mode" is a set of definitions which customize Emacs for editing
text of a particular sort. There are two varieties of modes: the major
modes, which are used for specialized editing tasks; and minor modes,
which provide features that several different major modes may use.
This chapter covers major and minor modes, the `mode-line-format', and
hooks. Other related topics such as keymaps and syntax tables are
covered in separate chapters. (*Note Keymaps::, and *Note Syntax
Tables::.)
* Menu:
* Major Modes::
* Minor Modes::
* Mode Line Format::
* Hooks::
▶1f◀
File: lispref Node: Major Modes, Prev: Major and Minor Modes, Up: Major and Minor Modes, Next: Minor Modes
Major Modes
===========
The major modes are mutually exclusive; each buffer has only one major
mode at a time. The least specialized major mode is called "Fundamental
mode". This mode has no mode-specific definitions or variable settings,
so each Emacs command behaves in its default manner, and each option is
in its default state. In contrast, Lisp Interaction mode provides
special key bindings for LFD (`eval-print-last-sexp'), TAB
(`lisp-indent-line'), and other keys.
When you need to write large quantities of code to help you perform a
specialized editing task, you are likely to want to create a new major
mode. By writing a new major mode, rather than adding to an existing
mode, you avoid having the one mode do double duty, and you thereby
avoid making the code, and its use, confusing. Also, in practice,
writing a major mode is often simple (this is a sharp contrast to
writing a minor mode, which is often complicated).
For example, Rmail Edit mode, which is in `emacs/lisp/rmailedit.el',
is a major mode that is very similar to Text mode except that it
provides three additional commands.
The additions to Rmail Edit mode are so small that you might not think
to use a major mode for such a job; instead, you might think to use a
recursive edit. But recursive edits don't change any commands, and so
are not useful. In a few circumstances, a recursive edit might be an
alternative to temporarily changing a buffer to a different mode; but
recursive edits are confusing to the user and should only be used when
there is no alternative, as in the Emacs debugger. For mail editing, a
major mode is better.
The standard GNU Emacs `lisp' library contains the code for several
major modes, including `text-mode.el', `texinfo.el', `lisp-mode.el',
`c-mode.el', and `rmail.el'. You can look at these libraries to see how
modes are written. Text mode is perhaps the simplest major mode,
besides Fundamental mode. Rmail mode is a rather complicated,
full-featured mode.
* Menu:
* Major Mode Conventions:: Coding conventions for keymaps, etc.
* Major Mode Examples:: Text mode and Lisp modes.
* Setting the Major Mode:: Selecting the right mode for a buffer.
* Mode Help:: Finding out how to use a mode.
* Major Line Information:: What is on the mode line.
▶1f◀
File: lispref Node: Major Mode Conventions, Prev: Major Modes, Up: Major Modes, Next: Major Mode Examples
Major Mode Conventions
----------------------
The code for existing major modes follows various coding conventions,
including conventions for local keymap and syntax table initialization,
global names, and hooks. When you create a new major mode, please keep
these conventions in mind.
* An apparently trivial, yet important convention is that a user
should be able to initialize a new major mode with a command that
has a `-mode' suffix to its name. You may also create other ways
to enter the mode, but you should have one function that can be
called to initialize the keymap, syntax table, and local variables
in an existing buffer without changing the buffer's text. In
addition, the documentation string for this function is what
`describe-mode' should use.
* This major mode function should include documentation that is
displayed by typing `C-h m' (`describe-mode').
The documentation string may include the special documentation
substrings, `\[COMMAND]', `\{KEYMAP}', and `\<KEYMAP>', that permit
you to change the values of keymaps without having to update the
documentation string. When the `describe-mode' function sees these
special documentation substrings, Emacs reads their current values.
(*Note Documentation Strings::.)
* The major mode function should set the variable `major-mode' to the
major mode function symbol. This is how `describe-mode' discovers
which documentation to print.
* The major mode function should set the variable `mode-name' to the
``pretty'' name of the mode, as a string. This appears in the mode
line.
* Since all global names are in the same name space, you should take
care to prefix the names of all global variables, constants, and
functions with the major mode name (or with an abbreviation of it
if the name is long).
* Each major mode typically has its own keymap, which is used as the
local keymap in all buffers in that mode. The major mode function
should just call `use-local-map' with the keymap variable. *Note
Global and Local Keymaps::, for more information.
This keymap should be kept in a global variable named
`MODENAME-mode-map'. This variable is usually set up when the
library that defines the mode is loaded.
Use `defvar' to set the variable, so that it is not reinitialized
if it already has a value. Such reinitialization could discard
customizations made by the user.
* It is good practice to use both a syntax table variable and an
abbrev table variable. The reasons for this are the same as for
using a keymap variable. You can use the tables of a related mode,
if they serve without change.
* To give variables a buffer-local binding, you should use
`make-local-variable' in the major mode function rather than
`make-variable-buffer-local'. The `make-local-variable' function
makes a variable local to just the current buffer; while the
`make-variable-buffer-local' function makes a variable local to
*every* buffer, even ones that are created later. Use of
`make-local-variable' has fewer unexpected consequences. (*Note
Buffer Local Variables::.)
* If hooks are appropriate for the mode, the major mode function
should run the hooks after completing all other initialization so
the user may further customize any of the settings.
* If this mode is appropriate only for text specially made by Emacs,
then the major mode command symbol should have a property named
`mode-class' with value `special', put on as follows:
(put funny-mode 'mode-class 'special)
This tells Emacs that new buffers created while a buffer in Funny
mode is current should not inherit Funny mode. Modes such as
Dired, Rmail, and Buffer List use this feature.
* The top level forms in the mode library should be written in such a
manner that they may be evaluated more than once without adverse
consequences. Even if you never load your library more than once,
someone else will.
* In the documentation, you should provide an example `autoload' form
and an example `auto-mode-alist' addition that users can include in
their `.emacs' files.
▶1f◀
File: lispref Node: Major Mode Examples, Prev: Major Mode Conventions, Up: Major Modes, Next: Setting the Major Mode
Major Mode Examples
-------------------
Text mode is perhaps the simplest mode besides Fundamental mode. Here
are excepts from `text-mode.el' that illustrate many of the conventions
listed above:
;; Create mode-specific tables.
(defvar text-mode-syntax-table nil
"Syntax table used while in text mode.")
(if text-mode-syntax-table
() ; Do not change the table if it is already set.
(setq text-mode-syntax-table (make-syntax-table))
(set-syntax-table text-mode-syntax-table)
(modify-syntax-entry ?\" ". " text-mode-syntax-table)
(modify-syntax-entry ?\\ ". " text-mode-syntax-table)
(modify-syntax-entry ?' "w " text-mode-syntax-table))
(defvar text-mode-abbrev-table nil
"Abbrev table used while in text mode.")
(define-abbrev-table 'text-mode-abbrev-table ())
(defvar text-mode-map nil "") ; Create a mode-specific keymap.
(if text-mode-map
() ; Do not change the keymap if it is already set.
(setq text-mode-map (make-sparse-keymap))
(define-key text-mode-map "\t" 'tab-to-tab-stop)
(define-key text-mode-map "\es" 'center-line)
(define-key text-mode-map "\eS" 'center-paragraph))
Here is the complete major mode function definition for Text mode:
(defun text-mode ()
"Major mode for editing text intended for humans to read.
Special commands: \\{text-mode-map}
Turning on text-mode calls the value of the variable text-mode-hook,
if that value is non-nil."
(interactive)
(kill-all-local-variables)
(use-local-map text-mode-map) ; This provides the local keymap.
(setq mode-name "Text") ; This name goes into the mode line.
(setq major-mode 'text-mode) ; This is how `describe-mode'
; finds out what to describe.
(setq local-abbrev-table text-mode-abbrev-table)
(set-syntax-table text-mode-syntax-table)
(run-hooks 'text-mode-hook)) ; Finally, this permits the user to
; customize the mode with a hook.
Each of the three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
Interaction mode) have more features than Text mode and the code is
correspondingly more complicated. Here are excerpts from `lisp-mode.el'
that illustrate how these modes are written.
;; Create mode-specific table variables.
(defvar lisp-mode-syntax-table nil "")
(defvar emacs-lisp-mode-syntax-table nil "")
(defvar lisp-mode-abbrev-table nil "")
(if (not emacs-lisp-mode-syntax-table) ; Do not change the table
; if it is already set.
(let ((i 0))
(setq emacs-lisp-mode-syntax-table (make-syntax-table))
;; Set syntax of chars up to 0 to class of chars that are
;; part of symbol names but not words.
;; (The number 0 is `48' in the ASCII character set.)
(while (< i ?0)
(modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
(setq i (1+ i)))
...
;; Set the syntax for other characters.
(modify-syntax-entry ? " " emacs-lisp-mode-syntax-table)
(modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table)
...
(modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table)
(modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table)
...
))
;; Create an abbrev table for lisp-mode.
(define-abbrev-table 'lisp-mode-abbrev-table ())
Much code is shared among the three Lisp modes; the code is all in one
library. Here is one function that sets various variables. This
function is called by each of the major Lisp mode functions.
(defun lisp-mode-variables (lisp-syntax)
;; The `lisp-syntax' argument is `nil' in Emacs Lisp mode,
;; and `t' in the other two Lisp modes.
(cond (lisp-syntax
(if (not lisp-mode-syntax-table)
;; The Emacs Lisp mode syntax table always exists, but
;; the Lisp Mode syntax table is created the first time a
;; mode that needs it is called. This is to save space.
(progn (setq lisp-mode-syntax-table
(copy-syntax-table emacs-lisp-mode-syntax-table))
;; Change some entries for Lisp mode.
(modify-syntax-entry ?\| "\" "
lisp-mode-syntax-table)
(modify-syntax-entry ?\[ "_ "
lisp-mode-syntax-table)
(modify-syntax-entry ?\] "_ "
lisp-mode-syntax-table)))
(set-syntax-table lisp-mode-syntax-table)))
(setq local-abbrev-table lisp-mode-abbrev-table)
...
...
Functions such as `forward-word' use the value of the
`paragraph-start' variable. Since Lisp code is different from ordinary
text, the `paragraph-start' variable needs to be set specially to handle
Lisp. Also, comments are indented in a special fashion in Lisp and the
Lisp modes need their own mode-specific `comment-indent-hook'. The code
to set these variables is the rest of `lisp-mode-variables'.
(make-local-variable 'paragraph-start)
(setq paragraph-start (concat "^$\\|" page-delimiter))
...
(make-local-variable 'comment-indent-hook)
(setq comment-indent-hook 'lisp-comment-indent))
Each of the different Lisp modes has a slightly different keymap. For
example, Lisp mode binds `C-c C-l' to `run-lisp', but the other Lisp
modes do not. However, all Lisp modes have some commands in common.
The following function adds these common commands to a given keymap.
(defun lisp-mode-commands (map)
(define-key map "\e\C-q" 'indent-sexp)
(define-key map "\177" 'backward-delete-char-untabify)
(define-key map "\t" 'lisp-indent-line))
Here is an example of using `lisp-mode-commands' to initialize a
keymap, as part of the code for Emacs Lisp mode.
First, `defvar' is used to create a mode-specific keymap variable if
one does not exist. Then an `if' expression tests whether the
`emacs-lisp-mode-map' variable has a value. If the variable does have a
value, the expression does not change it. This protects the else part
of the `if' expression against duplicate evaluation; and it lets the
user customize the keymap if he or she so wishes. But if the
`emacs-lisp-mode-map' variable lacks a value, the expression creates a
sparse keymap and defines some keys.
(defvar emacs-lisp-mode-map () "")
(if emacs-lisp-mode-map
()
(setq emacs-lisp-mode-map (make-sparse-keymap))
(define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
(lisp-mode-commands emacs-lisp-mode-map))
Finally, here is the complete major mode function definition for Emacs
Lisp mode.
(defun emacs-lisp-mode ()
"Major mode for editing Lisp code to run in Emacs.
Commands:
Delete converts tabs to spaces as it moves back.
Blank lines separate paragraphs. Semicolons start comments.
\\{emacs-lisp-mode-map}
Entry to this mode calls the value of emacs-lisp-mode-hook
if that value is non-nil."
(interactive)
(kill-all-local-variables)
(use-local-map emacs-lisp-mode-map) ; This provides the local keymap.
(set-syntax-table emacs-lisp-mode-syntax-table)
(setq major-mode 'emacs-lisp-mode) ; This is how `describe-mode'
; finds out what to describe.
(setq mode-name "Emacs-Lisp") ; This goes into the mode line.
(lisp-mode-variables nil) ; This define various variables.
(run-hooks 'emacs-lisp-mode-hook)) ; This permits the user to use a
; hook to customize the mode.
▶1f◀
File: lispref Node: Setting the Major Mode, Prev: Major Mode Examples, Up: Major Modes, Next: Mode Help
Setting the Major Mode
----------------------
Based on information in the file name or in the file itself, Emacs
automatically selects a major mode for a buffer.
* Command: fundamental-mode
Fundamental mode is a major mode that not specialized for
anything in particular. Other major modes are defined by
comparison with this one. The `fundamental-mode' function does
*not* run any hooks, so it is not readily customizable.
* Function: set-auto-mode
This function selects the major mode that is appropriate for the
current buffer. It may base its decision on the value of the `-*-'
line, on the visited file name (using `auto-mode-alist'), or on the
value of a local variable. *Note How Major Modes are Chosen:
(emacs)Choosing Modes).
However, this function does not look for the `mode:' local
variable near the end of a file. The `hack-local-variables'
function does that.
* Command: normal-mode &optional FIND-FILE
This function automatically chooses the major mode for the
current buffer. The mode is determined by first calling
`set-auto-mode'. After calling the major mode function selected by
`set-auto-mode', the `normal-mode' function then runs
`hack-local-variables' to parse, and bind or evaluate as
appropriate, any local variables.
If the FIND-FILE argument to `normal-mode' is non-`nil', Emacs
assumes that the `find-file' function is calling `normal-mode'. In
this case, if `inhibit-local-variables' is non-`nil', Emacs
requires confirmation before processing a local variables list. If
you run `normal-mode' yourself, the argument `find-file' is `nil',
so confirmation is never requested.
`normal-mode' uses `condition-case' around the call to the major
mode function, so errors are caught and reported as a `File mode
specification error', followed by the original error message.
* User Option: default-major-mode
This variable holds the default major mode for new buffers. The
standard value is `fundamental-mode'. If the value of
`default-major-mode' is `nil', Emacs uses the (previously) current
buffer's major mode for major mode of a new buffer.
* Variable: auto-mode-alist
This variable contains an association list of filename patterns
(regular expressions) and corresponding major mode functions.
Usually, the filename patterns are suffixes, such as `.el' and
`.c', but this need not be the case. Each element of the alist
looks like `(REGEXP . MODE-FUNCTION)'.
For example,
("^/tmp/fol/" . text-mode)
("\\.texinfo$" . texinfo-mode)
("\\.el$" . emacs-lisp-mode)
("\\.c$" . c-mode)
("\\.h$" . c-mode)
When you visit a file whose *full* path name matches REGEXP,
Emacs calls MODE-FUNCTION. This feature is used to cause Emacs to
select the major mode appropriate to the file.
Here is an example of how to prepend several pattern pairs to an
existing `auto-mode-alist'. (You might use this sort of expression
in your `.emacs' file to customize your `auto-mode-alist'.)
(setq auto-mode-alist
(append
'(("/\\.[^/]*$" . fundamental-mode) ; Filename starts with a dot.
("[^\\./]*$" . fundamental-mode) ; Filename has no dot.
("\\.C$" . c++-mode))
auto-mode-alist))
* Function: hack-local-variables &optional FORCE
This function parses, and binds or evaluates as appropriate, any
local variables for the current buffer. If non-`nil', the optional
argument FORCE overides the effect of a non-`nil' value for
`inhibit-local-variables'. *Note Local Variables in Files:
(emacs)File variables, for the syntax of the `hack-local-variables'
section of a file.
* User Option: inhibit-local-variables
When this variable is non-`nil', Emacs will query the user before
obeying a file's local-variables list. Emacs checks this variable
when the local-variables list is scanned automatically after you
find a file. However, if you yourself call `normal-mode', there is
no query, regardless of the value of this variable.
* Variable: initial-major-mode
The value of this variable determines the major mode of the
initial `*scratch*' buffer. The value of the variable is a symbol,
the name of the mode. The default value is
`lisp-interaction-mode'.
▶1f◀
File: lispref Node: Mode Help, Prev: Setting the Major Mode, Up: Major Modes, Next: Major Line Information
Getting Help about a Major Mode
-------------------------------
The `describe-mode' function is used to provide information about
major modes. It is normally called with `C-h m'. The `describe-mode'
function uses the value of `major-mode', which is why every major mode
function needs to set the `major-mode' variable.
* Command: describe-mode
This function displays the documentation of current major mode.
The `describe-mode' function calls the `documentation' function
using the value of `major-mode' as an argument. Thus, it displays
the documentation string of the major mode function. (*Note
Documentation Strings::.)
* Variable: major-mode
This variable holds the symbol for the current buffer's major
mode. This symbol should be the name of the function which is
called to initialize the mode. The `describe-mode' function uses
the documentation string of this symbol as the documentation of the
major mode.
▶1f◀
File: lispref Node: Major Line Information, Prev: Mode Help, Up: Major Modes
Information from the Mode Line
------------------------------
The normal mode line contains a considerable amount of information:
whether the buffer is modified, its name, the names of the major and
minor modes, and the percentage of the buffer scrolled off the top.
* Variable: mode-line-modified
This variable holds the mode-line control for displaying whether
the current buffer is modified.
The default value `mode-line-modified' is `("--%1*%1*-")'. This
means that the mode line displays `--**-' if the buffer is
modified, `-----' if the buffer is not modified, and `--%%-' if the
buffer is read only.
Changing this variable does not force an update of the mode line.
* Variable: mode-line-buffer-identification
This variable identifies the buffer being displayed. Its default
value is `Emacs: %17b', which means that it also causes the mode
line to display `Emacs'. You may want to change this, when you
write modes that do not behave like a `normal' Emacs.
* Variable: mode-name
This buffer-local variable holds the ``pretty'' name of the
current buffer's major mode. This string is displayed in the mode
line of the buffer, if `mode-line-format' includes `mode-name'.
This is why every major mode function needs to set the `mode-name'
variable.
* Variable: global-mode-string
This variable holds a string that is displayed in the mode line
if the variable is included in `mode-line-format' (the default) or
if a `%M' specification is included. Currently, only
`display-time' modifies `global-mode-string'.
There are several other mode-line related variables in addition to
those listed here. These other variables are `mode-line-process',
`mode-line-inverse-video', and `minor-mode-alist'.
For `mode-line-process', *Note Process Information::; for
`mode-line-inverse-video', *Note Screen Attributes::; and for
`minor-mode-alist', *Note Minor Modes::.
▶1f◀
File: lispref Node: Minor Modes, Prev: Major Modes, Up: Major and Minor Modes, Next: Mode Line Format
Minor Modes
===========
A "minor mode" provides features that users may enable or disable
independently of the choice of major mode. Minor modes can be enabled
individually or in combination.
A minor mode is not merely a modification of single major mode. For
example, you may use `auto-fill-mode' and `auto-justify-mode' in any
major mode that permits text insertion.
Minor modes would be better named `Generally available, optional
feature modes' except that such a name is unwieldy.
A minor mode is often much more difficult to implement than a major
mode. There are several reasons for this. One is that you should be
able to deactivate a minor mode and restore the environment of the major
mode to the state it was in before the minor mode was activated.
Often, in implementing a minor mode, the biggest problem is finding a
way to insert the necessary hook into the running system. For example,
some minor modes, such as Auto Fill mode, change how text is inserted
into a buffer. Without `auto-fill-hook', Auto Fill mode would be
implemented only at great pain and great cost in editing efficiency.
* Menu:
* Minor Mode Conventions:: Tips for writing a minor mode.
* Minor Mode Status:: Emacs tries to select the right mode.
* Minor Mode Difficulties:: It is hard to write a minor mode.
▶1f◀
File: lispref Node: Minor Mode Conventions, Prev: Minor Modes, Up: Minor Modes, Next: Minor Mode Status
Conventions for Writing Minor Modes
-----------------------------------
There are conventions for writing minor modes just as there are for
major modes. Several of the major mode conventions apply to minor modes
as well: those regarding the name of the mode initialization function,
the names of global symbols, and the use of keymaps and other tables.
In addition, there are several conventions that are specific to minor
modes.
* A minor mode initialization function should toggle the mode on and
off with each call, or turn the mode on if given a positive
integer.
* The minor mode function should set a variable with the same name as
the minor mode to a non-`nil' value. This variable is used in
conjunction with the `minor-mode-alist' to display the minor mode
name in the mode line.
* A two element list needs to be constructed, the first element of
which is the minor mode variable and the second element of which is
a short string name for the minor mode. This two list must be
added to the `minor-mode-alist'. (*Note Minor Mode Status::.)
* If the minor mode adds new keybindings to the local keymap, you
should be able to restore the keymap to its original value when you
deactivate the minor mode.
▶1f◀
File: lispref Node: Minor Mode Status, Prev: Minor Mode Conventions, Up: Minor Modes, Next: Minor Mode Difficulties
Minor Mode Status Display
-------------------------
Since minor modes can be enabled independently, it is nice to see
which ones are enabled in each buffer.
* Variable: minor-mode-alist
This variable holds an association list the elements of which
specify how Emacs should indicate in the mode line that a minor
mode is active. The usual procedure is to print a short name for
the mode when it is active.
Each element of the `minor-mode-alist' looks consists of the two
element list:
(MINOR-MODE-VARIABLE MODE-LINE-STRING)
MODE-LINE-STRING is included in the mode line when the value of
MINOR-MODE-VARIABLE is non-`nil' and not otherwise.
Conventionally, the MINOR-MODE-VARIABLE for a specific mode is set
to a non-`nil' value when that minor mode is activated.
The default value of `minor-mode-alist' looks like this:
minor-mode-alist
=> ((abbrev-mode " Abbrev")
(overwrite-mode " Ovwrt")
(auto-fill-hook " Fill")
(defining-kbd-macro " Def"))
(Note that in version 19, `auto-fill-hook' has been renamed
`auto-fill-function'. Also, note the space at the beginning of
each MODE-LINE-STRING.)
`minor-mode-alist' should not be made buffer-local. The
variables in the alist should be buffer-local if the minor mdoe is
enableable separately in each buffer.
Here is an example of a safe way to augment the alist when you
load a package or activate a minor mode; it avoids adding the
element more than once.
(or (assq 'leif-mode minor-mode-alist)
(setq minor-mode-alist
(cons '(leif-mode " Leif") minor-mode-alist)))
▶1f◀
File: lispref Node: Minor Mode Difficulties, Prev: Minor Mode Status, Up: Minor Modes
Difficulties Writing a Minor Mode
---------------------------------
It is very difficult to write a minor mode that responds to arbitrary
self-insert characters. The principal problem is that
`self-insert-command', the primitive to insert the last key typed, is a
primitive function written in C. It does not call any hooks, except in
special cases.
Unfortunately, you cannot simply substitute your own definition of
`self-insert-command' for the existing one, as you can with most
functions. This is a consequence of the way Emacs's command loop works:
in the command loop, Emacs checks whether a key is bound to
`self-insert-command' and, if it is, Emacs calls the primitive
`self-insert-command' function directly. Emacs does not check to see
whether you have written another version of the function to substitute
for it. This is done for speed.
(Indeed, in general, if you substitute a Lisp function for a
primitive, the C code within Emacs will continue to call the original
primitive, but Lisp code will call your substitute Lisp function.)
Instead of attempting to replace the function definition for
`self-insert-command', you could rebind all keys that call
`self-insert-command' using `substitute-key-definition'. This solution
works fine if you are using only one minor mode. But if you are using
several minor modes at the same time, and you want to deactivate them,
you must deactivate them in the reverse order that they were activated
to ensure that keymaps are properly restored.
▶1f◀
File: lispref Node: Mode Line Format, Prev: Minor Modes, Up: Major and Minor Modes, Next: Hooks
Mode Line Format
================
The `mode-line-format' is a buffer-local variable that holds a
template used to display the mode line of the current buffer. All
windows for the same buffer use the same `mode-line-format' and the mode
lines will appear the same (except, possibly, for the percentage of the
file scrolled off the top). The mode-line contains information about
the buffer such as its name, associated file, depth of recursive
editing, and, of course, the major and minor modes of the buffer.
The mode line of a window is normally updated whenever a different
buffer is shown in the window, or when the buffer's modified-status
changes from `nil' to `t' or vice-versa. If you modify any of the
variables referenced by `mode-line-format', you may want to force an
update of the mode line so as to display the new information. You can
do this with the following expression:
(set-buffer-modified-p (buffer-modified-p))
The mode line display the values of variables such as `mode-name' and
`minor-mode-alist'. Because of this, very few modes will need to alter
`mode-line-format' or `default-mode-line-format'. For most tasks, it is
sufficient to alter the variables referenced by `mode-line-format'.
If you are writing a new mode and you must modify the mode line, it is
good practice to use a value that is similar to the default since users
will expect information to be displayed in familiar places. You should
document what significant information might be displayed in the mode
line by your mode.
Any replacement for `mode-line-format' should use all the same
variables that are used by the default value, rather than duplicating
their contents or displaying the information in another fashion. This
permits customizations made by the user, by libraries (such as
`display-time') or by major modes via changes to those variables remain
effective.
Here is an example of a `mode-line-format' that might be useful for
`shell-mode' since it contains the hostname and default directory.
(setq mode-line-format
(list ""
'mode-line-modified
"%b--"
(getenv "HOST")
":"
'default-directory
" "
'global-mode-string
" %[(" 'mode-name
'minor-mode-alist
"%n"
'mode-line-process
")%]----"
'(-3 . "%p")
"-%-"))
* Variable: mode-line-format
The value of `mode-line-format' may be a list, cons cell, symbol,
or string. If the value is a list, its elements may be a list,
cons cell, symbol, or string.
`(STRING REST) or (REST REST)'
When the value of `mode-line-format' is a list whose first
element is a string or list, each element is processed
recursively and the results are concatenated. This is the
most common form.
`(SYMBOL)'
When the value of `mode-line-format' is a symbol, the value
of SYMBOL is used in place of SYMBOL unless SYMBOL is `t',
`nil', or void, in which case SYMBOL is ignored. The
exception is that if the value of SYMBOL is a string, it is
processed verbatim in that the "%-constructs" described below
are not recognized.
`(SYMBOL REST)'
When the value of `mode-line-format' is a list whose first
element is SYMBOL, the symbol's value is found, and if that
value is non-`nil', the second element of the list is
processed recursively. But if the value of SYMBOL is `nil',
the third element of the list (if there is one) is processed
recursively. This construct is, therefore, a conditional.
`(WIDTH REST)'
When the value of `mode-line-format' is a list whose first
element is an integer, the remainder of the list is processed
on its own and space filled (if positive) or truncated (if
negative) on the right to the width specified by WIDTH. For
example, the usual way to show what percent of a buffer is
above the top of the window is to use a list that looks like
this: `(-3 . "%p")'.
`STRING'
When the value of `mode-line-format' is a string, the
string is displayed verbatim in the mode line except for
"`%'-constructs". Decimal digits after the `%' specify the
field width for space filling on the right (i.e., the data is
left justified).
* Menu:
* %-constructs:: Putting information into a mode line.
▶1f◀
File: lispref Node: %-constructs, Prev: Mode Line Format, Up: Mode Line Format
`%'-constructs in the Mode Line
-------------------------------
The following table lists the recognized `%'-constructs and what they
mean.
`%b'
prints the buffer name; uses the `buffer-name' function.
`%f'
prints the visited file name; uses the `buffer-file-name' function.
`%*'
prints `*' if the buffer is modified (see `buffer-modified-p');
prints `-' if the buffer is not modified; prints `%' if the buffer
is read only (see `buffer-read-only').
`%s'
prints the process status (see `process-status').
`%p'
prints the percent of the buffer above the top of window, or Top,
Bottom or All.
`%n'
prints `Narrow' when a narrowing restriction is in effect (see
`narrow-to-region').
`%['
print one `[' for each recursive editing level. `%]' is similar.
`%%'
prints `%'
`%-'
prints dashes that fill the remainder of line, ignoring the
remainder of the template.
The following two `%'-constructs are still supported but are obsolete
since use of the `mode-name' and `global-mode-string' variables will
produce the same results.
`%m'
the value of `mode-name'.
`%M'
the value of `global-mode-string'. Currently, only `display-time'
modifies `global-mode-string'.
* Variable: default-mode-line-format
This variable holds the default `mode-line-format' for buffers
that do not override it. This is the same as `(default-value
'mode-line-format)'.
The default value of `default-mode-line-format' is:
(list ""
'mode-line-modified
'mode-line-buffer-identification
" "
'global-mode-string
" %[("
'mode-name
'minor-mode-alist
"%n"
'mode-line-process
")%]----"
'(-3 . "%p")
"-%-"))
▶1f◀
File: lispref Node: Hooks, Prev: Mode Line Format, Up: Major and Minor Modes
Hooks
=====
A "hook" is a variable whose value is a "hook function" or a list of
hook functions. These functions are called by parts of Emacs on
well-defined occasions.
Hooks are used for customization. The functions referenced by a hook
may be changed by the user or by other functions.
Most modes run hooks as the last step in the modes' initialization.
This makes its easy for a user to customize the behavior of a mode. But
hooks may also be used in other contexts. For example, the functions
named by `find-file-not-found-hooks' are called whenever a file is not
found by `find-file'.
*Note Standard Hooks::, for a list of hooks.
Typically, the hooks for a mode are run after the mode has completed
all its other initialization. You may, for example, use a hook to
change the initial values of buffer-local variables.
For example, you can put the following expression in your `.emacs'
file if you want to turn on Auto Fill mode in Lisp Interaction mode:
(setq lisp-interaction-mode-hook 'turn-on-auto-fill)
The following example shows how to use a hook to customize the way
Emacs formats C code. (People often have strong personal preferences
for one format compared to another.) Here the hook function is an
anonymous `lambda' expression.
(setq c-mode-hook
(function (lambda ()
(setq c-indent-level 4
c-argdecl-indent 0
c-label-offset -4
c-continued-statement-indent 0
c-brace-offset 0
comment-column 40
))))
(setq c++-mode-hook c-mode-hook)
Finally, here is an example of how to use the Text mode hook to
provide a customized mode line for buffers in Text mode. This hook
displays the directory in addition to the standard components of the
mode line. (If you have very long path names or display the time and
load, you may run out of space on the mode line.)
(setq text-mode-hook
(function (lambda ()
(setq mode-line-format
(list ""
'mode-line-modified
"Emacs: %14b"
" "
'default-directory
" "
'global-mode-string
"%[("
'mode-name
'minor-mode-alist
"%n"
'mode-line-process
") %]---"
'(-3 . "%p")
"-%-")))))
At the apprpriate time, Emacs uses the `run-hooks' function to run the
hooks you have specified. Most major modes have lines in their
functions defintions that look like these, from Text mode, C mode and
Mail mode respectively. Note that Mail mode runs two hooks in
succession.
(run-hooks 'text-mode-hook)
(run-hooks 'c-mode-hook)
(run-hooks 'text-mode-hook 'mail-mode-hook)
* Function: run-hooks &rest HOOKVAR
This function takes one or more hook names as arguments and runs
each one in turn. Each HOOKVAR argument should be a symbol which
is a hook variable. These arguments are processed in the order
specified.
If a hook variable has a non-`nil' value, that value may be a
function or a list of functions. If the value is a function
(either a lambda expression or a symbol with a function
definition), it is called. If it is a list, the elements are
called, in order.
The hook functions are all called with no arguments.
(run-hooks 'emacs-lisp-mode-hook)
Major mode functions may use this function to call any hooks
defined by the user.
▶1f◀