This chapter describes the various useful facilities which enable complex extensions to be built using MLisp programs.
The facilities for binding command key sequences to functions are very general in nature. When Emacs is accepting commands from the terminal, it translates those commands into Emacs functions. Every command key sequence will result in the execution of one function---either MLisp, a macro, an autoloaded function or some wired-in code.
A keymap is the entity that tells Emacs what to do when a given key is typed by the user. It will either indicate that a function should be called, or that another keymap should be used to obtain another character in a multicharacter command sequence.
For every buffer, there are two routes to follow for command key decoding; the global keymap and the buffer's local keymap . Command key sequences that are defined by the global keymap may be used from any buffer in Emacs, while command key sequences defined in local keymaps may only be used from buffers that associate with the keymap.
When accepting commands, Emacs makes transitions across the two trees of keymaps as though they were finite state automata. Keymaps can be regarded as look-up tables to make transitions across these automata. Each table contains 256 entries---one entry for each eight-bit ASCII character.
Keymaps have names which are entered into the function name-space. This means that it is quite legal to execute a keymap as a function. If you do this, the next key sequence input by Emacs will be translated starting with the executed keymap. If you execute more than one keymap, the last keymap executed is used to start the keymap translation.
Several functions and variables can be used to manipulate keymaps. These include the following:
(define-keymap name)
This function explicitly declares a keymap and initialises its contents. The keymap's name is entered into the function name-space. Once the keymap has been declared in this way, it can be explicitly nominated as a local or global keymap.
(use-global-map name)
Uses the nominated keymap as the global keymap for all subsequent command input. name must be an existing keymap.
(use-local-map name)
Uses the nominated keymap as the local keymap for the current buffer. Any previous local keymap association is removed (though the keymap itself will not be destroyed).
current-local-keymap
This variable contains the name of a buffer's current local keymap. The name it contains may be used with a use-local-map function.
default-global-keymap
This variable contains the default global keymap that Emacs initialises and uses when it starts up. It contains the standard command key sequences plus any global alterations the user has made.
Functions may be bound to any arbitrary key sequence using the functions described as follows:
(bind-to-key name keys)
Makes a global binding to a function. The function binding will be usable from any buffer. The function name must have already been declared in the function name-space. keys can be an arbitrary sequence of characters used to access the function. The following example binds the function set-mark to the Select key:
(bind-to-key "set-mark" "select)")
If keys is a character constant, then the binding is entered into the current global keymap. If keys is a string, then enough keymaps are automatically generated to define the entire path to the function. Automatically generated keymaps have names of the form auto-defined-keymap-n, where n is a sequence number.
If the key sequence specified is a control sequence, it must be a valid ISO control sequence. For example, the key sequence ESC-Select is not a valid ISO control sequence because it generates two consecutive ESC characters. However, Emacs allows you to bind commands to such sequences by providing the convert-key-string function. convert-key-string will convert a control sequence according to Emacs' control-string processing rules to a valid ISO control sequence. For example, to bind the unset-mark function to the ESC-Select key sequence, use the convert-key-string function as follows:
(bind-to-key "unset-mark"
(concat
""
(convert-key-string "select)")
)
)
(local-bind-to-key name keys)
Defines a local binding to a function. The binding is entered into the current buffer's local keymap. Character and string keys parameters are treated as described under bind-to-key. If a buffer does not have a local keymap, an error is reported.
(global-binding-of keys)
Returns a string containing the name of the function defined by the keys string using the current global keymap.
(local-binding-of keys)
Returns a string containing the name of the function defined by the keys string using the current buffer's local keymap.
(remove-all-local-bindings)
Removes all the local bindings in the current buffer's local keymap. The local keymap itself is not destroyed.
(remove-binding keys)
Removes the association of a function to a command key sequence from the global keymap.
(remove-local-binding keys)
Removes the association of a function to a command key sequence from the local keymap.
Emacs provides a comprehensive database management system.
The key components of the database system are database search-lists. These are ordered lists of database files. When data is to be fetched from a database search-list, Emacs scans all the files in the list until it either finds a key match, or the list is exhausted. When Emacs writes data to a database search-list, the data is always inserted into the database at the top of the specified search-list.
You can use any text as the key for a database entry. However keys used in the MLisp-library should conform to the rules for file names and not use upper case letters.
Certain optimisations are made to ease the problems of multiple invocations of Emacs using the same library files. Library files in a database search-list will always be closed and re-opened between each library operation. This may slow down library searches, but it does ensure that data in the library is not cached inside Emacs, so that other Emacs users can access the library.
Database files are of two types: read-only, and read-write. You control which type of access is required by specifying parameters to Emacs. If a database file is protected against writing, read-only access will be granted if possible.
Emacs uses the following database search-lists:
info
This list is used by the INFO subsystem to provide pages of information. The INFO database describes which files are accessed.
language
This list is used by the language modes C Mode and Bliss Mode as the source of language construct templates. The templates supplied with Emacs are found in the file EMACS_LIBRARY:EMACSLANG.TLB. During initialisation of the language subsystems, your language template file SYS$LOGIN:LANGUAGE-TEMPLATES.TLB is added to the search-list so that you can override the system templates with your own templates.
MLisp-library
This list provides database access to stored MLisp programs. All the distributed MLisp functions are stored in the file EMACS_LIBRARY:EMACSLIB.TLB. This file is visible in the search-list. To provide for user extensions and customisations, Emacs will also add the file SYS$LOGIN:EMACSLIB.TLB (if it exists) to the search-list during initialisation.
describe
This search-list is used by the describe-command, describe-variable and Help functions. The files in the list contain the Emacs help database. This search-list can grow as new packages are added into the running Emacs.
subr-names
This search-list is used by the describe-word-in-buffer function as the source of one-line information about words. It contains the supplied quick-information database files and the user's SYS$LOGIN:SUBRNAMES.TLB database if it exists.
The following commands are provided to manipulate database search-lists and to access the data contained in them:
(extend-database-search-list dbname dbfile access)
This command adds the database file specified to the nominated database search-list. The file's writeability is checked and a flag is set to indicate the file's type. If the database search-list does not exist, it is created. If the file already exists in the search-list, it is not added again. access is an optional argument containing access flags. The flags are specified as a bit-mask with the following meaning:
(remove-database dbname dbfile)
Removes the dbfile database file from the dbname database search-list. No error message is generated if the file does not exist. The database search-list will remain even if the last file is removed.
(list-databases)
Creates a buffer called Database list and inserts the names and file names of all the database search-lists. This buffer is then displayed in a window.
(put-database-entry dbname key)
Inserts the current buffer into the first library in the designated database search-list using the specified key. You cannot use put-database-entry on a read-only database. Completion is enabled for both the database search-list name and the key.
(fetch-database-entry dbname key)
Fetches the contents of the designated module and inserts the data into the current buffer at dot. Dot remains in the same place. Completion is enabled for both the database search-list name and the key. If the key does not exist, an error is generated.
(fetch-help-database-entry dbname keys)
Performs the special operation of fetching help from a VMS HELP library and formats it in the same way as the DCL HELP command. The location of the key must be a help library. The formatted help text is inserted into the buffer at dot. Dot remains in the same place. An error is reported if the keys are not found. The keys are defined as a space-separated list of up to 8 keys which access the required help text. fetch-help-database-flags controls the amount of information fetched from the entry.
fetch-help-database-flags
Controls the amount of help text that is inserted into the current buffer when the fetch-help-database-entry function is executed. It contains a bit-mask which can take the following values:
The default value of the bit-mask is 7, meaning that all the information is returned.
Emacs has a set of functions for controlling subprocesses. These processes are created by Emacs and can execute any shell to accept commands. You designate a name for each subprocess and use this name when you want to refer to it.
The number of concurrently running subprocesses is limited only by the resources available to you.
(start-process process-name)
Creates the named subprocess. process-name must not already exist. The current process is changed to the newly-created process.
(kill-process process-name)
Deletes the named subprocess. If the name is null, the current process is deleted. When the process has actually terminated, the process termination procedure will be called. After the termination procedure has finished executing, the process name will be removed from the process name-space.
(list-processes)
Displays a buffer containing the name and state of each existing process. A time value is also displayed; this is set to the time the last state-transition occurred. The associated output buffer, input and output procedures are also displayed.
The possible process states include:
(pause-process process-name)
Allows a given process to be temporarily suspended by sending a VMS SUSPEND request to it. A paused process will remain paused until it is explicitly resumed or killed.
(resume-process process-name)
Resumes a process which has been paused with pause-process.
(force-exit-process process-name reason)
Causes the image running in the specified process to be terminated with the specified status code. Processes that are not running in user mode will not be affected by the exit until they resume execution in user mode. If the process is not running an image, the force exit will be issued on the next image run in the process.
(set-process-termination-procedure process-name function)
Associates an Emacs function with a process. The associated function will be called when the process terminates (not when an image exits). When the associated function is called, the current process is temporarily set to the associated process.
(current-process-name)
Returns a string containing the current process name. This name will be either the name of the last created process, the name of the process which was a target of the set-current-process function, or the name of the associated process for functions called as a result of process input, output or termination.
(set-current-process process-name)
Changes the current process to the process with the specified name. If you change the current process name in an associated input, output or termination function, the effect will only last for the invocation of that function.
The following functions exist to make input and output to and from processes convenient.
For output, the data produced by the process can be inserted into a buffer associated with the process. This provides a convenient way for you to see the output. If, however, some processing of the output is required, then an Emacs function can be automatically called to obtain the output when it is available and perform the required processing.
The functions available for output include:
(set-process-output-buffer process-name buffer-name)
Associates a buffer with a process. When output is available from the process, it is inserted at the end of the buffer. The screen will be updated if the buffer is associated with a window.
If the number of characters exceeds the maximum for the process, characters will be deleted from the beginning of the buffer. This feature protects you from creating huge process buffers.
(set-process-output-procedure process-name function)
Associates an Emacs function with a process. This function will be called once for every line that is produced by the process. It is assumed that the function will obtain the output line and process it in some way. When the procedure is called, the current process is temporarily set to the process that produced the output line.
(process-output process-name)
Returns the next output line from the process.
For input, the user makes lines of input available to the process. If the process does not require input, an error is generated. To allow for co-ordination of input, the following functions are provided:
(set-process-input-procedure process-name function)
Associates an Emacs function with the process. When the process requests some input, the designated function is called. It is assumed that the function will provide some input to the process. During the call of the associated function, the current process is temporarily set to the associated process.
(send-string-to-process process-name input-line)
Sends some input to the designated process. If that process is not requesting input, an error is generated.
(wait-for-process-input-request process-name)
Suspends Emacs execution until the designated process requests some input. Keyboard input will also cause this function to return to prevent Emacs from becoming wedged. When a process asks for input, the function returns 1; otherwise, it returns 0, indicating that the user pressed a key on the keyboard.
Minor modes are used to alter the way Emacs performs an operation. All minor modes are independent of each other and of the selected major mode. The statuses of some minor modes are displayed in the mode lines for each window. Each minor mode is controlled by a variable that can be turned on or off. A non zero-value always turns the mode on, and an explicit zero value always turns the mode off.
The following minor modes are defined by Emacs:
Auto-fill Mode
This mode allows you to type text endlessly without worrying about the width of your screen. Line separators are inserted as required to prevent lines from becoming too long.
Auto-fill Mode is controlled by setting the variable right-margin. When an attempt is made to insert a word character passed the right margin, auto-filling is invoked.
Checkpoint Mode
Checkpoint Mode protects you from system crashes by periodically saving the buffers you are working with. Whenever you visit a file, checkpointing is enabled if the variable checkpoint-frequency is non-zero.
Checkpointing for individual buffers is also controlled by the buffer-specific variable current-buffer-checkpointable.
Journal Mode
Journal Mode protects you from system crashes by writing a journal of all the changes that are made to modified buffers. When you visit a file, journalling is automatically enabled if the variable journal-frequency is non-zero.
Journalling for individual buffers is controlled by the buffer-specific variable current-buffer-journalled.
Replace Mode
Replace Mode causes ordinary printing characters to replace existing text rather than be inserted. For example, if dot is in front of the B in FOOBAR, then in Replace Mode, typing a G changes it to FOOGAR, instead of making it FOOGBAR as usual.
This mode is controlled with variable replace-mode.
Abbreviation Mode
Abbreviation Mode allows you to define abbreviations that automatically expand as you type them. For example, am might expand to Abbrev mode. The abbreviations also may depend on the active major mode.
This mode is controlled by the variable abbrev-mode.
Read-only Mode
Read-only Mode allows you to protect the data in a buffer from being altered. When Read-only Mode is enabled, attempts to insert characters into the buffer are ignored and cause the bell to be sounded.
This mode is controlled by the variable read-only-buffer.
As with most things in Emacs, the information in the mode line is customisable. A buffer-specific variable mode-line-format exists for this purpose. mode-line-format contains a format string which governs the way that the mode line information is displayed. It contains literal text and embedded format effectors. The literal text will be displayed in the mode line as it is typed, while the format effectors will be expanded with the appropriate information. You normally alter the default value of this variable (default-mode-line-format) so that when a new buffer is created, it displays your customised mode line immediately.
The general form of the format effectors is %nx. n is the width of the string to be inserted and causes truncation or padding on the right. x is one of the letters in the following list:
a
Inserts the string Abbrev if Abbreviation Mode is on, otherwise it inserts nothing.
b
Inserts the current buffer's name.
c
Inserts the string Checkpoint if checkpointing is generally enabled and also enabled for the current buffer, otherwise it inserts nothing.
f
Inserts the current file name for buffers associated with files, or [No File] for scratch buffers.
h
Inserts the string <n< if the horizontal position of the window on the current buffer does not include column one. n indicates by how many characters column one is offset from the left-hand side of the window.
j
Inserts the string Journal if journalling is enabled for the buffer, otherwise nothing is inserted.
m
Inserts the value of the buffer-specific variable mode-string. This variable defines the major mode for the buffer.
M
Inserts the value of the global variable global-mode-string which defines the name of the currently running subsystem.
p
Inserts the position of dot in the current buffer as a percentage. If dot is at the beginning of the buffer, the string Top is inserted. If dot is at the end of the buffer, the string Bottom is inserted.
r
Inserts the string Overstrike if Replace Mode is currently enabled.
R
Inserts the string Readonly if Read-only Mode is currently enabled.
*
Inserts a asterisk if the current buffer has been modified since it was last written to disk, otherwise it inserts nothing.
[ and ]
Inserts zero or more square brackets depending on the depth of recursive editing. One bracket is inserted per level when the recursive edit depth is less than 5. When the edit depth is 5 or greater, the string [n] is inserted, where n is the recursive edit depth.
The default value of mode-line-format is:
%[%hBuffer: %b%* File: %f %M (%m%c%r%a) %p%]
The effects of all the Emacs commands which parse words or balance parentheses are controlled by syntax tables . Each ASCII character is represented by one entry in each syntax table. Each buffer has a syntax table associated with it. The default syntax table is called global-syntax-table. The name of the current syntax table (the syntax table associated with the current buffer) may be accessed through the variable current-buffer-syntax-table, and this table may be changed either by setting the variable, or by using the function use-syntax-table.
To alter a syntax table, the function modify-syntax-entry is provided. This command takes a single string argument which describes the attributes to be applied to the specified characters as follows:
· The first character is one of the following:
w
A word character, as used by such functions as forward-word and case-word-capitalize.
Space
A character with no special interpretation.
(
A open parenthesis. Typical candidates for this type are the characters (, [ and.
Characters of this type also have a matching closing parenthesis specified which appears as the second character of the parameter to modify-syntax-entry.
)
A close parenthesis. Typical candidates for this type are the characters ), ] and. Characters of this type also have a matching open parenthesis specified which appears as the second character of the parameter to modify-syntax-entry.
"
A double-quote character. The C string delimiters " and ' are usually given this class.
\
A prefix character, like \ in C.
· The second character of the string is the matching parenthesis if the first character is of the open or close parenthesis type. If you specify that ( is a left parenthesis matched by ), you should also specify that ) is a right parenthesis matched by (.
· The third character, if a , indicates that the characters described by this syntax entry begin a comment.
· The fourth character, if equal to , indicates that the character described by this syntax entry ends a comment.
· If either the beginning or ending comment sequence is two characters long, then the fifth character provides the second character of the comment sequence.
· The sixth and following characters specify which characters are described by the entry; a range of characters can be specified by using the sequence specifier a-b, where aand b are ASCII characters and a is less than b. -- can be described if it appears as the sixth character.
Attribute entries that are not relevant should be spaces.
For example:
(modify-syntax-entry "w -")
makes - behave as a word character;
(modify-syntax-entry "(] [")
makes [ behave as a left bracket which is matched by ].
The function list-syntax-tables is useful for finding out the names of all the syntax tables known to Emacs. Use dump-syntax-table to dump the contents of a syntax table. This function is very useful when trying to discover why a syntax table is not working as expected.