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