path: root/doc/API.ja

鬼車インターフェース Version 6.1.0   2016/08/22

#include <oniguruma.h>


# int onig_initialize(OnigEncoding use_encodings[], int num_encodings)

  ライブラリの初期化
  最初に呼び出す必要がある。

  * onig_init() は廃止

  引数
  1 use_encodings:         使用する文字エンコーディングの配列
  2 num_encodings:         文字エンコーディングの数


# int onig_error_code_to_str(UChar* err_buf, int err_code, ...)

  エラーメッセージを取得する。

  この関数を、onig_new()の結果に対して呼び出す場合には、onig_new()のpattern引数を
  メモリ解放するよりも前に呼び出さなければならない。

  正常終了戻り値: エラーメッセージ文字列のバイト長

  引数
  1 err_buf:              エラーメッセージを格納する領域
                          (必要なサイズ: ONIG_MAX_ERROR_MESSAGE_LEN)
  2 err_code:             エラーコード
  3 err_info (optional):  onig_new()のerr_info


# void onig_set_warn_func(OnigWarnFunc func)

  警告通知関数をセットする。

  警告:
    '[', '-', ']' in character class without escape.
    ']' in pattern without escape.

  引数
  1 func:    警告関数    void (*func)(char* warning_message)


# void onig_set_verb_warn_func(OnigWarnFunc func)

  詳細警告通知関数をセットする。

  詳細警告:
    redundant nested repeat operator.

  引数
  1 func:    詳細警告関数    void (*func)(char* warning_message)


# int onig_new(regex_t** reg, const UChar* pattern, const UChar* pattern_end,
            OnigOptionType option, OnigEncoding enc, OnigSyntaxType* syntax,
            OnigErrorInfo* err_info)

  正規表現オブジェクト(regex)を作成する。

  正常終了戻り値: ONIG_NORMAL

  引数
  1 reg:         作成された正規表現オブジェクトを返すアドレス
  2 pattern:     正規表現パターン文字列
  3 pattern_end: 正規表現パターン文字列の終端アドレス(pattern + pattern length)
  4 option:      正規表現コンパイル時オプション

      ONIG_OPTION_NONE               オプションなし
      ONIG_OPTION_SINGLELINE         '^' -> '\A', '$' -> '\Z'
      ONIG_OPTION_MULTILINE          '.'が改行にマッチする
      ONIG_OPTION_IGNORECASE         曖昧マッチ オン
      ONIG_OPTION_EXTEND             パターン拡張形式
      ONIG_OPTION_FIND_LONGEST       最長マッチ
      ONIG_OPTION_FIND_NOT_EMPTY     空マッチを無視
      ONIG_OPTION_NEGATE_SINGLELINE
            ONIG_SYNTAX_POSIX_BASIC, ONIG_SYNTAX_POSIX_EXTENDED,
            ONIG_SYNTAX_PERL, ONIG_SYNTAX_PERL_NG, ONIG_SYNTAX_JAVAで
            デフォルトで有効なONIG_OPTION_SINGLELINEをクリアする。

      ONIG_OPTION_DONT_CAPTURE_GROUP 名前付き捕獲式集合のみ捕獲
      ONIG_OPTION_CAPTURE_GROUP      名前無し捕獲式集合も捕獲

  5 enc:        文字エンコーディング

      ONIG_ENCODING_ASCII         ASCII
      ONIG_ENCODING_ISO_8859_1    ISO 8859-1
      ONIG_ENCODING_ISO_8859_2    ISO 8859-2
      ONIG_ENCODING_ISO_8859_3    ISO 8859-3
      ONIG_ENCODING_ISO_8859_4    ISO 8859-4
      ONIG_ENCODING_ISO_8859_5    ISO 8859-5
      ONIG_ENCODING_ISO_8859_6    ISO 8859-6
      ONIG_ENCODING_ISO_8859_7    ISO 8859-7
      ONIG_ENCODING_ISO_8859_8    ISO 8859-8
      ONIG_ENCODING_ISO_8859_9    ISO 8859-9
      ONIG_ENCODING_ISO_8859_10   ISO 8859-10
      ONIG_ENCODING_ISO_8859_11   ISO 8859-11
      ONIG_ENCODING_ISO_8859_13   ISO 8859-13
      ONIG_ENCODING_ISO_8859_14   ISO 8859-14
      ONIG_ENCODING_ISO_8859_15   ISO 8859-15
      ONIG_ENCODING_ISO_8859_16   ISO 8859-16
      ONIG_ENCODING_UTF8          UTF-8
      ONIG_ENCODING_UTF16_BE      UTF-16BE
      ONIG_ENCODING_UTF16_LE      UTF-16LE
      ONIG_ENCODING_UTF32_BE      UTF-32BE
      ONIG_ENCODING_UTF32_LE      UTF-32LE
      ONIG_ENCODING_EUC_JP        EUC-JP
      ONIG_ENCODING_EUC_TW        EUC-TW
      ONIG_ENCODING_EUC_KR        EUC-KR
      ONIG_ENCODING_EUC_CN        EUC-CN
      ONIG_ENCODING_SJIS          Shift_JIS
      ONIG_ENCODING_KOI8_R        KOI8-R
      ONIG_ENCODING_CP1251        CP1251
      ONIG_ENCODING_BIG5          Big5
      ONIG_ENCODING_GB18030       GB18030

      または、ユーザが定義したOnigEncodingTypeデータのアドレス

  6 syntax:     正規表現パターン文法定義

      ONIG_SYNTAX_ASIS              plain text
      ONIG_SYNTAX_POSIX_BASIC       POSIX Basic RE
      ONIG_SYNTAX_POSIX_EXTENDED    POSIX Extended RE
      ONIG_SYNTAX_EMACS             Emacs
      ONIG_SYNTAX_GREP              grep
      ONIG_SYNTAX_GNU_REGEX         GNU regex
      ONIG_SYNTAX_JAVA              Java (Sun java.util.regex)
      ONIG_SYNTAX_PERL              Perl
      ONIG_SYNTAX_PERL_NG           Perl + 名前付き捕獲式集合
      ONIG_SYNTAX_RUBY              Ruby
      ONIG_SYNTAX_DEFAULT           default (== Ruby)
                                    onig_set_default_syntax()

      または、ユーザが定義したOnigSyntaxTypeデータのアドレス

  7 err_info: エラー情報を返すためのアドレス
              onig_error_code_to_str()の三番目の引数として使用する



