Разные вспомогательные функции для модулей

В этом подразделе описаны несколько удобных функций, предоставляемых модулем API. Как и функции, описанные в предыдущих подразделах, все они на самом деле указатели на функции и должны вызываться через указатель emacs_env. Описание функций, добавленных после Emacs 25, указывает первую версию, в которой они стали доступны.

Функция: bool eq (emacs_env *env, emacs_value a, emacs_value b)

Эта функция возвращает true, если объекты Lisp, представленные a и b, идентичны, false, в противном случае. Это то же самое, что и функция Lisp eq (см. Предикаты равенства), но избегает необходимости интернирования объектов, представленных аргументами.

Нет функций API для других предикатов равенства, поэтому вам нужно использовать intern и funcall, описанные ниже, для выполнения более сложных проверок на равенство.

Функция: bool is_not_nil (emacs_env *env, emacs_value arg)

Эта функция проверяет, является ли объект Lisp, представленный arg, не nil; она возвращает true или false соответственно.

Обратите внимание, что вы могли бы реализовать эквивалентную проверку, используя intern для получения emacs_value, представляющего nil, а затем использовать eq, описанную выше, для проверки на равенство. Но использование этой функции более удобно.

Функция: emacs_value type_of (emacs_env *env, emacs_value arg)

Эта функция возвращает тип arg в виде значения, представляющего символ: string для строки, integer для целого числа, process для процесса и т. д. См. Предикаты типов. Вы можете использовать intern и eq для сравнения с известными символами типов, если вашему коду необходимо полагаться на тип объекта.

Функция: emacs_value intern (emacs_env *env, const char *name)

Эта функция возвращает интернированный символ Emacs с именем name, который должен быть строкой с нулевым завершением ASCII. Она создаёт новый символ, если он ещё не существует.

Вместе с funcall, описанной ниже, эта функция предоставляет способ вызова любой вызываемой функцией Lisp функции Emacs, при условии, что её имя является чистой строкой ASCII. Например, вот как интернировать символ, имя которого name_str не является ASCII, вызвав более мощную функцию Emacs intern (см. Создание символов):

emacs_value fintern = env->intern (env, "intern");
emacs_value sym_name =
  env->make_string (env, name_str, strlen (name_str));
emacs_value symbol = env->funcall (env, fintern, 1, &sym_name);

Функция: emacs_value funcall (emacs_env *env, emacs_value func, ptrdiff_t nargs, emacs_value *args)

Эта функция вызывает указанную функцию func, передавая ей nargs аргументов из массива, на который указывает args. Аргумент func может быть символом функции (например, возвращённым intern, описанным выше), функцией модуля, возвращённой make_function (см. Функции модулей), подпрограммой, написанной на C, и т. д. Если nargs равно нулю, args может быть указателем NULL.

Функция возвращает значение, возвращённое func.

Если ваш модуль включает потенциально длительный код, рекомендуется время от времени проверять в этом коде, хочет ли пользователь выйти, например, нажав C-g (см. Выход). Для этой цели предоставлена следующая функция, доступная с Emacs 26.1.

Функция: bool should_quit (emacs_env *env)

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

Для обработки событий ввода помимо проверки желания пользователя выйти используйте следующую функцию, доступную с Emacs 27.1.

Функция: enum emacs_process_input_result process_input (emacs_env *env)

Эта функция обрабатывает ожидающие события ввода. Она возвращает emacs_process_input_quit, если пользователь хочет выйти или произошла ошибка при обработке сигналов. В этом случае рекомендуется, чтобы функция вашего модуля прервала все текущие вычисления и вернулась как можно скорее. Если код модуля может продолжать выполняться, process_input возвращает emacs_process_input_continue. Возвращаемое значение равно emacs_process_input_continue, только если нет ожидающего выхода из функции env. Если модуль продолжает выполняться после вызова process_input, глобальное состояние, такое как значения переменных и содержимое буфера, может быть изменено произвольным образом.

Функция: int open_channel (emacs_env *env, emacs_value pipe_process)

Эта функция, доступная с Emacs 28, открывает канал к существующему процессу трубы. pipe_process должен ссылаться на существующий процесс трубы, созданный make-pipe-process. Процессы трубы. При успешном выполнении возвращаемое значение будет новым дескриптором файла, который вы можете использовать для записи в трубу. В отличие от всех других функций модуля, возвращённый дескриптор файла можно использовать из произвольных потоков, даже если среда модуля не активна. Вы можете использовать функцию write для записи в дескриптор файла. После завершения закройте дескриптор файла с помощью функции close. (libc)Низкоуровневый ввод-вывод.