Blame doc/CALLOUTS.API.ja

Packit b89d10
Callouts API  Version 6.8.2 2018/04/13
Packit b89d10
Packit b89d10
#include <oniguruma.h>
Packit b89d10
Packit b89d10
(1) 呼び出し関数
Packit b89d10
(2) 内容の呼び出し関数の設定/取得
Packit b89d10
(3) 名前の呼び出し関数の設定
Packit b89d10
(4) ユーザデータ
Packit b89d10
(5) OnigCalloutArgsからの値の取得
Packit b89d10
(6) 名札
Packit b89d10
(7) 呼び出しデータ (呼び出し関数内から使用される)
Packit b89d10
(8) 呼び出しデータ (アプリケーションから使用される)
Packit b89d10
(9) その他の関数
Packit b89d10
Packit b89d10
Packit b89d10
(1) 呼び出し関数
Packit b89d10
Packit b89d10
  型: OnigCalloutFunc
Packit b89d10
Packit b89d10
  typedef int (*OnigCalloutFunc)(OnigCalloutArgs* args, void* user_data);
Packit b89d10
Packit b89d10
  若し呼び出し関数として0(NULL)がセットされると、呼ばれることはない
Packit b89d10
Packit b89d10
Packit b89d10
  * 呼び出し関数の戻り値 (int)
Packit b89d10
Packit b89d10
    ONIG_CALLOUT_FAIL(1):     失敗
Packit b89d10
    ONIG_CALLOUT_SUCCESS(0):  成功
Packit b89d10
    -1未満:                   エラーコード (検索/照合の終了)
Packit b89d10
Packit b89d10
    ONIG_CALLOUT_FAIL/SUCCESSは、後退中の呼び出しでは無視される。
Packit b89d10
    後退は失敗の回復過程なので。
Packit b89d10
Packit b89d10
  * 呼び出し関数の例
Packit b89d10
Packit b89d10
    extern int always_success(OnigCalloutArgs* args, void* user_data)
Packit b89d10
    {
Packit b89d10
      return ONIG_CALLOUT_SUCCESS;
Packit b89d10
    }
Packit b89d10
Packit b89d10
Packit b89d10
Packit b89d10
(2) 内容の呼び出し関数の設定/取得
Packit b89d10
Packit b89d10
# OnigCalloutFunc onig_get_progress_callout(void)
Packit b89d10
Packit b89d10
  内容の呼び出し関数(前進)を返す
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_set_progress_callout(OnigCalloutFunc f)
Packit b89d10
Packit b89d10
  内容の呼び出し関数(前進)をセットする。
Packit b89d10
  この値はonig_initialize_match_param()の中でデフォルトの呼び出し関数として
Packit b89d10
  セットされる。
Packit b89d10
Packit b89d10
  正常終了: ONIG_NORMAL
Packit b89d10
Packit b89d10
Packit b89d10
# OnigCalloutFunc onig_get_retraction_callout(void)
Packit b89d10
Packit b89d10
  内容の呼び出し関数(後退)を返す
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_set_retraction_callout(OnigCalloutFunc f)
Packit b89d10
Packit b89d10
  内容の呼び出し関数(後退)をセットする。
Packit b89d10
  この値はonig_initialize_match_param()の中でデフォルトの呼び出し関数として
Packit b89d10
  セットされる。
Packit b89d10
Packit b89d10
  正常終了: ONIG_NORMAL
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_set_progress_callout_of_match_param(OnigMatchParam* mp, OnigCalloutFunc f)
Packit b89d10
Packit b89d10
  内容の呼び出し関数(前進)をセットする。
Packit b89d10
Packit b89d10
  引数
Packit b89d10
  1 mp: match-paramアドレス
Packit b89d10
  2 f: 関数