# int onig_new_without_alloc(regex_t* reg, const UChar* pattern,
            const UChar* pattern_end,
            OnigOptionType option, OnigEncoding enc, OnigSyntaxType* syntax,
            OnigErrorInfo* err_info)

  正規表現オブジェクト(regex)を作成する。
  regの領域を内部で割り当てない。

  正常終了戻り値: ONIG_NORMAL



# int onig_new_deluxe(regex_t** reg, const UChar* pattern, const UChar* pattern_end,
                      OnigCompileInfo* ci, OnigErrorInfo* einfo)

  正規表現オブジェクト(regex)を作成する。
  この関数は、onig_new()のデラックス版。

  正常終了戻り値: ONIG_NORMAL

  引数
  1 reg:         作成された正規表現オブジェクトを返すアドレス
  2 pattern:     正規表現パターン文字列
  3 pattern_end: 正規表現パターン文字列の終端アドレス(pattern + pattern length)
  4 ci:          コンパイル情報

    ci->num_of_elements: ciの要素数 (現在の版では: 5)
    ci->pattern_enc:     パターン文字列の文字エンコーディング
    ci->target_enc:      対象文字列の文字エンコーディング
    ci->syntax:          正規表現パターン文法定義
    ci->option:          正規表現コンパイル時オプション
    ci->case_fold_flag:  ONIG_OPTION_IGNORECASEモードでの
                         文字曖昧マッチ指定ビットフラグ

       ONIGENC_CASE_FOLD_MIN:           最小
       ONIGENC_CASE_FOLD_DEFAULT:       最小
                                        onig_set_default_case_fold_flag()

  5 err_info:    エラー情報を返すためのアドレス
                 onig_error_code_to_str()の三番目の引数として使用する


  異なる文字エンコーディングの組み合わせは、以下の場合にのみ許される。

    pattern_enc: ASCII, ISO_8859_1
    target_enc:  UTF16_BE, UTF16_LE, UTF32_BE, UTF32_LE

    pattern_enc: UTF16_BE/LE
    target_enc:  UTF16_LE/BE

    pattern_enc: UTF32_BE/LE
    target_enc:  UTF32_LE/BE


