Auto Completion

From Notepad++ Wiki
Jump to: navigation, search
Auto Completion in Notepad++


Completion features in Notepad++

Notepad++ offers automatic completion of various sorts of text after you have entered an initial substring (or prefix), which can save you having to type all of a long word (and potentially save you mistyping it). For instance, if you're coding in JavaScript and type "syn", Notepad++ can present "synchronized" (a JavaScript keyword) as a suggestion. You accept the suggestion by typing Enter or Tab, and the word is completed within your buffer as if you'd typed it all out. If the suggested word is not what you want, keep typing.

If more than one word in the list of candidate words matches what you've typed, Notepad++ will present a list containing the words; the highlighted word in the list is the one that will be selected on Enter, but you can use the Down- & Up-arrow keys, or PageDown & PageUp, to move through the list; or, type Esc to dismiss the list.

Functions and Words

There are two sets of candidate words that Notepad++ uses to create suggestions; these are referred to as "words" and "functions".

"Words" are taken from the current file—everywhere in the current file, comments and code. Any word two or more characters long is added to the list. This includes numbers, but numbers with decimal points are split into two different "words."

"Functions" are pre-defined and loaded along with the lexer that corresponds to the computer language of the file. (The lexer defines the syntax coloring; the auto-completion file specifies the names of the functions.) Typically these function words include language keywords (which technically are not functions) such as "switch" in C and similar languages or "lambda" in Python, and some set of standard library function names such as "assert" or "fdopen" in C.

These function lists are stored in auto-completion definition files, each named according to its language. (The words in these files do not necessarily include all the keywords listed in the lexer definitions.) These files can specify which of the words are keywords and which are functions; functions support an additional completion feature, "parameter hint."

Automatic completion

The completion list can be triggered automatically as you type, via settings in Settings -> Preferences -> Auto-Completion: Auto-Completion is enabled by a checkbox. Additionally there is a setting "From X th character", accepting a the minimum length of a prefix needed before the completion list is shown (some people like 2, some 3, some 4...); and, there is a setting to specify which candidates should be used: words, functions, or both.

With auto-completion enabled, after typing a prefix of at least the minimum length, a list is presented with all the available words from the selected list(s) that match what's been typed. (If none match, no list is shown.) The list may be a single entry long, or it may contain multiple items which require navigation, but either way you can select the match and, it is hoped, save yourself some typing.

If instead of selecting, you keep typing, items that no longer match will be removed from the list, and it will disappear entirely once you've typed a string that matches none of the selections. (Note that if you dismiss the list with Esc, and then keep typing, and what you type continues to match wordlist entries, then the list will reappear.)

Manual completion

If auto completion is turned off, you can manually force the completion of what you've typed, limiting the selection to either the list of functions or the list of words. By default, these functions are bound to Ctrl+Space (functions) or Ctrl+Enter (words); they are also available in the Edit menu. Typing one of these keystrokes attempts an immediate completion: if there is a single matching entry in the wordlist, that entry is used, with no display of a list. If there are multiple matching entries, the list is displayed just as if auto-completion were triggered at the same point.

Note: Manual "Function completion" (currently) shows a list of all the functions in the wordlist, even if they don't match the current prefix—unless no function matches the prefix, in which case no list is shown. Manual "Word completion" shows only the matching words.

Parameter hint

As noted above, the auto-complete definition file can specify if a keyword is a function. When a function name has been typed in, followed by the opening parenthesis used to enclose the function's arguments, Notepad++ will automatically, or manually, display a hint (a.k.a. a "call tip"): a small tooltip-style box opens with text containing a description of the function. While the actual text shown is up to the author of the definition file, typically this would show, at minimum, a keyword for each of the parameters taken by the function call. This may save you a trip to the function's documentation to remember what those parameters are.

Notepad++ will display the hint automatically when the open-parenthesis is typed, if that option is selected in the Auto-Completion settings. The user can also select the "Function parameters hint" from the menu or by keystroke (default: Ctrl+Shift+Space), when the cursor is between the opening and closing parentheses of the function call. And again, the hint can be dismissed with Esc.

Calltip in action: Calltip.png

Auto-insertion

Some characters traditionally work in pairs, so that it makes sense to ask an editor to type them in pairs when an opening bracket is being typed - the extra closing brace being disposable.

Through Settings -> Preferences -> Auto-Completion, the Auto-Insert options allow selection of any or all of five predefined characters—parenthesis, bracket, brace, double-quote and single quote (apostrophe)—to be automatically matched. Not only that, three custom pairs of characters may be specified. For instance, you might use Unicode open- and close- double quotes; with this feature, you can have both characters inserted when you type the opening quote mark. (Only single characters are allowed in these fields.)

In each case, when the opening character is typed, the closing character will automatically be inserted, with the cursor placed between the two.

Additionally, Auto-Insert supports automatic HTML & XML tag closure. With this enabled, when editing HTML or XML files, after you type an opening tag, such as <div>, the program will automatically match it with the closing </div>, with the cursor placed between the two tags so that content can be added. Matching will work even if attributes are entered while typing the opening tag. And if the opening tag is terminated with a slash (/) —such as <hr/> —then no matching tag is inserted. (In the case of <hr> entered without a slash, a matching close tag will still be inserted, even if unnecessary, for both HTML and XML editing. Consider this a push towards XML correctness in your HTML code.)