Packit b89d10
Packit b89d10
  正常終了: ONIG_NORMAL
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_set_retraction_callout_of_match_param(OnigMatchParam* mp, OnigCalloutFunc f)
Packit b89d10
Packit b89d10
  内容の呼び出し関数(後退)をセットする。
Packit b89d10
Packit b89d10
  引数
Packit b89d10
  1 mp: match-paramアドレス
Packit b89d10
  2 f: 関数
Packit b89d10
Packit b89d10
  正常終了: ONIG_NORMAL
Packit b89d10
Packit b89d10
Packit b89d10
Packit b89d10
(3) 名前の呼び出し関数の設定
Packit b89d10
Packit b89d10
# int onig_set_callout_of_name(OnigEncoding enc, OnigCalloutType type, OnigUChar* name, OnigUChar* name_end, int callout_in, OnigCalloutFunc callout, OnigCalloutFunc end_callout, int arg_num, unsigned int arg_types[], int opt_arg_num, OnigValue opt_defaults[])
Packit b89d10
Packit b89d10
  名前の呼び出し関数をセットする。
Packit b89d10
  名前に許される文字: _ A-Z a-z 0-9   (* 最初の文字: _ A-Z a-z)
Packit b89d10
Packit b89d10
  (enc, name)のペアが、呼び出し関数を見つけるためのキーとして使用される。
Packit b89d10
  アプリケーションで使用される各エンコーディングに対してこの関数を呼ぶ必要がある。
Packit b89d10
  しかし若しencエンコーディングがASCII互換であり、(enc, name)に対するエントリが
Packit b89d10
  見つからない場合には、(ASCII, name)エントリが参照される。
Packit b89d10
  従って、若しASCII互換エンコーディングのみ使用している場合には、この関数を(ASCII, name)
Packit b89d10
  について一回呼べば十分である。
Packit b89d10
Packit b89d10
  引数
Packit b89d10
   1 enc:         文字エンコーディング
Packit b89d10
   2 type:        呼び出し型 (現在は ONIG_CALLOUT_TYPE_SINGLE のみサポート)
Packit b89d10
   3 name:        名前のアドレス (encでエンコーディングされている文字列)
Packit b89d10
   4 name_end:    名前の終端アドレス
Packit b89d10
   5 callout_in:  方向フラグ (ONIG_CALLOUT_IN_PROGRESS/RETRACTION/BOTH)
Packit b89d10
   6 callout:     呼び出し関数
Packit b89d10
   7 end_callout: *まだ使用していない (0をセット)
Packit b89d10
   8 arg_num:     引数の数 (* 最大値 ONIG_CALLOUT_MAX_ARGS_NUM == 4)
Packit b89d10
   9 arg_types:   引数の型の配列
Packit b89d10
  10 opt_arg_num: オプション引数の数
Packit b89d10
  11 opt_defaults: オプション引数のデフォルト値
Packit b89d10
Packit b89d10
  正常終了: ONIG_NORMAL
Packit b89d10
  error:
Packit b89d10
    ONIGERR_INVALID_CALLOUT_NAME
Packit b89d10
    ONIGERR_INVALID_ARGUMENT
Packit b89d10
    ONIGERR_INVALID_CALLOUT_ARG
Packit b89d10
Packit b89d10
Packit b89d10
Packit b89d10
(4) ユーザデータ
Packit b89d10
Packit b89d10
# int onig_set_callout_user_data_of_match_param(OnigMatchParam* param, void* user_data)
Packit b89d10
Packit b89d10
  呼び出し関数の引数として渡されるユーザデータをセットする。
Packit b89d10
Packit b89d10
  正常終了: ONIG_NORMAL
Packit b89d10
Packit b89d10
Packit b89d10
Packit b89d10
(5) OnigCalloutArgsからの値の取得
Packit b89d10
Packit b89d10
# int onig_get_callout_num_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  この呼び出しの呼び出し番号を返す。
Packit b89d10
  "呼び出し番号"とは、正規表現パターンの中の呼び出しに対する識別子である。
