completion: Get a completion list for a R code fragment

Description

Returns names of objects/arguments/namespaces matching a code fragment.

Usage

completion(
  code,
  pos = nchar(code),
  min.length = 2,
  print = FALSE,
  types = c("default", "scintilla"),
  addition = FALSE,
  sort = TRUE,
  what = c("arguments", "functions", "packages"),
  description = FALSE,
  max.fun = 100,
  skip.used.args = TRUE,
  sep = "\n",
  field.sep = "\t",
  name.or.addition = c("name", "addition", "both")
)

Arguments

code

A partial R code to be completed.

pos

The position of the cursor in this code.

min.length

The minimal length in characters of code required before the completion list is calculated.

Logical, print result and return invisibly. See details.

types

A named list giving names of types. Set to NA to give only names. See details.

addition

Should only addition string be returned?

sort

Do we sort the list of completions alphabetically?

what

What are we looking for? Allow to restrict search for faster calculation.

description

Do we describe items in the completion list (could be slow)?

max.fun

In the case where we describe items, the maximum number of functions to process (if longer, no description is returned for function) because it can be very slow otherwise.

skip.used.args

Logical, if completion is within function arguments, should the already used named arguments be omitted?

sep

The separator to use between returned items.

field.sep

Character string to separate fields for each entry.

name.or.addition

Should we return the completion name, addition string, or both?

Value

If types == NA and description = FALSE, a character vector giving the completions, otherwise a data frame with two columns: 'completion', and 'type' when description = FALSE, or with four columns: 'completion', 'type', 'desc' and 'context' when description = TRUE. If name.or.addition == 'both', an 'addition' column is also returned. Attributes: attr(, "token") - a completed token. attr(, "triggerPos") - number of already typed characters. attr(, "fguess") - name of guessed function. `attr(, "isFirstArg")`` - is this a first argument?

Details

The completion list is context-dependent, and it is calculated as if the code was entered at the command line.

If the code ends with $ or [[, then the function look for items in a list or data.frame whose name is the last identifier.

If the code ends with @, then the function look for slots of the corresponding S4 object.

If the code ends with ::, then it looks for objects in a namespace.

If the code ends with a partial identifier name, the function returns all matching keywords visible from .GlobalEnv.

If the code is empty or parses into an empty last token, the list of objects currently in the global environment is returned.

Examples

Run this code

# NOT RUN {
# A data frame
data(iris)
completion("item <- iris$")
completion("item <- iris[[")

# An S4 object
setClass("track", representation(x = "numeric", y = "numeric"))
t1 <- new("track", x = 1:20, y = (1:20)^2)
completion("item2 <- t1@")

# A namespace
completion("utils::", description = TRUE)

# A partial identifier
completion("item3 <- va", description = TRUE)

# Otherwise, a list with the content of .GlobalEnv
completion("item4 <- ")

# TODO: directory and filename completion!
rm(iris, t1)
# }