User manual

Chapter 9: Completion 46
9 Completion
9.1 Completion of object names
The TAB key is for completion. The value of the variable ess-first-tab-never-complete
controls when completion is allowed controls when completion is allowed to occur. In ess-
mode TAB first tries to indent, and if there is nothing to indent, complete the object name
instead.
TAB comint-dynamic-complete Complete the S object name or filename before
point.
When the cursor is just after a partially-completed object name, pressing TAB provides
completion in a similar fashion to tcsh except that completion is performed over all known
S object names instead of file names. ESS maintains a list of all objects known to S at any
given time, which basically consists of all objects (functions and datasets) in every attached
directory listed by the search() command along with the component objects of attached
data frames (if your version of S supports them).
For example, consider the three functions (available in Splus version 3.0) called
binomplot(), binom.test() and binomial(). Typing bin TAB after the S prompt will
insert the characters ‘om’, completing the longest prefix (‘binom’) which distinguishes these
three commands. Pressing TAB once more provides a list of the three commands which
have this prefix, allowing you to add more characters (say, ‘.’) which specify the function
you desire. After entering more characters pressing TAB yet again will complete the object
name up to uniqueness, etc. If you just wish to see what completions exist without adding
any extra characters, type M-?.
[Command]ess-list-object-completions
M-? List all possible completions of the object name at point.
ESS also provides completion over the components of named lists and environments
(after ‘$’), S4 classes slots (after @), package and namespace objects (after :: and :::).
Completion is also provided over file names, which is particularly useful when using S
functions such as get() or scan() which require fully expanded file names.
In the Inferior ESS buffer, if the cursor is not in a string and does not follow a (partial)
object name, the TAB key has a third use: it expands history references. See Section 4.4
[History expansion], page 29.
Efficiency in completion is gained by maintaining a cache of objects currently known
to S; when a new object becomes available or is deleted, only one component of the cache
corresponding to the associated directory needs to be refreshed. If ESS ever becomes con-
fused about what objects are available for completion (such as when if refuses to complete
an object you know is there), the command M-x ess-resynch forces the entire cache to be
refreshed, which should fix the problem.