R rcompgen R 的补全生成器

说明

本页记录了一种从部分完成的命令行生成相关完成的机制。它本身并不是有用的，而是与使用它作为后端的其他机制结合使用。使用部分列出的函数提供了简单的控制和查询机制。实际的接口由一些未导出的函数组成，下面将进一步说明。

用法

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

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

.DollarNames(x, pattern)
.AtNames(x, pattern)

## Default S3 method:
.DollarNames(x, pattern = "")
## S3 method for class 'list'
.DollarNames(x, pattern = "")
## S3 method for class 'environment'
.DollarNames(x, pattern = "")
## Default S3 method:
.AtNames(x, pattern = "")

findMatches(pattern, values, fuzzy)

参数

ops	逻辑标志。在 $ 和 @ 运算符之后激活完成。
ns	逻辑标志。控制与命名空间相关的完成。
args	逻辑标志。启用函数参数的完成。
dots	逻辑标志。如果禁用，则从函数参数列表中删除...。仅当启用 args 时相关。
func	逻辑标志。启用函数检测。如果启用，可自定义扩展名(默认为"(")将附加到函数名称中。确定潜在完成是否是函数的过程需要评估，包括延迟加载的符号。这对于大型对象来说是不可取的，因为除了与加载相关的时间开销之外，还可能浪费内存。因此，该函数默认处于禁用状态。
S3	逻辑标志。当 args = TRUE 时，激活所有 S3 方法参数的完成(否则只是泛型，通常只有很少的参数)。
ipck	逻辑标志。允许在 library 和 require 中完成已安装的包名称。
data	逻辑标志。启用 data 内的数据集(包括那些已经可见的数据集)的完成。
help	逻辑标志。通过查看帮助索引文件，可以完成以问号开头的帮助请求。
argdb	逻辑标志。当 args = TRUE 时，尝试完成函数参数。通常，有效参数列表由对 args 的动态调用确定。虽然这给出了技术上正确的结果，但 ... 参数的使用通常隐藏了一些有用的参数。为了在这方面提供更大的灵活性，内部保留了特定函数的有效参数名称的可选表。设置 argdb = TRUE 可以在此内部数据库中优先查找其中包含条目的函数。当然，这仅当数据库包含有关感兴趣的函数的信息时才有用。一些函数已经包含在内，用户可以通过未导出的函数.addFunctionInfo 添加更多函数(见下文)。
fuzzy	逻辑标志。启用模糊匹配，如果未找到精确匹配，则考虑接近但不精确的匹配(例如，具有不同的大小写)。此函数是实验性的，详细信息可能会发生变化。在 findMatches 中，此参数默认为当前设置。
quotes	逻辑标志。启用完成R引号内的代码。这通常会导致文件名完成，但也可能取决于上下文(例如，当左引号前面带有?)，调用帮助完成。将其设置为FALSE将完成委托给底层完成前端，该前端可以进行自己的处理(例如，readline在 Unix-alikes 上会完成文件名补全)。
files	逻辑标志。已弃用。请改用quotes。
name , ...	user-settable选项。目前有效的名称是 function.suffix： 默认"(" funarg.suffix： 默认"=" package.suffix 默认"::" 用法与 options 类似。
x	计算并返回 "$" 后面的有效名称的 R 对象。
pattern	一个正则表达式。仅返回匹配的名称。
values	给出要在其中找到匹配项的候选值集的字符串。

细节

有多种类型的完成，其中一些可以使用 rc.settings 禁用。 rc.settings 的参数都是逻辑标志，用于打开和关闭特定的可选完成函数。默认情况下，除 ipck 、 func 和 fuzzy 之外的所有设置均处于启用状态。如果您的 CPU 周期很有价值，请关闭更多函数；你仍然会保持基本的完成度。

最基本的级别一旦激活补全函数就无法关闭，它提供搜索路径上可见的名称的补全以及一些特殊关键字(例如 TRUE )。如果正在完成的部分‘word’(又名令牌)为空(因为完成次数过多)，则不会尝试这种类型的完成。下面说明了更高级的完成类型。

提取器 $ 和 @ 后完成：

