5 Advanced Customisation

This chapter describes the more advanced customisation features provided by predictive mode. Many of these are on the borderline between user-customisations and features to be used by Lisp packages that enhanced predictive completion for specific major modes, though describing all the features available to Lisp packages is beyond the scope of this user guide.

5.1 Character Syntax and Key Bindings

Predictive mode significantly changes what happens when normal, printable characters are typed. Di erent characters cause di erent behaviour. For example, letter characters will usually be added to the current word, updating the completions, whereas punctuation characters end the completion process.

This chapter describes the mechanisms that determine the behaviour of di erent characters, and how to customise them.

5.1.1 Keymaps and Key Bindings

The following keymaps are defined by predictive mode:

predictive-map

Main keymap, enabled whenever predictive mode is.

completion-map

Keymap enabled whenever a completion minor mode (including predictive mode) is enabled.

completion-hotkey-map

Keymap used when hotkey completion is enabled. Constructed from completion-hotkey-list. Warning: setting this directly will cause errors! Set completion-hotkey-list instead. See Section 4.3 [Completion Hotkeys], page 5.

completion-hotkey-list

List of hotkey characters to use for selecting completions. Default is numerical characters 0 to 9. This must be set before predictive mode is loaded, so can not be customized, and must instead be set manually in your ‘.emacs’ file before the (require ’predictive) line (see Chapter 2 [Obtaining and Installing], page 2. See Section 4.3 [Completion Hotkeys], page 5.

completion-dynamic-map

Keymap assigned to the overlay used to highlight the provisional completions that are usually inserted when dynamic completion is enabled. Not currently used1. Use completion-map and the completion-run-if-within-overlays command instead. See Section 4.2 [Dynamic Completion], page 5.

1Minor mode keymaps override overlay keymaps in the stable version (21.x) of Emacs, limiting their use. They don’t even work well in the unstable version (22.x) when overlays have zero length, as they can do in predictive mode

completion-menu-map

Keymap enabled when the completion menu is enabled. See Section 4.5 [Completion Menu and Browser], page 6.

The various keymaps define key bindings for di erent situations that arise in predictive mode. The main completion-map keymap is enabled whenever predictive mode is enabled. By default, this keymap binds all printable characters to the completion-self-insert function.

Note: if you find yourself thinking of re-binding printable characters in completion-map to something other than completion-self-insert, don’t! (at least not until you’ve read on a bit). What you probably want to change are the completion-syntax-alist and completion-override-syntax-alist variables. See Section 5.1.2 [Syntax], page 9.

The completion-dynamic-map is provided for future versions of Emacs, and does not work properly at the moment. Someday, it will replace the use of completion-run-if- within-overlay in completion-map.

The other keymaps are enabled by the corresponding completion options.

The completion-hotkey-map is is constructed automatically from the characters listed in completion-hotkey-list, and binds all those characters to predictive-select- completion. It should not be set directly; you may get strange results if the keymap and key list do not correspond!

If the keymaps are not defined when predictive mode is first loaded (see Chapter 2 [Obtaining and Installing], page 2), it creates the default keymaps and loads them into Emacs. Therefore, to customise predictive mode key bindings, you must re-define the keymap variables before loading predictive mode (e.g. before the (require ’predictive) line).

5.1.2 Syntax

completion-syntax-alist

Alist associating character syntax descriptors with completion functions. Used by the completion-self-insert function to decide what to do based on a typed character’s syntax.

completion-override-syntax-alist

Alist associating characters with completion functions. Overrides the default function for a typed character’s syntax. Used by completion-self-insert.

When a character is typed, predictive mode decides what to do based on that character’s syntax, as defined by the current syntax table (see section “Syntax” in GNU Emacs Manual). All printable characters are bound by default to the function completion-self-insert, which inserts the character, looks up the character’s syntax descriptor in completion- syntax-alist, and carries out the associated actions.

By default, all word-constituent characters (syntax descriptor w) insert the character and complete the new prefix, all white-space and punctuation characters (descriptors SPACE and

.) accept any provisional completion and insert the character, and anything else rejects any provisional completion and inserts the character.

Occasionally, the syntax-derived behaviour needs to be overridden for individual characters. The completion-override-syntax-alist associates characters with functions, and takes precedence over completion-syntax-alist.

Each association in completion-syntax-alist and completion-override-syntax- alist is a three-element list of the form2:

(<accept|reject|add> t <basic|word|none>)

The first element determines what happens if there is a provisional completion at the point: accept accepts it, reject rejects it, and add adds the typed character to the completion’s prefix. The last element determines what kind of completion is done (if any) after the typed character is inserted: basic completes the current prefix and none doesn’t do any completion. The word option does more advanced completion. If completion is already in progress, it behaves as basic. If no completion is in progress and the point is within a word, it deletes from point to the end of the word, and completes the prefix constructed from the part of the word before the point (including the newly typed character)3.

5.1.3 Working with Major Modes

The many features of predictive mode allow you to set things up appropriately for whatever language you are typing, whether it be plain text, markup languages such as HTML or LaTEX, programming languages such as C or Lisp, etc. Predictive mode will work happily alongside the appropriate major-mode. However, since each language requires di erent things of predictive completion, you may find yourself changing a large number of settings when switching major modes.

To facilitate using predictive completion alongside di erent major-modes, predictive mode can run a setup function determined by the current major-mode whenever it is switched on in a bu er. Of course, you can also use major mode hooks, but hooks are less convenient if you don’t want to always switch on predictive mode in that major mode, or if you want to switch it on and o whilst within the mode.

predictive-major-mode-alist

Alist associating a major-mode symbol with a function. The alist is checked whenever predictive mode is switched on in a bu er using the predictive-mode or turn-on-predictive-mode commands (see Section 4.1 [Basic Completion Commands], page 4), and if the bu er’s major-mode matches one in the alist, the associated function is called. This makes it easier to customise predictive mode for di erent major modes.

Since the setup function is determined by the current major-mode, predictive mode should be switched on after switching to the appropriate major-mode. If you always want to use predictive mode with a particular major-mode, the easiest way to do this is to add the predictive-mode command to the major-mode hook in your ‘.emacs’ file, using a line something like this:

(add-hook ’major-mode-hook ’turn-on-predictive-mode)

2Lisp packages can additionally set the second element to nil, and can replace any element with a function that returns one of these values or nil, but this is beyond the scope of this user-guide.

3The value of completion-word-thing determines what is considered a word. Logically enough, it defaults to word. Lisp packages can redefine it, but this is again beyond the scope of this user-guide.