X11R6 Sample Implementation Frame Work(日本語訳)

この文書では、Xlib の参考実装の内部にあるロケール依存関数の全てで利用できる「構造」、「メソッド」及びその２つの「シグネチャ」を定義する。参考実装の内部にある構成要素群を次の図 (Fig.1) のように分割することを提案する。

基本的には、Xlib の国際化されている部分(ロケール依存の X、Locale Dependent X、LDX)は、３つの部品(object)から成る。即ち、ロケール(locale、LC)、入力メソッド(input method、IM)、及び出力メソッド(output method、OM)である。LC は、ユーザの言語環境に依存する情報一式を提供する。IM はテキスト入力を管理し、OM はテキストの描画を管理する。IM と OM は、両者とも LC のデータ(LC data)に大きく依存している。

X11R5 には、Xlib の国際化を試みた参考実装が２つ存在する。Ximp と Xsi である。しかし、どちらの実装においても IM と OM は、実際には LC の非公式の拡張を利用(参照)している。これによって、Ximp と Xsi の２つの参考実装は共存できなくなっている。例えば、ユーザが特別な目的のために Ximp の一部として新たな OM を作成した場合、この OM は Xsi とは協働できない。

この問題の解決するために、上記の３つの部品の間の標準 API を定義し、それらの部品に共通の構造を定義する。

この章では、ロケール・オブジェクト・バインディングに関わる関数(着脱可能な層(pluggable layer)を実装するためのもの)について説明する。

ロケール・ローダ(locale loader)は、ロケール・オブジェクトのエントリ・ポイントである。ロケール・ローダは、XLCd オブジェクトをインスタンス化し(具体的な XLCd オブジェクトを作成し)、ロケール・メソッド群を指定されたロケール名と結びつける。ローダの動作は実装依存である。また、利用できるローダの種類も実装依存である。

ローダは _XOpenLC の中で呼び出されるが、_XOpenLC の呼び出しを行う者は、同関数の内側のことを気にする必要は無い。例えば、ローダを実装するにあたって動的に読み込みを行う関数を使用しており、且つ、対応する XLCd を解放する時に、ローダによって動的に組み込まれた機能部品(module)を取り除く(unload)ことが期待されている場合、この取り除き処理は XLCdMethods 構造体の閉じるメソッド(close method)が行うものとする。(訳註：XLCdMethods 構造体は内部に様々な手続きを保持している構造体である。定義は X11R7.7/lib/libX11-1.5.0/src/xlibi18n/Xlcint.h にある。)

ロケール・ローダのリストを初期化する

関数 _XlcInitLoader は、開発企業固有の方法でロケール・ローダ(locale loader)のリストを初期化するものである。各ローダの登録は、_XlcAddLoader を呼び出して行う。リスト内のローダの数と順序は、実装依存である。

ローダを追加する

関数 _XlcAddLoader は、引数「proc」で指定されたロケール・ローダを内部のローダ・リストに登録するものである。引数 position によって、「proc」のローダをローダ・リストの先頭に加えるべきなのか(XlcHead)、それとも末尾(XlcTail)に加えるべきなのかを指定する。

オブジェクト・ローダを呼び出す時は、ローダ・リストの先頭から順番に呼び出すことになる。

ローダを削除する

関数 _XlcRemoveLoader は、引数「proc」で指定されたロケール・ローダをローダ・リストから削除するものである。

現在の実装では、以下のロケール・ローダが用意されている。

この章では、ロケール・メソッドの API について説明する。この API は、IM と OM の両方から利用できる関数を集めたものである。ロケール・メソッドの API は次のような機能を提供する。即ち、ロケール依存の情報を取得する機能、文字集合(charset)を操作する機能、テキストを変換する機能などである。

ロケール・オブジェクトの私的な拡張(開発企業が作ったもの)を利用する代わりに上記の API を用いることで、ロケール、IM 及び OM の３者が互いに独立している状態を保つことができるようになる。

ロケール・メソッドを開く

関数 _XOpenLC は、指定されたロケール名に対応するロケール・メソッドを開くものである。_XOpenLC は、ロケール・オブジェクト・ローダ(ロケール・オブジェクトを読み込む手続き)を呼び出す。このローダは、_XlcAddLoader を通じて内部のローダ・リストに登録してあるものである。呼び出されたローダが有効であり且つロケールを開くことに成功した場合、_XOpenLC は XLCd を返す(訳註：XLCd はメソッドとデータを併せ持つ構造体を指す。定義は X11R7.7/lib/libX11-1.5.0/src/xlibi18n/Xlcint.h にある)。呼び出されたローダが有効でなかったか、あるいはロケールを開くことに失敗した場合、_XOpenLC は(リスト中の)次のローダを呼び出す。登録されていたローダ全てでロケールを開けなかった場合、_XOpenLC は NULL を返す。

