Чтение имён файлов

Функции высокого уровня read-file-name, read-directory-name, и read-shell-command предназначены для чтения имён файлов, имён каталогов и команд оболочки соответственно. Они предоставляют специальные функции, включая автоматическое вставку каталога по умолчанию.

Функция: read-file-name prompt &optional directory default require-match initial predicate

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

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

1. Она вызывается через команду мыши.
2. Выбранный фрейм находится на графическом дисплее, поддерживающем такие диалоги.
3. Переменная use-dialog-box имеет значение отличное от nil. См. Диалоговые окна в Руководстве по GNU Emacs.
4. Аргумент directory, описанный ниже, не указывает на удалённый файл. См. Удалённые файлы в Руководстве по GNU Emacs.

Точное поведение при использовании графического диалога зависит от платформы. Здесь мы просто документируем поведение при использовании минибуфера.

read-file-name не автоматически расширяет возвращённое имя файла. Вы можете сами вызвать expand-file-name, если требуется абсолютное имя файла.

Необязательный аргумент require-match имеет то же значение, что и в completing-read. См. Автодополнение минибуфера.

Аргумент directory указывает каталог, используемый для автодополнения относительных имён файлов. Он должен быть абсолютным именем каталога. Если переменная insert-default-directory имеет значение отличное от nil, directory также вставляется в минибуфер как начальный ввод. По умолчанию используется значение переменной default-directory текущего буфера.

Если вы укажете initial, это будет начальное имя файла для вставки в буфер (после directory, если он вставлен). В этом случае курсор помещается в начало initial. По умолчанию для initial используется nil — не вставлять никакого имени файла. Чтобы увидеть, что делает initial, попробуйте команду C-x C-v в буфере, открывающем файл. Обратите внимание: мы рекомендуем использовать default вместо initial в большинстве случаев.

Если default имеет значение отличное от nil, то функция возвращает default, если пользователь закрывает минибуфер с теми же непустыми данными, что и read-file-name изначально вставил. Начальное содержимое минибуфера всегда непустое, если insert-default-directory имеет значение отличное от nil, как по умолчанию. default не проверяется на корректность, независимо от значения require-match. Однако, если require-match имеет значение отличное от nil, начальное содержимое минибуфера должно быть допустимым именем файла (или каталога). В противном случае read-file-name пытается выполнить автодополнение, если пользователь закрывает его без редактирования, и не возвращает default. default также доступен через команды истории.

Если default равно nil, read-file-name пытается найти заменительный default для использования вместо него, который обрабатывается точно так же, как если бы он был указан явно. Если default равно nil, но initial имеет значение отличное от nil, то значение по умолчанию — абсолютное имя файла, полученное из directory и initial. Если оба default и initial равны nil, а буфер открывает файл, read-file-name использует абсолютное имя этого файла как значение по умолчанию. Если буфер не открывает файл, то значение по умолчанию отсутствует. В этом случае, если пользователь нажимает RET в пустом минибуфере, read-file-name просто возвращает предварительно вставленное содержимое минибуфера.

Если пользователь нажимает RET в пустом минибуфере, эта функция возвращает пустую строку, независимо от значения require-match. Например, так пользователь может открыть текущий буфер без файла, используя команду M-x set-visited-file-name.

Если predicate имеет значение отличное от nil, он задаёт функцию одного аргумента, которая определяет, какие имена файлов являются допустимыми альтернативами автодополнения. Имя файла является допустимым значением, если predicate возвращает значение отличное от nil для него.

Вот пример использования read-file-name:

(read-file-name "The file is ")

;; After evaluation of the preceding expression,
;;   the following appears in the minibuffer:

---------- Buffer: Minibuffer ----------
The file is /gp/gnu/elisp/∗
---------- Buffer: Minibuffer ----------

Ввод manual TAB приводит к следующему:

---------- Buffer: Minibuffer ----------
The file is /gp/gnu/elisp/manual.texi∗
---------- Buffer: Minibuffer ----------

Если пользователь нажмёт RET, read-file-name вернёт имя файла как строку "/gp/gnu/elisp/manual.texi".

Переменная: read-file-name-function

Если имеет значение отличное от nil, это должна быть функция, принимающая те же аргументы, что и read-file-name. Когда read-file-name вызывается, она вызывает эту функцию с предоставленными аргументами вместо выполнения своей обычной работы.

Пользовательский параметр: read-file-name-completion-ignore-case

Если эта переменная имеет значение отличное от nil, read-file-name игнорирует регистр при выполнении автодополнения.

Функция: read-directory-name prompt &optional directory default require-match initial

Эта функция похожа на read-file-name, но позволяет использовать только имена каталогов как альтернативы автодополнения.

Если default равно nil и initial имеет значение отличное от nil, read-directory-name создаёт заменительный default, объединяя directory (или каталог по умолчанию текущего буфера, если directory равно nil ) и initial. Если оба default и initial равны nil, эта функция использует directory в качестве заменителя default, или каталог по умолчанию текущего буфера, если directory равно nil.

Пользовательский параметр: insert-default-directory

Эта переменная используется read-file-name, и, следовательно, косвенно, большинством команд чтения имён файлов. (Это включает все команды, использующие буквенные коды ‘f’ или ‘F’ в их интерактивной форме. См. Символы кода для интерактивного). Её значение определяет, вставляет ли read-file-name имя каталога по умолчанию в минибуфер, а также начальное имя файла, если оно есть. Если значение этой переменной равно nil, то read-file-name не вставляет никакой начальный ввод в минибуфер (если вы не укажете начальный ввод с помощью аргумента initial). В этом случае каталог по умолчанию всё ещё используется для автодополнения относительных имён файлов, но не отображается.

Если эта переменная равна nil и начальное содержимое минибуфера пустое, пользователю может потребоваться явно получить следующий элемент истории, чтобы получить значение по умолчанию. Если переменная имеет значение отличное от nil, начальное содержимое минибуфера всегда непустое, и пользователь всегда может запросить значение по умолчанию, сразу нажав RET в нередактируемом минибуфере. (См. выше.)

Например:

;; Here the minibuffer starts out with the default directory.
(let ((insert-default-directory t))
  (read-file-name "The file is "))

---------- Buffer: Minibuffer ----------
The file is ~lewis/manual/∗
---------- Buffer: Minibuffer ----------

;; Here the minibuffer is empty and only the prompt
;;   appears on its line.
(let ((insert-default-directory nil))
  (read-file-name "The file is "))

---------- Buffer: Minibuffer ----------
The file is ∗
---------- Buffer: Minibuffer ----------

Функция: read-shell-command prompt &optional initial history &rest args

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

Эта функция использует minibuffer-local-shell-command-map в качестве ключевой карты для ввода минибуфера. Аргумент history указывает список истории, который следует использовать; если он опущен или равен nil, он по умолчанию равен shell-command-history (см. shell-command-history). Необязательный аргумент initial задаёт начальное содержимое минибуфера (см. Начальный ввод). Остальные аргументы args, если они присутствуют, используются как аргументы default и inherit-input-method в read-from-minibuffer (см. Текст из минибуфера).

Переменная: minibuffer-local-shell-command-map

Эта ключевая карта используется read-shell-command для автодополнения имён команд и файлов, которые являются частью команды оболочки. Она использует minibuffer-local-map в качестве родительской ключевой карты и связывает TAB с completion-at-point.