Title: Auto Complete Mode - User Manual Numbering: yes CSS: style.css
[Japanese]
ac-source-abbrevac-source-css-propertyac-source-dictionaryac-source-eclimac-source-featuresac-source-filenameac-source-files-in-current-dirac-source-functionsac-source-gtagsac-source-imenuac-source-semanticac-source-semantic-rawac-source-symbolsac-source-variablesac-source-words-in-all-bufferac-source-words-in-bufferac-source-words-in-same-mode-buffersac-source-yasnippetauto-complete-mode automatically for specific modesac-delayac-auto-show-menuac-show-menu-immediately-on-auto-completeac-expand-on-auto-completeac-disable-facesac-stop-flymake-on-completingac-use-fuzzyac-fuzzy-cursor-colorac-use-comphistac-comphist-thresholdac-comphist-fileac-use-quick-helpac-quick-help-delayac-menu-heightac-quick-help-heightac-candidate-limitac-modesac-compatible-packages-regexpac-trigger-commandsac-trigger-commands-on-completingac-trigger-keyac-auto-startac-ignoresac-ignore-caseac-dwimac-use-menu-mapac-use-overriding-local-mapac-completion-faceac-candidate-faceac-selection-faceglobal-auto-complete-modeac-user-dictionaryac-user-dictionary-filesac-dictionary-directoriesac-sourcesac-completing-mapac-menu-mapac-mode-mapAuto Complete Mode (aka auto-complete.el, auto-complete-mode) is a extension that automates and advances completion-system of GNU Emacs. This is superior than old system:
This user manual covers from how to install and how to use to how to extend. Please contact me if you have question.
Auto Complete Mode is licensed under the term of GPLv3. And this document is licensed under the term of GFDL.
You can download from Auto Complete Mode top page.
It is easy to install by using a installation script called etc/install.el that is located in the package directory.
Type M-x load-file RET in the running Emacs or newly launched Emacs. Note that if you want to upgrade auto-complete-mode, you have to install in a newly launched Emacs with -q option. Then input a file name to load which is a path string with adding /etc/install.el to the package directory. For example, if the package directory is ~/tmp/auto-complete-1.2, the file name will be ~/tmp/auto-complete-1.2/etc/install.el.
Then input a directory where Auto Complete will be installed. You need to add a directory to load-path later if load-path doesn't include the directory. The directory is to be ~/.emacs.d by default.
Finally type RET to start installation. After installation, you may see the following buffer and follow instructions to edit .emacs.
You can also install from terminal like:
$ make install
$ # or with directory specified
$ make install DIR=$HOME/.emacs.d/
If you don't have GNU Make, run emacs like:
$ emacs -batch -l etc/install.el
Example message after installation (*Installation Result* Buffer)
Successfully installed!
Add the following code to your .emacs:
(add-to-list 'load-path "~/.emacs.d") ; This may not be appeared if you have already added.
(add-to-list 'ac-dictionary-directories "~/.emacs.d/ac-dict")
(require 'auto-complete-config)
(ac-config-default)
It is also possible to install manually if you follow a directory configuration. First, do byte-compile all .el files in the package directory. You may use Makefile in UNIX OS.
$ make byte-compile
If you can't use Makefile, open the directory from Emacs by C-x d and type * . el RET B RET to do byte-compile.
Then copy all .el files and .elc files to a directory which is added to load-path. You may do such the following command if the directory is ~/.emacs.d
$ cp *.el *.elc ~/.emacs.d
And then install dictionary files. They are optional to run Auto Complete Mode, but you should install if you don't have any reason. Dictionary files are located in called dict directory, it is needed that they are installed to a directory which is auto-complete.el has been installed. If you installed auto-complete.el to a directory called ~/.emacs.d, you also have to install dictionary files to ~/.emacs.d. Please be careful not to overwrite existed files. It may be rare case, but the installation script above avoids overwrite by renaming dict directory to ac-dict directory.
$ cp -r dict ~/.emacs.d
Finally add the following code to .emacs.
(add-to-list 'ac-dictionary-directories "~/.emacs.d/dict")
(require 'auto-complete-config)
(ac-config-default)
If you haven't added the directory to load-path, you need to add the following code too.
(add-to-list 'load-path "~/.emacs.d")
Type some characters in *scratch* buffer in a restarted Emacs or newly launched Emacs. It is successful if you see completion menu. If you have error or no completion is started, it is failure maybe. Please contact me in such case with confirmation following:
Using correct load-path?
A directory which auto-complete.el is installed to is in load-path.
Characters AC in mode-line?
If you don't see characters AC in mode-line (a gray line of bottom of buffer), auto-complete-mode is not enabled. Type M-x auto-complete-mode to enable and try again.
Error occurred
If you have *Backtrace* with errors or errors in minibuffer (bottom of frame), please contact me with the errors.
First, in a meaning, auto-complete-mode has no "usage". Because auto-complete-mode is designed to fade into Emacs editing system. Users will be received a highly-developed completion-system automatically without any difficulty. Ultimately, a goal of auto-complete-mode is to provide a system that does what users want without any command, but it is impossible to accomplish 100% accuracy actually. So there is "usage" to cover that points.
Inputting characters is basic. Any completion will never be shown without any character. So when completion will be started, in other others, what character causes completion to be started? It is good question but it is difficult to answer here. In simple words, completion will be started when just character is inserted. See ac-trigger-commands for more details.
After completion is started, completion by TAB will be enabled temporarily. Completion by TAB is the most important and most frequent used command. TAB has several meanings.
Case that only one candidate remains
If only on candidate remains, the candidate will be used to complete.
Case that there is common part among candidates
For example, if all candidates start with "set", it means they have common part "set". So TAB completes "set" at first.
Otherwise
Otherwise, select candidates in cycle by typing TAB.
It may be different a little according to settings, but basically completion by TAB works as we wrote above. A reason why TAB has several meanings is that we want users to do anything with TAB.
Like completion by TAB but some points are different:
It is necessary to type TAB a few times for completion by TAB. Completion by RET instead complete a selected candidate immediately, so when you see a candidate you want, just type RET. If the candidate has an action, the action will be executed. Take a example of builtin abbrev completion. In completion by TAB, an abbrev which expands "www" to "World Wide Web" will be completed to "www", but in completion by RET, the abbrev will be expanded to "World Wide Web" as completion.
Following auto-complete-mode philosophy, it is not recommended to select candidates. Because, it means it has been failed to guess completion, and also it requires for users to do candidate selection which is a high cost operation. We think there is so many cases that requires to do candidate selection, because completion by TAB will help candidate selection somehow and in recent version, a statistic method contributes to make a candidate suggestion more accurate. However, actually, this is such cases. So we also think it is not bad idea to remember how to select candidates.
Selecting candidates is not a complex operation. You can select candidates forward or backward by cursor key or M-p and M-n. According to setting, a behavior of completion by TAB will be changed as a behavior of completion by RET. See ac-dwim for more details.
There is other ways to select candidates. M-1 to select candidate 1, M-2 to select candidate 2, and so on.
auto-complete-mode has two type of help functionalities called Quick Help and Buffer Help. They are different in a point of displaying. Quick help will appear at the side of completion menu, so you can easily see that, but there is a problem if there is no space to displaying the help. Quick help will be shown automatically. To use quick help, you need to set ac-use-quick-help to t. Delay time show quick help is given by ac-quick-help-delay.
On other side, buffer help will not be shown without any instructions from users. Buffer help literally display a help in a buffer of other window. It costs much to see than quick help, but it has more readability. To show buffer help, press C-? or f1. By pressing C-M-v or C-M-S-v after showing buffer help, you can scroll forward or backward for help buffer. Other commands will be fallbacked and buffer help will be closed.
Completion will be started by inserting characters. After completion is started, operations in the following table will be enabled temporarily. After completion is finished, these operations will be disable.
| Key | Command | Description |
|---|---|---|
| TAB, C-i | ac-expand | Completion by TAB |
| RET, C-m | ac-complete | Completion by RET |
| down, M-n | ac-next | Select next candidate |
| up, M-p | ac-previous | Select previous candidate |
| C-?, f1 | ac-help | Show buffer help |
To stop completion, use C-g simply.
auto-complete commandBasically there is assumption that auto-complete-mode will be started automatically, but there is also exception. For example, that is a case that an user wants to complete without inserting any character or a case not to start auto-complete-mode automatically by settings. A command called auto-complete is useful in such cases, which is used with key binding in general. The following code changes a default completion command to more advanced feature that auto-complete-mode provides.
(define-key ac-mode-map (kbd "M-TAB") 'auto-complete)
So, as of auto-complete command, it is a little different from an original automatic completion.
Case that only one candidate remains
Complete immediately without showing completion menu.
Case that no candidates remains
Attempt to complete with fuzzy matching. See Completion by Fuzzy Matching for more details.
Otherwise
Otherwise start completion with/without expanding a whole common part and showing completion menu. See also ac-show-menu-immediately-on-auto-complete and ac-expand-on-auto-complete.
In a case that there is no candidates by auto-complete command or a case that ac-fuzzy-complete command is executed, auto-complete-mode attempts to complete with fuzzy matching instead of usual exact matching. Parameters of fuzzy matching has already been optimized for use, so users don't need to change them. However if you want to know the internals, see fuzzy.el. Using completion by fuzzy matching, typo will be fixed as a series of completion. For instance, input "messaeg" in a buffer, and then do M-x auto-complete or M-x ac-fuzzy-complete. The cursor color will be changed to red if completion has been successful, and then you can continue to complete with regarding of "messaeg" as "message". It is not bad idea to bind auto-complete command to some key in a meaning of handling such cases.
You can start filtering by C-s. The cursor color will be changed to blue. Then input characters to filter. It is possible to do completion by TAB or select candidates, which changes the cursor color to original so that telling filtering completion candidates has done. The filtering string will be restored when C-s again. To delete the filter string, press DEL or C-h. Other general operations is not allowed there.
It is difficult what key auto-complete command is bound to. It should be bound to a key which is easy to press as much as possible because completion operation is often happened. However, it is a major problem that there is no empty key to press easily. auto-complete-mode provides a feature called Trigger Key that handles such the problem. Using trigger key, you can use an arbitrary key temporarily if necessary. The following code uses TAB as trigger key.
(ac-set-trigger-key "TAB")
Trigger key will be enabled after inserting characters. Otherwise it is dealt as an usual command (TAB will be indent). Generally, trigger key is used with auto-auto-start being nil.
(setq ac-auto-start nil)
As of ac-auto-start, see Not to complete automatically or ac-auto-start for more details.
auto-complete-mode analyzes completion operations one by one and reduces overheads of completion as much as possible. For example, having a candidate "foobar" been completed few times, auto-complete-mode arranges it to top of the candidates next time and make a situation that allows users to complete the word with one time TAB or few times TAB. It is called comphist internally, and you can use it by setting ac-use-comphist to t. It is enabled by default. Collection operations data will be stored in user-emacs-directory or ~/.emacs.d/ with a name ac-comphist.dat.
auto-complete-mode collects two types of data to accomplish accurate candidate suggestion.
Simply saying, it collects not only a completion count but also a position of completion. A completion candidate will be scored with the count and the point. If you complete find-file with a word f few times, in next time find-file will be arranged to top of candidates. However it is too simple. Actually find-file with find- will not have the same score, because a distance between f and find- will reduce a weight of scoring. It means that if you often complete find-library after find-, find-library will get high score than find-file at that position. So auto-complete-mode can guess find-file will be top after f and find-library will be top after find- as it seems to learn from users' operations.
Dictionary is a simple list of string. There is three types of dictionary: user defined dictionary, major mode dictionary, and extension dictionary. You need to add ac-source-dictionary to ac-sources (default). See source for more details.
User defined dictionary is composed of a list of string specified ac-user-dictionary and dictionary files specified by ac-user-dictionary-files. Dictionary file is a word list separated with newline. User defined dictionary is shared with all buffers. Here is example adding your mail address to dictionary.
(add-to-list 'ac-user-dictionary "foobar@example.com")
Setting will be applied immediately. Try to input "foo" in a buffer. You may see foobar@example.com as a completion candidate. This setting will be cleared if Emacs will quit. You need to write the following code to keep setting in next Emacs launching.
(setq ac-user-dictionary '("foobar@example.com" "hogehoge@example.com"))
There is more easy way to add word to dictionary. Files specified by ac-user-dictionary-files will be treated as dictionary files. By default, ~/.dict will be a dictionary file, so edit ~/.dict like:
foobar@example.com
hogehoge@example.com
As we said, words are separated with newline. They are not applied immediately, because auto-complete-mode uses cache not to load every time from a dictionary file. It may be high cost. To clear cache, do M-x ac-clear-dictionary-cache. After that, dictionary files will be load absolutely.
No need to say perhaps, you can use other files as dictionary file by adding to ac-user-dictionary-files.
You can use other dictionaries for every major-modes and extensions. A dictionary will loaded from a directory specified with ac-dictionary-directories. ac-dictionary-directories may be the following setting if you followed installation instructions.
(add-to-list 'ac-dictionary-directories "~/.emacs.d/ac-dict")
A dictionary named c++-mode for specific major-mode and a dictionary named txt for specific extension will be stored in the directory. For instance, you complete in a buffer named a.cpp with dictionary completion, following the setting above, ~/.emacs.d/ac-dict/c++-mode and ~/.emacs.d/ac-dict/cpp will be loaded as dictionary file. You can edit the dictionary files and make a new one. In addition, you can add a new dictionary file to a directory that has same configuration.
As same as user defined dictionary, after editing and adding dictionary, you should do M-x ac-clear-dictionary-cache to apply changes.
Source is a concept that insures a extensibility of auto-complete-mode. Simply saying, source is a description about:
Anybody who know about Emacs Lisp a little can define a source easily. See extend for how to define a source. Here we can explain how to use builtin sources.
Usually a name of source starts with ac-source-. So you can list up sources with apropos (M-x apropos RET ^ac-source-). You may see ac-source-filename and ac-source-dictionary which are entities of sources.
If you wrote (ac-config-default) in your .emacs, it is rare to change a source setting because it is already optimized to use. Here is a short explanation about source however. Sources will be used by setting ac-sources to a list of sources. You can see the setting by evaluating ac-sources in *scratch* buffer:
;; Formatted
(ac-source-filename
ac-source-functions
ac-source-yasnippet
ac-source-variables
ac-source-symbols
ac-source-features
ac-source-abbrev
ac-source-words-in-same-mode-buffers
ac-source-dictionary)
As you see, ac-sources in *scratch* buffer has six sources. We explain each source for detail, you can guess meanings of sources. It is worth to remember that ac-sources is a buffer local variable, which means each ac-sources for buffers will be different.
Here is an example. Think you are at *scratch* buffer. As we said, this buffer has many sources. Some people think it is too many. So try to change ac-sources to reduce functionalities. It is easy to change. Just evaluate the following code in *scratch* buffer or with M-::
(setq ac-sources '(ac-source-symbols ac-source-words-in-same-mode-buffers))
This example changes ac-source setting and enable only symbol completion and word completion among same major modes. Then, how can we enable this setting in next Emacs launching? We can change settings by adding a hook which is called when *scratch* buffer is created.
(defun my-ac-emacs-lisp-mode ()
(setq ac-sources '(ac-source-symbols ac-source-words-in-same-mode-buffers)))
(add-hook 'emacs-lisp-mode-hook 'my-ac-emacs-lisp-mode)
If a code (ac-config-default) is written in .emacs, the code above may not be worked correctly. It is because of (ac-config-default) will overwrite the setting. In such case, you can redefine a function which is used in (ac-config-default). The function name is ac-emacs-lisp-mode-setup in emacs-lisp-mode. See auto-complete-config.el for more details.
(defun ac-emacs-lisp-mode-setup ()
(setq ac-sources '(ac-source-symbols ac-source-words-in-same-mode-buffers)))
So, now you know how to change sources in a specific major mode. Summary is:
ac-sourcesc++-mode-hook, ruby-mode-hook, and python-mode-hook, etc)By the way, how can we change a setting for all buffers? We use setq-default to change ac-sources instead of setq in such case. Then the default value of ac-sources will be changed to the value you specified.
(setq-default ac-sources '(ac-source-words-in-all-buffer))
There is other ways to do that. (ac-config-default) changes the default value of ac-sources by registering a hook for auto-complete-mode. The registered function is ac-common-setup that adds ac-source-filename to the first of ac-sources by default. So all auto-complete-mode enabled buffer will have ac-source-filename at the first of ac-sources. A reason why adding to the first is relating to omni completion. Anyway you don't care about it here. So if you want to change ac-sources of all buffer, you can redefine ac-common-setup function to do that.
;; Add ac-source-dictionary to ac-sources of all buffer
(defun ac-common-setup ()
(setq ac-sources (append ac-sources '(ac-source-dictionary))))
Here are defined sources in auto-complete.el and auto-complete-config.el.
ac-source-abbrevA source for Emacs abbreviation function. See info emacs Abbrevs about abbreviation function.
ac-source-css-propertyA source for CSS property.
ac-source-dictionaryA source for dictionary. See completion by dictionary about dictionary.
ac-source-eclimA source for Emacs-eclim.
ac-source-featuresA source for completing features which are available with (require '.
ac-source-filenameA source for completing file name. Completion will be started after inserting /.
ac-source-files-in-current-dirA source for completing files in a current directory. It may be useful with eshell.
ac-source-functionsA source for completing Emacs Lisp functions. It is available only after (.
ac-source-gtagsA source for completing tags of Global.
ac-source-imenuA source for completing imenu nodes. See info emacs imenu for details.
ac-source-semanticA source for Semantic. It can be used for completing member name for C/C++.
ac-source-semantic-rawUnlike ac-source-semantic, this source is for completing symbols in a raw namespace.
ac-source-symbolsA source for completing Emacs Lisp symbols.
ac-source-variablesA source for completing Emacs Lisp symbols.
ac-source-words-in-all-bufferA source for completing words in all buffer. Unlikely ac-source-words-in-same-mode-buffers, it doesn't regard major-mode.
ac-source-words-in-bufferA source for completing words in a current buffer.
ac-source-words-in-same-mode-buffersA source for completing words which are collected over buffers whom major-mode is same to of a current buffer. For example, words will shared among a.cpp and b.cpp, but not shared among a.pl and b.cpp because they are different major-mode buffers. Usually this source is more useful than ac-source-words-in-all-buffer.
ac-source-yasnippetA source for Yasnippet to complete and expand snippets.
If you are being annoyed with displaying completion menu, you can disable automatic starting completion by setting ac-auto-start to nil.
(setq ac-auto-start nil)
You need to bind some key to auto-complete command (because you need to complete anyway). For example, bind to ac-mode-map, which is a key map for auto-complete-mode enabled buffer:
(define-key ac-mode-map (kbd "M-TAB") 'auto-complete)
Or bind to global key map.
(global-set-key "\M-/" 'auto-complete)
In addition, if you allow to start completion automatically but also want to be silent as much as possible, you can do it by setting ac-auto-start to an prefix length integer. For example, if you want to start completion automatically when you has inserted 4 or more characters, just set ac-auto-start to 4:
(setq ac-auto-start 4)
Setting ac-auto-start to large number will result in good for performance. Lesser ac-auto-start, more high cost to produce completion candidates, because there will be so many candidates necessarily. If you feel auto-complete-mode is stalling, change ac-auto-start to a larger number or nil.
See ac-auto-start for more details.
And consider to use trigger key.
There is another approach to solve the annoying problem is that not to show completion menu automatically. Not to show completion menu automatically, set ac-auto-show-menu to nil.
(setq ac-auto-show-menu nil)
When you select or filter candidates, completion menu will be shown.
In other way, you can delay showing completion menu by setting ac-auto-show-menu to seconds in real number.
;; Show 0.8 second later
(setq ac-auto-show-menu 0.8)
This interface has both good points of completely automatic completion and completely non-automatic completion. This may be default in the future.
You can stop completion by pressing C-g. However you won't press C-g while defining a macro. In such case, it is a good idea to bind some key to ac-completing-map.
(define-key ac-completing-map "\M-/" 'ac-stop)
Now you can stop completion by pressing M-/.
As we described above, there is many behaviors in TAB. You need to use TAB and RET properly, but there is a simple interface that bind RET to original and TAB to finish completion:
(define-key ac-completing-map "\t" 'ac-complete)
(define-key ac-completing-map "\r" nil)
By evaluating the following code, you can select candidates with C-n/C-p, but it might be annoying sometimes.
;; Bad config
(define-key ac-completing-map "\C-n" 'ac-next)
(define-key ac-completing-map "\C-p" 'ac-previous)
In this case, it is better that selecting candidates is enabled only when completion menu is displayed so that the key input will not be taken as much as possible. ac-menu-map is a keymap for completion on completion menu which is enabled when ac-use-menu-map is t.
(setq ac-use-menu-map t)
;; Default settings
(define-key ac-menu-map "\C-n" 'ac-next)
(define-key ac-menu-map "\C-p" 'ac-previous)
See ac-use-menu-map and ac-menu-map for more details.
A tooltip help that is shown when completing is called quick help. You can disable it if you don't want to use it:
(setq ac-use-quick-help nil)
Set ac-menu-height to number of lines.
;; 20 lines
(setq ac-menu-height 20)
auto-complete-mode automatically for specific modesauto-complete-mode won't be enabled automatically for modes that are not in ac-modes. So you need to set if necessary:
(add-to-list 'ac-modes 'brandnew-mode)
There is three ways to distinguish upper case and lower case.
;; Just ignore case
(setq ac-ignore-case t)
;; Ignore case if completion target string doesn't include upper characters
(setq ac-ignore-case 'smart)
;; Distinguish case
(setq ac-ignore-case nil)
Default is smart.
Set ac-ignores to words that stops completion automatically. In ruby, some people want to stop completion automatically after inserting "end":
(add-hook 'ruby-mode-hook
(lambda ()
(make-local-variable 'ac-ignores)
(add-to-list 'ac-ignores "end")))
Note that ac-ignores is not a buffer local variable, so you need to make it buffer local with make-local-variable if it is buffer specific setting.
Colors settings are following:
| Face | Description |
|---|---|
ac-completion-face |
Foreground color of inline completion |
ac-candidate-face |
Color of completion menu |
ac-selection-face |
Selection color of completion menu |
To change face background color, use set-face-background. To change face foreground color, use set-face-foreground. To set underline, use set-face-underline.
;; Examples
(set-face-background 'ac-candidate-face "lightgray")
(set-face-underline 'ac-candidate-face "darkgray")
(set-face-background 'ac-selection-face "steelblue")
Read source first if you don't familiar with sources. To change default of sources, use setq-default:
(setq-default ac-sources '(ac-source-words-in-all-buffer))
For example, you may want to use specific sources for C++ buffers. To do that, register a hook by add-hook and change ac-sources properly:
(add-hook 'c++-mode (lambda () (add-to-list 'ac-sources 'ac-source-semantic)))
You can start completion with specific source. For example, if you want to complete file name, do M-x ac-complete-filename at point. Or if you want to complete C/C++ member name, do M-x ac-complete-semantic at point. Usually, you may bind them to some key like:
;; Complete member name by C-c . for C++ mode.
(add-hook 'c++-mode-hook
(lambda ()
(local-set-key (kbd "C-c .") 'ac-complete-semantic)))
;; Complete file name by C-c /
(global-set-key (kbd "C-c /") 'ac-complete-filename)
Generally, such commands will be automatically available when sources are defined. Assume that a source named ac-source-foobar is being defined for example, a command called ac-complete-foobar will be also defined automatically. See also builtin sources for available commands.
If you want to use multiple sources for a command, you need to define a command for it like:
(defun semantic-and-gtags-complete ()
(interactive)
(auto-complete '(ac-source-semantic ac-source-gtags)))
auto-complete function can take an alternative of ac-sources.
Use ac-persist-help instead of ac-help, which is bound to M-<f1> and C-M-?.
ac-last-help command shows a lastly completed candidate help in a ac-help (buffer help) form. If you give an argument by C-u or just call ac-last-persist-help, its help buffer will not disappear automatically.
ac-last-quick-help command show a lastly completed candidate help in a ac-quick-help (quick help) form. It is useful if you want to see a function documentation, for example.
You may bind keys to these command like:
(define-key ac-mode-map (kbd "C-c h") 'ac-last-quick-help)
(define-key ac-mode-map (kbd "C-c H") 'ac-last-help)
If pos-tip.el is installed, auto-complete-mode uses its native rendering engine for displaying quick help instead of legacy one.
Any configuration item will be set in .emacs or with M-x customize-group RET auto-complete RET.
ac-delayDelay time to start completion in real number seconds. It is a trade off of responsibility and performance.
ac-auto-show-menuShow completion menu automatically if t specified. t means always automatically showing completion menu. nil means never showing completion menu. Real number means delay time in seconds.
ac-show-menu-immediately-on-auto-completeWhether or not to show completion menu immediately on auto-complete command. If inline completion has already been showed, this configuration will be ignored.
ac-expand-on-auto-completeWhether or not to expand a common part of whole candidates.
ac-disable-facesSpecify a list of face symbols for disabling auto completion. Auto completion will not be started if a face text property at a point is included in the list.
ac-stop-flymake-on-completingWhether or not to stop Flymake on completion.
ac-use-fuzzyWhether or not to use fuzzy matching.
ac-fuzzy-cursor-colorChange cursor color to specified color when fuzzy matching is started. nil means never changed. Available colors can be seen with M-x list-colors-display.
ac-use-comphistWhether or not to use candidate suggestion. nil means never using it and get performance better maybe.
ac-comphist-thresholdSpecify a percentage of limiting lower scored candidates. 100% for whole scores.
ac-comphist-fileSpecify a file stores data of candidate suggestion.
ac-use-quick-helpWhether or not to use quick help.
ac-quick-help-delayDelay time to show quick help in real number seconds.
ac-menu-heightSpecify an integer of lines of completion menu.
ac-quick-help-heightSpecify an integer of lines of quick help.
ac-candidate-limitLimit a number of candidates. Specifying an integer, the value will be a limit of candidates. nil means no limit.
ac-modesSpecify major modes as a list of symbols that will be enabled automatically if global-auto-complete-mode is enabled.
ac-compatible-packages-regexpSpecify a regexp that identifies starting completion or not for that package.
ac-trigger-commandsSpecify commands as a list of symbols that starts completion automatically. self-insert-command is one of default.
ac-trigger-commands-on-completingSame as ac-trigger-commands expect this will be used on completing.
ac-trigger-keySpecify a trigger key.
ac-auto-startSpecify how completion will be started. t means always starting completion automatically. nil means never started automatically. An integer means completion will not be started until the value is more than a length of the completion target string.
ac-ignoresSpecify a list of strings that stops completion.
ac-ignore-caseSpecify how distinguish case. t means always ignoring case. nil means never ignoring case. smart in symbol means ignoring case only when the completion target string doesn't include upper characters.
ac-dwim"Do What I Mean" function. t means:
ac-use-menu-mapSpecify a special keymap (ac-menu-map) should be enabled when completion menu is displayed. ac-menu-map will be enabled when it is t and satisfy one of the following conditions:
ac-auto-start and ac-auto-show-menu are not nil, and completion menu is displayed after starting completionauto-complete commandac-isearch commandac-use-overriding-local-mapUse only when operations is not affected. Internally it uses overriding-local-map, which is too powerful to use with keeping orthogonality. So don't use as much as possible.
ac-completion-faceFace of inline completion.
ac-candidate-faceFace of completion menu background.
ac-selection-faceFace of completion menu selection.
global-auto-complete-modeWhether or not to use auto-complete-mode globally. It is t in general.
ac-user-dictionarySpecify a dictionary as a list of string for completion by dictionary.
ac-user-dictionary-filesSpecify a dictionary files as a list of string for completion by dictionary.
ac-dictionary-directoriesSpecify a dictionary directories as a list of string for completion by dictionary.
ac-sourcesSpecify sources as a list of source. This is a buffer local variable.
ac-completing-mapKeymap for completion.
ac-menu-mapKeymap for completion on completion menu. See also ac-use-menu-map.
ac-mode-mapKeymap for auto-complete-mode enabled buffers.
A meaning to extend auto-complete-mode is just defining a source. This section describe how to define a source.
Source basically takes a form of the following:
(defvar ac-source-mysource1
'((prop . value)
...))
As you see, source is just an associate list. You can define a source by combining pairs of defined property and its value.
The most important property for source is candidates property. This property describes how to generate completion candidates by giving a function, an expression, or a variable. A result of evaluation should be a list of strings. Here is an example to generate candidates "Foo", "Bar", and "Baz":
(defvar ac-source-mysource1
'((candidates . (list "Foo" "Bar" "Baz"))))
Then add this source to ac-sources and use:
(setq ac-sources '(ac-source-mysource1))
It is successful if you have "Bar" and "Baz" by inserting "B". The example above has an expression (list ...) in candidates property. The expression specified there will not be byte-compiled, so you should not use an expression unless it is too simple, because it has a bad affection on performance. You should use a function instead maybe:
(defun mysource1-candidates ()
'("Foo" "Bar" "Baz"))
(defvar ac-source-mysource1
'((candidates . mysource1-candidates)))
The function specified in candidates property will be called without any arguments on every time candidates updated. There is another way: a variable.
You may want to initialize a source at first time to complete. Use init property in these cases. As same as candidates property, specify a function without any parameters or an expression. Here is an example:
(defvar mysource2-cache nil)
(defun mysource2-init ()
(setq mysource2-cache '("Huge" "Processing" "Is" "Done" "Here")))
(defvar ac-source-mysource2
'((init . mysource2-init)
(candidates . mysource2-cache)))
In this example, mysource2-init function does huge processing, and stores the result into mysource2-cache variable. Then specifying the variable in candidates property, this source prevents huge processing on every time update completions. There are possible usage:
requireCaching strategy is important for auto-complete-mode. There are two major ways: init property and cache property that is described in this section. Specifying cache property in source definition, a result of evaluation of candidates property will be cached and reused the result as the result of evaluation of candidates property next time.
Rewrite the example in previous section by using cache property.
(defun mysource2-candidates ()
'("Huge" "Processing" "Is" "Done" "Here"))
(defvar ac-source-mysource2
'((candidates . mysource2-candidates)
(cache)))
There is no performance problem because this source has cache property even if candidates property will do huge processing.
It is possible to keep among more wider scope than init property and cache property. It may be useful for remembering all function names which is rarely changed. In these cases, how can we clear cache property not at the expense of performance? This is true time use that functionality.
Use ac-clear-variable-after-save to clear cache every time a buffer saved. Here is an example:
(defvar mysource3-cache nil)
(ac-clear-variable-after-save 'mysource3-cache)
(defun mysource3-candidates ()
(or mysource3-cache
(setq mysource3-cache (list (format "Time %s" (current-time-string))))))
(defvar ac-source-mysource3
'((candidates . mysource3-candidates)))
Add this source to ac-sources and complete with "Time". You may see a time when completion has been started. After that, you also see the same time, because mysource3-candidates returns the cache as much as possible. Then, save the buffer once and complete with "Time" again. In this time, you may find a new time. An essence of this source is to use ac-clear-variable-after-save to manage a variable for cache.
It is also possible to clear cache periodically. Use ac-clear-variable-every-minute to do that. A way to use is same to ac-clear-variable-after-save except its cache will be cleared every minutes. A builtin source ac-source-functions uses this functionality.
Complete by RET will evaluate a function or an expression specified in action property. A builtin sources ac-source-abbrev and ac-source-yasnippet use this property.
Omni Completion is a type of completion which regards of a context of editing. A file name completion which completes with slashed detected and a member name completion in C/C++ with dots detected are omni completions. To make a source support for omni completion, use prefix property. A result of evaluation of prefix property must be a beginning point of completion target string. Retuning nil means the source is disabled within the context.
Consider a source that completes mail addresses only after "To: ". First of all, define a mail address completion source as same as above.
(defvar ac-source-to-mailaddr
'((candidates . (list "foo1@example.com"
"foo2@example.com"
"foo3@example.com"))))
(setq ac-sources '(ac-source-to-mailaddr))
Then enable completions only after "To: " by using prefix property. prefix property must be one of:
Specifying a regexp, auto-complete-mode thinks of a point of start of group 1 or group 0 as a beginning point of completion target string by doing re-search-backward[1] with the regexp. If you want to do more complicated, use a function or an expression instead. The beginning point that is evaluated here will be stored into ac-point. In above example, regexp is enough.
^To: \(.*\)
A reason why capturing group 1 is skipping "To: ". By adding this into the source definition, the source looks like:
(defvar ac-source-to-mailaddr
'((candidates . (list "foo1@example.com"
"foo2@example.com"
"foo3@example.com"))
(prefix . "^To: \\(.*\\)")))
Add this source to ac-sources and then type "To: ". You will be able to complete mail addresses.
ac-define-sourceYou may use an utility macro called ac-define-source which defines a source and a command.
(ac-define-source mysource3
'((candidates . (list "Foo" "Bar" "Baz"))))
This expression will be expanded like:
(defvar ac-source-mysource3
'((candidates . (list "Foo" "Bar" "Baz"))))
(defun ac-complete-mysource3 ()
(interactive)
(auto-complete '(ac-source-mysource3)))
A source will be defined as usual and in addition a command that completes with the source will be defined. Calling auto-complete without arguments will use ac-sources as default sources and with arguments will use the arguments as default sources. Considering compatibility, it is difficult to answer which you should use defvar and ac-define-source. Builtin sources are defined with ac-define-sources, so you can use them alone by binding some key to these commands such like ac-complete-filename. See also [this tips](#Completionwithspecific_source].
initSpecify a function or an expression that is evaluated only once when completion is started.
candidatesSpecify a function, an expression, or a variable to calculate candidates. Candidates should be a list of string. If cache property is enabled, this property will be ignored twice or later.
prefixSpecify a regexp, a function, or an expression to find a point of completion target string for omni completion. This source will be ignored when nil returned. If a regexp is specified, a start point of group 1 or group 2 will be used as a value.
requiresSpecify a required number of characters of completion target string. If nothing is specified, auto-complete-mode uses ac-auto-start instead.
actionSpecify a function or an expression that is executed on completion by RET.
limitSpecify a limit of candidates. It overrides ac-candidate-limit partially.
symbolSpecify a symbol of candidate meaning in one character string. The symbol will be any character, but you should follow the rule:
| Symbol | Meaning |
|---|---|
| s | Symbol |
| f | Function, Method |
| v | Variable |
| c | Constant |
| a | Abbreviation |
| d | Dictionary |
summarySpecify a summary of candidate in string. It should be used for summarizing the candidate in short string.
cacheUse cache.
requireSpecify an integer or nil. This source will be ignored when the integer value is lager than a length of completion target string. nil means nothing ignored.
candidate-faceSpecify a face of candidate. It overrides ac-candidate-face partially.
selection-faceSpecify a face of selection. It overrides ac-selection-face partially.
dependsSpecify a list of features (which are required) that the source is depending.
availableSpecify a function or an expression that describe the source is available or not.
Here is a list of often used variables.
ac-bufferA buffer where completion started.
ac-pointA start point of completion target string.
ac-prefixA string of completion target.
ac-limitA limit of candidates. Its value may be one of ac-candidate-limit and limit property.
ac-candidatesA list of candidates.
To keep much responsibility is very important for auto-complete-mode. However it is well known fact that a performance is a trade off of functionalities. List up options related to the performance.
ac-auto-startFor a larger number, it reduces a cost of generating completion candidates. Or you can remove the cost by setting nil and you can use when you truly need. See not to complete automatically for more details.
ac-delayFor a larger number, it reduces a cost of starting completion.
ac-auto-show-menuFor a larger number, it reduces a displaying cost of completion menu.
ac-use-comphistSetting ac-use-comphist to nil to disable candidate suggestion, it reduces a cost of suggestion.
ac-candidate-limitFor a property number, it reduces much computation of generating candidates.
There is two major cases.
auto-complete-mode tries to reduce a cost of computation of columns to show completion menu correctly by using a optimized function at the expense of accuracy. However, it probably causes a menu to be disrupted. Not to use the optimized function, evaluate the following code:
(setq popup-use-optimized-column-computation nil)
There is a problem when render IPA font with Xft in Ubuntu 9.10. Use VL gothic, which renders more suitably. Or disable Xft, then it can render correctly.
We don't good answers now, but you may shot the troubles by changing font size with set-face-font. For instance, completion menu may be disrupted when displaying the menu including Japanese in NTEmacs. In such case, it is worth to try to evaluate the following code to fix it:
(set-face-font 'ac-candidate-face "MS Gothic 11")
(set-face-font 'ac-selection-face "MS Gothic 11")
flyspell-mode enabledA way of delaying processes of flyspell-mode disables auto completion. You can avoid this problem by M-x ac-flyspell-workaround. You can write the following code into your ~/.emacs.
(ac-flyspell-workaround)
Visit Auto Complete Mode Bug Tracking System and create a new ticket.
Strictly re-search-backward with the added adding 28d397e87306b8631f3ed80d858d35f0= at the end ↩
Title: Auto Complete Mode - Demo CSS: style.css
Title: Auto Complete Mode - GNU Emacsのための最も賢い自動補完機能 CSS: style.css
GNU Emacsのための最も賢い自動補完機能
[English]
Auto Complete ModeはGNU Emacsのための最も賢い自動補完機能です。従来の使いづらい補完インターフェースを一新し、ユーザーがより本質的な作業に集中できる環境を提供します。
利用者の声をぜひお聞かせください。あなたの名前（匿名希望可）とコメントをそえてtomo@cx4a.orgまでメールでお願いします。どんなコメントでも歓迎です。
ソースコードは以下のGitリポジトリから取得できます。
Auto Complete Modeのバグトラッキングシステムに新しいチケットを登録してください。
このソフトウェアはGPLv3のもとで配布されます。
debian/copyright 0000644 0000000 0000000 00000002335 11733623750 011133 0 ustar This work was packaged for Debian by: Takaya YamashitaTitle: Auto Complete Mode - Changes CSS: style.css
[Japanese]
See also documentation.
Major changes in v1.3.
ac-disable-facesac-show-menu-immediately-on-auto-completeac-expand-on-auto-completeac-use-menu-mapflyspell-mode confliction (M-x flyspell-workaround)Major changes in v1.2 since v1.0.
ac-delay)ac-auto-show-menu)Title: Auto Complete Mode - The most intelligent auto-completion extension for GNU Emacs CSS: style.css
The most intelligent auto-completion extension for GNU Emacs
[Japanese]
Auto Complete Mode is the most intelligent auto-completion extension for GNU Emacs. Auto Complete Mode renews an old completion interface and provides an environment that makes users could be more concentrate on their own works.
Auto Complete Mode User Manual
Please send me a comment with your name (or anonymous) to tomo@cx4a.org if you like it. Any comments are welcome.
Git repositories are available:
Visit Auto Complete Mode Bug Tracking System and create a new ticket.
This software is distributed under the term of GPLv3+.
debian/README.source 0000644 0000000 0000000 00000000751 11733623750 011357 0 ustar README.source ------------- Original upstream documents(doc/*.txt) are written in "Extended Markdown". But I can't find suitable converter in official Debian archives. So the source package uses BlueFeather[1] to publish html document(there are in debian/). When package upgrading, you should update html document in debian/*.html using BlueFeather. [1] http://ruby.morphball.net/bluefeather/index_en.html -- Youhei SASAKITitle: Auto Complete Modeユーザーマニュアル Numbering: yes CSS: style.css
[English]
ac-source-abbrevac-source-css-propertyac-source-dictionaryac-source-eclimac-source-featuresac-source-filenameac-source-files-in-current-dirac-source-functionsac-source-gtagsac-source-imenuac-source-semanticac-source-semantic-rawac-source-symbolsac-source-variablesac-source-words-in-all-bufferac-source-words-in-bufferac-source-words-in-same-mode-buffersac-source-yasnippetac-delayac-auto-show-menuac-show-menu-immediately-on-auto-completeac-expand-on-auto-completeac-disable-facesac-stop-flymake-on-completingac-use-fuzzyac-fuzzy-cursor-colorac-use-comphistac-comphist-thresholdac-comphist-fileac-use-quick-helpac-quick-help-delayac-menu-heightac-quick-help-heightac-candidate-limitac-modesac-compatible-packages-regexpac-trigger-commandsac-trigger-commands-on-completingac-trigger-keyac-auto-startac-ignoresac-ignore-caseac-dwimac-use-menu-mapac-use-overriding-local-mapac-completion-faceac-candidate-faceac-selection-faceglobal-auto-complete-modeac-user-dictionaryac-user-dictionary-filesac-dictionary-directoriesac-sourcesac-completing-mapac-menu-mapac-mode-mapAuto Complete Mode（通称、auto-complete.el, auto-complete-mode）はGNU Emacs（以下Emacs）の補完システムを自動化・高度化する拡張です。従来の補完システムと比べて以下の点で優れています。
本マニュアルはインストール方法から基本的な使い方・設定方法、また拡張方法までを網羅しています。不明な点があれば開発者まで連絡をください。
なお、Auto Complete ModeはGPLv3のもとでライセンスされています。また、このドキュメントはGFDLのもとでライセンスされています。
Auto Complete Modeのトップページからダウンロードできます。
パッケージディレクトリ内のetc/install.elというインストールスクリプトを利用すれば簡単にインストールを行うことができます。
起動中のEmacsあるいは新しく起動したEmacsでM-x load-file RETと入力してください。なおauto-complete-modeをアップグレードする場合は-qオプションで新しく起動したEmacsでインストールを行ってください。auto-complete-modeロードするファイル名を尋ねられるのでアーカイブを展開したディレクトリに/etc/install.elを追加したフルパスを入力します。例えば展開したディレクトリのパスが~/tmp/auto-complete-1.2である場合、~/tmp/auto-complete-1.2/etc/install.elと入力します。
次にインストール先のディレクトリを尋ねられますので、お好みディレクトリを入力してください。このディレクトリがload-pathに設定されていない場合は後で設定する必要があります。デフォルトでは~/.emacs.dです。
最後にRETを押してインストールを開始してください。インストールが完了すると次のようなバッファが表示されるので、指示に従って.emacsを編集してください。
あるいは、次のようにターミナルからインストールすることもできます。
$ make install
$ # あるいはディレクトリをあらかじめ指定して
$ make install DIR=$HOME/.emacs.d/
GNU Makeがない場合は次のようにします。
$ emacs -batch -l etc/install.el
インストール後のメッセージ例（*Installation Result*バッファ）
Successfully installed!
Add the following code to your .emacs:
(add-to-list 'load-path "~/.emacs.d") ; load-pathにすでに設定されている場合は表れません
(add-to-list 'ac-dictionary-directories "~/.emacs.d/ac-dict")
(require 'auto-complete-config)
(ac-config-default)
ディレクトリ構成と設定が正しければ手動によるインストールも可能です。まず展開したディレクトリにおいて全ての.elファイルに対してバイトコンパイルを実行してください。UNIX系OSであれば同封のMakefileを利用できると思います。
$ make byte-compile
Makefileを利用できない場合は、EmacsからC-x dで展開したディレクトリを開き* . el RET B RETで.elファイルをバイトコンパイルしてください。
次に全て.elファイルと.elcファイルをload-pathが通ったディレクトリにコピーします。例えばそのディレクトリが~/.emacs.dであれば次のようなコマンドを実行します。
$ cp *.el *.elc ~/.emacs.d
次に辞書ファイルをインストールします。このファイルがなくても動作しますが、特に理由がなければインストールしたほうがよいでしょう。辞書ファイルはdictディレクトリに格納されており、auto-complete.elがインストールされたディレクトリと同じディレクトリにインストールされる必要があります。例えばauto-complete.elを~/.emacs.dにインストールしたのであれば、~/.emacs.dにdictディレクトリをコピーします。この際、既存のファイルを上書きしないようにしてください。おそらくそのようなケースは起こらないと思いますが、上記のインストールスクリプトではac-dictという名前のディレクトリに辞書ファイルを格納することにより、他のファイルを上書きしたり干渉する可能性を最小限にしています。
$ cp -r dict ~/.emacs.d
最後に.emacsに次のような設定を記述します。
(add-to-list 'ac-dictionary-directories "~/.emacs.d/dict")
(require 'auto-complete-config)
(ac-config-default)
load-pathの設定が行われていない場合は次のコードも記述する必要があります。
(add-to-list 'load-path "~/.emacs.d")
Emacsを再起動するか新規に起動して*scratch*バッファで適当な文字を入力してください。補完メニューが表われて補完が開始されればインストール成功です。エラーが出たり補完が開始されない場合は以下のことを確認した後、開発者に連絡してください。
load-pathは正しいか
auto-complete.elをインストールしたディレクトリがload-pathに設定されているかどうか。
モードラインにACという文字があるか
モードライン（バッファ下部の灰色の行）にACという文字がない場合はauto-complete-modeが有効になっていない可能性があります。M-x auto-complete-modeで有効にして再度試してください。
エラーが発生
*Backtrace*バッファにエラーが表示されたり、ミニバッファ（フレーム下部の入力欄）にエラーメッセージが表示された場合は、その内容を添付のうえ開発者に連絡してください。
出鼻をくじくようですが、ある意味ではauto-complete-modeには「使い方」が存在しません。というのも、Emacsの編集システムに自然に溶け込むようにauto-complete-modeが設計されているからです。ユーザーは快適な編集操作を邪魔されることなく、高度な補完機能を自動的に享受することができるのです。究極的には、ユーザーのいかなる指示もなしにユーザーが望むように自動的に補完することが目標となりますが、100%の補完推測は現実的に不可能です。その点をカバーするために若干の「使い方」が存在します。この節ではその「使い方」を説明します。
まず基本となるのが文字入力です。文字が入力されなければ補完もできません。ではどの文字が入力されたときに補完が開始されるのかという疑問がわくと思いますが、それを説明するのは難しいのでここでは割愛します。簡単に言えば、キーの押し込みによる単純な文字追加時に補完が開始されます。詳しくはac-trigger-commandsを参照してください。
補完が開始されるとTABによる補完が一時的に有効になります。TABによる補完はauto-complete-modeにおいて最も重要で最もよく使う操作です。TABは状況によって様々な意味を持ちます。
補完候補が一つしかない場合
補完候補が一つの場合は、その補完候補で補完を実行します。
補完候補に共通部分がある場合
例えばsという単語の補完候補が全てsetではじまる場合、その共通部分はsetであると解釈され、TABによってsetまで展開されます。
その他の場合
その他の場合、TABを押すごとに補完候補を先頭から順繰りで選択していきます。補完候補の末尾にきたら再び補完候補の先頭から選択していきます。
設定によって若干挙動が異なりますが、基本的にはこのような挙動になります。このようにTABに様々な意味を持たせるのは、TABのみで全て完結させようという狙いがあります。
TABによる補完と似ていますが、RETによる補完は以下の点で異なります。
TABによる補完では共通部分の展開などで何度かTABを押す必要があります。RETによる補完では選択中の補完候補で即時に補完されるので、目的の補完候補であると視認したならRETを押すとよいでしょう。その際、アクションというのものが実行される可能性がありますが、ここでは詳しくは触れません。アクションの例としては、標準添付の略語補完が分かりやすいでしょう。wwwをWorld Wide Webと展開する略語が登録されている時、wという単語でwwwを補完することができますが、RETによる補完の場合は、さらに略語展開を行いWorld Wide Webと補完します。つまりTABによる補完ではwwwが最終的な補完結果になり、RETによる補完ではWorld Wide Webが最終的な補完結果になります。
auto-complete-modeの考え方に従えば、補完候補の選択は推奨されるものではありません。なぜなら、その時点でユーザーの補完推測に失敗しており、さらにユーザーに補完候補を選択させるというオーバーヘッドの高い操作を要求しているからです。補完候補の選択はTABによる補完でもある程度補うことができ、さらに最近のバージョンでは統計的手法によって補完推測の精度があがっているので、補完候補の選択が必要になるケースはそれほど多くないと考えられます。しかし、実際にそのようなケースは存在するので、補完候補の選択方法を覚えておくのも悪いことではないかもしれません。
前置きが長いですが、補完候補の選択自体は難しい操作ではありません。補完中にカーソルキーあるいはM-p, M-nで前後に選択することができます。設定によりますが、補完候補の選択が行われた後はTABによる補完がRETによる補完に近い挙動に変化します。詳しくはac-dwimを参照してください。
その他の方法としてMetaキーと数字の組合せで選択することもできます。例えばM-1を押せば1番目の候補を選択して補完します。これもオーバーヘッドが大きいので極力使わないでください。
auto-complete-modeにはクイックヘルプとバッファヘルプの二つのヘルプ機能が備え付けられています。両者の違いは見せ方だけです。クイックヘルプは補完メニューのすぐ隣に表示するので、視線の移動が最小限で済むというメリットがありますが、表示領域が狭すぎると可読性が低くなるというデメリットがあります。またクイックヘルプは補完メニューを表示してからしばらく待つと自動的に表示されます。クイックヘルプを利用するにはac-use-quick-helpをtにしておく必要があります。表示までの時間はac-quick-help-delayで制御できます。
一方、ユーザーが明示的に命令することで表示されるのがバッファヘルプです。バッファヘルプはその名の通り、別ウィンドウにヘルプ用バッファを表示します。クイックヘルプに比べて視線の移動が大きい分、、可読性に優れています。バッファヘルプを表示するには補完中にC-?あるいはf1を押します。バッファヘルプ表示後はさらにC-M-vあるいはC-M-S-vでバッファヘルプの上下スクロールが可能です。それ以外の命令の場合はバッファヘルプを閉じてフォールバックします。
補完は文字の入力によって開始されます。補完が開始されると次の表に示す操作が時的に有効になります。補完が完了したら、これらの操作は無効になります。
| キー | コマンド | 説明 |
|---|---|---|
| TAB, C-i | ac-expand | TABによる補完を実行する |
| RET, C-m | ac-complete | RETによる補完を実行する |
| down, M-n | ac-next | 次の候補を選択する |
| up, M-p | ac-previous | 前の候補を選択する |
| C-?, f1 | ac-help | バッファヘルプを表示する |
補完を途中で中断するにはC-gを使うとよいでしょう。
前節に引き続いて、もう少し高度な使い方を説明します。とはいってもあくまでユーザーの視点での話なので、auto-complete-modeを意のままに操りたいという方は、次節以降を読み進めるとよいでしょう。
auto-completeコマンド基本的にauto-complete-modeは自動的に補完を開始するという前提がありますが、その限りではない場合もあります。例えば、文字は入力しないけど補完はしたいという場合や、設定によって自動的に補完が開始されないようにしている場合などです。そのような時に利用するのがauto-completeというコマンドで、普通は何らかのキーに割り当てて利用します。例えば従来のM-TABによる補完を、auto-complete-modeが提供するより高度な補完に切り替えるには次のコードを評価します。
(define-key ac-mode-map (kbd "M-TAB") 'auto-complete)
さて、auto-completeコマンドに関してですが、これは通常の自動的な補完とは若干異なる挙動になっています。
補完候補が一つしかない場合
補完メニューを表示しないで、そのまま補完を実行します。
補完候補が一つもない場合
曖昧マッチによる補完を試みます。詳しくは曖昧マッチによる補完を参照してください。
その他の場合
その他の場合、全体共通部分を展開しつつ補完メニューを表示して補完を開始します。その後の操作は自動的に補完が開始された場合と同じになります。ac-show-menu-immediately-on-auto-completeとac-expand-on-auto-completeも参照してください。
auto-completeコマンドで補完候補が一つもない場合やac-fuzzy-completeコマンドが実行された場合、通常の確実なマッチではなく曖昧なマッチによって補完を試みます。曖昧マッチのパラメータはあらかじめ最適化されているのでユーザーが変更する必要はありませんが、内部を知りたい場合はfuzzy.elを参照してください。曖昧マッチによる補完を利用すれば、タイポも補完の一環として修正することができます。例えば適当なバッファでmessaegと入力してM-x auto-completeあるいはM-x ac-fuzzy-completeしてください。曖昧マッチに成功したらカーソルの色が赤色に変化し、messaegではなくmessageであると解釈して補完を継続することができます。このようなケースにすぐさま対処するという意味でもauto-completeコマンドを何らかのキーに割り当てておくのは決して悪いことではありません。
補完中にC-sを押すことで絞り込みを開始できます。絞り込みが開始されるとカーソルの色が青色に変化します。その後に続いて絞り込む文字列を入力していきます。絞り込みはインクリメンタルに更新されるので直感的に理解できると思います。絞り込みの最中でもTABによる補完や候補選択を行うことができます。その際、カーソルの色が元に戻りますが、これは絞り込みが終了したことを意味しています。再度C-sを押したときは、前回の絞り込み文字列が復元されます。絞り込み文字列を削除するにはDELまたはC-hを押してください。それ以外の一般的な編集操作はここでは利用できません。
auto-completeコマンドをどのキーに割り当てるかは結構難しい問題です。補完という操作は頻繁に行うため、できるだけ押しやすいキーに割り当てるべきです。しかし押しやすいキーはすでに他のコマンドに割り当てられているというのはEmacsでは非常によくあることなのです。そういうケースに対処するためauto-complete-modeはトリガーキーと呼ばれる機能を提供しています。トリガーキーを利用すれば、任意のキーを必要なときに一時的にのっとってauto-completeコマンドに割り当てることができます。例えばTABをトリガーキーに設定するには次のようになります。
(ac-set-trigger-key "TAB")
トリガーキーは文字入力の直後に有効になります。それ以外の場合は通常のコマンドが実行されます（TABならインデント）。通常、トリガーキーはac-auto-startをnilにして利用します。
(setq ac-auto-start nil)
ac-auto-startに関しては自動的に補完しないあるいはac-auto-startを参照してください。
auto-complete-modeはユーザーの補完行動を逐一解析して、可能な限り補完のオーバーヘッドを削減しようとします。具体的には、例えば何度かfoobarが補完されれば、次回以降はfoobarが補完候補の上位に配置され、一回あるいは数回以内のTABで補完できる環境を作ります。内部的にはcomphistと呼ばれる機構を使っており、ac-use-comphistがtの場合にこの機能が有効になります。デフォルトでは有効になっています。収集された行動データはuser-emacs-directoryあるいは~/.emacs.dにac-comphist.datというファイル名で永続化され、次回以降も再利用されます。
優れた補完推測を実現するため、次の二つのデータを収集します。
簡単に言えば、単純に補完回数を数えるのではなく、補完位置ごとに補完回数を数えていき、その補完候補のスコアは補完されている位置との比較でうまく重み付けされます。例えばfと入力してfind-fileを補完するという行動を何度か繰り返せば、fを入力した段階でfind-fileが上位に配置されます。ただ、続けてfind-と入力したときにfind-fileが先ほどと同じスコアになるかといえば、そういうわけではなく、先ほどと位置として4離れているわけですから、それだけ重み付けが軽くなります。逆にfind-の後にfind-libraryが補完されやすい場合は、そちらの補完候補のスコアのほうが上位に来る可能性が高くなるので、結果的にfの時点ではfind-fileが上位に、find-の時点ではfind-libraryが上位に来るといった、ユーザーの行動を学習したかのような推測が可能になるわけです。
ユーザーはこの機能をできるだけ活用するために、よく入力する単語はできるだけ前の位置で補完するように心がけてください。また、できるだけ行動は一貫してください。補完位置が毎回変わるようではうまく学習できないからです。おそらくあまり気にせず使っていれば、自動的にそのような行動になるでしょう。
辞書とは単純な文字列のリストのことであり、それぞれユーザー定義辞書、メジャーモード辞書、拡張子辞書の3つがあります。なお、辞書による補完を利用するには情報源にac-source-dictionaryを設定しておく必要があります（デフォルトでは設定済み）。詳しくは情報源を参照してください。
ユーザー定義辞書はac-user-dictionaryに設定された文字列リストおよびac-user-dictionary-filesで指定された辞書ファイルで構築されます。辞書ファイルは改行で区切られた単語の一覧です。ユーザー定義辞書は全てのバッファで共通です。例えば自分のメールアドレスを辞書に登録する場合、次のようにac-user-dictionaryに単語を追加します。
(add-to-list 'ac-user-dictionary "foobar@example.com")
設定は直ちに反映されます。試しに適当なバッファでfooと入力してください。foobar@example.comが補完候補になると思います。この設定はEmacsを終了したら消去されます。永続化させるためには.emacsに記述しておく必要があります。
(setq ac-user-dictionary '("foobar@example.com" "hogehoge@example.com"))
もっと分かりやすいのは辞書ファイルを利用する方法です。ac-user-dictionary-filesに指定されているファイルは辞書ファイルとして扱われます。デフォルトで~/.dictが辞書ファイルになるので、~/.dictを開いて次のように記述してください。
foobar@example.com
hogehoge@example.com
前述したように改行が単語の区切りになります。保存してもすぐには反映されません。コストの高い辞書ファイルの読み込みを抑えるためにキャッシュを使っているからです。キャッシュを消去するにはM-x ac-clear-dictionary-cacheを実行します。後は先ほどと同じように適当なバッファで文字を入力すれば定義した単語を補完できるようになると思います。
言うまでもないかもしれませんが、ac-user-dictionary-filesに任意の辞書ファイルを追加することで、違う辞書ファイルを読み込むことも可能です。
メジャーモードや拡張子ごとに違う辞書を利用することもできます。辞書はac-dictionary-directoriesに設定されたディレクトリから読み込まれます。ac-dictionary-directoriesはインストール時に次のように設定しているはずです。
(add-to-list 'ac-dictionary-directories "~/.emacs.d/ac-dict")
このディレクトリにはc++-modeのようなメジャーモードのための辞書ファイルやtxtのような拡張子のための辞書ファイルが格納されています。例えばa.cppというバッファで辞書による補完を利用する場合、上記の設定を前提にすれば、~/.emacs.d/ac-dict/c++-modeと~/.emacs.d/ac-dict/cppから辞書が読み込まれます。ユーザーはこれらの辞書ファイルを変更することができますし、また新しく追加することもできます。さらに、同様の構成のディレクトリを作成してac-dictionary-directoriesに追加することで、辞書ファイルを追加することも可能です。この際、ac-dictionary-directoriesの先頭にあるディレクトリが優先されることに気をつけてください。
ユーザー定義辞書と同様、辞書の追加・編集後はM-x ac-clear-dictionary-cacheでキャッシュを消去してください。
auto-complete-modeの拡張性を保証しているのがこの情報源という概念です。情報源とは簡単に言えば、下記する事柄をひとまとめに記述したものと言えます。
Emacs Lispについて若干の知識があれば誰でも簡単に情報源を定義することができます。情報源の定義に関しては拡張方法を参照してください。ここでは情報源の利用方法と標準添付されている情報源について説明します。
情報源の名前はac-source-で始まる慣習となっています。そのためaproposを使ってどのような情報源が定義されているか調べることができます（M-x apropos RET ^ac-source-)。ac-source-filenameやac-source-dictionaryなどが見付かると思いますが、これらが情報源と呼ばれる実体になっています。
.emacsに(ac-config-default)を記述している場合、デフォルトで最適な設定が使われるので、おそらく情報源の設定を変更するケースはまれだと思いますが、一応簡単に触れておきます。情報源はac-sourcesという変数にリストとして設定されます。インストール直後に*scracth*でac-sourcesを評価すると次のような結果になると思います。
;; 整形済み
(ac-source-filename
ac-source-functions
ac-source-yasnippet
ac-source-variables
ac-source-symbols
ac-source-features
ac-source-abbrev
ac-source-words-in-same-mode-buffers
ac-source-dictionary)
見てのとおり、*scratch*バッファのac-sourcesには6つの情報源が設定されていることがわかります。それぞれの説明は後述しますが、大体の意味は推測できるでしょう。大事なことなので記憶しておいてほしいのですが、ac-sourcesはバッファーローカル変数になっており、バッファごとに独立した設定を許可しています。つまりあるバッファでac-sourcesを変更しても、他のバッファには影響がないことになります。
例を示します。今、*scratch*バッファにいると考えてください。上記のように、このバッファには多くの情報源が設定されています。多機能すぎると感じるユーザーもいるでしょう。そこで、もう少し機能を制限するためにac-sourcesの変更を考えます。変更方法は簡単で、次のようなコードを*scratch*バッファあるいはM-:で評価するだけです。
(setq ac-sources '(ac-source-symbols ac-source-words-in-same-mode-buffers))
この例では、ac-sourcesを減らして、シンボル補完と同一メジャーモード間での単語補完のみを有効にしました。さて、これを次のEmacsの起動時にも有効にするにはどうしたらよいのでしょうか。*scratch*バッファ作成時にemacs-lisp-mode-hookというフックが実行されるので、このフックに適当な関数を追加するのがよいでしょう。
(defun my-ac-emacs-lisp-mode ()
(setq ac-sources '(ac-source-symbols ac-source-words-in-same-mode-buffers)))
(add-hook 'emacs-lisp-mode-hook 'my-ac-emacs-lisp-mode)
.emacsに(ac-config-default)が記述されている場合は、上記の方法では正しく動作しないかもしれません。というのも(ac-config-default)内部で同様のことを行っているので、どちらかが設定を上書きしてしまうからです。その場合は(ac-config-default)で利用する関数を再定義してしまうのがよいでしょう。emacs-lisp-modeの場合は、その関数名はac-emacs-lisp-mode-setupです。詳しくはauto-complete-config.elを参照してください。
(defun ac-emacs-lisp-mode-setup ()
(setq ac-sources '(ac-source-symbols ac-source-words-in-same-mode-buffers)))
さて、これで特定のメジャーモードで情報源を変更する方法が分かったと思います。まとめると次のようになるでしょう。
ac-sourcesを変更する関数を定義するadd-hookで適当なモードフックにその関数を登録する（c++-mode-hook, ruby-mode-hook, python-mode-hookなど）では、全てのバッファに対してac-sourcesを設定するにはどうしたらよいのでしょうか。その場合はsetqではなくsetq-defaultでac-sourcesを設定します。そうするとバッファローカル変数であるac-sourcesのデフォルト値が設定した値になります。
(setq-default ac-sources '(ac-source-words-in-all-buffer))
他にも方法があります。(ac-config-default)はauto-complete-modeのフックであるauto-complete-mode-hookに関数を追加することにより、setq-defaultによるデフォルト値の変更に近いことをやっています。その関数はac-common-setupであり、ac-sourcesの先頭にac-source-filenameという情報源を追加しています。これによりauto-complete-modeが有効な全てのバッファでac-source-filenameが情報源の先頭に追加されます。なぜ先頭なのかというと、これにはオムニ補完の仕様が関係しているのですが、とりあえずここでは気にしなくてもいいです。つまるところ、(ac-config-default)を使っていて共通してac-sourcesを変更したい場合は、このac-common-setup関数を再定義することも一つの手段となります。
;; 全てのバッファの`ac-sources`の末尾に辞書情報源を追加
(defun ac-common-setup ()
(setq ac-sources (append ac-sources '(ac-source-dictionary))))
auto-complete.elおよびauto-complete-config.elに定義されている情報源の一覧です。
ac-source-abbrevEmacsの略語機能のための情報源です。略語機能に関してはinfo emacs Abbrevsを参照してください。
ac-source-css-propertyCSSプロパティのための情報源です。
ac-source-dictionary辞書のための情報源です。辞書に関しては辞書による補完を参照してください。
ac-source-eclimEmacs-eclimのための情報源です。
ac-source-features(require 'で有効なfeatureを補完するための情報源です。
ac-source-filenameファイル名を補完するための情報源です。/を入力した時点で補完が開始されます。
ac-source-files-in-current-dirカレントディレクトリのファイルを補完するための情報源です。eshellなどで便利かもしれません。
ac-source-functionsEmacs Lispの関数を補完するための情報源です。(の直後で有効です。
ac-source-gtagsGlobalのタグを補完するための情報源です。
ac-source-imenuimenuノードを補完するための情報源です。詳しくはinfo emacs imenuを参照してください。
ac-source-semanticSemanticのための情報源です。C/C++でメンバー名補完として利用できます。
ac-source-semantic-rawac-source-semanticと違って、この情報源は生の名前空間でシンボルを補完するのに使います。
ac-source-symbolsEmacs Lispのシンボルを補完するための情報源です。
ac-source-variablesEmacs Lispの変数を補完するための情報源です。
ac-source-words-in-all-buffer全てのバッファの単語を補完するための情報源です。ac-source-words-in-same-mode-buffersと違って、メジャーモードを考慮しません。
ac-source-words-in-buffer現在のバッファの単語を補完するための情報源です。
ac-source-words-in-same-mode-buffers現在のバッファと同じメジャーモードの全てのバッファの単語を補完するための情報源です。例えばa.cppとb.cppでは単語が共有されますが、a.plとb.cppではメジャーモードが異なるので単語が共有されません。通常はac-source-words-in-all-bufferよりこちらのほうが使い勝手がよいでしょう。
ac-source-yasnippetYasnippetのスニペットを補完・展開するための情報源です。
補完メニューが現われたり消えたりすると、編集操作に集中できないというユーザーがいます。私の経験では得てしてEmacsの上級ユーザーなのですが、とにかくauto-complete-modeはそのような用途も想定しています。次のようにac-auto-startをnilにすることにより自動的に補完されなくなります。
(setq ac-auto-start nil)
この際、auto-completeコマンドを何らかのキーに割り当ておくべきです（じゃないと補完できないので）。例えば次のようにac-mode-map（auto-complete-modeが有効なバッファで利用できるキーマップ）に割り当てたり、
(define-key ac-mode-map (kbd "M-TAB") 'auto-complete)
あるいはグローバルキーマップに割り当てるのもよいでしょう。
(global-set-key "\M-/" 'auto-complete)
また、自動的に補完してもいいけど、もう少し長い単語のときだけ補完を開始するということも可能です。例えば4文字以上の単語のときに補完を開始するにはac-auto-startに4を設定します。
(setq ac-auto-start 4)
ac-auto-startを大きめの数値に設定するのはパフォーマンスに良い影響をもたらします。ac-auto-startが小さい数値だと、必然的に補完候補数が増えるので、それだけ補完候補の生成にかかるコストが大きくなります。もしauto-complete-modeが重いと感じるならac-auto-startに大きめの数値を設定するかnilを設定するとよいでしょう。
ac-auto-startに関してはac-auto-startを参照してください。
またトリガーキーを利用も考慮してみてください。
補完メニューによって集中力が削がれる問題のもう一つの対処としては、補完メニューを表示しないという方法が考えられます。補完メニューを非表示にするにはac-auto-show-menuをnilにします。
(setq ac-auto-show-menu nil)
これで補完メニューは自動で表示されなくなりますが、補完候補の選択や絞り込みを行うと補完メニューは表示されます。
あるいは補完メニューの表示を遅延させることにより、補完メニューが必要な時だけ自動で表示させるようにすることも可能です。そのためにはac-auto-show-menuに実数で遅延する時間を秒単位で設定します。
;; 0.8秒後に自動で表示
(setq ac-auto-show-menu 0.8)
このインターフェースはデフォルトの完全自動補完と上記した非自動補完のよいところだけを組合せたものと言えます。将来はこれがデフォルトになるかもしれません。
補完の中止はC-gで行うことができますが、マクロ定義中などはC-gしたくないでしょう。そのような場合はac-completing-mapに補完を中止するキーを割り当てるとよいでしょう。
(define-key ac-completing-map "\M-/" 'ac-stop)
これで補完中でもM-/で中止することができます。
上記したようにTABには様々な挙動が定義されています。auto-complete-modeを正しく使いこなすにはTABとRETによる補完を使いわけなければなりませんが、RETはそのまま改行でTABで補完完了するといった単純な操作方法も十分考えられます。。そのような場合は次のように設定します。
(define-key ac-completing-map "\t" 'ac-complete)
(define-key ac-completing-map "\r" nil)
次のコードを評価することでC-n/C-pで補完候補を選択できますが、これでは邪魔だと感じることがあります。
;; 良くない設定
(define-key ac-completing-map "\C-n" 'ac-next)
(define-key ac-completing-map "\C-p" 'ac-previous)
そこで補完メニュー表示時のみにC-n/C-pで補完候補を選択できるようにして、キー入力を極力奪わないようにしてみます。ac-menu-mapは補完メニューが表示されているときに利用されるキーマップで、ac-use-menu-mapがtのときに有効になります。
(setq ac-use-menu-map t)
;; デフォルトで設定済み
(define-key ac-menu-map "\C-n" 'ac-next)
(define-key ac-menu-map "\C-p" 'ac-previous)
詳しくはac-use-menu-mapおよびac-menu-mapを参照してください。
補完中に1秒ほど待ったときに出てくるツールチップヘルプをクイックヘルプと呼んでいますが、これを利用したくない場合は次のように設定します。
(setq ac-use-quick-help nil)
ac-menu-heightに行数を設定します。
;; 20行分表示
(setq ac-menu-height 20)
auto-complete-modeを有効にするac-modesに設定されていないモードでは自動でauto-complete-modeが有効になりません。適宜設定してください。
(add-to-list 'ac-modes 'brandnew-mode)
大文字・小文字の区別方法を設定するにはac-ignore-caseに次のように設定します。
;; 大文字・小文字を区別しない
(setq ac-ignore-case t)
;; 補完対象に大文字が含まれる場合のみ区別する
(setq ac-ignore-case 'smart)
;; 大文字・小文字を区別する
(setq ac-ignore-case nil)
デフォルトはsmartです。
ac-ignoresに自動的に補完を中止する単語を設定します。例えばRubyでendと入力した後に自動的に補完を中止するには以下のようにします。
(add-hook 'ruby-mode-hook
(lambda ()
(make-local-variable 'ac-ignores)
(add-to-list 'ac-ignores "end")))
ac-ignoresはバッファローカル変数ではないので、バッファ特有の設定にする場合はmake-local-variableで適宜バッファローカルにする必要があります。
色の設定はそれぞれ次のようになっています。
| フェイス名 | 説明 |
|---|---|
ac-completion-face |
インライン補完の文字色 |
ac-candidate-face |
補完メニューの背景色 |
ac-selection-face |
補完メニューの選択色 |
フェイスの背景色を変更するにはset-face-background、前景色を変更するにはset-face-foreground、下線の設定にはset-face-underlineを使います。
;; 設定例
(set-face-background 'ac-candidate-face "lightgray")
(set-face-underline 'ac-candidate-face "darkgray")
(set-face-background 'ac-selection-face "steelblue")
情報源について分からない場合は最初に情報源を参照してください。デフォルトの情報源（全てのバッファに共通）を変更するにはsetq-defaultを使います。
(setq-default ac-sources '(ac-source-words-in-all-buffer))
例えばC++のバッファでは特定の情報源を利用したいということがあるでしょう。その場合はadd-hookでフックを登録して、適宜ac-sourcesを変更するにようします。
(add-hook 'c++-mode (lambda () (add-to-list 'ac-sources 'ac-source-semantic)))
特定の情報源で補完することも可能です。例えばファイル名補完を行いたい場合はM-x ac-complete-filenameとします。あるいはC/C++のメンバー名補完を行いたい場合はM-x ac-complete-semanticとします。普通は次のようにこれらのコマンドをキーバインドします。
;; C++モードにもC-c .でメンバー名補完
(add-hook 'c++-mode-hook
(lambda ()
(local-set-key (kbd "C-c .") 'ac-complete-semantic)))
;; C-c /でファイル名補完
(global-set-key (kbd "C-c /") 'ac-complete-filename)
一般的に、このようなコマンドは自動的に定義されます。例えばac-source-foobarという情報源を定義しているとすれば、ac-complete-foobarというコマンドも同時に自動的に定義されるのです。利用可能なコマンドは標準情報源を参照してください。
一つの補完コマンドで複数の情報源を使うには次のように別途定義する必要があります。
(defun semantic-and-gtags-complete ()
(interactive)
(auto-complete '(ac-source-semantic ac-source-gtags)))
auto-complete関数はac-sourcesの代替を引数として取ることができます。
ac-helpの代わりにac-persist-helpを使ってください。デフォルトでM-<f1>とC-M-?に割り当てられています。
ac-last-helpコマンドは最後に補完した候補のヘルプをac-help（バッファヘルプ）と同じ形式で表示してくれます。C-uで引数をあたえるかac-last-persist-helpを呼び出すことで、そのヘルプバッファを永続的に表示することも可能です。
ac-last-quick-helpコマンドは最後に補完した候補のヘルプをac-quick-help（クイックヘルプ）と同じ形式で表示してくれます。例えば、後から関数のドキュメントを見るときなどに便利です。
これらのコマンドは次のようにキーバインドするとよいでしょう。
(define-key ac-mode-map (kbd "C-c h") 'ac-last-quick-help)
(define-key ac-mode-map (kbd "C-c H") 'ac-last-help)
pos-tip.elがインストールされている場合、auto-complete-modeは従来のレンダリングエンジンの代わりに、pos-tip.elが提供するネイティブレンダリングエンジンを利用してヘルプを表示します。
それぞれの設定項目は.emacsで変更するかM-x customize-group RET auto-complete RETで変更可能です。
ac-delay補完可能になるまでの遅延時間（秒）を実数で指定します。小さいほど瞬時に反応しますが、パフォーマンスの低下につながります。
ac-auto-show-menu補完時に自動的に補完メニューを表示するかどうかです。tの場合は常に自動的に表示します。nilの場合は絶対に表示されません。実数を指定すると表示までの遅延時間を秒数で指定できます。
ac-show-menu-immediately-on-auto-completeauto-complete時にただちに補完メニューを表示するかどうかです。すでにインライン補完が表示されている場合は、この設定は無視されます。
ac-expand-on-auto-completeauto-complete時に補完候補全体の共通部分を展開するかどうかです。
ac-disable-faces自動補完を無効にするフェイス名をシンボルのリストで指定します。カーソル位置のフェイステキストプロパティがそのリストに含まれる場合に自動補完が無効になる仕組みです。
ac-stop-flymake-on-completing補完時にFlymakeを中止するかどうかです。
ac-use-fuzzy曖昧マッチによる補完を利用するかどうかです。
ac-fuzzy-cursor-color曖昧マッチによる補完時にカーソルの指定した色に変更します。nilの場合は変更しません。利用できる色はM-x list-colors-displayで確認できます。
ac-use-comphist補完推測機能を利用するかどうかです。nilにすると利用しませんが、パフォーマンスが向上する可能性があります。
ac-comphist-threshold低いスコアの補完候補を排除する閾値をパーセンテージで指定します。スコアの全体を100%とします。
ac-comphist-file補完推測機能のデータを永続化するファイルを指定します。
ac-use-quick-helpクイックヘルプを利用するかどうかです。
ac-quick-help-delayクイックヘルプを表示するまでの時間（秒）を実数で指定します。
ac-menu-height補完メニューの行数を整数で指定します。
ac-quick-help-heightクイックヘルプの行数を整数で指定します。
ac-candidate-limit補完候補数を制限します。整数が指定されている場合は、その値を表示する補完候補数の上限にします。nilの場合は無制限です。
ac-modesglobal-auto-complete-modeが有効な時にauto-complete-modeが自動的に有効になるモードをシンボルのリストで指定します。
ac-compatible-packages-regexp自動補完を開始するコマンドのパッケージを正規表現で指定します。
ac-trigger-commands自動補完を開始するコマンドをシンボルのリストで指定します。self-insert-commandがデフォルトですが、まれに文字の挿入を独自のコマンドに設定しているモードがあるので、その対応のための設定項目です。
ac-trigger-commands-on-completingac-trigger-commandsと同様ですが、補完中に使用される点が異なります。
ac-trigger-keyトリガーキーを指定します。
ac-auto-start補完が自動的に開始されるかどうかを指定します。tの場合は常に自動的に開始されます。nilの場合は絶対に自動的に開始されません。整数の場合は、補完対象文字列の長さがその値以上になるまで自動的に開始されません。
ac-ignores補完しない文字列を文字列のリストで指定します。
ac-ignore-case補完時に大文字・小文字を区別するかどうかです。tの場合は常に無視します。nilの場合は無視しません。シンボルでsmartが指定された場合は、補完対象文字列に大文字が含まれる場合のみ区別します。
ac-dwim"Do What I Mean"機能です。tの場合は次の挙動になります。
ac-use-menu-map補完メニュー表示時に特別なキーマップ（ac-menu-map）を有効にするかどうかです。tかつ次の条件を満たしたときにac-menu-mapが有効になります。
ac-auto-startおよびac-auto-show-menuがnilでなく、補完を開始してから一定時間後にメニューが表示されたときauto-completeコマンドでメニューが表示されたときac-isearchコマンドでメニューが表示されたときac-use-overriding-local-map補完の選択などの補完中のキー入力が効かない場合に利用します。内部的にはoverriding-local-mapを使いますが、効果が強力すぎて他の拡張と干渉することがあるので、極力利用しないでください。
ac-completion-faceインライン補完のためのフェイスです。
ac-candidate-face補完候補の背景のためのフェイスです。
ac-selection-face選択された補完候補のフェイスです。
global-auto-complete-modeグローバルにauto-complete-modeを利用するかどうかです。
ac-user-dictionary辞書による補完のための辞書を文字列のリストで指定します。
ac-user-dictionary-files辞書による補完のための辞書ファイルを文字列のリストで指定します。
ac-dictionary-directories辞書による補完のための辞書ファイルディレクトリを文字列のリストで指定します。
ac-sources使用する情報源をリストで指定します。これはバッファローカル変数です。
ac-completing-map補完中に使用するキーマップです。
ac-menu-mapメニュー表示時に使用するキーマップです。ac-use-menu-mapも参照してください。
ac-mode-mapauto-complete-modeが有効なバッファで使用するキーマップです。
auto-complete-modeを拡張するとはつまり情報源を定義することです。この節では情報源の定義の仕方を説明します。
情報源はおおまかに言って次のような形をとります。
(defvar ac-source-mysource1
'((prop . value)
...))
見てわかる通り情報源とは単なる連想リストでしかないのです。あらかじめ定義されたプロパティ名と正しい値のペアを連想リストとして組合せるだけで情報源が定義できてしまうのです。
情報源で一番重要なプロパティはcandidatesプロパティです。このプロパティに関数あるいは式、変数を与えることで補完候補の生成を行います。プロパティの評価結果は文字列のリストであるべきです。例として補完候補としてFoo, Bar, Bazを生成する情報源を定義してみましょう。
(defvar ac-source-mysource1
'((candidates . (list "Foo" "Bar" "Baz"))))
次にこの情報源をac-sourcesに設定して実際に補完してみましょう。
(setq ac-sources '(ac-source-mysource1))
Bと入力してBar, Bazが補完候補として現われれば成功です。上記の例ではcandidatesプロパティに(list ...)という式を指定しました。ここで指定した式はバイトコンパイルされないので、よほど簡単なものでないかぎり式で指定するのはパフォーマンスの悪化をもたらします。代替策・正攻法としては関数を利用するのがよいでしょう。
(defun mysource1-candidates ()
'("Foo" "Bar" "Baz"))
(defvar ac-source-mysource1
'((candidates . mysource1-candidates)))
candidatesプロパティに指定した関数は引数なしで補完が更新される度に呼び出されます。その他の方法として変数を直接指定することもできます。
補完が開始されたときに一度だけ初期化処理を行いたいということがあります。そのためにはinitプロパティを利用します。candidatesプロパティ同様、引数なしの関数あるいは式を指定します。次に簡単な例を示します。
(defvar mysource2-cache nil)
(defun mysource2-init ()
(setq mysource2-cache '("Huge" "Processing" "Is" "Done" "Here")))
(defvar ac-source-mysource2
'((init . mysource2-init)
(candidates . mysource2-cache)))
この例ではmysource2-init関数で大規模な処理を行い、mysource2-cache変数にその結果を保存しています。そしてcandidatesプロパティにその変数を指定することで、補完が更新される度に大規模な処理が行われるのを防いでいます。この例の他にも次のような用途が考えられます。
requireするauto-complete-modeではキャッシュの戦略が重要になります。その方法として、前節で触れたinitプロパティによるものと、この節で説明するcacheプロパティによるものが基本となります。情報源の定義にcacheプロパティを設定しておくと、初回のcandidatesプロパティの結果が内部的にキャッシュされ、それ以降はcandidatesプロパティを評価する代わりに、そのキャッシュを利用するにようになります。
前節の例をcacheプロパティを利用して書き直してみます。
(defun mysource2-candidates ()
'("Huge" "Processing" "Is" "Done" "Here"))
(defvar ac-source-mysource2
'((candidates . mysource2-candidates)
(cache)))
candidatesプロパティに大規模な処理が必要な関数が指定されていますが、初回のみ実行されるのでパフォーマンスの問題は軽減されます。
initプロパティやcacheプロパティより大きいスコープでキャッシュを保持することがあります。例えば滅多に変更のない関数名のリストなどがそうです。その場合にパフォーマンスを犠牲にすることなく、適度にキャッシュをクリアするにはどうすればよいのでしょうか。auto-complete-modeはキャッシュの寿命を管理する機構を持っており、ユーザーはそこにキャッシュ用の変数を登録しておくことにより、適当なイベントごとにキャッシュがクリアされます。
バッファが保存されるたびにキャッシュをクリアするにはac-clear-variable-after-saveで変数を登録します。簡単な例を示します。
(defvar mysource3-cache nil)
(ac-clear-variable-after-save 'mysource3-cache)
(defun mysource3-candidates ()
(or mysource3-cache
(setq mysource3-cache (list (format "Time %s" (current-time-string))))))
(defvar ac-source-mysource3
'((candidates . mysource3-candidates)))
これをac-sourcesに設定してTimeで補完を行ってください。すると補完候補に補完時の時間が表示されると思います。二度目以降も同じ時間が表示されるのはmysource3-candidatesは可能な限りキャッシュを返すようになっているからです。それでは一度そのバッファを保存して、再びTimeで補完を行ってください。今度は新しい時間に更新されたと思います。この情報源のキモはac-clear-variable-after-saveでキャッシュ用変数を登録しているところにあります。
さらに定期的にキャッシュをクリアすることも可能です。そのためにはac-clear-variable-every-minuteで変数を登録します。使い方はac-clear-variable-after-saveと同じですが、一分ごとに定期的にキャッシュがクリアされる点が異なります。標準の情報源であるac-source-functionsなどがこの機能を利用しています。
RETによる補完の場合、actionプロパティで指定された関数あるいは式が評価されます。標準情報源ではac-source-abbrevやac-source-yasnippetが利用しています。
オムニ補完とは現在編集中のコンテキストを考慮して行う補完のことです。スラッシュを検出して行うファイル名補完や、ドットを検出して行うC/C++のメンバー補完は、このオムニ補完であると言えます。情報源をオムニ補完に対応させるにはprefixプロパティを使います。prefixプロパティは補完対象文字列の開始位置をポイントで返さなければなりません。nilを返した場合は、その情報源が現在のコンテキストでは無効であると解釈します。
例としてTo:の後にメールアドレスを補完する情報源を考えてみましょう。まず、これまでの知識からメールアドレスを補完する情報源を定義します。
(defvar ac-source-to-mailaddr
'((candidates . (list "foo1@example.com"
"foo2@example.com"
"foo3@example.com"))))
(setq ac-sources '(ac-source-to-mailaddr))
ここまでは簡単です。次にprefixプロパティを使ってTo:の後にのみ補完が開始されるようにします。prefixプロパティには次の三つが指定できます。
正規表現を指定した場合、その正規表現を使ってre-search-backwardを行い[1]、マッチしたグループ1あるいはグループ0の先頭位置を補完対象文字列の開始位置とします。もう少し複雑な制御が必要な場合は関数あるいは式を指定します。ここで評価された開始位置はac-pointに格納されます。先の例では次の正規表現で事足ります。
^To: \(.*\)
グループ1をキャプチャしているのはTo:を補完対象文字列に含めないためです。これをprefixプロパティに設定した最終的な情報源は次のようになります。
(defvar ac-source-to-mailaddr
'((candidates . (list "foo1@example.com"
"foo2@example.com"
"foo3@example.com"))
(prefix . "^To: \\(.*\\)")))
試しにTo:と入力してみましょう。メールアドレスが補完できるようになったら成功です。
ac-define-sourceこれまではdefvarで情報源を定義してきましたが、ac-define-sourceというユーティリティマクロを使って定義することも可能です。
(ac-define-source mysource3
'((candidates . (list "Foo" "Bar" "Baz"))))
このマクロは次のように展開されます。
(defvar ac-source-mysource3
'((candidates . (list "Foo" "Bar" "Baz"))))
(defun ac-complete-mysource3 ()
(interactive)
(auto-complete '(ac-source-mysource3)))
defvarは従来通り定義され、続いてその情報源のみで補完を行うコマンドが定義されます。auto-completeは引数なしで呼び出された場合はac-sourcesを情報源として使い、引数ありで呼び出された場合はその値を情報源として使います。defvarかac-define-sourceかどちらを使うかは微妙ですが、後方互換性を保持するならdefvarのほうが無難でしょう。ちなみに標準情報源は全てac-define-sourceで定義されています。つまりac-complete-filenameなどを他のキーに割り当てて個別に利用することができます。
init補完開始時に一度だけ指定された関数あるいは式を評価します。
candidates補完更新時に指定された関数あるいは式、変数を評価します。評価結果は文字列のリストであるべきです。cacheプロパティが有効な場合は、その補完では二度目以降評価されません。
prefix指定された正規表現、関数あるいは式を評価して、オムニ補完のための補完対象文字列の開始位置を取得します。nilを返した場合はその情報源は無視されます。正規表現が指定された場合、グループ1の開始位置あるいはグループ0の開始位置が評価値として使われます。
requires情報源が有効になる補完対象文字列の文字数を指定します。指定のない場合はac-auto-startの値が利用されます。
actionRETによる補完時に実行するアクションを関数あるいは式で指定します。
limit補完候補の上限数を設定します。ac-candidate-limitを部分的に上書きします。
symbol補完候補の意味を現わす記号を一文字の文字列で指定します。指定する記号は任意ですが、基本的に以下の慣習に従うべきです。
| 記号 | 意味 |
|---|---|
| s | シンボル |
| f | 関数・メソッド |
| v | 変数 |
| c | 定数 |
| a | 略語 |
| d | 辞書 |
summary補完候補のサマリを文字列で指定します。これは補完候補を簡潔に説明するために使うべきです。
cacheキャッシュを利用します。
require整数あるいはnilを指定します。整数が指定された場合、その値が補完対象文字列の長さより大きい場合は、その情報源は無視されます。nilの場合は常に有効になります。
candidate-face補完候補のフェイスを指定します。ac-candidate-faceを部分的に上書きします。
selection-face選択された補完候補のフェイスを指定します。ac-selection-faceを部分的に上書きします。
depends依存するfeature（requireされる）をリストで指定します。
availableこの情報源が利用できるかを示す関数あるいは式を指定します。
情報源でよく利用する変数を一覧します。
ac-buffer補完が開始されたバッファです。
ac-point補完対象文字列の開始位置です。
ac-prefix補完対象文字列です。
ac-limit現在の情報源の候補上限数です。ac-candidate-limitやlimitプロパティで制御されます。
ac-candidates補完候補のリストです。
十分なレスポンス性能を確保するのはauto-complete-modeにとって大変重要なことですが、よく知られているように、それは機能性とのトレードオフでもあります。以下にレスポンス性能に関連する設定項目を挙げるので、もし問題があれば参照してください。
ac-auto-startac-auto-startに大きめの数値を設定することで、補完候補の生成コストを軽減するができます。あるいはnilに設定することで、本当に必要な時だけ補完を実行することもできます。詳しくは自動的に補完しないを参照してください。
ac-delayac-delayに大きめの数値を設定することで、補完開始コストを軽減することができます。
ac-auto-show-menuac-auto-show-menuに大きめの数値を設定することで、補完メニューの表示コストを軽減することができます。
ac-use-comphistac-use-comphistにnilを設定して補完推測機能を無効にすることで、推測のための計算コストを軽減することができます。
ac-candidate-limitac-candidate-limitに適切な数値を設定することで、多量の計算を行わないようにすることができます。
補完メニューの表示が崩れる問題には大きく分けて二つあります。
auto-complete-modeは補完メニューを正しく表示するのに必須な処理であるカラム計算のコストを軽減するために、正確さをある程度犠牲にした最適化バージョンのカラム計算関数を利用していますが、これが原因で補完メニューの表示が崩れる可能性があります。最適化バージョンを使わないためには次のコードを評価します。
(setq popup-use-optimized-column-computation nil)
Ubuntu 9.10にてIPAフォントをXftでレンダリングすると、補完メニューの表示が崩れる問題を確認しています。VLゴシックなどではXftでレンダリングしても正しく表示されるようなので、そちらをお使いください。また、Xftを使わなければIPAフォントも正しくレンダリングできます。
現在のところ完全な対応策は見つかっていませんが、set-face-fontで補完メニューのフォントサイズを適切なサイズに変更することで対応できる可能性があります。例えばNTEmacsでは日本語を含む補完メニューを表示すると補完メニューの表示が崩れることがあります。これは以下のようにフォントサイズを調整することで対応することができます。
(set-face-font 'ac-candidate-face "MS Gothic 11")
(set-face-font 'ac-selection-face "MS Gothic 11")
flyspell-modeが有効なバッファで自動補完できないflyspell-modeの遅延手法が原因で自動補完ができません。これを回避するにはM-x ac-flyspell-workaroundとするか~/.emacsに次のように書いてください。
(ac-flyspell-workaround)
Auto Complete Modeのバグトラッキングシステムに新しいチケットを登録してください。
厳密にはその正規表現の末尾にカーソルを意味する\=を付与したものでre-search-backwardされます ↩
Title: Auto Complete Mode - 変更点 CSS: style.css
[English]
ユーザーマニュアルも参照してください。
v1.3の主な変更点は次のようになります。
ac-disable-facesac-show-menu-immediately-on-auto-completeac-expand-on-auto-completeac-use-menu-mapflyspell-modeとの衝突（M-x flyspell-workaroundで解決）v1.0からv1.2の主な変更点は次のようになります。
ac-delay)ac-auto-show-menu)