関数 _XlcCurrentLC は、現在のロケールに結び付けられている XLCd を返すものである。

ロケール・メソッドを閉じる

関数 _XCloseLC は、引数 lcd で指定されたロケール・メソッドを閉じるものである。

ロケール・メソッドの属性値(values)を取得する

関数 _XGetLCValues は、エラーが起きなければ NULL を返す。エラーが起きた場合、取得に失敗した最初の引数の名前を返す。以下の属性が標準の引数として定義されている。これ以外の属性は実装依存である。

XlcCharSet は、ロケール・オブジェクトの中にある文字集合(文字群の部分集合の中の１つ)を表す識別子である。

typedef enum {
      XlcUnknown, XlcC0, XlcGL, XlcC1, XlcGR, XlcGLGR, XlcOther
} XlcSide;

typedef struct _XlcCharSetRec *XlcCharSet;

typedef struct {
      char *name;
      XPointer value;
} XlcArg, *XlcArgList;

typedef char* (*XlcGetCSValuesProc)(charset, args, num_args);
      XlcCharSet charset;
      XlcArgList args;
      int num_args;

typedef struct _XlcCharSetRec {
      char *name;
      XrmQuark xrm_name;
      char *encoding_name;
      XrmQuark xrm_encoding_name;
      XlcSide side;
      int char_size;
      int set_size;
      char *ct_sequence;
      XlcGetCSValuesProc get_values;
} XlcCharSetRec;

XlcCharSet を取得する

関数 _XlcGetCharSet は、「name」で指定された文字集合名に対応する XlcCharSet を返すものである。指定された「name」に結び付けられた XlcCharSet が存在しない場合、 _XlcGetCharSet は NULL を返す。

以下の文字集合が予め登録されている。

XlcCharSet を追加する

関数 _XlcAddCharSet は、「charset」で指定された XlcCharSet を登録するものである。

文字集合の属性値を取得する

関数 _XlcGetCSValues は、エラーが起きなければ NULL を返す。エラーが起きた場合、値が取得できなかった最初の引数の名前を返す。標準の引数として以下の属性が定義されている。これ以外の属性は実装依存である。

コンバータに関する共通 API 一式を用意している。この API は、入力テキストの型と出力テキストの型のどちらにも依存しないものである。

typedef struct _XlcConvRec *XlcConv;

typedef void (*XlcCloseConverterProc)(conv);
      XlcConv conv;

typedef int (*XlcConvertProc)(conv, from, from_left, to, to_left, args, num_args);
      XlcConv conv;
      XPointer *from;
      int *from_left;
      XPointer *to;
      int *to_left;
      XPointer *args;
      int num_args;

typedef void (*XlcResetConverterProc)(conv);
      XlcConv conv;

typedef struct _XlcConvMethodsRec {
      XlcCloseConverterProc close;
      XlcConvertProc convert;
      XlcResetConverterProc reset;
} XlcConvMethodsRec, *XlcConvMethods;

typedef struct _XlcConvRec {
    XlcConvMethods methods;
    XPointer state;
} XlcConvRec;

コンバータ(変換器)を開く

関数 _XlcOpenConverter はコンバータを開設するものである。このコンバータは、テキストを「from_type」で指定された型の符号化方式から「to_type」で指定された型の符号化方式へと変換する。関数 _XlcOpenConverter は、適切なコンバータを見つけられなかった場合、あるいは該当する(見つけた)コンバータを開けなかった場合、NULL を返す。それ以外の場合、同関数は変換記述子(conversion descriptor)を返す。

以下の型が予め定義されている。これ以外の型は実装依存である。

コンバータを閉じる

関数 _XlcCloseConverter は、「conv」で指定されたコンバータを閉鎖するものである。

符号の変換

関数 _XlcConvert は、ある型の文字の並び(from で指定された配列に入っているもの)を別の型の対応する文字の並び(to で指定された配列に入る)へと変換するものである。型は、_XlcOpenConverter の呼び出しの際に指定したものであり、その呼び出しで返る変換記述子「conv」を使って指定する。引数「from」「from_left」「to」「to_left」の意味(仕様)は、XPG4 iconv 関数と同じである。

状態依存の符号化方式(state-dependent encodings：訳註：shift encoding のこと)の場合、_XlcConvert の呼び出しにおいて「from」が NULL ポインタそのものであるか、あるいは「from」が NULL ポインタを指すポインタであれば、変換記述子「conv」は初期シフト状態へと移行する。

ロケールが用意する次の２つのコンバータは、args[0] が指す領域に適切な文字集合(XlcCharSet)を返すものである。