当ops 设置打开时，将尝试在$ 和@ 之后完成。这需要对前缀进行求值，除非涉及显式函数调用(涉及使用 [ 、 $ 等的隐式函数调用不会禁止求值)，否则会尝试求值。

$ 和 @ 提取器之后的有效完成分别由通用函数 .DollarNames 和 .AtNames 确定。提供了一些基本方法，并且可以为自定义类编写更多方法。 findMatches 函数可用于此目的。

命名空间内的补全：

当 ns 设置打开时，当标记前面有 :: 或 ::: 运算符时，将尝试在命名空间内完成。此外，基本完成机制已扩展为包括所有加载的命名空间，即，如果 "foopkg" 是加载的命名空间，则 foopkg:: 成为 foo 的有效完成。

包命名空间的完成仅适用于已加载的命名空间，即如果未加载 MASS ，则 MAS 将不会完成为 MASS:: 。但是，如果命名空间尚未加载，则在表观命名空间内尝试完成将尝试加载该命名空间，例如尝试在 MASS::fr 上完成将加载 MASS(如果尚未加载)。

完成帮助项目：

当 help 设置打开时，如果标记前面有 ? ，则会尝试完成帮助主题。支持前缀(例如 class 、 method )以及包含特殊字符的引用帮助主题。

函数参数的完成：

当 args 设置打开时，只要认为合适，就会尝试完成函数参数。如果在上一个提示中输入了相关函数(在请求完成时)(这特别意味着正在键入当前行以响应继续提示，通常是 + )，则当前使用的机制将失败。请注意，用换行符分隔是可以的。

生成的可能的参数完成列表可能会产生误导。非泛型函数没有问题(除了 ... 被列为完成；这是故意的，因为它表明该函数可以接受更多参数)。然而，对于泛型函数，在不评估参数的情况下几乎不可能给出可靠的参数列表(甚至在某些情况下也不可能)，这是有风险的(除了难以编码之外，这也是它没有评估的真正原因)甚至没有尝试过)，特别是当该参数本身是内联函数调用时。我们的妥协是考虑该泛型的所有当前可用方法的参数。这有两个缺点。首先，并非所有列出的完成都适合当前正在构造的调用。其次，对于具有多种方法的泛型(例如 print 和 plot )，需要考虑许多匹配，这可能需要相当长的时间。尽管存在这些缺点，我们相信这种行为比唯一的其他实用替代方案(仅列出泛型参数)更有用。

目前仅支持这种方式的 S3 方法，并且可以使用 S3 设置将其关闭。