# void onig_free(regex_t* reg)

  正規表現オブジェクトのメモリを解放する。

  引数
  1 reg: 正規表現オブジェクト


# void onig_free_body(regex_t* reg)

  正規表現オブジェクトのメモリを解放する。(reg自身の領域を除いて)

  引数
  1 reg: 正規表現オブジェクト



# int onig_search(regex_t* reg, const UChar* str, const UChar* end, const UChar* start,
                   const UChar* range, OnigRegion* region, OnigOptionType option)

  正規表現で文字列を検索し、検索結果とマッチ領域を返す。

  正常終了戻り値: マッチ位置 (p - str >= 0)
  検索失敗:       ONIG_MISMATCH (< 0)

  引数
  1 reg:    正規表現オブジェクト
  2 str:    検索対象文字列
  3 end:    検索対象文字列の終端アドレス
  4 start:  検索対象文字列の検索先頭位置アドレス
  5 range:  検索対象文字列の検索終了位置アドレス
    前方探索  (start <= 探索される文字列 < range)
    後方探索  (range <= 探索される文字列 <= start)
  6 region: マッチ領域情報(region)  (NULLも許される)
  7 option: 検索時オプション

    ONIG_OPTION_NOTBOL        文字列の先頭(str)を行頭と看做さない
    ONIG_OPTION_NOTEOL        文字列の終端(end)を行末と看做さない
    ONIG_OPTION_POSIX_REGION  region引数をPOSIX APIのregmatch_t[]にする


# int onig_match(regex_t* reg, const UChar* str, const UChar* end, const UChar* at,
		 OnigRegion* region, OnigOptionType option)

  文字列の指定位置でマッチングを行い、結果とマッチ領域を返す。

  正常終了戻り値: マッチしたバイト長 (>= 0)
  not match:      ONIG_MISMATCH      ( < 0)

  引数
  1 reg:    正規表現オブジェクト
  2 str:    検索対象文字列
  3 end:    検索対象文字列の終端アドレス
  4 at:     検索対象文字列の検索アドレス
  5 region: マッチ領域情報(region)  (NULLも許される)
  6 option: 検索時オプション

    ONIG_OPTION_NOTBOL        文字列の先頭(str)を行頭と看做さない
    ONIG_OPTION_NOTEOL        文字列の終端(end)を行末と看做さない
    ONIG_OPTION_POSIX_REGION  region引数をPOSIX APIのregmatch_t[]にする


# int onig_scan(regex_t* reg, const UChar* str, const UChar* end,
                OnigRegion* region, OnigOptionType option,
                int (*scan_callback)(int, int, OnigRegion*, void*),
                void* callback_arg)

  正規表現で文字列をスキャンして、マッチングする毎にコールバック関数を呼び出す。

  正常終了: マッチ回数 (0回も含める)
  エラー:   エラーコード (< 0)
  中断: コールバック関数が０以外の戻り値を返したとき、その値を戻り値として中断

  引数
  1 reg:    正規表現オブジェクト
  2 str:    検索対象文字列
  3 end:    検索対象文字列の終端アドレス
  4 region: マッチ領域情報(region)  (NULLも許される)
  5 option: 検索時オプション
  6 scan_callback: コールバック関数
  7 callback_arg:  コールバック関数に渡される付加引数値


# OnigRegion* onig_region_new(void)

  マッチ領域情報(region)を作成する。