XlcNMultiByte/XlcNWideChar から XlcNCharSet への変換では、同じ符号化文字集合の文字群を持つ部分(segment)が抽出される。この関数の呼び出し１回につき１つの部分(segment)しか変換できない。

コンバータをリセットする

関数 _XlcResetConverter は、「conv」で指定されたコンバータをリセットするものである。

コンバータを登録する

typedef XlcConv (*XlcOpenConverterProc)(from_lcd, from_type, to_lcd, to_type);
      XLCd from_lcd;
      char *from_type;
      XLCd to_lcd;
      char *to_type;

関数 _XlcSetConverter は、(指定された XLCd の)コンバータ・リストにコンバータ１つを登録するものである。ここで登録されるコンバータは、from_type の型から to_type の型への変換を行う。

X ロケール・データベースには、言語によって定まるユーザの環境の情報の一部が入っている。以下の API は、X ロケール・データベース及びその他のロケール関連ファイルを利用するために用意されたものである。

X ロケール・データベースについて詳しく知りたければ、X ロケール・データベースの定義に関する文書を見てほしい。(訳註：「X Locale Database Specification」)

データベースからリソースを取得する

関数 _XlcGetResource は、指定された「lcd」のロケールと結び付けられている、ロケール依存のデータを取得するものである。ロケール・データは、システム・ロケールあるいは X ロケール・データベースによって提供される。どんな種類のデータが利用可能であるかは、実装依存である。

指定された「category」と「class」は、目的のロケール・データを見つけ出すために使用するものである。

戻り値は、引数 value に文字列のリスト(配列)の形式で返る。count に返る値によって、value 内の文字列の数がわかる。

value の戻り値はロケール・メソッドが所有しているため、関数 _XlcGetResource を呼び出した者はこれを変更したり解放したりしてはいけない。

ロケールに結びついたファイル名を取得する

関数 _XlcFileName は、指定された「lcd」と「category」に結び付けられているファイル名を null 文字終端の文字列の形で返すものである。ファイル名が見つからなかった場合、あるいは見つけたファイル名に対応する読み込み可能なファイルが存在しなかった場合、_XlcFileName は NULL を返す。返ってきたファイル名は、この関数を呼び出した者が解放する。

ファイル名を探す手続きは実装依存である。現在の実装では、_XlcFileName は「{category}.dir」ファイルを対応表として使用している。この表には、完全ロケール名とそれに対応するファイル名とを表す文字列の対が並んでいる。

Latin-1 文字列を比較する

関数 _XlcCompareIsoLatin1 は、ISO-8859-1 の文字列２つを比較するものである。ASCII の小文字を表すバイトは、比較を行う前に大文字に変換される。戻り値は整数であるが、「str1」が「str2」と比べて辞書的に(1)前にあるか(2)等しいか(3)後にあるかに応じて、0 より(1)小さいか(2)等しいか(3)大きくなる。

関数 _XlcNCompareIsoLatin1 は、最大でも「len」バイトしか比較を行わない点を除き、_XlcCompareISOLatin1 と同じである。

リソース関連のユーティリティ

XtNumber と同様のもの。

_XtCopyFromArg 及び _XtCopyToArg と同様のもの。

_XtCountVaList と同様のもの。

_XtVaToArgList と同様のもの。

typedef struct _XlcResource {
      char *name;
      XrmQuark xrm_name;
      int size;
      int offset;
      unsigned long mask;
} XlcResource, *XlcResourceList;

#define    XlcCreateMask   (1L<<0)
#define    XlcDefaultMask  (1L<<1)
#define    XlcGetMask      (1L<<2)
#define    XlcSetMask      (1L<<3)
#define    XlcIgnoreMask   (1L<<4)

_XtCompileResourceList と同様のもの。

XtGetSubvalues と同様のもの。

XtSetSubvalues と同様のもの。

ANSI C 互換の関数

以下に挙げるのは、非 ANSI C 環境のための ANSI C/MSE 互換の関数群である。

関数 _Xmblen は、「str」が指す文字の個数を返すものである。戻り値となる文字の個数を決めるにあたっては、「str」の中の「len」バイトしか使用しない。「str」が指す文字群の属するコード・セットは、現在のロケールにおける有効なコード・セットであれば何でもよい。

_Xmblen の呼び出しは、_Xmbtowc((wchar_t*)NULL, str, len) と等価である。(訳註：原文は「_Xmbtowc(_Xmbtowc((wchar_t*)NULL, str, len))」)

関数 _Xmbtowc は、「str」が指す文字群を(同文字群の)ワイド文字表現へと変換し、結果を「wstr」が指す領域に格納するものである。「len」は、「str」中の変換すべきバイトの数である。戻り値は、変換された文字の個数である。

_Xmbtowc の呼び出しは、_Xlcmbtowc((XLCd)NULL, wstr, str, len) と等価である。

