Основные функции дополнения

Следующие функции дополнения сами по себе не имеют отношения к минибуферам. Мы описываем их здесь, чтобы расположить рядом с функциями дополнения более высокого уровня, которые используют минибуфер.

Функция: try-completion string collection &optional predicate

Эта функция возвращает самую длинную общую подстроку всех возможных вариантов дополнения string в collection.

collection называется таблицей дополнения. Ее значением должен быть список строк или cons-ячеек, obarray, хеш-таблица или функция дополнения.

try-completion сравнивает string с каждым допустимым вариантом дополнения, заданным таблицей дополнения. Если ни один допустимый вариант дополнения не подходит, функция возвращает nil. Если подходит только один вариант дополнения и совпадение точное, функция возвращает t. В противном случае она возвращает самую длинную начальную последовательность, общую для всех подходящих вариантов дополнения.

Если collection — список, допустимые варианты дополнения задаются элементами списка, каждый из которых должен быть строкой или cons-ячейкой, чей CAR является строкой или символом (символ преобразуется в строку с помощью symbol-name). Элементы списка любого другого типа игнорируются.

Если collection — obarray (см. Создание и интернирование символов), имена всех символов в obarray образуют множество допустимых вариантов дополнения.

Если collection — хеш-таблица, возможными вариантами дополнения являются ключи, представляющие собой строки или символы. Другие ключи игнорируются.

В качестве collection также можно использовать функцию. В этом случае функция самостоятельно выполняет дополнение; try-completion возвращает то, что возвращает эта функция. Функция вызывается с тремя аргументами: string, predicate и nil (третий аргумент нужен, чтобы одну и ту же функцию можно было использовать в all-completions и выполнять соответствующие действия в обоих случаях). См. Дополнение с помощью программ.

Если аргумент predicate не равен nil, он должен быть функцией одного аргумента, если только collection не является хеш-таблицей; в последнем случае это должна быть функция двух аргументов. Она используется для проверки каждого возможного совпадения, и совпадение принимается, только если predicate возвращает значение, не равное nil. Аргумент, передаваемый в predicate, — это строка или cons-ячейка (ее CAR является строкой) из alist либо символ (не имя символа) из obarray. Если collection — хеш-таблица, predicate вызывается с двумя аргументами: строковым ключом и связанным с ним значением.

Кроме того, чтобы считаться допустимым, вариант дополнения должен соответствовать всем регулярным выражениям в completion-regexp-list. (Если collection является функцией, эта функция должна самостоятельно обрабатывать completion-regexp-list.)

В первом из следующих примеров строке «foo» соответствуют три значения CAR из alist. Все совпадения начинаются с символов «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"

Функция: all-completions string collection &optional predicate

Эта функция возвращает список всех возможных вариантов дополнения string. Аргументы этой функции совпадают с аргументами try-completion, а completion-regexp-list используется так же, как в try-completion.

Если collection — функция, она вызывается с тремя аргументами: string, predicate и t; затем all-completions возвращает то, что возвращает эта функция. См. Дополнение с помощью программ.

Вот пример, в котором используется функция test, показанная в примере для try-completion:

(defun test (s)
  (> (length (car s)) 6))
     ⇒ test

(all-completions
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 'test)
     ⇒ ("foobar1" "foobar2")

Функция: test-completion string collection &optional predicate

Эта функция возвращает значение, не равное nil, если string является допустимым вариантом дополнения, заданным collection и predicate. Аргументы те же, что и у try-completion. Например, если collection — список строк, функция возвращает истину, когда string присутствует в списке и удовлетворяет условию predicate.

Эта функция использует completion-regexp-list так же, как try-completion.

Если predicate не равен nil и collection содержит несколько строк, равных друг другу согласно compare-strings и completion-ignore-case, то predicate должен принимать либо все эти строки, либо ни одну из них. В противном случае возвращаемое значение test-completion фактически непредсказуемо.

Если collection — функция, она вызывается с тремя аргументами: значениями string, predicate и lambda; test-completion возвращает то, что возвращает эта функция.

Функция: completion-boundaries string collection predicate suffix

Эта функция возвращает границы поля, с которым будет работать collection, предполагая, что string содержит текст перед точкой, а suffix — текст после точки.

Обычно дополнение выполняется для всей строки, поэтому для всех обычных коллекций эта функция всегда возвращает (0 . (length suffix)). Однако при более сложном дополнении, например дополнении имен файлов, оно выполняется по одному полю за раз. Например, дополнение для "/usr/sh" будет включать "/usr/share/", но не "/usr/share/doc", даже если существует "/usr/share/doc". Кроме того, all-completions для "/usr/sh" не будет включать "/usr/share/", а только "share/". Поэтому, если string — это "/usr/sh", а suffix — это "e/doc", completion-boundaries вернет (5 . 1), что означает, что collection будет возвращать сведения о дополнении только для области после "/usr/" и перед "/doc". try-completion не учитывает нетривиальные границы; например, try-completion для "/usr/sh" может по-прежнему вернуть "/usr/share/", а не "share/".

Если вы сохраняете alist дополнения в переменной, следует пометить эту переменную как потенциально опасную, задав ей свойство risky-local-variable, не равное nil. См. Локальные переменные файла.

Переменная: completion-ignore-case

Если значение этой переменной не равно nil, регистр символов при дополнении не учитывается. В read-file-name эта переменная переопределяется переменной read-file-name-completion-ignore-case (см. Ввод имен файлов); в read-buffer она переопределяется переменной read-buffer-completion-ignore-case (см. Функции дополнения высокого уровня).

Переменная: completion-regexp-list

Это список регулярных выражений. Функции дополнения считают вариант допустимым, только если он соответствует всем регулярным выражениям из этого списка, при этом case-fold-search (см. Поиск и регистр символов) привязана к значению completion-ignore-case.

Не задавайте этой переменной глобально значение, отличное от nil, поскольку это небезопасно и, скорее всего, приведет к ошибкам в командах дополнения. Эту переменную следует привязывать к значениям, отличным от nil, только на время вызова основных функций дополнения: try-completion, test-completion и all-completions.

Макрос: lazy-completion-table var fun

Этот макрос позволяет инициализировать переменную 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 добавляет завершающую строку.