# void onig_region_free(OnigRegion* region, int free_self)

  マッチ領域情報(region)で使用されているメモリを解放する。

  引数
  1 region:    マッチ領域情報オブジェクト
  2 free_self:  [1: region自身を含めて全て解放, 0: region自身は解放しない]


# void onig_region_copy(OnigRegion* to, OnigRegion* from)

  マッチ領域情報(region)を複製する。

  引数
  1 to:   対象領域
  2 from: 元領域


# void onig_region_clear(OnigRegion* region)

  マッチ領域情報(region)の中味をクリアする。

  引数
  1 region: 対象領域


# int onig_region_resize(OnigRegion* region, int n)

  マッチ領域情報(region)の捕獲式集合(グループ)数を変更する。

  正常終了戻り値: ONIG_NORMAL

  引数
  1 region: 対象領域
  2 n:      新しいサイズ


# int onig_name_to_group_numbers(regex_t* reg, const UChar* name, const UChar* name_end,
                                  int** num_list)

  指定した名前に対する名前付き捕獲式集合(グループ)の
  グループ番号リストを返す。
  名前付き捕獲式集合は、(?<name>....)によって定義できる。

  正常終了戻り値:  指定された名前に対するグループ数
                   (例 /(?<x>..)(?<x>..)/  ==>  2)
  名前に対するグループが存在しない: -1

  引数
  1 reg:       正規表現オブジェクト
  2 name:      捕獲式集合(グループ)名
  3 name_end:  捕獲式集合(グループ)名の終端アドレス
  4 num_list:  番号リストを返すアドレス


# int onig_name_to_backref_number(regex_t* reg, const UChar* name, const UChar* name_end,
                                  OnigRegion *region)

  指定された名前の後方参照(\k<name>)に対する捕獲式集合(グループ)の番号を返す。
  名前に対して、複数のマッチ領域が有効であれば、その中の最大の番号を返す。
  名前に対する捕獲式集合が一個しかないときには、対応するマッチ領域が有効か
  どうかに関係なく、その番号を返す。(従って、regionにはNULLを渡してもよい。)

  正常終了戻り値: 番号

  引数
  1 reg:       正規表現オブジェクト
  2 name:      捕獲式集合(グループ)名
  3 name_end:  捕獲式集合(グループ)名の終端アドレス
  4 region:    search/match結果のマッチ領域


# int onig_foreach_name(regex_t* reg,
                        int (*func)(const UChar*, const UChar*, int,int*,regex_t*,void*),
                        void* arg)

  全ての名前に対してコールバック関数呼び出しを実行する。

  正常終了戻り値: 0
  エラー:         コールバック関数の戻り値

  引数
  1 reg:     正規表現オブジェクト
  2 func:    コールバック関数
             func(name, name_end, <number of groups>, <group number's list>,
                  reg, arg);

             funcが0以外の値を返すと、それ以降のコールバックは行なわずに
             終了する。

  3 arg:     funcに対する追加引数


# int onig_number_of_names(regex_t* reg)

  パターン中で定義された名前の数を返す。
  一個の名前の多重定義は一個と看做す。

  引数
  1 reg:    正規表現オブジェクト


# OnigEncoding     onig_get_encoding(regex_t* reg)
# OnigOptionType   onig_get_options(regex_t* reg)
# OnigCaseFoldType onig_get_case_fold_flag(regex_t* reg)
# OnigSyntaxType*  onig_get_syntax(regex_t* reg)

  正規表現オブジェクトに対して、対応する値を返す。

  引数
  1 reg:    正規表現オブジェクト


# int onig_number_of_captures(regex_t* reg)

  パターン中で定義された捕獲グループの数を返す。

  引数
  1 reg:    正規表現オブジェクト


# int onig_number_of_capture_histories(regex_t* reg)

  パターン中で定義された捕獲履歴(?@...)の数を返す。

  使用する文法で捕獲履歴機能が有効(ONIG_SYN_OP2_ATMARK_CAPTURE_HISTORY)
  でなければ、捕獲履歴機能は使用できない。

  引数
  1 reg:    正規表現オブジェクト


