Tabulated List mode — Elisp

Режим табулированного списка

Режим табулированного списка — это основной режим для отображения табулированных данных, то есть данных, состоящих из записей, каждая из которых занимает одну текстовую строку, а её содержимое разделено на столбцы. Режим табулированного списка предоставляет средства для красивого форматирования строк и столбцов, а также для сортировки строк по значениям в каждом столбце. Он является производным от специального режима (см. Основные режимы).

Режим табулированного списка предназначен для отображения текста с использованием моноширинных шрифтов, одного шрифта и одного размера текста. Если вы хотите отобразить таблицу с использованием шрифтов переменной ширины или изображений, вместо него можно использовать make-vtable. vtable также поддерживает размещение в буфере нескольких таблиц или таблицы вместе с дополнительным текстом. Дополнительные сведения см. в разделе (vtable)Введение.

Режим табулированного списка предназначен для использования в качестве родительского режима более специализированным основным режимом. Примеры включают режим меню процессов (см. Информация о процессах) и режим меню пакетов (см. Меню пакетов в Руководстве GNU Emacs).

Такой производный режим должен использовать define-derived-mode обычным образом, указывая tabulated-list-mode в качестве второго аргумента (см. Определение производных режимов). Тело формы define-derived-mode должно задавать формат табулированных данных, присваивая значения переменным, описанным ниже; при необходимости после этого можно вызвать функцию tabulated-list-init-header, которая заполнит заголовок именами столбцов.

Производный режим также должен определить команду вывода списка. Именно её, а не команду режима, вызывает пользователь (например, M-x list-processes). Команда вывода списка должна создать буфер или переключиться на него, включить производный режим, задать табулированные данные и, наконец, вызвать tabulated-list-print для заполнения буфера.

Пользовательский параметр: tabulated-list-gui-sort-indicator-asc

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

При изменении направления сортировки в буферах табулированного списка этот индикатор переключается между сортировкой по возрастанию («asc») и по убыванию («desc»).

Пользовательский параметр: tabulated-list-gui-sort-indicator-desc: Подобен tabulated-list-gui-sort-indicator-asc, но используется, когда столбец отсортирован по убыванию.

Пользовательский параметр: tabulated-list-tty-sort-indicator-asc: Подобен tabulated-list-gui-sort-indicator-asc, но используется в текстовых окнах.

Пользовательский параметр: tabulated-list-tty-sort-indicator-desc: Подобен tabulated-list-tty-sort-indicator-asc, но используется, когда столбец отсортирован по убыванию.

Переменная: tabulated-list-format

Эта буферно-локальная переменная задаёт формат данных табулированного списка. Её значением должен быть вектор. Каждый элемент вектора представляет столбец данных и должен быть списком (name width sort . props), где

name — имя столбца (строка).
width — ширина, выделяемая для столбца (целое число). Для последнего столбца это значение не имеет смысла, поскольку он продолжается до конца каждой строки.
sort задаёт способ сортировки записей по столбцу. Если nil, столбец нельзя использовать для сортировки. Если t, столбец сортируется путём сравнения строковых значений. В противном случае это должна быть функция-предикат для sort (см. Функции перестановки списков), принимающая два аргумента той же формы, что и элементы tabulated-list-entries (см. ниже).
props — это список свойств (см. Списки свойств) с дополнительными свойствами столбца. Если значение свойства :right-align не равно nil, столбец следует выровнять по правому краю. Свойство :pad-right задаёт количество дополнительных пробелов справа от столбца (по умолчанию — 1, если свойство не указано).

Переменная: tabulated-list-entries

Эта буферно-локальная переменная задаёт записи, отображаемые в буфере табулированного списка. Её значением должен быть список или функция.

Если значение является списком, каждый его элемент соответствует одной записи и должен иметь форму (id contents), где

id — либо nil, либо объект Lisp, идентифицирующий запись. Во втором случае после повторной сортировки записей курсор остаётся на той же записи. Сравнение выполняется с помощью equal.
contents — вектор с тем же количеством элементов, что и tabulated-list-format. Каждый элемент вектора может быть строкой, которая вставляется в буфер без изменений; дескриптором изображения, используемым для вставки изображения (см. Дескрипторы изображений); или списком (label . properties), который означает, что нужно вставить текстовую кнопку, вызвав insert-text-button с аргументами label и properties (см. Создание кнопок).
Ни одна из этих строк не должна содержать символов новой строки.

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

Переменная: tabulated-list-groups

Эта буферно-локальная переменная задаёт группы записей, отображаемые в буфере табулированного списка. Её значением должен быть список или функция.

Если значение является списком, каждый его элемент соответствует одной группе и должен иметь форму (group-name entry1 entry2 …), где group-name — строка, вставляемая перед всеми записями группы, а entry1, entry2 и так далее имеют тот же формат, что и элемент tabulated-list-entries (см. выше).

