E.8.4 その他の便利なモジュール用関数

このサブセクションではモジュールAPIが提供する便利な関数をいくつか説明します。前のサブセクションで説明した関数と同じようにこれらの関数は実際には関数ポインターであり、emacs_envポインターを介して呼び出す必要があります。Emacs 25以降に導入された関数の説明はそれらが利用可能になった最初のバージョンを付記します。

Function: bool eq (emacs_env *env, emacs_value a, emacs_value b)

この関数はaとbが表すLispオブジェクトが等しければtrue、それ以外ならfalseをリターンする。これはLisp関数eq (Equality Predicatesを参照)と同じだが、引数が表すオブジェクトのinternの要否を無視する。

等価性に関する他の述語はAPI関数には存在しないので、より複雑な等価性のテストを行うためには、以下で説明するinternとfuncallを使う必要がある。

Function: bool is_not_nil (emacs_env *env, emacs_value arg)

このえ関数はargで表されるLispオブジェクトをテストして非nilならtrue、それ以外はfalseをリターンする。

等価性をテストするたにinternを使ってnilを表すemacs_valueを取得して、上述のeqを使用すれば自身で等価性テストを実装できることに注意。しかしこの関数を使用するほうが簡便だろう。

Function: emacs_value type_of (emacs_env *env, emacs_value arg)

この関数はシンボルを表す値(文字列はstring、整数はinteger、プロセスならprocess等)としてargのタイプをリターンする。Type Predicatesを参照のこと。オブジェクトのタイプにコードが依存する必要があれば、既知のタイプシンボルと比較するためにinternとeqを使用できる。

Function: emacs_value intern (emacs_env *env, const char *name)

この関数は名前がname (null終端されたASCII文字列であること)であるような、internされたEmacsシンボルをリターンする。すでに存在していなれば新たにシンボルを作成する。

この関数は以下で説明するfuncallと共に用いることにより、Lispで呼び出し可能なEmcas関数(名前が純粋なASCII文字列である場合にかぎる)純粋なASCII文字列であるようなを呼び出す手段を提供する。たとえば以下はより協力なEmacsのintern関数(Creating Symbolsを参照)を呼び出すことにより、名前name_strが非ASCIIであるようなシンボルを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);

Function: emacs_value funcall (emacs_env *env, emacs_value func, ptrdiff_t nargs, emacs_value *args)

この関数はargsが指す配列のnargs個の引数を渡してfuncの指定先を呼び出す。引数funcは(上述のinternがリターンした)関数シンボル、make_functionがリターンしたモジュール関数(Module Functionsを参照)、Cで記述されたサブルーチン等。nargsが0ならargsはNULLポインターでもよい。

この関数はfuncがリターンした値をリターンする。

モジュールに長時間実行される可能性のあるコードが含まれる場合には、たとえばC-gをタイプする(Quittingを参照)等によりユーザーがquitを望むかどうかをコード内でときどきチェックするのはよいアイデアです。Emacs 26.1から利用可能になった以下の関数は、この目的のために提供されました。

Function: bool should_quit (emacs_env *env)

この関数はユーザーがquitを望むようならtrueをリターンする。この場合にはモジュール関数は実行中の処理をabortして可能なかぎり速やかにリターンすることを推奨する。ほとんどの場合はprocess_inputを使用すること。

ユーザーがquitを望むかどうかをチェックすることに加えて入力イベントを処理するには、Emacs 27.1以降で利用可能になった以下の関数を使用してください。

Function: enum emacs_process_input_result process_input (emacs_env *env)

この関数は保留中の入力イベントを処理する。ユーザーがquitを望んでいたり、シグナル処理中にエラーが発生したらemacs_process_input_quitをリターンする。この場合にはモジュール関数は行っているすべての処理をabortして可能なかぎり即座にリターンすることを推奨する。モジュールコードが実行を継続できるなら、process_inputはemacs_process_input_continueをリターンする。env内に保留中の非ローカルexitが存在しない場合のみ、リターン値はemacs_process_input_continue。process_input呼び出し後にモジュールが継続する場合には、変数値やバッファーコンテンツのとうなグローバル状態は任意の手段で変更され得る。

Function: int open_channel (emacs_env *env, emacs_value pipe_process)

このEmacs 28以降で利用可能になった関数は、既存のpipeプロセスへのチャンネルをオープンする。pipe_processはmake-pipe-processが作成した既存のpipeプロセスを参照しなければならない。Pipe Processesを参照のこと。成功すると、そのpipeへの書き込みに使用できる新たなファイルデスクリプターを値としてリターンする。他のすべてのモジュール関数と異なり、アクティブなモジュール環境がなくても、任意のスレッドがリターンしたファイルデスクリプターを使用できる。このファイルデスクリプターへの書き込みにはwrite関数を使用できる。使用後にはcloseを使用してファイルデスクリプターをクローズする。(libc)Low-Level I/Oを参照のこと。