# OnigCaptureTreeNode* onig_get_capture_tree(OnigRegion* region)

  捕獲履歴データのルートノードを返す。

  マッチが失敗している場合には、この値は不定である。

  引数
  1 region: マッチ領域


# int onig_capture_tree_traverse(OnigRegion* region, int at,
                  int(*func)(int,int,int,int,int,void*), void* arg)

  捕獲履歴データ木を巡回してコールバックする。

  正常終了戻り値: 0
  エラー:         コールバック関数の戻り値

  引数
  1 region:  マッチ領域
  2 at:      コールバックを行なうタイミング

    ONIG_TRAVERSE_CALLBACK_AT_FIRST:
        最初にコールバックして、子ノードを巡回
    ONIG_TRAVERSE_CALLBACK_AT_LAST:
        子ノードを巡回して、コールバック
    ONIG_TRAVERSE_CALLBACK_AT_BOTH:
        最初にコールバックして、子ノードを巡回、最後にもう一度コールバック

  3 func:    コールバック関数
             funcが0以外の値を返すと、それ以降の巡回は行なわずに
             終了する。

             int func(int group, int beg, int end, int level, int at,
                      void* arg)
               group: グループ番号
               beg:   マッチ開始位置
               end    マッチ終了位置
               level: ネストレベル (0から)
               at:    コールバックが呼び出されたタイミング
                      ONIG_TRAVERSE_CALLBACK_AT_FIRST
                      ONIG_TRAVERSE_CALLBACK_AT_LAST
               arg:   追加引数

  4 arg;     funcに対する追加引数


# int onig_noname_group_capture_is_active(regex_t* reg)

  名前なし式集合の捕獲機能が有効かどうかを返す。

  有効: 1
  無効: 0

  引数
  1 reg:    正規表現オブジェクト


  オプションのONIG_OPTION_DONT_CAPTURE_GROUPがON --> 無効

  パターンが名前つき式集合を使用している
  AND 使用文法で、ONIG_SYN_CAPTURE_ONLY_NAMED_GROUPがON
  AND オプションのONIG_OPTION_CAPTURE_GROUPがOFF
  --> 無効

  上記以外の場合 --> 有効


# UChar* onigenc_get_prev_char_head(OnigEncoding enc, const UChar* start, const UChar* s)

  文字一個分前の文字列位置を返す。

  引数
  1 enc:   文字エンコーディング
  2 start: 文字列の先頭アドレス
  3 s:     文字列中の位置


# UChar* onigenc_get_left_adjust_char_head(OnigEncoding enc,
                                           const UChar* start, const UChar* s)

  文字の先頭バイト位置になるように左側に調整したアドレスを返す。

  引数
  1 enc:   文字エンコーディング
  2 start: 文字列の先頭アドレス
  3 s:     文字列中の位置


# UChar* onigenc_get_right_adjust_char_head(OnigEncoding enc,
                                            const UChar* start, const UChar* s)

  文字の先頭バイト位置になるように右側に調整したアドレスを返す。

  引数
  1 enc:   文字エンコーディング
  2 start: 文字列の先頭アドレス
  3 s:     文字列中の位置


# int onigenc_strlen(OnigEncoding enc, const UChar* s, const UChar* end)
# int onigenc_strlen_null(OnigEncoding enc, const UChar* s)

  文字列の文字数を返す。


# int onigenc_str_bytelen_null(OnigEncoding enc, const UChar* s)

  文字列のバイト数を返す。


# int onig_set_default_syntax(OnigSyntaxType* syntax)

  デフォルトの正規表現パターン文法をセットする。

  引数
  1 syntax: 正規表現パターン文法


# void onig_copy_syntax(OnigSyntaxType* to, OnigSyntaxType* from)

  正規表現パターン文法をコピーする。

  引数
  1 to:   対象
  2 from: 元


