TextAutocomplete Plugin

by Jakub Holý

Table of Contents

Introduction

TextAutocomplete collects "words" in the current buffer and those that you type and offers you automatically a list of possible completions. It's pretty similar to the jEdit's function "Complete Word" but it's automatic, you don't need to press any key to invoke the list of completions. Contrary to "Complete Word" it doesn't search the buffer every time for possible completions. Instead of that it keeps a list of remembered words (i.e. possible completions) that is created by parsing the buffer at startup and is updated with new words that you type. You can export (save), import and modify the list of remembered words. It's also possible to import a default list of words for new buffers, see below. The plugin was inspired by a similar functionality in OpenOffice.org.

The plugin is configurable, you can define what is a "word", what words (not) to remember etc. - see below. It's also possible to modify manually the list of remembered words.

You must enable the autocompletion manually for every buffer where you want it (Plugins - TextAutocomplete - Start for buffer). Alternatively, you can enable the autocompletion for all buffers (Plugins - TextAutocomplete - Start for all buffers) or set the plugin to start automatically for every new buffer that you open (Plugins - Plugin Options... - TextAutocomplete - check "Start autom. for new buffers").

Special features

Loading default words for a buffer

Since: 0.9.8

You can create a list of words that will be loaded by default for any buffer or for any buffer with a particular extension provided that TextAutocomplete is enabled for that buffer. Every line of the file is taken as a 'word' - but see notes on the import word list function above. Currently this isn't yet configurable but it's planned for the future.

