下列补全函数本身与小缓冲无关。在此介绍是为了与使用小缓冲的高级补全功能放在一起。
该函数返回 collection 中所有可补全项与 string 的最长公共前缀子串。
collection 称为 补全表(completion table)。其值必须是字符串或 cons 单元列表、obarray、哈希表或补全函数。
try-completion 将 string 与补全表指定的所有合法补全项对比。若无匹配项,返回 nil。若仅有一个精确匹配项,返回 t。否则返回所有可能匹配项的最长公共初始序列。
若 collection 是列表,合法补全项由列表元素指定:每个元素应为字符串,或 CAR 为字符串或符号的 cons 单元(符号通过 symbol-name 转为字符串)。列表中其他类型元素会被忽略。
若 collection 是 obarray(see 创建与编入符号),则 obarray 中所有符号的名称构成合法补全集合。
若 collection 是哈希表,则字符串或符号类型的键为可补全项,其他键被忽略。
也可使用函数作为 collection。此时补全完全由该函数负责;try-completion 直接返回该函数的结果。函数被调用时传入三个参数:string、predicate 和 nil(第三个参数使同一函数可同时用于 all-completions 并区分行为)。See Programmed Completion。
若参数 predicate 非 nil,则必须是单参数函数(若 collection 是哈希表,则为双参数函数)。它用于测试每个可能匹配,仅当 predicate 返回非 nil 时匹配有效。传给 predicate 的参数可以是 alist 中的字符串或 cons 单元(其 CAR 为字符串),或 obarray 中的符号( 不是 符号名)。若 collection 是哈希表,predicate 接收两个参数:字符串键与对应值。
此外,可接受的补全项还必须匹配 completion-regexp-list 中的所有正则表达式(除非 collection 是函数,此时需由该函数自行处理 completion-regexp-list)。
下面第一个例子中,字符串 ‘foo’ 与 alist 中的三个 CAR 匹配。所有匹配均以 ‘fooba’ 开头,因此结果为该字符串。第二个例子中仅有一个精确匹配,返回值为 t。
(try-completion
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
⇒ "fooba"
(try-completion "foo" '(("barfoo" 2) ("foo" 3)))
⇒ t
下例中,许多符号以 ‘forw’ 开头,且全部以 ‘forward’ 开头。多数符号后接 ‘-’,但并非全部,因此最多只能补全到 ‘forward’。
(try-completion "forw" obarray)
⇒ "forward"
最后一例中,三个可能匹配里只有两个通过谓词 test(字符串 ‘foobaz’ 太短)。两者均以 ‘foobar’ 开头。
(defun test (s)
(> (length (car s)) 6))
⇒ test
(try-completion
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
'test)
⇒ "foobar"
该函数返回 string 的所有可能补全项组成的列表。参数
与 try-completion 相同,且以相同方式使用 completion-regexp-list。
若 collection 是函数,会以三个参数调用:string、predicate 和 t;然后 all-completions 返回该函数的结果。See Programmed Completion。
以下示例使用 try-completion 示例中的函数 test:
(defun test (s)
(> (length (car s)) 6))
⇒ test
(all-completions
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
'test)
⇒ ("foobar1" "foobar2")
若 string 是 collection 和 predicate 指定的合法补全选项,该函数返回非 nil。参数与 try-completion 相同。例如,若 collection 是字符串列表,则当 string 出现在列表中且满足 predicate 时返回真。
该函数以与 try-completion 相同的方式使用 completion-regexp-list。
若 predicate 非 nil,且 collection 包含多个由 compare-strings(按 completion-ignore-case)判定为相等的字符串,则 predicate 应要么全部接受要么全部拒绝。否则 test-completion 的返回值本质上不可预测。
若 collection 是函数,会以三个参数调用:string、predicate 和 lambda;test-completion 直接返回该函数结果。
该函数假设 string 保存光标前文本、suffix 保存光标后文本,返回 collection 操作字段的边界。
通常补全作用于整个字符串,因此对所有常规集合,它始终返回 (0 . (length suffix))。但更复杂的补全(如文件补全)会逐字段处理。例如,"/usr/sh" 的补全会包含 "/usr/share/",但不包含 "/usr/share/doc"(即使存在)。同样,对 "/usr/sh" 的 all-completions 不会返回 "/usr/share/",只返回 "share/"。因此若 string 为 "/usr/sh"、suffix 为 "e/doc",completion-boundaries 会返回 (5 . 1),表示集合只返回 "/usr/" 之后、"/doc" 之前区域的补全信息。try-completion 不受非平凡边界影响;例如对 "/usr/sh" 仍可能返回 "/usr/share/" 而非 "share/"。
若将补全 alist 存入变量,应通过为其设置非 nil 的 risky-local-variable 属性将变量标记为风险变量。See 文件局部变量。
若此变量值非 nil,补全时不区分大小写。在 read-file-name 中,该变量会被 read-file-name-completion-ignore-case 覆盖(see Reading File Names);在 read-buffer 中,会被 read-buffer-completion-ignore-case 覆盖(see High-Level Completion Functions)。
这是一个正则表达式列表。补全函数仅接受匹配列表中所有正则表达式的补全项,匹配时 case-fold-search(see Searching and Case)绑定为 completion-ignore-case 的值。
不要全局将此变量设为非 nil,这不安全且可能导致补全命令出错。此变量只应在调用基础补全函数(try-completion、test-completion、all-completions)时局部绑定为非 nil。
该宏以惰性方式将变量 var 初始化为补全集合,直到首次使用时才计算实际内容。使用此宏生成一个值并存入 var。首次使用 var 执行补全时,通过无参数调用 fun 完成实际计算,fun 返回的值成为 var 的永久值。
示例:
(defvar foo (lazy-completion-table foo make-my-alist))
存在多个接收现有补全表并返回修改版本的函数。completion-table-case-fold 返回不区分大小写的表。completion-table-in-turn 和 completion-table-merge 以不同方式合并多个输入表。completion-table-subvert 修改表以使用不同初始前缀。completion-table-with-quoting 返回适合处理带引号文本的表。completion-table-with-predicate 使用谓词函数过滤表。completion-table-with-terminator 添加终止字符串。