Packit b89d10
Packit b89d10
Packit b89d10
# OnigCalloutIn onig_get_callout_in_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  この呼び出しが起きた時の方向(前進中/後退中)を返す。
Packit b89d10
  (ONIG_CALLOUT_IN_PROGRESS か ONIG_CALLOUT_IN_RETRACTION)
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_get_name_id_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  この呼び出しの名前(name)の識別子を返す。
Packit b89d10
  若しこの呼び出しが内容の呼び出しのときには、ONIG_NON_NAME_IDが返される。
Packit b89d10
Packit b89d10
Packit b89d10
# const OnigUChar* onig_get_contents_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  この呼び出しの内容文字列(NULL終端あり)を返す。
Packit b89d10
  若しこの呼び出しが名前の呼び出しのときには、NULLを返す。
Packit b89d10
Packit b89d10
Packit b89d10
# const OnigUChar* onig_get_contents_end_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  この呼び出しの内容(contents)の終端を返す。
Packit b89d10
  若しこの呼び出しが名前の呼び出しのときには、NULLを返す。
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_get_args_num_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  この呼び出しの引数の数を返す。
Packit b89d10
  正規表現パターンの中で渡されなかったオプション引数も含む。
Packit b89d10
  若しこの呼び出しが内容の呼び出しのときには、ONIGERR_INVALID_ARGUMENTが返される。
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_get_passed_args_num_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  この呼び出しの本当に渡された引数の数を返す。
Packit b89d10
  若しこの呼び出しが内容の呼び出しのときには、ONIGERR_INVALID_ARGUMENTが返される。
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_get_arg_by_callout_args(OnigCalloutArgs* args, int index, OnigType* type, OnigValue* val)
Packit b89d10
Packit b89d10
  この呼び出しの一個の引数の値と型を返す。
Packit b89d10
  若しこの呼び出しが内容の呼び出しのときには、ONIGERR_INVALID_ARGUMENTが返される。
Packit b89d10
Packit b89d10
  正常終了: ONIG_NORMAL
Packit b89d10
Packit b89d10
Packit b89d10
# const OnigUChar* onig_get_string_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  対象文字列のアドレスを返す。
Packit b89d10
  onig_search()の二番目の引数(str)である。
Packit b89d10
Packit b89d10
Packit b89d10
# const OnigUChar* onig_get_string_end_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  対象文字列の終端アドレスを返す。
Packit b89d10
  onig_search()の三番目の引数(end)である。
Packit b89d10
Packit b89d10
Packit b89d10
# const OnigUChar* onig_get_start_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  対象文字列の現在の照合処理開始アドレスを返す。
Packit b89d10
Packit b89d10
Packit b89d10
# const OnigUChar* onig_get_right_range_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  対象文字列の現在の照合範囲アドレスを返す。
Packit b89d10
Packit b89d10
Packit b89d10
# const OnigUChar* onig_get_current_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  対象文字列の現在の照合位置アドレスを返す。
Packit b89d10
Packit b89d10
Packit b89d10
# OnigRegex onig_get_regex_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  この呼び出しの正規表現オブジェクトのアドレスを返す。
Packit b89d10
Packit b89d10
Packit b89d10
# unsigned long onig_get_retry_counter_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  retry-limit-in-matchのためのリトライカウンタの現在値を返す。
Packit b89d10
Packit b89d10
Packit b89d10
Packit b89d10
(6) 名札
Packit b89d10
Packit b89d10
  "Tag" (名札)とは、正規表現パターンの中で呼び出しに割り当てられた名前である。
Packit b89d10
  tag文字列に使用できる文字: _ A-Z a-z 0-9   (* 先頭の文字: _ A-Z a-z)
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_callout_tag_is_exist_at_callout_num(OnigRegex reg, int callout_num)
Packit b89d10
Packit b89d10
  その呼び出しにtagが割り当てられていれば1を返す、そうでなければ0を返す。
