Спецификация двустороннего преобразования

Наиболее общая из двух возможностей контролируется переменной format-alist, списком спецификаций форматов файлов, описывающих текстовые представления, используемые в файлах для данных в буфере Emacs. Описания для чтения и записи сопряжены, поэтому мы называем это «двусторонней» спецификацией (см. Форматирование по частям для непарной спецификации).

Переменная: format-alist

Этот список содержит одно определение формата для каждого определенного формата файла. Каждое определение формата — это список следующего вида:

(name doc-string regexp from-fn to-fn modify mode-fn preserve)

Вот что означают элементы в определении формата:

name

Название этого формата.

doc-string

Строка документации для формата.

regexp

Регулярное выражение, используемое для распознавания файлов, представленных в этом формате. Если nil, формат никогда не применяется автоматически.

from-fn

Команда оболочки или функция для декодирования данных в этом формате (для преобразования данных файла в обычное представление данных Emacs).

Команда оболочки представлена как строка; Emacs выполняет команду как фильтр для выполнения преобразования.

Если from-fn является функцией, она вызывается с двумя аргументами, begin и end, которые указывают часть буфера, которую она должна преобразовать. Она должна преобразовать текст, редактируя его на месте. Поскольку это может изменить длину текста, from-fn должна возвращать изменённую конечную позицию.

Одна из обязанностей from-fn — убедиться, что начало файла больше не соответствует regexp. В противном случае её, вероятно, снова вызовут. Кроме того, from-fn не должна взаимодействовать с другими буферами или файлами, кроме того, который декодируется, иначе внутренний буфер, используемый для форматирования, может быть перезаписан.

to-fn

Команда оболочки или функция для кодирования данных в этом формате — то есть преобразования обычного представления данных Emacs в этот формат.

Если to-fn является строкой, это команда оболочки; Emacs выполняет команду как фильтр для выполнения преобразования.

Если to-fn является функцией, она вызывается с тремя аргументами: begin и end, которые указывают часть буфера, которую она должна преобразовать, и buffer, который указывает, какой буфер. Есть два способа выполнения преобразования:

• Редактируя буфер на месте. В этом случае to-fn должна вернуть конечную позицию изменённого диапазона текста.
• Возвращая список аннотаций. Это список элементов вида (position . string), где position — целое число, указывающее относительную позицию в тексте, который нужно записать, а string — аннотация, которую нужно добавить туда. Список должен быть отсортирован по позиции при возвращении to-fn.

  Когда write-region фактически записывает текст из буфера в файл, он смешивает указанные аннотации в соответствующих позициях. Всё это происходит без изменения буфера.

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

modify

Флаг, t, если функция кодирования изменяет буфер, и nil, если она работает, возвращая список аннотаций.

mode-fn

Функция малой моды, вызываемая после посещения файла, преобразованного из этого формата. Функция вызывается с одним аргументом, целым числом 1; это сообщает функции малой моды включить режим.

preserve

Флаг, t, если format-write-file не должен удалять этот формат из buffer-file-format.

Функция insert-file-contents автоматически распознает форматы файлов при чтении указанного файла. Она проверяет текст начала файла на соответствие регулярным выражениям определений форматов и, если находит совпадение, вызывает функцию декодирования для этого формата. Затем она снова проверяет все известные форматы. Проверка продолжается, пока ни один из них не будет применимым.

Посещение файла с помощью find-file-noselect или команд, использующих его, выполняет преобразование аналогичным образом (поскольку оно вызывает insert-file-contents); оно также вызывает функцию режима для каждого формата, который оно декодирует. Оно сохраняет список имён форматов в локальной переменной буфера buffer-file-format.

Переменная: buffer-file-format

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

Когда write-region записывает данные в файл, оно сначала вызывает функции кодирования для форматов, перечисленных в buffer-file-format, в порядке их появления в списке.

Команда: format-write-file файл формат &optional подтверждение

Эта команда записывает содержимое текущего буфера в файл file в формате, основанном на format, который является списком имён форматов. Оно создаёт фактический формат, начиная с format, а затем добавляя любые элементы из значения buffer-file-format с флагом preserve, отличным от %%%CODE_BLOCK_17%% (см. выше), если они ещё не присутствуют в format. Затем оно обновляет buffer-file-format этим форматом, делая его значением по умолчанию для будущих сохранений. За исключением аргумента format, эта команда похожа на write-file. В частности, confirm имеет такое же значение и интерактивное поведение, как соответствующий аргумент для write-file. См. Определение write-file.

Команда: format-find-file файл формат

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

Аргумент format является списком имён форматов. Если format nil, преобразование не происходит. В интерактивном режиме ввод только RET для format задаёт nil.

Команда: format-insert-file файл формат &optional beg end

Эта команда вставляет содержимое файла file, преобразуя его в соответствии с форматом format. Если beg и end не пустые, они указывают, какую часть файла читать, как в insert-file-contents (см. Чтение из файлов).

Возвращаемое значение похоже на то, что возвращает insert-file-contents: список абсолютного имени файла и длины вставленных данных (после преобразования).

Аргумент format — список имён форматов. Если format nil, преобразование не происходит. В интерактивном режиме ввод только RET для format задаёт nil.

Переменная: buffer-auto-save-file-format

Эта переменная задаёт формат, используемый для автоматического сохранения. Её значение — список имён форматов, подобно значению buffer-file-format; однако, оно используется вместо buffer-file-format для записи файлов автоматического сохранения. Если значение t, значение по умолчанию, автоматическое сохранение использует тот же формат, что и обычное сохранение в том же буфере. Эта переменная всегда локальна для буфера во всех буферах.