A Completion Generator for R
This page documents a mechanism to generate relevant completions from a partially completed command line. It is not intended to be useful by itself, but rather in conjunction with other mechanisms that use it as a backend. The functions listed in the usage section provide a simple control and query mechanism. The actual interface consists of a few unexported functions described further down.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
rc.settings(ops, ns, args, func, ipck, S3, data, help, argdb, fuzzy, quotes, files) rc.status() rc.getOption(name) rc.options(...) .DollarNames(x, pattern) ## Default S3 method: .DollarNames(x, pattern = "") ## S3 method for class 'list' .DollarNames(x, pattern = "") ## S3 method for class 'environment' .DollarNames(x, pattern = "")
logical, turning some optional completion features on and off.
All settings are turned on by default except
user-settable options. Currently valid names are
Usage is similar to that of
An R object for which valid names after
A regular expression. Only matching names are returned.
There are several types of completion, some of which can be disabled
rc.settings. The most basic level, which can not be
turned off once the completion functionality is activated, provides
completion on names visible on the search path, along with a few
special keywords (e.g.,
TRUE). This type of completion is not
attempted if the partial ‘word’ (a.k.a. token) being completed
is empty (since there would be too many completions). The more
advanced types of completion are described below.
- Completion after extractors
opssetting is turned on, completion after
@is attempted. This requires the prefix to be evaluated, which is attempted unless it involves an explicit function call (implicit function calls involving the use of
$, etc do not inhibit evaluation).
Valid completions after the
$extractor are determined by the generic function
.DollarNames. Some basic methods are provided, and more can be written for custom classes.
- Completion inside namespaces:
nssetting is turned on, completion inside namespaces is attempted when a token is preceded by the
:::operators. Additionally, the basic completion mechanism is extended to include all loaded namespaces, i.e.,
foopkg::becomes a valid completion of
"foopkg"is a loaded namespace.
The completion of package namespaces applies only to already loaded namespaces, i.e.\sspaceif
MASSis not loaded,
MASwill not complete to
MASS::. However, attempted completion inside an apparent namespace will attempt to load the namespace if it is not already loaded, e.g.\sspacetrying to complete on
MASSif it is not already loaded.
- Completion for help items:
helpsetting is turned on, completion on help topics is attempted when a token is preceded by
?. Prefixes (such as
method) are supported, as well as quoted help topics containing special characters.
- Completion of function arguments:
argssetting is turned on, completion on function arguments is attempted whenever deemed appropriate. The mechanism used will currently fail if the relevant function (at the point where completion is requested) was entered on a previous prompt (which implies in particular that the current line is being typed in response to a continuation prompt, usually
+). Note that separation by newlines is fine.
The list of possible argument completions that is generated can be misleading. There is no problem for non-generic functions (except that
...is listed as a completion; this is intentional as it signals the fact that the function can accept further arguments). However, for generic functions, it is practically impossible to give a reliable argument list without evaluating arguments (and not even then, in some cases), which is risky (in addition to being difficult to code, which is the real reason it hasn't even been tried), especially when that argument is itself an inline function call. Our compromise is to consider arguments of all currently available methods of that generic. This has two drawbacks. First, not all listed completions may be appropriate in the call currently being constructed. Second, for generics with many methods (like
plot), many matches will need to be considered, which may take a noticeable amount of time. Despite these drawbacks, we believe this behaviour to be more useful than the only other practical alternative, which is to list arguments of the generic only.
Only S3 methods are currently supported in this fashion, and that can be turned off using the
Since arguments can be unnamed in R function calls, other types of completion are also appropriate whenever argument completion is. Since there are usually many many more visible objects than formal arguments of any particular function, possible argument completions are often buried in a bunch of other possibilities. However, recall that basic completion is suppressed for blank tokens. This can be useful to list possible arguments of a function. For example, trying to complete
seq(from = 1, [TAB])will both list only the arguments of
seq(or any of its methods), whereas trying to complete
seq(length[TAB]will list both the
length.outargument and the
length(function as possible completions. Note that no attempt is made to remove arguments already supplied, as that would incur a further speed penalty.
- Special functions:
For a few special functions (
data, etc), the first argument is treated specially, in the sense that normal completion is suppressed, and some function specific completions are enabled if so requested by the settings. The
ipcksetting, which controls whether
requirewill complete on installed packages, is disabled by default because the first call to
installed.packagesis potentially time consuming (e.g., when packages are installed on a remote network file server). Note, however, that the results of a call to
installed.packagesis cached, so subsequent calls are usually fast, so turning this option on is not particularly onerous even in such situations.
rc.settings is called without any arguments, it returns the
current settings as a named logical vector. Otherwise, it returns
rc.status returns, as a list, the contents of an internal
(unexported) environment that is used to record the results of the
last completion attempt. This can be useful for debugging. For such
use, one must resist the temptation to use completion when typing the
rc.status itself, as that then becomes the last attempt
by the time the call is executed.
The items of primary interest in the returned list are:
The possible completions generated by the last
The token that was (or, is to be) completed, as
set by the last call to
The full line, as set by the last call to
The start position of the token in the line
buffer, as set by the last call to
The end position of the token in the line
buffer, as set by the last call to
Logical, indicating whether the cursor is currently inside quotes.
The name of the function the cursor is currently inside.
Logical. If cursor is inside a function, is it the first argument?
In addition, the components
the current values of settings and options respectively.
rc.options behave much like
There are several unexported functions in the package. Of these, a few are special because they provide the API through which other mechanisms can make use of the facilities provided by this package (they are unexported because they are not meant to be called directly by users). The usage of these functions are:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
text), and indicating where (
end, which should be integers) the token is placed within the complete line typed so far (
line). Potential completions of the token are generated by
.completeToken, and the completions can be retrieved as an R character vector using
.retrieveCompletions. It is possible for the user to specify a replacement for this function by setting
rc.options("custom.completer"); if not
NULL, this function is called to compute potential completions. This facility is meant to help in situations where completing as R code is not appropriate. See source code for more details. If the cursor is inside quotes, completion may be suppressed. The function
.getFileCompcan be used after a call to
.completeTokento determine if this is the case (returns
TRUE), and alternative completions generated as deemed useful. In most cases, filename completion is a reasonable fallback. The
.guessTokenFromLinefunction is provided for use with backends that do not already break a line into tokens. It requires the linebuffer and endpoint (cursor position) to be already set, and itself sets the token and the start position. It returns the token as a character string. The
.win32consoleCompletionis similar in spirit, but is more geared towards the Windows GUI (or rather, any front-end that has no completion facilities of its own). It requires the linebuffer and cursor position as arguments, and returns a list with three components,
comps. If there is an unambiguous extension at the current position,
additioncontains the additional text that should be inserted at the cursor. If there is more than one possibility, these are available either as a character vector of preformatted strings in
possible, or as a single string in
possibleconsists of lines formatted using the current
widthoption, so that printing them on the console one line at a time will be a reasonable way to list them.
compsis a space separated (collapsed) list of the same completions, in case the front-end wishes to display it in some other fashion. The
minlengthargument can be used to suppress completion when the token is too short (which can be useful if the front-end is set up to try completion on every keypress). If
TRUE, it is detected if the same completion is being requested more than once in a row, and ambiguous completions are returned only in that case. This is an attempt to emulate GNU Readline behaviour, where a single TAB completes up to any unambiguous part, and multiple possibilities are reported only on two consecutive TABs. As the various front-end interfaces evolve, the details of these functions are likely to change as well. The function
.addFunctionInfocan be used to add information about the permitted argument names for specific functions. Multiple named arguments are allowed in calls to it, where the tags are names of functions and values are character vectors representing valid arguments. When the
TRUE, these are used as a source of valid argument names for the relevant functions.
If you are uncomfortable with unsolicited evaluation of pieces of
code, you should set
ops = FALSE. Otherwise, trying to
foo@ba will evaluate
foo, trying to complete
foo[i, 1:10]$ba will evaluate
foo[i, 1:10], etc. This
should not be too bad, as explicit function calls (involving
parentheses) are not evaluated in this manner. However, this
will affect promises and lazy loaded symbols.
Deepayan Sarkar, firstname.lastname@example.org