Packit b89d10
Packit b89d10
Packit b89d10
# const OnigUChar* onig_get_callout_tag_start(OnigRegex reg, int callout_num)
Packit b89d10
Packit b89d10
  その呼び出しに対するtag文字列(NULL終端あり)の先頭アドレスを返す。
Packit b89d10
Packit b89d10
Packit b89d10
# const OnigUChar* onig_get_callout_tag_end(OnigRegex reg, int callout_num)
Packit b89d10
Packit b89d10
  その呼び出しに対するtag文字列の終端アドレスを返す。
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_get_callout_num_by_tag(OnigRegex reg, const OnigUChar* tag, const OnigUChar* tag_end)
Packit b89d10
Packit b89d10
  そのtagに対する呼び出し番号を返す。
Packit b89d10
Packit b89d10
Packit b89d10
Packit b89d10
(7) 呼び出しデータ (呼び出し関数内から使用される)
Packit b89d10
Packit b89d10
  "呼び出しデータ" (callout data)とは、
Packit b89d10
  それぞれの呼び出しに対してそれぞれの検索処理の中で割り当てられた、
Packit b89d10
  ONIG_CALLOUT_DATA_SLOT_NUM(== 5)個の値の領域である。
Packit b89d10
  一個の呼び出しに対する各値の領域は、"スロット"(slot)番号(0 - 4)によって示される。
Packit b89d10
  呼び出しデータは呼び出し関数の実装者によって任意の目的に使用される。
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_get_callout_data_by_callout_args(OnigCalloutArgs* args, int callout_num, int slot, OnigType* type, OnigValue* val)
Packit b89d10
Packit b89d10
  callout_num/slotによって示された呼び出しスロットに対するデータの値/型を返す。
Packit b89d10
Packit b89d10
  正常終了: ONIG_NORMAL
Packit b89d10
        1: 値が未セット (typeは ONIG_TYPE_VOID)
Packit b89d10
      < 0: エラーコード
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_get_callout_data_by_callout_args_self(OnigCalloutArgs* args, int slot, OnigType* type, OnigValue* val)
Packit b89d10
Packit b89d10
  自分自身の呼び出しのslotによって示されたスロットに対するデータの値/型を返す。
Packit b89d10
Packit b89d10
  正常終了: ONIG_NORMAL
Packit b89d10
        1: 値が未セット (typeは ONIG_TYPE_VOID)
Packit b89d10
      < 0: エラーコード
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_set_callout_data_by_callout_args(OnigCalloutArgs* args, int callout_num, int slot, OnigType type, OnigValue* val)
Packit b89d10
Packit b89d10
  callout_num/slotによって示された呼び出しスロットに対する値/型をセットする。。
Packit b89d10
Packit b89d10
  正常終了: ONIG_NORMAL
Packit b89d10
      < 0: エラーコード
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_set_callout_data_by_callout_args_self(OnigCalloutArgs* args, int slot, OnigType type, OnigValue* val)
Packit b89d10
Packit b89d10
  自分自身の呼び出しのslotによって示されたスロットに対する値/型をセットする。。
Packit b89d10
Packit b89d10
  正常終了: ONIG_NORMAL
Packit b89d10
      < 0: エラーコード
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_get_callout_data_by_callout_args_self_dont_clear_old(OnigCalloutArgs* args, int slot, OnigType* type, OnigValue* val)
Packit b89d10
Packit b89d10
  この関数は、onig_get_callout_data_by_callout_args_self()とほぼ同じである。
Packit b89d10
  しかしこの関数は、現在の照合処理以前の失敗した照合処理の中でセットされた値を
Packit b89d10
  クリアしない。
Packit b89d10
  他のonig_get_callout_data_xxxx()関数は、以前の失敗した照合処理の中でセットされた値を
Packit b89d10
  クリアする。
