File: completion.el.html

What to put in .emacs
-----------------------
(dynamic-completion-mode)

---------------------------------------------------------------------------
Documentation [Slightly out of date]
---------------------------------------------------------------------------
 (also check the documentation string of the functions)

Introduction
---------------

    After you type a few characters, pressing the "complete" key inserts
the rest of the word you are likely to type.

This watches all the words that you type and remembers them. When typing a new word, pressing "complete" (meta-return) "completes" the word by inserting the most recently used word that begins with the same characters. If you press meta-return repeatedly, it cycles through all the words it knows about.

 If you like the completion then just continue typing, it is as if you
entered the text by hand. If you want the inserted extra characters to go away, type control-w or delete. More options are described below.

 The guesses are made in the order of the most recently "used". Typing
in a word and then typing a separator character (such as a space) "uses" the word. So does moving a cursor over the word. If no words are found, it uses an extended version of the dabbrev style completion.

  You automatically save the completions you use to a file between
sessions.

  Completion enables programmers to enter longer, more descriptive
variable names while typing fewer keystrokes than they normally would.

Full documentation
---------------------

  A "word" is any string containing characters with either word or symbol
syntax. [E.g., any alphanumeric string with hyphens, underscores, etc.] Unless you change the constants, you must type at least three characters for the word to be recognized. Only words longer than 6 characters are saved.

  When you load this file, completion will be on. I suggest you use the
compiled version (because it is noticeably faster).

 M-x completion-mode toggles whether or not new words are added to the
database by changing the value of enable-completion.

 SAVING/LOADING COMPLETIONS
  Completions are automatically saved from one session to another
(unless save-completions-flag or enable-completion is nil).
Activating this minor-mode (calling completion-initialize) loads a completions database for a saved completions file
(default: ~/.completions). When you exit, Emacs saves a copy of the
completions that you often use. When you next start, Emacs loads in the saved completion file.

  The number of completions saved depends loosely on
*saved-completions-decay-factor*. Completions that have never been
inserted via "complete" are not saved. You are encouraged to experiment with different functions (see compute-completion-min-num-uses).

  Some completions are permanent and are always saved out. These
completions have their num-uses slot set to T. Use add-permanent-completion to do this

  Completions are saved only if enable-completion is T. The number of old
versions kept of the saved completions file is controlled by completions-file-versions-kept.

COMPLETE KEY OPTIONS
  The complete function takes a numeric arguments.
 control-u :: leave the point at the beginning of the completion rather
              than the middle.
 a number :: rotate through the possible completions by that amount
 - :: same as -1 (insert previous completion)

HOW THE DATABASE IS MAINTAINED
 <write>

UPDATING THE DATABASE MANUALLY
  m-x kill-completion
    kills the completion at point.
  m-x add-completion
  m-x add-permanent-completion

UPDATING THE DATABASE FROM A SOURCE CODE FILE
  m-x add-completions-from-buffer
    Parses all the definition names from a C or LISP mode buffer and
    adds them to the completion database.

  m-x add-completions-from-lisp-file
    Parses all the definition names from a C or Lisp mode file and
    adds them to the completion database.

UPDATING THE DATABASE FROM A TAGS TABLE
  m-x add-completions-from-tags-table
    Adds completions from the current tags-table-buffer.

HOW A COMPLETION IS FOUND
 <write>

STRING CASING
  Completion is string case independent if case-fold-search has its
 normal default of T. Also when the completion is inserted the case of the
 entry is coerced appropriately.
 [E.G. APP --> APPROPRIATELY app --> appropriately
        App --> Appropriately]

INITIALIZATION
 The form (completion-initialize) initializes the completion system by
trying to load in the user's completions. After the first call, further calls have no effect so one should be careful not to put the form in a site's standard site-init file.

---------------------------------------------------------------------------


---------------------------------------------------------------------------
Functions you might like to call
---------------------------------------------------------------------------

 add-completion string &optional num-uses
   Adds a new string to the database

 add-permanent-completion string
   Adds a new string to the database with num-uses = T

 kill-completion string
   Kills the completion from the database.

 clear-all-completions
   Clears the database

 list-all-completions
   Returns a list of all completions.

 next-completion string &optional index
   Returns a completion entry that starts with string.

 find-exact-completion string
   Returns a completion entry that exactly matches string.

 complete
   Inserts a completion at point

 completion-initialize
   Loads the completions file and sets up so that exiting Emacs will
 save them.

 save-completions-to-file &optional filename
 load-completions-from-file &optional filename

-----------------------------------------------
Other functions
-----------------------------------------------

 get-completion-list string

These things are for manipulating the structure
 make-completion string num-uses
 completion-num-uses completion
 completion-string completion
 set-completion-num-uses completion num-uses
 set-completion-string completion string


-----------------------------------------------
To Do :: (anybody ?)
-----------------------------------------------

  Implement Lookup and keyboard interface in C
  Add package prefix smarts (for Common Lisp)
  Add autoprompting of possible completions after every keystroke (fast
     terminals only !)
  Add documentation to texinfo

-----------------------------------------------

Defined variables (30)

Defined functions (58)

Defined faces (0)