1. DESCRIPTION: This is just another word completion function which uses the TAB key as completion key by default. The words that are targets for completion are loaded from a file. File is read line by line and may include other files. Target word may actually be one or more words. There may be optional fields in the line delimited by two colons where the additional fields may hold e.g. a syntax for a programming function and a help text for the function. Using the newline escape character "\n" in the syntax will see it expanded upon completion. Using the "@@" string in the syntax will have it replaced with the editing point upon completion. Using the single character, '@' after a target word, means that it is an alias (see 3.1.). Thus, you can create the equivalent of simple boilerplate snippets. 2. NAME AND LOCATION OF THE COMPLETIONS FILE The name and location of the file holding the target words for completion defaults to /home/${user}/.completions_{mode}, i.e. a hidden file in your home directory, which e.g. in slang_mode would be named ".completions_slang" or in text_mode, ".completions_text". If you don't like that, you can change it in a mode hook by giving a new name to the completions file as an argument to the init_tabcomplete function, e.g. define slang_mode_hook () { .. init_tabcomplete ("/home/user/myslangfuns"); } 3. INSTALLATION 1) Move the file, "tabcomplete.sl" to a directory in your jed library path, usually /usr/share/jed/lib or /usr/local/share/jed/lib 2) Create a file with target words or snippets to complete from. See sections 2. and 4. 3) In your $HOME/.jedrc, insert the following line: autoload ("init_tabcomplete", "tabcomplete"); After this line, you must specify what modes to use completion for in a mode hook. E.g. in your $HOME/.jedrc insert: define slang_mode_hook () { Wordchars = "a-zA-Z0-9"; Extended_Wordchars = "_" init_tabcomplete (); } A completions file for SLang is supplied which also includes syntaxes. If you don't like that, you can just start up with no completions file, then one will be auto-generated and written to your home directory as ".completions_slang", without syntaxes, of course. 4. FORMAT OF THE COMPLETIONS FILE Each entry is on a line by itself. Line format is: target word :: [optional syntax for word] :: [optional help text for word] I.e. three fields all delimited by two colons where the last two fields are optional. So in their simplest form, lines in the completions file may look like this: cave caveat emptor! If these lines were the only two lines in the completion file, then typing 'c' and hitting the TAB key two or more times would alternate between inserting the words on the two lines after the editing point. Typing e.g. the space key after the word(s) has been inserted will confirm the insertion of the completed word. Typing "cavea" + TAB would insert only "caveat emptor!". Lines may also look like this: fopen :: (@@, ) In this case, after having completed "fopen" with TAB and confirmed its insertion with the enter key, then the inserted line will look like fopen (, ) with the editing point being just before the comma, as the two at-signs have been replaced by the editing point. Or lines may look like this: _for :: i (0, @@, 1)\n{\n\n} In this case, after having completed "_for" with TAB , then the inserted line will expand to _for i (0, , 1) { } with the editing point being just before the second comma. A line may also look like this: read_with_completion :: (@@, , , , ) :: Void read_with_completion (String prt, String dflt, String s, Integer type) The last field is a short help text, in this case explaining the syntax of the function that may be shown in the minibuffer upon completion. 4.1 ALIASES Using the single '@' character after the target word in the first field means that the word is an alias. The alias word will not be inserted. Thereby you can create mnemonic little snippets to be inserted. E.g.: duck@ :: Donald Duck\n1313 Webfoot Walk\nDuckburg\nCalisota. Typing "duck" + TAB will then yield Donald Duck 1313 Webfoot Walk Duckburg Calisota as the newline escapes "\n" will be expanded. 4.2 INCLUDE OTHER FILES In the completions file, you can include other files to complete from with the "#INC" directive like this #INC /some/otherfile/to/include 5. USAGE These keys perform the following actions: - TAB: cycles through possible completions or inserts completed word and breaks cycle if there is only one completion. This key may be redefined (see section 5.1). - Shift-Tab: Will move the editing point two lines down and run the indent_line () function. Useful for quickly moving from a condition statement to a block between a pair of braces or to quickly move out from such a block. - : breaks the cycle and returns you to the stub - : breaks cycle and inserts completion plus possible syntax. If there is no syntax to be inserted, a space is inserted after the completed word. - : Like , but does not insert a space after a completed word with no syntax attached. - any other key: breaks cycle and inserts the key pressed - F1: Shows help for word at point (if available). - F2: An "apropos" function that searches the help texts and returns the corresponding functions, if available. - ctrl-c c: Select a different completions file. - ctrl-c w: Append the word at point or marked words to the completions file. You can redefine these keys in a mode hook. Multi line constructs, including nested constructs will be automatically indented upon insertion. 5.1 User Definable Variables In your $HOME/.jedrc you can enter the following variables which modify the behaviour of some of the functions like this, their default values are shown: variable Show_Help_Upon_Completion = 1; This variable toggles the display of a help text in the minibuffer. 0 == off, 1 == on variable Completion_Key = "\t"; The completion key. Default is TAB. variable Wordchars = "\a"R; This variable controls which characters that may be part of a word. This is crucial as to what words you want completed. variable Extended_Wordchars = "-_"; This variable controls what other characters may be part of a word. variable Insert_Completion_Word = 1; This variable controls whether or not the completion word itself should be inserted into the buffer. variable Newl_Delim = "\\n"; This variable controls the delimiter to use for expanding newlines in aliases and syntax. variable Tabcomplete_Use_Help = 1; This variable controls whether to use the native help interface or not. If you use the julia mode, you should set this to '0' as julia.sl defines its own help interface. variable Use_Completion_Menu = 0; This variable controls whether to use a pop up menu with completion targets or to complete from or if completing from the editing point. variable Sep_Fun_Par_With_Space = 0; Should there be a space between function name and opening parenthesis upon completion? E.g. strtok () vs. strtok(). Looping or conditional keywords will always have a space. The julia language will not accept spaces, so set it to 0 in that case. All of these variables should first be entered globally in your ~/.jedrc with your preferred default values and then possibly fine tuned with other values within a mode hook for that particular mode. E.g: define slang_mode_hook () { Extended_Wordchars = "_#%"; init_tabcomplete (); } PLEASE NOTE that the variables must come BEFORE the init_tabcomplete () function. 6. Create a Wordlist to Complete From An easy way to make a word list of regular words to be completed from, is to use a spell checkers' function to dump the master word list into a completions file. E.g. with aspell: cd aspell -d fr dump master > .tabcomplete_fr this would dump all words from aspell's French dictionary into the hidden file ".tabcomplete_fr" in your home directory. 7. Use Tabcomplete With Aspell If you have installed the aspell spell checking extension from http://mbjnet.dk/aspell, then you may use it to autoload completion files that match your spell checking language. E.g., when writing emails, it is normal to write in different languages, so if you also want to be able to complete words, it would be convenient to have a completion file for e.g. English loaded when spell checking in that language. In that case, you might configure this in the mailedit_mode_hook, if you use Jed's mailedit.sl extension to edit your emails: define mailedit_mode_hook () { Aspell_Use_Replacement_Wordlist = 1; Aspell_Ask_Dictionary = 1; Aspell_Use_Tabcompletion = 1; init_aspell (); } Please note that the Aspell.* variables must PRECEDE the init_aspell () function in the mode hook and that these variables should already have been defined outside the mode hook, first. Normally, you would use the "init_tabcomplete ()" function in the mode hook to load the tabcompletion functions, but in this case, you simply set the variable, Aspell_Use_Tabcompletion, then a completions file, "$HOME/.tabcompletion_$LANG" is loaded automatically, where $LANG corresponds to your current spell checking dictionary. For English, the hidden file would then be named ".tabcomplete_en" or ".tabcomplete_en_US" for American English, residing in your home directory. These completion files must of course be created first, see above. For modes, i.e. programming language modes, where you don't want spell checking, use the "init_tabcomplete ()" function in the mode hook instead to load the tabcomplete functions. The $LANG part should match as a substring of your current locale setting in either one of the environment variables, $LANG, $LC_MESSAGES or $LC_ALL, e.g. if the environment variable $LANG is set to "en_US.utf-8". Send bug reports or suggestions to: Morten Bo Johansen, listmail (at) mbjnet.dk