rcompgen {rcompgen}R Documentation

A completion generator for R

Description

This package provides 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.

Usage


rc.settings(ops, ns, args, func, ipck, S3, data, help, argdb, files)
rc.status()

rc.getOption(name)
rc.options(...)

Arguments

ops, ns, args, func, ipck, S3, data, help, argdb, files logical, turning some optional completion features on and off.
ops:
activates completion after the $ and @ operators

ns:
controls namespace related completions

args:
enables completion of function arguments

func:
enables detection of functions. If enabled, a customizable extension ("(" by default) is appended to function names. The process of determining whether a potential completion is a function requires evaluation, including for lazy loaded symbols. This is extremely undesirable for large objects, because of potentially wasteful use of memory in addition to the time overhead associated with loading. For this reason, this feature is disabled by default.

S3:
when args=TRUE, activates completion on arguments of all S3 methods (otherwise just the generic, which usually has very few arguments)

ipck:
enables completion of installed package names inside library and require

data:
enables completion of data sets (including those already visible) inside data

help:
enables completion of help requests starting with a question mark, by looking inside help index files

argdb:
when args=TRUE, completion is attempted on function arguments. Generally, the list of valid arguments is determined by dynamic calls to args. While this gives results that are technically correct, the use of the ... argument often hides some useful arguments. To give more flexibility in this regard, rcompgen internally retains an optional table of valid arguments names for specific functions. Setting argdb=TRUE enables preferential lookup in this internal data base for functions with an entry in it. Of course, this is useful only when the data base contains information about the function of interest. Some functions are included in the package (the maintainer is happy to add more upon request), and more can be added by the user through the unexported function .addFunctionInfo (see below).

files:
enables filename completion in R code. This is initially set to FALSE, in which case the underlying completion front-end can take over (and hopefully do a better job than we would have done). For systems where no such facilities exist, this can be set to TRUE if file name completion is desired. This is currently experimental and may not work very well.


All settings are turned on by default except ipck, func and files. Turn more off if your CPU cycles are valuable; you will still retain basic completion on names of objects in the search list. See below for additional details.
name, ... user-settable options. Currently valid names are
function.suffix:
default "("
funarg.suffix:
default " = "
package.suffix
default "::"
See options for detailed usage description

Details

There are several types of completion, some of which can be disabled using rc.settings. The most basic level, which can not be turned off once the package is loaded, 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 $ and @:
When the ops setting is turned on, completion after $ and @ 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).
Completion inside namespaces:
When the ns setting is turned on, completion inside namespaces is attempted when a token is preceded by the :: or ::: operators. Additionally, the basic completion mechanism is extended to include attached namespaces, or more precisely, foopkg:: becomes a valid completion of foo if the return value of search() includes the string "package:foopkg".

The completion of package namespaces applies only to attached packages, i.e. if MASS is not attached (whether or not it is loaded), MAS will 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. trying to complete on MASS::fr will load MASS (but not necessarily attach it) even if it is not already loaded.

Completion of function arguments:
When the args setting 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 print and 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 S3 setting.

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 possibilites. 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([TAB] and 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.out argument 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 (library, 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 ipck setting, which controls whether library and require will complete on installed packages, is disabled by default because the first call to installed.packages is 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.packages is cached, so subsequent calls are usually fast, so turning this option on is not particularly onerous even in such situations.

Needless to say, the details above describe intended behaviour; whether actual behaviour matches it remains to be seen.

Value

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 call to 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:

comps the possible completions generated by the last call to .completeToken, as a character vector
token the token that was (or, is to be) completed, as set by the last call to .assignToken (possibly inside a call to .guessTokenFromLine)
linebuffer the full line, as set by the last call to .assignLinebuffer
start the start position of the token in the line buffer, as set by the last call to .assignStart
end the end position of the token in the line buffer, as set by the last call to .assignEnd
fileName logical, indicating whether the cursor is currently inside quotes. If so, no completion is attempted. A reasonable default behaviour for the backend in that case is to fall back to filename completion.
fguess the name of the function rcompgen thinks the cursor is currently inside
isFirstArg logical. If cursor is inside a function, is it the first argument?


In addition, the components settings and options give the current values of settings and options respectively.
rc.getOption and rc.options behave much like getOption and options respectively.

Unexported API

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:

    .assignToken(text)
    .assignLinebuffer(line)
    .assignStart(start)
    .assignEnd(end)

    .completeToken()
    .retrieveCompletions()
    .getFileComp()

    .guessTokenFromLine()
    .win32consoleCompletion(linebuffer, cursorPosition,
                            check.repeat = TRUE, 
                            minlength = -1)

    .addFunctionInfo(...)

The first four functions set up a completion attempt by specifying the token to be completed (text), and indicating where (start and end, which should be integers) the token is placed within the complete line typed so far (line).

Potenial completions of the token are generated by .completeToken, and the completions can be retrieved as an R character vector using .retrieveCompletions.

If the cursor is inside quotes, no completion is attempted. The function .getFileComp can be used after a call to .completeToken to 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 .guessTokenFromLine function 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. (This is used by the ESS completion hook example given in the examples/altesscomp.el file.)

The .win32consoleCompletion is 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, addition, possible and comps. If there is an unambiguous extension at the current position, addition contains 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 comps. possible consists of lines formatted using the current width option, so that printing them on the console one line at a time will be a reasonable way to list them. comps is a space separated (collapsed) list of the same completions, in case the front-end wishes to display it in some other fashion.

The minlength argument 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 check.repeat is 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 upto 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 .addFunctionInfo can 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 argdb setting is TRUE, these are used as a source of valid argument names for the relevant functions.

Note

If you are uncomfortable with unsolicited evaluation of pieces of code, you should set ops = FALSE. Otherwise, trying to complete 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 lazy loaded symbols (and presumably other promise type thingies).

Author(s)

Deepayan Sarkar, deepayan.sarkar@r-project.org


[Package rcompgen version 0.1-17 Index]