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

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

Function: bool eq (emacs_env *env, emacs_value val1, emacs_value val2)

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

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

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

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

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

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

この関数はシンボルを表す値(文字列はstring、整数はinteger、プロセスならprocess等)としてobjectのタイプをリターンする。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 intern_args[] = { sym_name, env->intern (env, "nil") };
emacs_value symbol = env->funcall (env, fintern, 2, intern_args);

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して可能なかぎり速やかにリターンすることを推奨する。