Основные функции завершения

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

Функция: try-completion коллекция строк &опциональный предикат

Эта функция возвращает самую длинную общую подстроку всех возможных завершений строки 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 которой является строкой) из списка, или символ (не имя символа) из obarray. Если collection является хэш-таблицей, predicate вызывается с двумя аргументами: строковым ключом и связанным значением.

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

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

Функция: all-completions строка коллекция &опциональный предикат

Эта функция возвращает список всех возможных завершений строки 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 строка коллекция &опциональный предикат

Эта функция возвращает не 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 строка коллекция предикат суффикс

Эта функция возвращает границы поля, на котором будет работать 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/".

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

Переменная: 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.

Макрос: lazy-completion-table переменная функция

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