Returns names of objects/arguments/namespaces matching a code fragment.
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
coderequired before the completion list is calculated.Logical, print result and return invisibly. See details.
- types
A named list giving names of types. Set to
NAto 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.
Note
Take care: depending on the context, the completion list could be incorrect (but it should work for code entered at the command line). For instance, inside a function call, the context is very different, and arguments and local variables should be returned instead. This may be implemented in the future, but for now, we focus on completion that should be most useful for novice useRs that are using R expressions entered one after the other at the R console or in a script (and considering the script is run or sourced line after line in R).
There are other situations where the completion can be calculated, see the
help of rc.settings().
If print == TRUE, results are returned invisibly, and printed in a form:
triggerPos newline completions separated by sep.
If types are supplied, a completion will consist of name and type,
separated by type.sep. types may me a vector of length 5, giving the type
codes for "function", "variable", "environment", "argument" and "keyword".
If types == "default", above type names are given; types == "scintilla"
will give numeric codes that can be used with "scintilla.autoCShow" function
(e.g., with the SciViews-K Komodo Edit plugin).
See also
Examples
# A data frame
data(iris)
completion("item <- iris$")
#> completion type
#> 3 iris$Petal.Length variable
#> 4 iris$Petal.Width variable
#> 1 iris$Sepal.Length variable
#> 2 iris$Sepal.Width variable
#> 5 iris$Species variable
completion("item <- iris[[")
#> completion type
#> 3 iris[["Petal.Length" variable
#> 4 iris[["Petal.Width" variable
#> 1 iris[["Sepal.Length" variable
#> 2 iris[["Sepal.Width" variable
#> 5 iris[["Species" variable
# An S4 object
setClass("track", representation(x = "numeric", y = "numeric"))
t1 <- new("track", x = 1:20, y = (1:20)^2)
completion("item2 <- t1@")
#> completion type
#> 1 t1@ variable
# A namespace
completion("utils::", description = TRUE)
#> completion type desc context
#> 140 utils::.AtNames variable utils
#> 45 utils::.DollarNames variable utils
#> 188 utils::.RtangleCodeLabel variable utils
#> 201 utils::.S3methods variable utils
#> 10 utils::.romans variable utils
#> 72 utils::? variable utils
#> 76 utils::RShowDoc variable utils
#> 35 utils::RSiteSearch variable utils
#> 145 utils::Rprof variable utils
#> 105 utils::Rprofmem variable utils
#> 193 utils::Rtangle variable utils
#> 123 utils::RtangleFinish variable utils
#> 215 utils::RtangleRuncode variable utils
#> 95 utils::RtangleSetup variable utils
#> 126 utils::RtangleWritedoc variable utils
#> 89 utils::RweaveChunkPrefix variable utils
#> 206 utils::RweaveEvalWithOpt variable utils
#> 135 utils::RweaveLatex variable utils
#> 184 utils::RweaveLatexFinish variable utils
#> 172 utils::RweaveLatexOptions variable utils
#> 147 utils::RweaveLatexSetup variable utils
#> 29 utils::RweaveLatexWritedoc variable utils
#> 85 utils::RweaveTryStop variable utils
#> 66 utils::Stangle variable utils
#> 39 utils::Sweave variable utils
#> 5 utils::SweaveHooks variable utils
#> 134 utils::SweaveSyntConv variable utils
#> 110 utils::SweaveSyntaxLatex variable utils
#> 109 utils::SweaveSyntaxNoweb variable utils
#> 151 utils::URLdecode variable utils
#> 229 utils::URLencode variable utils
#> 59 utils::View variable utils
#> 227 utils::adist variable utils
#> 44 utils::alarm variable utils
#> 106 utils::apropos variable utils
#> 12 utils::aregexec variable utils
#> 202 utils::argsAnywhere variable utils
#> 17 utils::as.person variable utils
#> 117 utils::as.personList variable utils
#> 108 utils::as.relistable variable utils
#> 9 utils::as.roman variable utils
#> 104 utils::asDateBuilt variable utils
#> 52 utils::askYesNo variable utils
#> 19 utils::aspell variable utils
#> 73 utils::aspell_package_C_files variable utils
#> 122 utils::aspell_package_R_files variable utils
#> 213 utils::aspell_package_Rd_files variable utils
#> 24 utils::aspell_package_vignettes variable utils
#> 163 utils::aspell_write_personal_dictionary_file variable utils
#> 23 utils::assignInMyNamespace variable utils
#> 51 utils::assignInNamespace variable utils
#> 162 utils::available.packages variable utils
#> 64 utils::bibentry variable utils
#> 96 utils::browseEnv variable utils
#> 77 utils::browseURL variable utils
#> 180 utils::browseVignettes variable utils
#> 20 utils::bug.report variable utils
#> 21 utils::capture.output variable utils
#> 3 utils::changedFiles variable utils
#> 94 utils::charClass variable utils
#> 65 utils::checkCRAN variable utils
#> 161 utils::chooseBioCmirror variable utils
#> 185 utils::chooseCRANmirror variable utils
#> 8 utils::citEntry variable utils
#> 57 utils::citFooter variable utils
#> 119 utils::citHeader variable utils
#> 118 utils::citation variable utils
#> 209 utils::cite variable utils
#> 111 utils::citeNatbib variable utils
#> 47 utils::close.socket variable utils
#> 226 utils::clrhash variable utils
#> 168 utils::combn variable utils
#> 154 utils::compareVersion variable utils
#> 228 utils::contrib.url variable utils
#> 155 utils::count.fields variable utils
#> 61 utils::create.post variable utils
#> 93 utils::data variable utils
#> 115 utils::data.entry variable utils
#> 175 utils::dataentry variable utils
#> 187 utils::de variable utils
#> 131 utils::de.ncols variable utils
#> 190 utils::de.restore variable utils
#> 113 utils::de.setup variable utils
#> 78 utils::debugcall variable utils
#> 36 utils::debugger variable utils
#> 37 utils::demo variable utils
#> 87 utils::download.file variable utils
#> 182 utils::download.packages variable utils
#> 149 utils::dump.frames variable utils
#> 158 utils::edit variable utils
#> 83 utils::emacs variable utils
#> 217 utils::example variable utils
#> 132 utils::file.edit variable utils
#> 167 utils::fileSnapshot variable utils
#> 178 utils::file_test variable utils
#> 171 utils::find variable utils
#> 121 utils::findCRANmirror variable utils
#> 70 utils::findLineNum variable utils
#> 60 utils::findMatches variable utils
#> 211 utils::fix variable utils
#> 2 utils::fixInNamespace variable utils
#> 220 utils::flush.console variable utils
#> 148 utils::formatOL variable utils
#> 189 utils::formatUL variable utils
#> 164 utils::getAnywhere variable utils
#> 142 utils::getCRANmirrors variable utils
#> 225 utils::getFromNamespace variable utils
#> 146 utils::getParseData variable utils
#> 138 utils::getParseText variable utils
#> 100 utils::getS3method variable utils
#> 107 utils::getSrcDirectory variable utils
#> 176 utils::getSrcFilename variable utils
#> 219 utils::getSrcLocation variable utils
#> 204 utils::getSrcref variable utils
#> 31 utils::getTxtProgressBar variable utils
#> 80 utils::gethash variable utils
#> 195 utils::glob2rx variable utils
#> 62 utils::globalVariables variable utils
#> 30 utils::hasName variable utils
#> 124 utils::hashtab variable utils
#> 143 utils::head variable utils
#> 58 utils::head.matrix variable utils
#> 136 utils::help variable utils
#> 43 utils::help.request variable utils
#> 203 utils::help.search variable utils
#> 231 utils::help.start variable utils
#> 4 utils::history variable utils
#> 165 utils::hsearch_db variable utils
#> 50 utils::hsearch_db_concepts variable utils
#> 75 utils::hsearch_db_keywords variable utils
#> 200 utils::install.packages variable utils
#> 7 utils::installed.packages variable utils
#> 79 utils::is.hashtab variable utils
#> 55 utils::is.relistable variable utils
#> 153 utils::isS3method variable utils
#> 38 utils::isS3stdGeneric variable utils
#> 54 utils::limitedLabels variable utils
#> 88 utils::loadhistory variable utils
#> 144 utils::localeToCharset variable utils
#> 27 utils::ls.str variable utils
#> 207 utils::lsf.str variable utils
#> 18 utils::maintainer variable utils
#> 223 utils::make.packages.html variable utils
#> 91 utils::make.socket variable utils
#> 205 utils::makeRweaveLatexCodeRunner variable utils
#> 221 utils::maphash variable utils
#> 25 utils::memory.limit variable utils
#> 130 utils::memory.size variable utils
#> 71 utils::menu variable utils
#> 67 utils::methods variable utils
#> 159 utils::mirror2html variable utils
#> 41 utils::modifyList variable utils
#> 212 utils::new.packages variable utils
#> 32 utils::news variable utils
#> 40 utils::nsl variable utils
#> 152 utils::numhash variable utils
#> 84 utils::object.size variable utils
#> 74 utils::old.packages variable utils
#> 139 utils::osVersion variable utils
#> 129 utils::package.skeleton variable utils
#> 6 utils::packageDate variable utils
#> 177 utils::packageDescription variable utils
#> 194 utils::packageName variable utils
#> 169 utils::packageStatus variable utils
#> 116 utils::packageVersion variable utils
#> 173 utils::page variable utils
#> 26 utils::person variable utils
#> 166 utils::personList variable utils
#> 233 utils::pico variable utils
#> 216 utils::process.events variable utils
#> 137 utils::prompt variable utils
#> 42 utils::promptData variable utils
#> 46 utils::promptImport variable utils
#> 191 utils::promptPackage variable utils
#> 125 utils::rc.getOption variable utils
#> 224 utils::rc.options variable utils
#> 230 utils::rc.settings variable utils
#> 103 utils::rc.status variable utils
#> 197 utils::read.DIF variable utils
#> 34 utils::read.csv variable utils
#> 48 utils::read.csv2 variable utils
#> 53 utils::read.delim variable utils
#> 28 utils::read.delim2 variable utils
#> 120 utils::read.fortran variable utils
#> 112 utils::read.fwf variable utils
#> 170 utils::read.socket variable utils
#> 150 utils::read.table variable utils
#> 127 utils::readCitationFile variable utils
#> 210 utils::recover variable utils
#> 160 utils::relist variable utils
#> 22 utils::remhash variable utils
#> 183 utils::remove.packages variable utils
#> 114 utils::removeSource variable utils
#> 16 utils::rtags variable utils
#> 198 utils::savehistory variable utils
#> 208 utils::select.list variable utils
#> 133 utils::sessionInfo variable utils
#> 181 utils::setBreakpoint variable utils
#> 157 utils::setRepositories variable utils
#> 81 utils::setTxtProgressBar variable utils
#> 68 utils::sethash variable utils
#> 128 utils::stack variable utils
#> 214 utils::str variable utils
#> 102 utils::strOptions variable utils
#> 14 utils::strcapture variable utils
#> 90 utils::summaryRprof variable utils
#> 11 utils::suppressForeignCheck variable utils
#> 82 utils::tail variable utils
#> 99 utils::tail.matrix variable utils
#> 156 utils::tar variable utils
#> 222 utils::timestamp variable utils
#> 179 utils::toBibtex variable utils
#> 56 utils::toLatex variable utils
#> 13 utils::txtProgressBar variable utils
#> 69 utils::type.convert variable utils
#> 33 utils::typhash variable utils
#> 86 utils::undebugcall variable utils
#> 196 utils::unstack variable utils
#> 98 utils::untar variable utils
#> 232 utils::unzip variable utils
#> 97 utils::update.packages variable utils
#> 186 utils::upgrade variable utils
#> 141 utils::url.show variable utils
#> 63 utils::vi variable utils
#> 199 utils::vignette variable utils
#> 218 utils::warnErrList variable utils
#> 174 utils::write.csv variable utils
#> 192 utils::write.csv2 variable utils
#> 1 utils::write.socket variable utils
#> 101 utils::write.table variable utils
#> 92 utils::xedit variable utils
#> 15 utils::xemacs variable utils
#> 49 utils::zip variable utils
# A partial identifier
completion("item3 <- va", description = TRUE)
#> completion type desc
#> 1 validEnc function Check if a Character Vector is Validly Encoded
#> 2 validObject function Test the Validity of an Object
#> 3 validSlotNames function Utilities for Managing Class Definitions
#> 4 validUTF8 function Check if a Character Vector is Validly Encoded
#> 5 vapply function Apply a Function over a List or Vector
#> 6 var function Correlation, Variance and Covariance (Matrices)
#> 7 var.test function F Test to Compare Two Variances
#> 8 variable.names function Case and Variable Names of Fitted Models
#> 9 varimax function Rotation Methods for Factor Analysis
#> context
#> 1 base
#> 2 methods
#> 3 methods
#> 4 base
#> 5 base
#> 6 stats
#> 7 stats
#> 8 stats
#> 9 stats
# Otherwise, a list with the content of .GlobalEnv
completion("item4 <- ")
#> completion type
#> 1 iris variable
# TODO: directory and filename completion!
rm(iris, t1)
#> Warning: object 'iris' not found