関数 _Xlcmbtowc は、引数「lcd」が必要である点を除き、_Xmbtowc と同じである。「lcd」が (XLCd) NULL である場合、_Xlcmbtowc は現在のロケールを判断するために _XlcCurrentLC を呼び出す。

関数 _Xwctomb は、「wc」が指す単一のワイド文字をそのマルチバイト表現へと変換し、結果を「str」が指す領域に格納するものである。成功した場合、戻り値は 1 である。

_Xwctomb の呼び出しは、_Xlcwctomb((XLCd)NULL, str, wstr) と等価である。

関数 _Xlcwctomb は、引数「lcd」を必要とする点を除き、_Xwctomb と同じである。「lcd」が (XLCd) NULL である場合、_Xlcwctomb は現在のロケールを判断するために _XlcCurrentLC を呼び出す。

関数 _Xmbstowcs は、「str」が指す NULL 文字終端の文字列をそのワイド文字表現へと変換し、結果を「wstr」が指す領域へと格納するものである。「len」は、「str」中の変換すべき文字の個数である。

_Xmbstowcs の呼び出しは、_Xlcmbstowcs((XLCd)NULL, wstr, str, len) と等価である。

関数 _Xlcmbstowcs は、引数「lcd」が必要である点を除き、_Xmbstowcs と同じである。「lcd」が (XLCd) NULL である場合、_Xlcmbstowcs は現在のロケールを判断するために _XlcCurrentLC を呼び出す。

関数 _Xwcstombs は、 「wstr」が指す (wchar_t) NULL 文字終端のワイド文字列を NULL 文字終端のマルチバイト文字列に変換し、結果を「str」が指す領域に格納するものである。

_Xwcstombs の呼び出しは、_Xlcwcstombs((XLCd)NULL, str, wstr, len) と等価である。

関数 _Xlcwcstombs は、引数「lcd」が必要である点を除き、_Xwcstombs と同じである。「lcd」が (XLCd) NULL である場合、_Xlcwcstombs は現在のロケールを判断するために _XlcCurrentLC を呼び出す。

関数 _Xwcslen は、「wstr」が指す (wchar_t) NULL 文字終端のワイド文字列に入っているワイド文字の個数を返すものである。

関数 _Xwcscpy は、「wstr2」が指す (wchar_t) NULL 文字終端のワイド文字列を「wstr1」が指す対象に複写するものである。「wstr1」も (wchar_t) NULL 文字終端である。戻り値は「wstr1」へのポインタである。

関数 _Xwcsncpy は、「len」個のワイド文字を「wstr2」が指す対象から「wstr1」が指す対象へと複写する点を除き、_Xwcscpy と同じである。

関数 _Xwcscmp は、(wchar_t) NULL 文字終端のワイド文字列２つを比較するものである。戻り値は整数であるが、「wstr1」が「wstr2」と比べて辞書的に(1)前にあるか(2)等しいか(3)後にあるかに応じて、0 より(1)小さいか(2)等しいか(3)大きくなる。

関数 _Xwcsncmp は、最大でも「len」個のワイド文字しか比較されない点を除き、_XlcCompareISOLatin1 (訳註：多分 _Xwcscmp の間違い)と同じである。

関数 _XlcResolveI18NPath は、X ロケール・データベースの経路名のリストを返す。取得した経路は「dir」が指す配列に格納される。この経路は、コロンで区切られた(複数の)ディレクトリ経路から成る。

環境変数 XLOCALEDIR が設定されている場合、取得した経路には同変数の内容が含まれる。

X ロケール・データベースのデフォルトの経路は実装依存である。現在の実装では、デフォルトの経路は構築(build)の時点で決まる。

_XlcResolveI18NPath では、引数「dir」が指す配列のオーバーフロー(配列の容量を超えてしまうこと)の検査は行わない。この関数を呼び出す者が、経路を表す文字列を格納するのに十分なバッファを用意しなければならない。

関数 _XlcResolveLocaleName は完全ロケール名を返す。取得した完全ロケール名は、引数「full_name」が指す配列に格納される。完全ロケール名の言語、地域、コードセットを表す部分はそれぞれ、戻り値を受け取る引数「language」「territory」「codeset」に複写される。これらの引数に NULL を指定することは可能である。

ロケール名からそれに対応する完全ロケール名を導き出す規則は、実装依存である。

_XlcResolveLocaleName では、「full_name」「language」「territory」「codeset」が指す配列のオーバーフローの検査は行わない。この関数を呼び出す者が、それらの文字列を格納するのに十分なバッファを用意しなければならない。

現在の実装では、_XlcResolveLocaleName は、ロケール名と完全ロケール名の文字列の対を記録している対応表として locale.alias ファイルを用いている。