Packit b89d10
Packit b89d10
  例えば、組み込み呼び出し(*TOTAL_COUNT)は、検索処理の中の全ての照合処理の積算カウントを
Packit b89d10
  得るためにこの関数を使用して実装されている。
Packit b89d10
  組み込む呼び出し(*COUNT)は、この関数を使用しないので、最後の成功した照合処理だけの
Packit b89d10
  カウントを返す。
Packit b89d10
Packit b89d10
Packit b89d10
Packit b89d10
(8) 呼び出しデータ (アプリケーションから使用される)
Packit b89d10
Packit b89d10
# int onig_get_callout_data(OnigRegex reg, OnigMatchParam* mp, int callout_num, int slot, OnigType* type, OnigValue* val)
Packit b89d10
Packit b89d10
  callout_num/slotによって示された呼び出しスロットに対するデータの値/型を返す。
Packit b89d10
Packit b89d10
  正常終了: ONIG_NORMAL
Packit b89d10
        1: 値が未セット (typeは ONIG_TYPE_VOID)
Packit b89d10
      < 0: エラーコード
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_get_callout_data_by_tag(OnigRegex reg, OnigMatchParam* mp, const OnigUChar* tag, const OnigUChar* tag_end, int slot, OnigType* type, OnigValue* val)
Packit b89d10
Packit b89d10
  tag/slotによって示された呼び出しスロットに対するデータの値/型を返す。
Packit b89d10
Packit b89d10
  正常終了: ONIG_NORMAL
Packit b89d10
        1: 値が未セット (typeは ONIG_TYPE_VOID)
Packit b89d10
      < 0: エラーコード
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_set_callout_data(OnigRegex reg, OnigMatchParam* mp, int callout_num, int slot, OnigType type, OnigValue* val)
Packit b89d10
Packit b89d10
  callout_num/slotによって示された呼び出しスロットに対する値/型をセットする。。
Packit b89d10
Packit b89d10
  正常終了: ONIG_NORMAL
Packit b89d10
      < 0: エラーコード
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_set_callout_data_by_tag(OnigRegex reg, OnigMatchParam* mp, const OnigUChar* tag, const OnigUChar* tag_end, int slot, OnigType type, OnigValue* val)
Packit b89d10
Packit b89d10
  tag/slotによって示された呼び出しスロットに対する値/型をセットする。。
Packit b89d10
Packit b89d10
  正常終了: ONIG_NORMAL
Packit b89d10
      < 0: エラーコード
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_get_callout_data_dont_clear_old(OnigRegex reg, OnigMatchParam* mp, int callout_num, int slot, OnigType* type, OnigValue* val)
Packit b89d10
Packit b89d10
  この関数を使用する必要はないと思われる。
Packit b89d10
  廃止予定。
Packit b89d10
Packit b89d10
Packit b89d10
Packit b89d10
(9) その他の関数
Packit b89d10
Packit b89d10
# OnigUChar* onig_get_callout_name_by_name_id(int name_id)
Packit b89d10
Packit b89d10
  名前の識別子に対する名前を返す。
Packit b89d10
  不正な識別子が渡された場合には0を返す。
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_get_capture_range_in_callout(OnigCalloutArgs* args, int mem_num, int* begin, int* end)
Packit b89d10
Packit b89d10
  現在の捕獲範囲を返す。
Packit b89d10
  位置は、対象文字列に対するバイト単位で表される。
Packit b89d10
  未捕獲のmem_numに対しては、ONIG_REGION_NOTPOSがセットされる。
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_get_used_stack_size_in_callout(OnigCalloutArgs* args, int* used_num, int* used_bytes)
Packit b89d10
Packit b89d10
  現在使用されている照合処理用スタックサイズを返す。
Packit b89d10
Packit b89d10
  used_num:   要素数
Packit b89d10
  used_bytes: バイト数
Packit b89d10
Packit b89d10
//END