Bracket insertion before Notepad++ 6.6

Up to v6.5, Notepad++ did not support auto-matching, but two plugins do:

  • TextFX has an option, TextFX -> TextFX Settings -> Autoclose {([Brace, which toggles this option on or off. But the set of brackets is not configurable.
  • XBracket Lite has three sets. It provides:
    • An option to toggle autocompletion of all active sets of brackets;
    • A Settings dialog to customize what will be autoclosed:
      • The basic set of brackets being autoclosed is made of {{[". You have the option to force autocompletion even if a closing matching bracket is detected nearby.
      • You can treat single quotes as brackets
      • The autocompletion of < by > is further customizable. You can restrict it to files the extension of which is in a given set, and ask /> to close a <. These advanced options are geared towards markup languages, which use these brackets extensively.

Further, the plugin can optionally skip brackets preceded by a backslash, since this usually means they are to be taken as normal characters.

Path completion

Last but not least, there is a path autocompletion list, invoked by the default shortcut Ctrl+Alt+Space. This feature allows you to build a path based on your current actual disk contents. The path, unfortunately, must be fully qualified per Windows, with a drive letter and colon, and supports only backslashes as delimiters; network paths cannot be completed, nor can relative paths. Completion only works from the start of the path to the point of colon, and only completes for the name immediately following the previous backslash; to complete more than one part of the path, the shortcut needs to be invoked multiple times.

How to create keyword auto-completion definition files

Since version 5.0 Notepad++ has support for so called Calltips, and has introduced a new way of storing autocomplete data. Now everything is stored in the XML format, which allows for easy extension of functionality. By doing so, autocomplete and calltip data are combined in a single file. Older .api plain text files are no longer used by Notepad++, and can be safely deleted if present.

You can choose what srt of auto-completion you wish to have, from Settings -> Preferences -> Auto Completion -> Enable Auto-completion on each input: words from the current document, functions from the current language, or both.

The AutoComplete files are located in the "plugins\APIs" folder, to be found in the Notepad++ Install Folder, most often C:\Program Files\Notepad++.

The syntax of AutoComplete files is simple, but does have a few rules, most importantly correct syntax and proper sorting. If the syntax is incorrect, the XML file will fail to load and AutoComplete will be disabled. A more formal description can be found at Editing Auto Completion files.

Improper sorting (see below) can cause the AutoComplete function to behave erratic, causing it to fail on certain words.

The basic character set used to recognise keywords is made of letters a-z, A-Z, 0-9 digits and the underscore. In future release of Notepad++, you will be able to add more characters - the dot is a likely candidate - by specifying the additionalWordChars parameter in the environment. The value will be a string with all the extra parameters without any separators. However, this additionalWordChars is still not working (Notepad++ v.6.5.2)!

Syntax:

<?xml version="1.0" encoding="Windows-1252" ?>
<NotepadPlus>
   <AutoComplete language="C++">
       <Environment ignoreCase="no" startFunc="(" stopFunc=")" paramSeparator="," terminal=";" additionalWordChar = "."/>
       <KeyWord name="abs" func="yes">
           <Overload retVal="int" descr="Returns absolute value of given integer">
               <Param name="int number" />
           </Overload>
       </KeyWord>
   </AutoComplete>
</NotepadPlus>

A small example of how the XML file is built is given above. NotepadPlus, AutoComplete and Environment are singleton elements, there should be only one of each, and all of them should be present for correctness, although it is allowed to remove the <Environment> element. Doing so will default all values to the ones given in the above example.

For keywords that are not functions, the Keyword tag is autoclosing and only has the "name" attribute. To indicate a keyword can be displayed in a calltip, add the attribute 'func' with the value "yes". In this case, the Keyword tag is a node and contains other tags.

Then, for each overload of the function, an Overload element should be added ,which specifies the behavior and the parameters of the function. A function must have at least one Overload or it will not be displayed as a calltip. The 'retVal' attribute must be present and specifies the type of the return value, but the 'descr' attribute is optional and describes the functions behavior, like a comment. You can add newlines in the description if you wish to do so. For each parameter the function takes, a 'Param' element can be added. The 'name' attribute must be present and specifies the type of the parameters and/or any name of the parameter.

In the 'AutoComplete' element you can add the 'language' attribute but it is not used by Notepad++, you can add it for completeness if you wish and can take any string you want.


Sorting

Depending on the value of the 'ignoreCase' attribute in the 'Environment' element, the XML file has to be sorted case sensitive or case insensitive (if the attribute is absent it will default to case sensitive).

The simples approach, when building an autocompletion file, may be to first define a plain text, one word a line file of words to be recognized, then sort it, then turn lines int Keyword tags, then add all Overload information as needed. The following will focus on the sorting part. A tool will be made available which will read any given XML API file and sort it properly - not released as of v6.6.6.

For case sensitive sorting you can use any generic ASCII/ANSI sorter that sorts on the byte value of the characters. Simply put this means underscore is between uppercase and lowercase letters. When you have to sort case insensitive, treat lowercase letters as uppercase, that is, subtract 32 from each one. This means the underscore comes both after uppercase and lowercase letters. The default strcmpi() function in the standard C library does not seem to work correctly, but the TextFX plugin does, which is installed by default with Notepad++.

More detailed information appears in the complete reference on Editing Configuration Files.