5.5.2 Automatic Learning

Predictive mode can automatically learn which words you use most often as you type, in order to make better predictions. This feature is especially useful when you first start using a dictionary, to adapt it to your writing style. Once a dictionary has been trained and is making good predictions, it can be turned off to fix the order in which completions are offered (see What is predictive completion?), though leaving it on usually doesn't cause the order to change that much.

The following variables control automatic learning:

predictive-auto-learn

Controls automatic word frequency learning. When non-nil (the default), the weight for a word in is incremented each time it is accepted as a completion, making the word more likely to be offered higher up the list of completions in the future. Words that are not already in the dictionary are ignored unless predictive-auto-add-to-dict is set.

predictive-auto-add-to-dict

Controls automatic adding of new words to dictionaries. If nil (the default), new words are never automatically added to a dictionary. If t, new words are automatically added to the active dictionary. If set to a dictionary name, new words are automatically added to that dictionary instead of the active one.

predictive-add-to-dict-ask

If non-nil, predictive mode will ask for confirmation before automatically adding any word to a dictionary. Enabled by default. This has no effect unless predictive-auto-add-to-dict is also set.

predictive-use-buffer-local-dict

If non-nil, a special, buffer-local dictionary will be created for each predictive mode buffer. The buffer-local dictionary is used in conjunction with the predictive-main-dict, and the two act as a single, combined main dictionary for the buffer. The buffer-local dictionary is initially empty, but whenever a word is learnt (auto-learnt, auto-added, learnt from a buffer or file, or added manually), it is added to the buffer-local dictionary, and its weight there is incremented by a value predictive-buffer-local-learn-multiplier times higher than for normal dictionaries. Thus the buffer-local dictionary will help predictive mode adapt much faster to the vocabulary used in a specific buffer than global dictionaries alone can.

If predictive-dict-autosave is enabled and the buffer is associated with a file, the buffer-local dictionary will automatically be saved to the directory containing the file¹. When you load the file in the future, predictive mode will look for the buffer-local dictionary in the same directory; there is no need to add the directory to your load path. If the buffer is not associated with a file, the buffer-local dictionary will be discarded when you end the Emacs session.

predictive-buffer-local-learn-multiplier

Sets the learning speed for buffer-local dictionaries. Whenever a word is added to a buffer-local dictionary, the weight increment is multiplied by this value before being added to any existing word weight. The default is 50.

predictive-use-auto-learn-cache

If non-nil (the default), auto-learnt and auto-added words are cached, and only actually added to the dictionary when Emacs has been idle for predictive-flush-auto-learn-delay seconds or the buffer is killed (it has no effect unless at least one of predictive-auto-learn or predictive-auto-add-to-dict is also set). This avoids small but sometimes noticeable delays when typing. New words or word weights will not be taken into account until the cache is fully flushed.

predictive-auto-add-min-chars

Minimum length of words auto-added to the dictionary. When enabled, words shorter than this will be ignored when auto-add is used.

predictive-auto-add-filter

When this variable is set to a function, and when predictive-auto-add-to-dict is enabled, the function will called whenever a word is going to be auto-added to the dictionary, passing the word (a string) and the dictionary as arguments. The word will only be added if the function returns non-nil. If predictive-use-auto-learn-cache is enabled, the filter function will be called when cached entries are flushed, not when they're added to the cache, allowing even time-consuming filter functions to be used.

Note that if predictive-main-dict contains a list of dictionary names (see Basic Dictionary Usage), an automatically learnt or added word may not end up where you want it. The weight of a word is incremented in the first dictionary it is found in, and words are added to the first dictionary in the list (assuming predictive-auto-add-to-dict is set to t). It is best to ensure that dictionaries in the list do not duplicate any words. The predictive-auto-add-filter is not a customization option, so it can only be set from Lisp code (e.g. a setup function, see Major Modes). One example of its use would be to filter out words that contain non-letter characters (though it may be better to customize completion-dynamic-syntax-alist and completion-dynamic-override-syntax-alist instead, see Syntax). The following will accomplish this:

     (setq predictive-auto-add-filter
           (lambda (word dict) (string-match "^[[:alpha:]]$" word)))

Note that the function must accept both the word and dictionary arguments, even if it doesn't make use of the dictionary.

Another example would be to check that words are spelled correctly before auto-adding them to a dictionary, either using ispell or using the English dictionary that comes with predictive mode. This sounds tautological, but it does make sense: the dictionary you use for predictive completion will only contain words you've used at least once, but typos and spelling mistakes won't make it into the dictionary (see Getting the Most out of Dictionaries).

     (setq predictive-auto-add-filter (lambda (word dict) (lookup-words word)))

Using the supplied predictive English dictionary will be faster than ispell, since it is optimised for looking up words, though this isn't such an issue if predictive-use-auto-learn-cache is enabled (the following assumes dict-english is already loaded, see Loading and Saving Dictionaries).

     (setq predictive-auto-add-filter
           (lambda (word) (dictree-member-p dict-english word)))

Other possible uses for predictive-auto-add-filter are limited only by your imagination!