If you want some words to be readily available in any buffer using the TextAutocomplete plugin then store them into the file named autocompleteDefaultWordList under the jEdit settings directory (see Utilities - Settings Directory; for me it's /home/jholy/.jedit).

If you want some words to be loaded only for a buffer (file) with a particular extension then store them into a file with the name autocompleteDefaultWordList and the appropriate extension under the settings directory. So to load some words by default only for PHP files, create the file autocompleteDefaultWordList.php. The word list file's extension must be in lower-case (i.e. not Php). If there is an extension-specific word list file then the common word list described above is not loaded.

Keywords from buffer's syntax highlighting mode as completions

Since: 0.9.9

In jEdit each buffer has a particular edit mode, which may define special keywords that should be highlighted in a special way such as programming language's reserved words or function names. To help people using Text Autocomplete when writing code, it does load the list of keywords from the buffer's edit mode and adds it to the list of completions. In addition to that it also takes into account what characters are considered to be part of words by the edit mode (such as '@' in PHP).

Beware that some edit modes may define a large number of keywords (e.g. over 25.000 for PHP) and thus you may need to adjust the max. words to remember. With multiple buffers open this can also consume considerable memory.

By default this functionality is off and must be enabled in Options.

Words, completions and how does it work

As described above, the plugin parses the buffer and what you type to find and remember the words to offer as completions later on. But what is a word and when/how is the list of completions offered?

To consider a string as a word it must pass some tests - see the options "Belongs to word?" and "Is word to remember?". The first one determines whether the character typed may start/extend a word or whether it ends one, i.e. whether it is a word separator or a word constituent. By default only letters are regarded as constituting a word. The second option may be used to limit what words are remembered as possible completions - by default we ignore words shorter than determined by the option "Remember words long at least".

The pop-up window with completions appears when you type the beginning of a word long enough (assuming there are some completions for that prefix). The length is given by the option "Minimal prefix length". So, with the default setting, you must type at least two letters before the completions may be offered.

The important thing to note is that even though you can add arbitrary string to the list of remembered words (by importing them from a file or by adding the string by means of the "Remembered words" dialog), it will never be offered as a completion unless it satisfies the condition for the pop-up completions window to turn up, in other words it must start with a word that is at least as long as the "Minimal prefix length" - under the default setting it must start with two letters.

Please be aware that the words are case sensitive, so "Something", "something" and "someTHING" are three different words.

Control keys of the completions pop-up window

By default, the following keys may be used to control the completion pop-up window:

• Escape - Cancel (dispose) the window.
• Enter, Tab - Accept and insert the selected completion.
• Up arrow - Select the completion above the currently selected one. It cycles through the list, so pressing Up on the first entry gets you to the last one.
• Down arrow - Select the completion below the currently selected one. It cycles through the list.
• Numbers 0-9 - Accept and insert the completion with the given number. You may disable it if you want numbers to be treated as regular characters or you may set it so that <a modifier key> + number inserts a completion while number without the modifier is just appended to the current word.

Menu

Start for buffer

Enable autocompletion for the current buffer. The buffer is parsed to collect the words that already exist in it.

Stop for buffer

Disable autocompletion for the current buffer and forget all remembered words.

Parse buffer (collect words)

Scan the current buffer for words to remember and add them to the list of remembered words. You will rarely need this as buffer is scanned automatically upon start.

Forget all remembered words

Forget all words in the completions list including those from scanning the buffer and those from other sources such as the default word list.

Show remembered words

Display the list of remember words that you can edit:

1. Add a word typed in the text field; the string is remembered as is, even if normally it wouldn't be considered to be a word - but it should start as a word, see the explanation above.
2. Delete selected - forgets the words you've selected in the list. To select multiple entries use Control+click.
3. Delete all - forget all remembered words. You can Parse buffer to get them back.
   

Additionally, you can:

1. Import words - read a file with previously saved words and add them to the list. One line is considered as one word and is added to the list "as is" even if it wouldn't normally be considered as a word - but it should start as a word, see the explanation above.
2. Export words - save the remembered words into a file, one per line.

Start for all buffers

Enable autocompletion for all currently opened buffers. (To detach from all buffers, open the Plugin Manager and under Manage uncheck and re-check the TextAutocomplete plugin.)

Stop for all buffers

Disable autocompletion for all buffers that have it enabled and forget all remembered words.

Options

It's possible to set some options that will apply to autocompletion in all buffers.

When you put the mouse pointer above some of the text field on the option page and wait for a while, a tool tip with more detailed description will show up.

Start autom. for new buffers

Enable autocompletion for every new buffer that you will open from that moment on.
Default: Off

Filename filters

Specify filename glob patterns to be included or excluded from autocompletion.
Default: Include all files

The following options influence words and completions.

Remember at max. words

The maximal number of words that should be remembered as potential completions. Notice, that completions are only offered based on the list of remembered words.
Default: 1000

Minimal prefix length

Don't offer possible completions until at least the given number of characters have been typed.

Default: 2.

Remember words long at least

Don't remember words shorter than the given value.

Default: 5.

Complete keywords defined by syntax highlighting rules

Add keywords and characters that aren't considered as word separators from the buffer's syntax highlighting rules (defined by its edit mode such as 'php') to the completions list upon start. Warning: this can easily lead to reaching the limit of remembered words per buffer. If new word's aren't remembered, check the Utilities | Troubleshooting | Activity log for a line like TextAutocompletePlugin: AutoComplete.rememberWord: the max. number of remembered words(1000) has just been reached.

Default: false.

Consider only keywords from the main edit mode

When "Complete keywords defined by syntax highlighting rules" is enabled, check this to load keywords and no word separators only from the main edit mode. For example the edit mode for PHP has a number of "sub-modes" with additional keywords, over 25.450 in total. With this option you can save memory and the max. words limit while still getting completion of the most important keywords. (Unfortunately e.g. for PHP this doesn't help since its main mode contains no keywords.)

Value of the following properties is a beanshell expression that evaluates to either true or false. It can make use of special variables - see below. If the code isn't correct, BeanShell will throw an exception when it is first executed so you should make sure that it is all right; than it reverts to the default setting to prevent repetitions of the same error. The description of such an exception will mention either PreferencesManager.precompileCode or PreferencesManager.executeCachedCode and either the method accept (for "Belongs to word?") or isWordToRemember. The expression must be valid Java expression, so it should end with a semicolon.

Is word to remember? [code]

Return true if the word that has just been typed should be remembered. In addition to that, the word must also be at least as long as required by "Remember words long at least". The variable word (String) holds the word in question.

Example: ! word.startsWith("X");

Default: always true

Belongs to word? [code]

Return true when the insertion (the typed character) doesn't end the word being typed, in other words, it must return false for word separators. The available variables are prefix (String; the word that has been typed so far), insertion (char; the newly typed character), and noWordSeparators (String; characters that should not end a word, extracted e.g. from the buffer's edit mode; example: "@-_" in PHP). This determines what is considered as a word while the previous option determines whether something, that is already considered to be a word, should be remembered or not.

Example: Character.isLetterOrDigit(insertion) || insertion == '_' || (prefix.startsWith("<") && prefix.indexOf(">") == -1); // alphanumeric string or anything between < and >

Default: Character.isLetterOrDigit( insertion ) || noWordSeparators.indexOf( insertion ) >= 0;

Use the following properties to change the default control keys (see above). All of them take a list of keys separated by a single space or by a comma. A key is represented by the name of one of the constants of the class java.awt.event.KeyEvent that start with the prefix "VK_". You can only use special keys, that means keys that don't produce a character. It includes VK_ENTER, VK_ESCAPE, VK_BACK_SPACE, VK_DELETE, VK_F1 etc., VK_TAB, VK_UP, VK_DOWN and others.

Accept with key

Accept and insert the currently selected completion.

Default: VK_ENTER,VK_TAB

Dispose with key

Hide the window with completions.

Default: VK_ESCAPE

Up in completions key

Select the completion above.

Default: VK_UP

Down in completions key

Select the completion below.

Default: VK_DOWN

Select compl. by number

If checked, pressing a number inserts the completion with that index. If unchecked, the number is just inserted as an ordinary character.
Default: Checked (i.e. enabled)

Select by number modifier

If you press the selected modifier key + a number, the completion with that index is inserted. If you press only the number, it's inserted into the buffer. Note: Some of the modifiers may not work for you. There are reports of problems with AltGr.
Default: None (no modifier key, pressing the number inserts the completion)

The button Reset options resets them to the default values.

Accessing the plugin from BeanShell

If you know Java programming, you can access and control the plugin via BeanShell - either by means of the Console plugin or from a macro.

You can see the current options by calling the methods of PreferencesManager, for example
net.jakubholy.jedit.autocomplete.PreferencesManager.getPreferencesManager().getMaxCountOfWords()
To modify the options you'd need to set some properties (jEdit.setProperty) - see the file TextAutocomplete.props within the plugin's .jar archive.

You could also invoke the actions that are usually run from the menu - for example net.jakubholy.jedit.autocomplete.AutoComplete.attachAction(buffer).

To get the AutoComplete associated with the buffer, call net.jakubholy.jedit.autocomplete.AutoComplete.getAutoCompleteOfBuffer(buffer). If it returns null, you must attach one first.

See the JavaDoc for AutoComplete, PreferencesManager, WordList, Completion and TextAutocompletePlugin included with this plugin or download the plugins's source with the full API JavaDoc. You can also browse the plugin's source files via Source Forge's web interface to the SVN repository.

Development

Feedback

The preferred way to send bug reports is to use the Sourceforge Bug Tracker at http://sourceforge.net/bugs/?group_id=588 and also notify me by e-mail.

You can also write to:

Jakub Holý alias MalyVelky <malyvelky@users.sourceforge.net>;

If you find a bug, help to discover it by switching on verbose logging for the plugin - execute the following BeanShell code (paste it into a new buffer, select it and execute it via Utilities > BeanShell > Evaluate Selection):

You will need to either reload the plugin or restart jEdit to activate the change. (WordTypedListener reads the log level only upon its creation.) Look for the logs starting with "TextAutocompletePlugin:" in Utilities > Troubleshooting > Activity Log. To disable the logging again, execute:

And reload/restart.

Wish list

• Options - check that the beanshell expressions are ok before the preferences are saved
• Allow for the insertion of longer texts after a prefix (so far only 1 character can be inserted/typed)
• Support the insertion of the "longest common suffix" of two or more completions (typed: "co", possible completions: community, communist => insert (co)mmuni)
• Option to show the completion popup only after a period of inactivity (e.g. when the user stops typing for 2 seconds).

Change Log

Version 1.0.0, April 2013

• Fixed 1725711: Make it possible to accept a completion with the TAB key
• Build fixes for jEdit 5.0.0, improved docs.

Version 0.9.9, August 2009

This is a minor enhancement release.

New features:

• Add the edit mode's keywords to the buffer's list of completions and take into account its list of no word separators. By default this functionality is off and must be enabled in Options.

Version 0.9.8, September 2008

This is a bug fixes and enhancement release. Additionally, the plugin has been updated for jEdit 4.3pre15.

Bug fixes:

• Fixed the function 'Import words', which stopped working due to a change in jEdit API.
• Fixed positioning of the completion completions which was broken at least in 4.3pre15.
• Enabled the use of backspace while the completions window is visible.

New features:

• Load a default words for any buffer or for a buffer with a particular extension from a file.

Version 0.9.4, October 2006

Added the possibility to disable selection of a completion by number or to require a modifier key together with the number.

Version 0.9.3, May 2006

Added handling of backspace.

Development: added unit tests, corrections of the code (thanks to JUnit!).

Version 0.9.2, April 2006

This is a bug fixes and enhancement release. Additionally, the plugin has been updated for jEdit 4.3pre3.

Bug fixes:

• Prevent the cursor from switching buffer/view: When you edited one or two file(s) in a split view, it sometimes happened that you started writing in one and suddenly the cursor jumped into the another. This should be now fixed (We prefer jEdit.getActiveView over the remembered view). I'd like to thank Jeremias, who discovered the bug.

New features:

• Start for all opened buffers and Stop for all opened buffers
• Start automatically for new buffers
• The number of remembered words is now limited to 1000, the limit may be changed.
• It's now possible to export/import (append) the list of remembered words.

Version 0.9, May 2006

Initial release.

Overview of the Classes

Core classes:

• AutoComplete - ties together all the core classes: registers a WordTypedListener for the buffer, stores the words into a WordList and displays a CompletionPopup window with the possible completions. It keeps the map (buffer to its autocompletion instance).
• PreferencesManager - handles options; other classes use its methods and do not access the preferences directly. Only one instance exists.
• CompletionPopup - Pop-up window with completions of the word being typed. It intercepts keys and handles the control keys.
• WordList [interface] - structure for storage of the words (more exactly completions) to remember.
• WordListTreeSet - a concrete implementation of the WordList.
• WordTypedListener - it listens to what keys are typed in the buffer and notifies others (the AutoComplete) about such events as a character being appended to a word and the end of a word.

GUI classes:

• TextAutocompletePlugin - implements jEdit plugin.
• TextAutocompletePane - the Option pane.
• WordListEditorUI - the editor of remembered words.

Helper classes

• Completion - the structure used to keep a word to remember. Using it instead of a string enables us to add later on additional information to each word and, for instance, offer completions order with respect to the frequency of their occurrence.
• WordTypedEvent - produced by WordTypedListener to carry information about what's going on in the buffer.
• ActionException - thrown when some of the actions invoked via menu fails.

For more info see http://jakubholy.net/comp/jedit.html.

How does it work?

A BufferListener (implemented by my WordTypedListener) is attached to the buffer. When it detects an important event (a letter appended to a word, a word ended...), it notifies the main class AutoComplete via the Observer/Observable mechanism. It may then display (or dispose) a list of completions. When the list of completions is displayed, it intercepts special keys being pressed (such as Enter, Escape...) and reacts according to its setting (hide itself, insert the selected completion...).

Source code

    svn co https://jedit.svn.sourceforge.net/svnroot/jedit/plugins/TextAutocomplete/trunk TextAutocomplete

License

This plugin is released under the GNU General Public License version 2 (GPL). Please see http://www.fsf.org/copyleft/gpl.html.

Moreover, permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no "Invariant Sections", "Front-Cover Texts" or "Back-Cover Texts", each as defined in the license. A copy of the license can be found in the file COPYING.DOC.txt included with jEdit.

Jakub Holý 2006