# unsigned int onig_get_syntax_op(OnigSyntaxType* syntax)
# unsigned int onig_get_syntax_op2(OnigSyntaxType* syntax)
# unsigned int onig_get_syntax_behavior(OnigSyntaxType* syntax)
# OnigOptionType onig_get_syntax_options(OnigSyntaxType* syntax)

# void onig_set_syntax_op(OnigSyntaxType* syntax, unsigned int op)
# void onig_set_syntax_op2(OnigSyntaxType* syntax, unsigned int op2)
# void onig_set_syntax_behavior(OnigSyntaxType* syntax, unsigned int behavior)
# void onig_set_syntax_options(OnigSyntaxType* syntax, OnigOptionType options)

  正規表現パターン文法の要素を参照/取得する。

  引数
  1 syntax:                     正規表現パターン文法
  2 op, op2, behavior, options: 要素の値


# void onig_copy_encoding(OnigEncoding to, OnigEncoding from)

  文字エンコーディングをコピーする。

  引数
  1 to:   対象
  2 from: 元


# int onig_set_meta_char(OnigSyntaxType* syntax, unsigned int what,
                         OnigCodePoint code)

  メタ文字を指定したコードポイント値にセットする。
  ONIG_SYN_OP_VARIABLE_META_CHARACTERSが正規表現パターン文法で有効に
  なっていない場合には、エスケープ文字を除いて、ここで指定したメタ文字は
  機能しない。(組込みの文法では有効にしていない。)

  正常終了戻り値: ONIG_NORMAL

  引数
  1 syntax: 対象文法
  2 what:   メタ文字機能の指定

          ONIG_META_CHAR_ESCAPE
          ONIG_META_CHAR_ANYCHAR
          ONIG_META_CHAR_ANYTIME
          ONIG_META_CHAR_ZERO_OR_ONE_TIME
          ONIG_META_CHAR_ONE_OR_MORE_TIME
          ONIG_META_CHAR_ANYCHAR_ANYTIME

  3 code: メタ文字のコードポイント または ONIG_INEFFECTIVE_META_CHAR.


# OnigCaseFoldType onig_get_default_case_fold_flag()

  デフォルトのcase foldフラグを取得する。


# int onig_set_default_case_fold_flag(OnigCaseFoldType case_fold_flag)

  デフォルトのcase foldフラグをセットする。

  引数
  1 case_fold_flag: case foldフラグ


# unsigned int onig_get_match_stack_limit_size(void)

  マッチスタックサイズの最大値を返す。
  (デフォルト: 0 == 無制限)


# int onig_set_match_stack_limit_size(unsigned int size)

  マッチスタックサイズの最大値を指定する。
  (size = 0: 無制限)

  正常終了戻り値: ONIG_NORMAL


# int onig_unicode_define_user_property(const char* name, OnigCodePoint* ranges))

  新しいUnicodeプロパティを定義する。
  (この関数はスレッドセーフではない)

  引数
  1 name:    プロパティ名 (ASCIIコードのみ。 文字 ' ', '-', '_' は無視される。)
  2 ranges:  プロパティコードポイント範囲
             (最初の要素は範囲の数)

    [num-of-ranges, 1st-range-start, 1st-range-end, 2nd-range-start... ]

    * この関数を呼んだ後で、rangesを変更/破壊しないこと

  正常終了戻り値: ONIG_NORMAL


# unsigned int onig_get_parse_depth_limit(void)

  再帰パース処理の最大深さを返す。
  (デフォルト: regint.h で定義されている DEFAULT_PARSE_DEPTH_LIMIT。現在は 4096)


# int onig_set_parse_depth_limit(unsigned int depth)

  再帰パース処理の最大深さを指定する。
  (depth = 0: regint.h で定義されたデフォルト値に設定する。)

  正常終了戻り値: ONIG_NORMAL


# int onig_end(void)

  ライブラリの使用を終了する。

  正常終了戻り値: ONIG_NORMAL

  onig_init()を再度呼び出しても、以前に作成した正規表現オブジェクト
  を使用することはできない。


# const char* onig_version(void)

  バージョン文字列を返す。(例 "5.0.3")

// END