由于参数可以是未命名的R只要参数完成，函数调用、其他类型的完成也适用。由于通常存在比任何特定函数的形式参数更多的可见对象，因此可能的参数完成通常隐藏在一堆其他可能性中。但是，请记住，对于空白标记，基本完成是被抑制的。这对于列出函数的可能参数很有用。例如，尝试完成seq([TAB]和seq(from = 1, [TAB])都将只列出参数seq(或其任何方法)，同时尝试完成seq(length[TAB]将列出length.out论证和length(函数尽可能完成。请注意，不会尝试删除已提供的参数，因为这会导致进一步的速度损失。

特殊函数：

对于一些特殊函数( library 、 data 等)，第一个参数会被特殊对待，即抑制正常完成，并且如果设置有要求，则启用一些特定于函数的完成。 ipck 设置控制 library 和 require 是否在已安装的软件包上完成，默认情况下处于禁用状态，因为第一次调用 installed.packages 可能很耗时(例如，当软件包安装在远程网络文件上时)服务器)。但请注意，installed.packages 的调用结果会被缓存，因此后续调用通常很快，因此即使在这种情况下，打开此选项也不是特别繁重。

findMatches 是一个实用函数，在内部使用来确定匹配。它可用于编写 .DollarNames 或 .AtNames 的方法，主要好处是它将考虑当前的 fuzzy 设置。

值

如果在不带任何参数的情况下调用rc.settings，它将返回当前设置作为命名逻辑向量。否则，它将不可见地返回NULL。

rc.status 以列表形式返回内部(未导出)环境的内容，该环境用于记录上次完成尝试的结果。这对于调试很有用。对于此类使用，在键入对 rc.status 本身的调用时必须抵制使用完成的诱惑，因为这将成为执行调用时的最后一次尝试。

返回列表中主要感兴趣的项目是：

comps	最后一次调用 .completeToken 生成的可能的补全，作为字符向量。
token	已完成(或将要完成)的令牌，由上次调用 .assignToken 设置(可能在 .guessTokenFromLine 调用内)。
linebuffer	完整的行，由最后一次调用 .assignLinebuffer 设置。
start	行缓冲区中令牌的起始位置，由最后一次调用 .assignStart 设置。
end	行缓冲区中令牌的结束位置，由最后一次调用 .assignEnd 设置。
fileName	逻辑，指示光标当前是否在引号内。
fguess	光标当前所在函数的名称。
isFirstArg	逻辑性强。如果光标位于函数内部，它是第一个参数吗？

此外，组件settings和options分别给出设置和选项的当前值。

rc.getOption 和 rc.options 的行为分别与 getOption 和 options 非常相似。

findMatches 返回与输入模式匹配的值，同时考虑到 fuzzy 标志。

未导出的API

包中有几个未导出的函数。其中，有一些是特殊的，因为它们提供了 API，其他机制可以通过该 API 使用此包提供的函数(它们是未导出的，因为它们不应该由用户直接调用)。这些函数的用法是：

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

    .completeToken(custom = TRUE)
    .retrieveCompletions()
    .getFileComp()

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

    .addFunctionInfo(...)

前四个函数通过指定要完成的标记 ( text ) 并指示标记放置在迄今为止键入的完整行中的位置( start 和 end ，应该是整数)来设置完成尝试(line)。

令牌的潜在完成由以下方式生成.completeToken，并且完成可以作为R特征向量使用.retrieveCompletions。用户可以通过设置指定此函数的替代品rc.options("custom.completer");如果不NULL，调用此函数来计算潜在的完成情况。此函数旨在帮助解决不适合作为 R 代码完成的情况。请参阅源代码了解更多详细信息。可以通过设置禁用自定义完成custom = FALSE调用时.completeToken.

如果光标位于引号内，则可能会抑制完成。可以在调用 .completeToken 后使用函数 .getFileComp 来确定是否是这种情况(返回 TRUE )，并生成认为有用的替代补全。在大多数情况下，文件名完成是一个合理的后备方案。

提供.guessTokenFromLine 函数用于尚未将行分成标记的后端。它要求已经设置了行缓冲区和端点(光标位置)，并且它本身设置了标记和开始位置。它以字符串形式返回标记。

.win32consoleCompletion 在精神上类似，但更适合 Windows GUI(或者更确切地说，任何没有自己的完成设施的前端)。它需要行缓冲区和光标位置作为参数，并返回包含三个组件的列表： addition 、 possible 和 comps 。如果当前位置有明确的扩展名，addition 包含应在光标处插入的附加文本。如果存在不止一种可能性，则它们可以作为 possible 中预格式化字符串的字符向量使用，也可以作为 comps 中的单个字符串使用。 possible 由使用当前 width 选项格式化的行组成，因此在控制台上一次打印一行将是列出它们的合理方式。 comps 是相同完成的空格分隔(折叠)列表，以防前端希望以其他方式显示它。

minlength 参数可用于在令牌太短时抑制完成(如果将前端设置为在每次按键时尝试完成，这可能很有用)。如果 check.repeat 是 TRUE ，则会检测是否连续多次请求相同的完成，并且仅在这种情况下才返回不明确的完成。这是模拟 GNU Readline 行为的尝试，其中单个 TAB 完成任何明确的部分，并且仅在两个连续的 TAB 上报告多种可能性。

随着各种前端接口的发展，这些函数的细节也可能发生变化。

函数 .addFunctionInfo 可用于添加有关特定函数允许的参数名称的信息。调用它时允许使用多个命名参数，其中标签是函数名称，值是表示有效参数的字符向量。当 argdb 设置为 TRUE 时，这些将用作相关函数的有效参数名称的来源。

注意

如果您对主动评估代码片段感到不舒服，则应该设置 ops = FALSE 。否则，尝试完成 foo@ba 将评估 foo ，尝试完成 foo[i, 1:10]$ba 将评估 foo[i, 1:10] 等。这应该不会太糟糕，因为显式函数调用(涉及括号)不会以这种方式评估。但是，这将影响承诺和延迟加载符号。

作者

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