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 surrounded by one or more spaces 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 message area upon completion. A line may also look like this: .gcolor :: &groff_get_color_names(1) :: Set (glyph) drawing color Here the second field, "&groff_get_color_names(1)", is a S-Lang function to be executed upon completion, which is implied by prefixing the function name with the "&" character. 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). If the character before the editing point is one of, ')', ']' or '}', this key will insert or delete any of these characters until they are balanced with their matching delimiters, '(', '[' or '{'. NOTE: If you have already fully typed the word you want to complete and this word forms the beginning of other words that are completion candidates, such as if you type "if" (which forms the beginning of "ifnot") and then hit , then nothing happens but if you type , the "if" construct will be expanded. Typing another time will complete to "ifnot". - Shift-Tab: In "C" and "SLang" modes, this 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 message area upon insertion of the completed word. 0 == off, 1 == on variable Completion_Key = "\t"; The completion key. Default is TAB. variable Wordchars = "\w"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. If this is enabled, completion in the minibuffer will be disabled. 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. variable SLang_Completion_In_Minibuffer = 0; Setting this variable in SLang mode to '1' will enable this utility's completion at the minibuffer's S-Lang> cli prompt. Note that key (sequence) bound to invoking the S-Lang> prompt is detected and if you have more than one key (sequence) bound to invoking the prompt, it may not detect the one you're actually using. In that case, check those key bindings and remove the one(s) you're not using. variable Minimum_Completion_Word_Size = 2; This variable controls the minimum size for words that are candidates for completion. If completion is from a generic word list such as a list that may be generated with the "aspell (..) dump master (..)" command, then personally I prefer a rather large value such as e.g. 10 for this variable so that the completion candidates will be limited to words that are cumbersome to write and/or difficult to spell. I think it is especially convenient if also the variable Use_Completion_Menu is set to 1. variable Tabcomplete_Compl_Delims = 0; By typing one of the characters, '(', '[', or '"' will insert "()", "[]" and '""' into the buffer and place the editing point between the two characters. Set to '1' to enable. variable Match_Is_Case_Insensitive = 0; When matching the letters before the editing point to the possible completion candidates, should the matching be case insensitive? Set to '1' to enable. All of these variables should first be entered globally in your ~/.jedrc with your preferred default values (or no values) and then possibly fine tuned with other values within a mode hook for that particular mode. E.g: variable Show_Help_Upon_Completion; variable SLang_Completion_In_Minibuffer; variable Tabcomplete_Use_Help; variable Extended_Wordchars; define slang_mode_hook () { Extended_Wordchars = "_#%"; Show_Help_Upon_Completion = 1; SLang_Completion_In_Minibuffer = 1; Tabcomplete_Use_Help = 1; 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 spell.sl If you have installed the enchant2 spell checking wrapper program and a spell checker along with spell.sl spell checking extension, 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. In your ~/.jedrc: variable Spell_Use_Replacement_Wordlist; variable Spell_Ask_Dictionary; variable Spell_Use_Tabcompletion; define mailedit_mode_hook () { Spell_Use_Replacement_Wordlist = 1; Spell_Ask_Dictionary = 1; Spell_Use_Tabcompletion = 1; spell_init (); } Please note that the Spell.* variables must PRECEDE the spell_init () 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, Spell_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, mortenbo at hotmail dot com