Можно использовать seq-group-by, чтобы создать tabulated-list-groups из tabulated-list-entries. Например:

(setq tabulated-list-groups
      (seq-group-by 'Buffer-menu-group-by-mode
                    tabulated-list-entries))

где Buffer-menu-group-by-mode можно определить следующим образом:

(defun Buffer-menu-group-by-mode (entry)
  (concat "* " (aref (cadr entry) 5)))

Переменная: tabulated-list-revert-hook: Этот обычный хук выполняется перед восстановлением буфера табулированного списка. Производный режим может добавить в этот хук функцию для пересчёта tabulated-list-entries.

Переменная: tabulated-list-printer: Значение этой переменной — функция, вызываемая для вставки записи в точке вместе с завершающим символом новой строки. Функция должна принимать два аргумента, id и contents, имеющих то же значение, что и в tabulated-list-entries. По умолчанию используется функция, которая вставляет запись простым способом; режим, использующий табулированный список более сложным образом, может задать другую функцию.

Переменная: tabulated-list-sort-key: Значение этой переменной задаёт текущий ключ сортировки буфера табулированного списка. Если оно равно nil, сортировка не выполняется. В противном случае оно должно иметь форму (name . flip), где name — строка, совпадающая с одним из имён столбцов в tabulated-list-format, а flip, если оно не равно nil, означает изменение порядка сортировки на обратный.

Функция: tabulated-list-init-header

Эта функция вычисляет и устанавливает header-line-format для буфера табулированного списка (см. Заголовки окон), а также назначает строке заголовка карту клавиш, позволяющую сортировать записи щелчком по заголовкам столбцов.

Режимы, производные от режима табулированного списка, должны вызывать эту функцию после установки указанных выше переменных (в частности, только после установки tabulated-list-format).

Функция: tabulated-list-print &optional remember-pos update

Эта функция заполняет текущий буфер записями. Её должна вызывать команда вывода списка. Она стирает содержимое буфера, сортирует записи, заданные tabulated-list-entries, в соответствии с tabulated-list-sort-key, а затем вызывает функцию, заданную в tabulated-list-printer, для вставки каждой записи.

Если необязательный аргумент remember-pos не равен nil, функция ищет элемент id в текущей строке, если он там есть, и пытается перейти к этой записи после повторной вставки всех записей.

Если необязательный аргумент update не равен nil, функция удаляет или добавляет только те записи, которые изменились с момента последнего вывода. Если с момента предыдущего вызова этой функции большинство записей не изменилось, это выполняется в несколько раз быстрее. Единственное различие в результате состоит в том, что теги, установленные с помощью tabulated-list-put-tag, не будут удалены из неизменившихся записей (обычно удаляются все теги).

Функция: tabulated-list-delete-entry

Эта функция удаляет запись в точке.

Она возвращает список (id cols), где id — идентификатор удалённой записи, а cols — вектор её дескрипторов столбцов. Функция перемещает точку в начало текущей строки. Если в точке нет записи, она возвращает nil.

Обратите внимание, что эта функция изменяет только содержимое буфера; она не изменяет tabulated-list-entries.

Функция: tabulated-list-get-id &optional pos: Эта defsubst возвращает объект идентификатора из tabulated-list-entries (если это список) или из списка, возвращаемого tabulated-list-entries (если это функция). Если pos не указан или равен nil, по умолчанию используется точка.

Функция: tabulated-list-get-entry &optional pos: Эта defsubst возвращает объект записи из tabulated-list-entries (если это список) или из списка, возвращаемого tabulated-list-entries (если это функция). Для идентификатора в pos это будет вектор. Если в pos нет записи, функция возвращает nil.

Функция: tabulated-list-header-overlay-p &optional POS: Эта defsubst возвращает значение, не равное nil, если в pos находится фиктивный заголовок. Фиктивный заголовок используется, если tabulated-list-use-header-line равно nil, чтобы поместить имена столбцов в начало буфера. Если pos не указан или равен nil, по умолчанию используется point-min.

Функция: tabulated-list-put-tag tag &optional advance: Эта функция помещает tag в область отступа текущей строки. Область отступа может быть пустым пространством в начале строки; её ширина задаётся переменной tabulated-list-padding. tag должна быть строкой длиной не более tabulated-list-padding. Если advance не равен nil, функция перемещает точку на одну строку вперёд.

Функция: tabulated-list-clear-all-tags: Эта функция удаляет все теги из области отступа текущего буфера.

Функция: tabulated-list-set-col col desc &optional change-entry-data

Эта функция изменяет запись табулированного списка в точке, устанавливая для col значение desc. col — номер или имя изменяемого столбца. desc — новый дескриптор столбца, который вставляется с помощью tabulated-list-print-col.

Если change-entry-data не равен nil, функция изменяет исходные данные (обычно дескриптор столбца в списке tabulated-list-entries), присваивая дескриптору столбца вектора значение desc.