From 0dbf3761f6b98e5c16c9bfa0306ae5d3257d081f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= Date: Tue, 12 Aug 2014 21:06:31 +0200 Subject: Imported Upstream version 5.9.5 --- doc/API | 602 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/API.ja | 610 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/FAQ | 37 ++++ doc/FAQ.ja | 130 +++++++++++++ doc/RE | 449 +++++++++++++++++++++++++++++++++++++++++++++ doc/RE.ja | 460 ++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 2288 insertions(+) create mode 100644 doc/API create mode 100644 doc/API.ja create mode 100644 doc/FAQ create mode 100644 doc/FAQ.ja create mode 100644 doc/RE create mode 100644 doc/RE.ja (limited to 'doc') diff --git a/doc/API b/doc/API new file mode 100644 index 0000000..f3b8875 --- /dev/null +++ b/doc/API @@ -0,0 +1,602 @@ +Oniguruma API Version 5.9.2 2008/02/19 + +#include + + +# int onig_init(void) + + Initialize library. + + You don't have to call it explicitly, because it is called in onig_new(). + + +# int onig_error_code_to_str(UChar* err_buf, int err_code, ...) + + Get error message string. + If this function is used for onig_new(), + don't call this after the pattern argument of onig_new() is freed. + + normal return: error message string length + + arguments + 1 err_buf: error message string buffer. + (required size: ONIG_MAX_ERROR_MESSAGE_LEN) + 2 err_code: error code returned by other API functions. + 3 err_info (optional): error info returned by onig_new(). + + +# void onig_set_warn_func(OnigWarnFunc func) + + Set warning function. + + WARNING: + '[', '-', ']' in character class without escape. + ']' in pattern without escape. + + arguments + 1 func: function pointer. void (*func)(char* warning_message) + + +# void onig_set_verb_warn_func(OnigWarnFunc func) + + Set verbose warning function. + + WARNING: + redundant nested repeat operator. + + arguments + 1 func: function pointer. 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) + + Create a regex object. + + normal return: ONIG_NORMAL + + arguments + 1 reg: return regex object's address. + 2 pattern: regex pattern string. + 3 pattern_end: terminate address of pattern. (pattern + pattern length) + 4 option: compile time options. + + ONIG_OPTION_NONE no option + ONIG_OPTION_SINGLELINE '^' -> '\A', '$' -> '\Z' + ONIG_OPTION_MULTILINE '.' match with newline + ONIG_OPTION_IGNORECASE ambiguity match on + ONIG_OPTION_EXTEND extended pattern form + ONIG_OPTION_FIND_LONGEST find longest match + ONIG_OPTION_FIND_NOT_EMPTY ignore empty match + ONIG_OPTION_NEGATE_SINGLELINE + clear ONIG_OPTION_SINGLELINE which is enabled on + ONIG_SYNTAX_POSIX_BASIC, ONIG_SYNTAX_POSIX_EXTENDED, + ONIG_SYNTAX_PERL, ONIG_SYNTAX_PERL_NG, ONIG_SYNTAX_JAVA + + ONIG_OPTION_DONT_CAPTURE_GROUP only named group captured. + ONIG_OPTION_CAPTURE_GROUP named and no-named group captured. + + 5 enc: character encoding. + + 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 + + or any OnigEncodingType data address defined by user. + + 6 syntax: address of pattern syntax definition. + + 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 + named group + ONIG_SYNTAX_RUBY Ruby + ONIG_SYNTAX_DEFAULT default (== Ruby) + onig_set_default_syntax() + + or any OnigSyntaxType data address defined by user. + + 7 err_info: address for return optional error info. + Use this value as 3rd argument of 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) + + Create a regex object. + reg object area is not allocated in this function. + + normal return: ONIG_NORMAL + + + +# int onig_new_deluxe(regex_t** reg, const UChar* pattern, const UChar* pattern_end, + OnigCompileInfo* ci, OnigErrorInfo* einfo) + + Create a regex object. + This function is deluxe version of onig_new(). + + normal return: ONIG_NORMAL + + arguments + 1 reg: return address of regex object. + 2 pattern: regex pattern string. + 3 pattern_end: terminate address of pattern. (pattern + pattern length) + 4 ci: compile time info. + + ci->num_of_elements: number of elements in ci. (current version: 5) + ci->pattern_enc: pattern string character encoding. + ci->target_enc: target string character encoding. + ci->syntax: address of pattern syntax definition. + ci->option: compile time option. + ci->case_fold_flag: character matching case fold bit flag for + ONIG_OPTION_IGNORECASE mode. + + ONIGENC_CASE_FOLD_MIN: minimum + ONIGENC_CASE_FOLD_DEFAULT: minimum + onig_set_default_case_fold_flag() + + 5 err_info: address for return optional error info. + Use this value as 3rd argument of onig_error_code_to_str(). + + + Different character encoding combination is allowed for + the following cases only. + + 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) + + Free memory used by regex object. + + arguments + 1 reg: regex object. + + +# void onig_free_body(regex_t* reg) + + Free memory used by regex object. (Except reg oneself.) + + arguments + 1 reg: regex object. + + +# int onig_search(regex_t* reg, const UChar* str, const UChar* end, const UChar* start, + const UChar* range, OnigRegion* region, OnigOptionType option) + + Search string and return search result and matching region. + + normal return: match position offset (i.e. p - str >= 0) + not found: ONIG_MISMATCH (< 0) + + arguments + 1 reg: regex object + 2 str: target string + 3 end: terminate address of target string + 4 start: search start address of target string + 5 range: search terminate address of target string + in forward search (start <= searched string < range) + in backward search (range <= searched string <= start) + 6 region: address for return group match range info (NULL is allowed) + 7 option: search time option + + ONIG_OPTION_NOTBOL string head(str) isn't considered as begin of line + ONIG_OPTION_NOTEOL string end (end) isn't considered as end of line + ONIG_OPTION_POSIX_REGION region argument is regmatch_t[] of POSIX API. + + +# int onig_match(regex_t* reg, const UChar* str, const UChar* end, const UChar* at, + OnigRegion* region, OnigOptionType option) + + Match string and return result and matching region. + + normal return: match length (>= 0) + not match: ONIG_MISMATCH ( < 0) + + arguments + 1 reg: regex object + 2 str: target string + 3 end: terminate address of target string + 4 at: match address of target string + 5 region: address for return group match range info (NULL is allowed) + 6 option: search time option + + ONIG_OPTION_NOTBOL string head(str) isn't considered as begin of line + ONIG_OPTION_NOTEOL string end (end) isn't considered as end of line + ONIG_OPTION_POSIX_REGION region argument is regmatch_t[] type of POSIX API. + + +# OnigRegion* onig_region_new(void) + + Create a region. + + +# void onig_region_free(OnigRegion* region, int free_self) + + Free memory used by region. + + arguments + 1 region: target region + 2 free_self: [1: free all, 0: free memory used in region but not self] + + +# void onig_region_copy(OnigRegion* to, OnigRegion* from) + + Copy contents of region. + + arguments + 1 to: target region + 2 from: source region + + +# void onig_region_clear(OnigRegion* region) + + Clear contents of region. + + arguments + 1 region: target region + + +# int onig_region_resize(OnigRegion* region, int n) + + Resize group range area of region. + + normal return: ONIG_NORMAL + + arguments + 1 region: target region + 2 n: new size + + +# int onig_name_to_group_numbers(regex_t* reg, const UChar* name, const UChar* name_end, + int** num_list) + + Return the group number list of the name. + Named subexp is defined by (?....). + + normal return: number of groups for the name. + (ex. /(?..)(?..)/ ==> 2) + name not found: -1 + + arguments + 1 reg: regex object. + 2 name: group name. + 3 name_end: terminate address of group name. + 4 num_list: return list of group number. + + +# int onig_name_to_backref_number(regex_t* reg, const UChar* name, const UChar* name_end, + OnigRegion *region) + + Return the group number corresponding to the named backref (\k). + If two or more regions for the groups of the name are effective, + the greatest number in it is obtained. + + normal return: group number. + + arguments + 1 reg: regex object. + 2 name: group name. + 3 name_end: terminate address of group name. + 4 region: search/match result region. + + +# int onig_foreach_name(regex_t* reg, + int (*func)(const UChar*, const UChar*, int,int*,regex_t*,void*), + void* arg) + + Iterate function call for all names. + + normal return: 0 + error: func's return value. + + arguments + 1 reg: regex object. + 2 func: callback function. + func(name, name_end, , , + reg, arg); + if func does not return 0, then iteration is stopped. + 3 arg: argument for func. + + +# int onig_number_of_names(regex_t* reg) + + Return the number of names defined in the pattern. + Multiple definitions of one name is counted as one. + + arguments + 1 reg: regex object. + + +# 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) + + Return a value of the regex object. + + arguments + 1 reg: regex object. + + +# int onig_number_of_captures(regex_t* reg) + + Return the number of capture group in the pattern. + + arguments + 1 reg: regex object. + + +# int onig_number_of_capture_histories(regex_t* reg) + + Return the number of capture history defined in the pattern. + + You can't use capture history if ONIG_SYN_OP2_ATMARK_CAPTURE_HISTORY + is disabled in the pattern syntax.(disabled in the default syntax) + + arguments + 1 reg: regex object. + + + +# OnigCaptureTreeNode* onig_get_capture_tree(OnigRegion* region) + + Return the root node of capture history data tree. + + This value is undefined if matching has faild. + + arguments + 1 region: matching result. + + +# int onig_capture_tree_traverse(OnigRegion* region, int at, + int(*func)(int,int,int,int,int,void*), void* arg) + + Traverse and callback in capture history data tree. + + normal return: 0 + error: callback func's return value. + + arguments + 1 region: match region data. + 2 at: callback position. + + ONIG_TRAVERSE_CALLBACK_AT_FIRST: callback first, then traverse childs. + ONIG_TRAVERSE_CALLBACK_AT_LAST: traverse childs first, then callback. + ONIG_TRAVERSE_CALLBACK_AT_BOTH: callback first, then traverse childs, + and at last callback again. + + 3 func: callback function. + if func does not return 0, then traverse is stopped. + + int func(int group, int beg, int end, int level, int at, + void* arg) + + group: group number + beg: capture start position + end: capture end position + level: nest level (from 0) + at: callback position + ONIG_TRAVERSE_CALLBACK_AT_FIRST + ONIG_TRAVERSE_CALLBACK_AT_LAST + arg: optional callback argument + + 4 arg; optional callback argument. + + +# int onig_noname_group_capture_is_active(regex_t* reg) + + Return noname group capture activity. + + active: 1 + inactive: 0 + + arguments + 1 reg: regex object. + + if option ONIG_OPTION_DONT_CAPTURE_GROUP == ON + --> inactive + + if the regex pattern have named group + and syntax ONIG_SYN_CAPTURE_ONLY_NAMED_GROUP == ON + and option ONIG_OPTION_CAPTURE_GROUP == OFF + --> inactive + + else --> active + + +# UChar* onigenc_get_prev_char_head(OnigEncoding enc, const UChar* start, const UChar* s) + + Return previous character head address. + + arguments + 1 enc: character encoding + 2 start: string address + 3 s: target address of string + + +# UChar* onigenc_get_left_adjust_char_head(OnigEncoding enc, + const UChar* start, const UChar* s) + + Return left-adjusted head address of a character. + + arguments + 1 enc: character encoding + 2 start: string address + 3 s: target address of string + + +# UChar* onigenc_get_right_adjust_char_head(OnigEncoding enc, + const UChar* start, const UChar* s) + + Return right-adjusted head address of a character. + + arguments + 1 enc: character encoding + 2 start: string address + 3 s: target address of string + + +# int onigenc_strlen(OnigEncoding enc, const UChar* s, const UChar* end) +# int onigenc_strlen_null(OnigEncoding enc, const UChar* s) + + Return number of characters in the string. + + +# int onigenc_str_bytelen_null(OnigEncoding enc, const UChar* s) + + Return number of bytes in the string. + + +# int onig_set_default_syntax(OnigSyntaxType* syntax) + + Set default syntax. + + arguments + 1 syntax: address of pattern syntax definition. + + +# void onig_copy_syntax(OnigSyntaxType* to, OnigSyntaxType* from) + + Copy syntax. + + arguments + 1 to: destination address. + 2 from: source address. + + +# 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) + + Get/Set elements of the syntax. + + arguments + 1 syntax: syntax + 2 op, op2, behavior, options: value of element. + + +# void onig_copy_encoding(OnigEncoding to, OnigOnigEncoding from) + + Copy encoding. + + arguments + 1 to: destination address. + 2 from: source address. + + +# int onig_set_meta_char(OnigSyntaxType* syntax, unsigned int what, + OnigCodePoint code) + + Set a variable meta character to the code point value. + Except for an escape character, this meta characters specification + is not work, if ONIG_SYN_OP_VARIABLE_META_CHARACTERS is not effective + by the syntax. (Build-in syntaxes are not effective.) + + normal return: ONIG_NORMAL + + arguments + 1 syntax: target syntax + 2 what: specifies which meta character it is. + + 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: meta character or ONIG_INEFFECTIVE_META_CHAR. + + +# OnigCaseFoldType onig_get_default_case_fold_flag() + + Get default case fold flag. + + +# int onig_set_default_case_fold_flag(OnigCaseFoldType case_fold_flag) + + Set default case fold flag. + + 1 case_fold_flag: case fold flag + + +# unsigned int onig_get_match_stack_limit_size(void) + + Return the maximum number of stack size. + (default: 0 == unlimited) + + +# int onig_set_match_stack_limit_size(unsigned int size) + + Set the maximum number of stack size. + (size = 0: unlimited) + + normal return: ONIG_NORMAL + + +# int onig_end(void) + + The use of this library is finished. + + normal return: ONIG_NORMAL + + It is not allowed to use regex objects which created + before onig_end() call. + + +# const char* onig_version(void) + + Return version string. (ex. "5.0.3") + +// END diff --git a/doc/API.ja b/doc/API.ja new file mode 100644 index 0000000..f681fa5 --- /dev/null +++ b/doc/API.ja @@ -0,0 +1,610 @@ +鬼車インターフェース Version 5.9.2 2008/02/19 + +#include + + +# int onig_init(void) + + ライブラリの初期化 + + onig_new()の中で呼び出されるので、この関数を明示的に呼び出さなくてもよい。 + + +# 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[]にする + + +# 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) + + 指定した名前に対する名前付き捕獲式集合(グループ)の + グループ番号リストを返す。 + 名前付き捕獲式集合は、(?....)によって定義できる。 + + 正常終了戻り値: 指定された名前に対するグループ数 + (例 /(?..)(?..)/ ==> 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)に対する捕獲式集合(グループ)の番号を返す。 + 名前に対して、複数のマッチ領域が有効であれば、その中の最大の番号を返す。 + 名前に対する捕獲式集合が一個しかないときには、対応するマッチ領域が有効か + どうかに関係なく、その番号を返す。(従って、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, , , + 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, OnigOnigEncoding 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_end(void) + + ライブラリの使用を終了する。 + + 正常終了戻り値: ONIG_NORMAL + + onig_init()を再度呼び出しても、以前に作成した正規表現オブジェクト + を使用することはできない。 + + +# const char* onig_version(void) + + バージョン文字列を返す。(例 "5.0.3") + +// END diff --git a/doc/FAQ b/doc/FAQ new file mode 100644 index 0000000..46a3e0e --- /dev/null +++ b/doc/FAQ @@ -0,0 +1,37 @@ +FAQ 2006/11/14 + +1. Lognest match + + You can execute longest match by using ONIG_OPTION_FIND_LONGEST option + in onig_new(). + + +2. Thread safe + + In order to make thread safe, which of (A) or (B) must be done. + + (A) Oniguruma Layer + + Define the macro below in oniguruma/regint.h. + + USE_MULTI_THREAD_SYSTEM + THREAD_ATOMIC_START + THREAD_ATOMIC_END + THREAD_PASS + + THREAD_SYSTEM_INIT + THREAD_SYSTEM_END + + + (B) Application Layer + + The plural threads should not do simultaneously that making + new regexp objects or re-compiling objects or freeing objects, + even if these objects are differ. + + +3. Mailing list + + There is no mailing list about Oniguruma. + +// END diff --git a/doc/FAQ.ja b/doc/FAQ.ja new file mode 100644 index 0000000..1d65f9f --- /dev/null +++ b/doc/FAQ.ja @@ -0,0 +1,130 @@ +FAQ 2007/07/23 + +1. 最長マッチ + + onig_new()の中で、ONIG_OPTION_FIND_LONGESTオプション + を使用すれば最長マッチになる。 + + +2. スレッドセーフ + + スレッドセーフにするには、以下の(A)と(B)のどちらかを行なえば + よい。 + + (A) Oniguruma Layer + + oniguruma/regint.hの中の以下のマクロを定義する。 + + USE_MULTI_THREAD_SYSTEM + THREAD_ATOMIC_START + THREAD_ATOMIC_END + THREAD_PASS + + 何らかの初期化/終了処理が必要であれば、以下のマクロに定義する。 + THREAD_SYSTEM_INIT + THREAD_SYSTEM_END + + + (B) Application Layer + + 同時に複数のスレッドが、正規表現オブジェクトを作成する、 + または解放する、ことを行なってはならない。 + それらのオブジェクトが全く別のものであっても。 + + もう少し詳しい説明は、このドキュメントの中の + "スレッドセーフに関する補足"に書いておいた。 + + +3. CR + LF + + DOSの改行(CR(0x0c) + LF(0x0a)の連続) + + regenc.hの中の、以下の部分を有効にする。 + + /* #define USE_CRNL_AS_LINE_TERMINATOR */ + + +4. メーリングリスト + + 鬼車に関するメーリングリストは存在しない。 + +//END + + + +スレッドセーフに関する補足 + +スレッドセーフにするには、個別のアプリケーションの中で行うか、 +Onigurumaライブラリの中で行うか、どちらかを選ぶことができます。 +(Onigurumaを使用する側で対処するか、Onigurumaに対処させるか +どちらか片方で行う必要があるということです。) + +これらの方法について、以下(A)と(B)で説明します。 + +マルチスレッドAPIは、それぞれのプラットフォームによっても +異なりますので、以下の説明の中で具体的に何を呼ぶのかを +書くことは無理です。実際に使用されるマルチスレッドAPIで、 +対応する機能のものを指定してください。 + +(A) Onigurumaの中で対応する場合 + +oniguruma/regint.hの中で以下のマクロを定義して再コンパイルしてください。 + +USE_MULTI_THREAD_SYSTEM + + 単に有効にすればよいです。 + +THREAD_ATOMIC_START +THREAD_ATOMIC_END + + THREAD_ATOMIC_STARTからTHREAD_ATOMIC_ENDで囲まれた + プログラムのコード部分をあるスレッドが実行中に、他の + スレッドに実行権が移動しないことを保障するものに定義 + してください。 + (名前の通り、囲まれたコード部分をスレッドアトミックに + するという意味) + +THREAD_PASS + + これを実行したスレッドから、他のスレッドに実行権を委譲 + するものに定義をしてください。(再スケジュールを呼び出す + という意味) + 対応する機能が全くなければ、空定義にしてください。 + +(参考例) +Rubyの場合を例にすると、 +Rubyは自分自身で独自のスレッド機能を実装しています。 +その機能を使用すると、以下のように定義すればよいことに +なります。 + +#define USE_MULTI_THREAD_SYSTEM +#define THREAD_SYSTEM_INIT +#define THREAD_SYSTEM_END +#define THREAD_ATOMIC_START DEFER_INTS +#define THREAD_ATOMIC_END ENABLE_INTS +#define THREAD_PASS rb_thread_schedule() + +Rubyの場合、タイマ割り込みを使用して、スレッドの切り替えを +行っています。DEFER_INTSは割り込みハンドラの実行を一時的に +止めるためのマクロです。ENABLE_INTSマクロで割り込みハンドラ +の実行を許可します。 +これによって、THREAD_ATOMIC_STARTからTHREAD_ATOMIC_END +で囲まれた部分の実行中に、他のスレッドに実行権が移動しません。 + + +(B) アプリケーションの中で対応する場合 + +以下を保障するように、スレッドの実行を制御してください。 + +同時に複数のスレッドが、正規表現オブジェクトを作成する、または解放する、ことを +行なってはならない。それらのオブジェクトが全く別のものであっても。 + +onig_new(), onig_new_deluxe(), onig_free()のどれかの呼び出しを、 +複数のスレッドが同時に実行することを避けてください。同時でなければ別にかまいません。 + +これは何故必要なのかというと、正規表現オブジェクトを作成する +過程で、内部で共通に参照するテーブルがあります。 +このテーブルに対してのデータ登録処理が複数のスレッドで衝突して +異常な状態にならないために必要です。 + +// END diff --git a/doc/RE b/doc/RE new file mode 100644 index 0000000..21efe53 --- /dev/null +++ b/doc/RE @@ -0,0 +1,449 @@ +Oniguruma Regular Expressions Version 5.9.1 2007/09/05 + +syntax: ONIG_SYNTAX_RUBY (default) + + +1. Syntax elements + + \ escape (enable or disable meta character meaning) + | alternation + (...) group + [...] character class + + +2. Characters + + \t horizontal tab (0x09) + \v vertical tab (0x0B) + \n newline (0x0A) + \r return (0x0D) + \b back space (0x08) + \f form feed (0x0C) + \a bell (0x07) + \e escape (0x1B) + \nnn octal char (encoded byte value) + \xHH hexadecimal char (encoded byte value) + \x{7HHHHHHH} wide hexadecimal char (character code point value) + \cx control char (character code point value) + \C-x control char (character code point value) + \M-x meta (x|0x80) (character code point value) + \M-\C-x meta control char (character code point value) + + (* \b is effective in character class [...] only) + + +3. Character types + + . any character (except newline) + + \w word character + + Not Unicode: + alphanumeric, "_" and multibyte char. + + Unicode: + General_Category -- (Letter|Mark|Number|Connector_Punctuation) + + \W non word char + + \s whitespace char + + Not Unicode: + \t, \n, \v, \f, \r, \x20 + + Unicode: + 0009, 000A, 000B, 000C, 000D, 0085(NEL), + General_Category -- Line_Separator + -- Paragraph_Separator + -- Space_Separator + + \S non whitespace char + + \d decimal digit char + + Unicode: General_Category -- Decimal_Number + + \D non decimal digit char + + \h hexadecimal digit char [0-9a-fA-F] + + \H non hexadecimal digit char + + + Character Property + + * \p{property-name} + * \p{^property-name} (negative) + * \P{property-name} (negative) + + property-name: + + + works on all encodings + Alnum, Alpha, Blank, Cntrl, Digit, Graph, Lower, + Print, Punct, Space, Upper, XDigit, Word, ASCII, + + + works on EUC_JP, Shift_JIS + Hiragana, Katakana + + + works on UTF8, UTF16, UTF32 + Any, Assigned, C, Cc, Cf, Cn, Co, Cs, L, Ll, Lm, Lo, Lt, Lu, + M, Mc, Me, Mn, N, Nd, Nl, No, P, Pc, Pd, Pe, Pf, Pi, Po, Ps, + S, Sc, Sk, Sm, So, Z, Zl, Zp, Zs, + Arabic, Armenian, Bengali, Bopomofo, Braille, Buginese, + Buhid, Canadian_Aboriginal, Cherokee, Common, Coptic, + Cypriot, Cyrillic, Deseret, Devanagari, Ethiopic, Georgian, + Glagolitic, Gothic, Greek, Gujarati, Gurmukhi, Han, Hangul, + Hanunoo, Hebrew, Hiragana, Inherited, Kannada, Katakana, + Kharoshthi, Khmer, Lao, Latin, Limbu, Linear_B, Malayalam, + Mongolian, Myanmar, New_Tai_Lue, Ogham, Old_Italic, Old_Persian, + Oriya, Osmanya, Runic, Shavian, Sinhala, Syloti_Nagri, Syriac, + Tagalog, Tagbanwa, Tai_Le, Tamil, Telugu, Thaana, Thai, Tibetan, + Tifinagh, Ugaritic, Yi + + + +4. Quantifier + + greedy + + ? 1 or 0 times + * 0 or more times + + 1 or more times + {n,m} at least n but not more than m times + {n,} at least n times + {,n} at least 0 but not more than n times ({0,n}) + {n} n times + + reluctant + + ?? 1 or 0 times + *? 0 or more times + +? 1 or more times + {n,m}? at least n but not more than m times + {n,}? at least n times + {,n}? at least 0 but not more than n times (== {0,n}?) + + possessive (greedy and does not backtrack after repeated) + + ?+ 1 or 0 times + *+ 0 or more times + ++ 1 or more times + + ({n,m}+, {n,}+, {n}+ are possessive op. in ONIG_SYNTAX_JAVA only) + + ex. /a*+/ === /(?>a*)/ + + +5. Anchors + + ^ beginning of the line + $ end of the line + \b word boundary + \B not word boundary + \A beginning of string + \Z end of string, or before newline at the end + \z end of string + \G matching start position + + +6. Character class + + ^... negative class (lowest precedence operator) + x-y range from x to y + [...] set (character class in character class) + ..&&.. intersection (low precedence at the next of ^) + + ex. [a-w&&[^c-g]z] ==> ([a-w] AND ([^c-g] OR z)) ==> [abh-w] + + * If you want to use '[', '-', ']' as a normal character + in a character class, you should escape these characters by '\'. + + + POSIX bracket ([:xxxxx:], negate [:^xxxxx:]) + + Not Unicode Case: + + alnum alphabet or digit char + alpha alphabet + ascii code value: [0 - 127] + blank \t, \x20 + cntrl + digit 0-9 + graph include all of multibyte encoded characters + lower + print include all of multibyte encoded characters + punct + space \t, \n, \v, \f, \r, \x20 + upper + xdigit 0-9, a-f, A-F + word alphanumeric, "_" and multibyte characters + + + Unicode Case: + + alnum Letter | Mark | Decimal_Number + alpha Letter | Mark + ascii 0000 - 007F + blank Space_Separator | 0009 + cntrl Control | Format | Unassigned | Private_Use | Surrogate + digit Decimal_Number + graph [[:^space:]] && ^Control && ^Unassigned && ^Surrogate + lower Lowercase_Letter + print [[:graph:]] | [[:space:]] + punct Connector_Punctuation | Dash_Punctuation | Close_Punctuation | + Final_Punctuation | Initial_Punctuation | Other_Punctuation | + Open_Punctuation + space Space_Separator | Line_Separator | Paragraph_Separator | + 0009 | 000A | 000B | 000C | 000D | 0085 + upper Uppercase_Letter + xdigit 0030 - 0039 | 0041 - 0046 | 0061 - 0066 + (0-9, a-f, A-F) + word Letter | Mark | Decimal_Number | Connector_Punctuation + + + +7. Extended groups + + (?#...) comment + + (?imx-imx) option on/off + i: ignore case + m: multi-line (dot(.) match newline) + x: extended form + (?imx-imx:subexp) option on/off for subexp + + (?:subexp) not captured group + (subexp) captured group + + (?=subexp) look-ahead + (?!subexp) negative look-ahead + (?<=subexp) look-behind + (?subexp) atomic group + don't backtrack in subexp. + + (?subexp), (?'name'subexp) + define named group + (All characters of the name must be a word character.) + + Not only a name but a number is assigned like a captured + group. + + Assigning the same name as two or more subexps is allowed. + In this case, a subexp call can not be performed although + the back reference is possible. + + +8. Back reference + + \n back reference by group number (n >= 1) + \k back reference by group number (n >= 1) + \k'n' back reference by group number (n >= 1) + \k<-n> back reference by relative group number (n >= 1) + \k'-n' back reference by relative group number (n >= 1) + \k back reference by group name + \k'name' back reference by group name + + In the back reference by the multiplex definition name, + a subexp with a large number is referred to preferentially. + (When not matched, a group of the small number is referred to.) + + * Back reference by group number is forbidden if named group is defined + in the pattern and ONIG_OPTION_CAPTURE_GROUP is not setted. + + + back reference with nest level + + level: 0, 1, 2, ... + + \k (n >= 1) + \k (n >= 1) + \k'n+level' (n >= 1) + \k'n-level' (n >= 1) + + \k + \k + \k'name+level' + \k'name-level' + + Destinate relative nest level from back reference position. + + ex 1. + + /\A(?|.|(?:(?.)\g\k))\z/.match("reer") + + ex 2. + + r = Regexp.compile(<<'__REGEXP__'.strip, Regexp::EXTENDED) + (? \g \g* \g ){0} + (? < \g \s* > ){0} + (? [a-zA-Z_:]+ ){0} + (? [^<&]+ (\g | [^<&]+)* ){0} + (? >){0} + \g + __REGEXP__ + + p r.match('fbbbf').captures + + + +9. Subexp call ("Tanaka Akira special") + + \g call by group name + \g'name' call by group name + \g call by group number (n >= 1) + \g'n' call by group number (n >= 1) + \g<-n> call by relative group number (n >= 1) + \g'-n' call by relative group number (n >= 1) + + * left-most recursive call is not allowed. + ex. (?a|\gb) => error + (?a|b\gc) => OK + + * Call by group number is forbidden if named group is defined in the pattern + and ONIG_OPTION_CAPTURE_GROUP is not setted. + + * If the option status of called group is different from calling position + then the group's option is effective. + + ex. (?-i:\g)(?i:(?a)){0} match to "A" + + +10. Captured group + + Behavior of the no-named group (...) changes with the following conditions. + (But named group is not changed.) + + case 1. /.../ (named group is not used, no option) + + (...) is treated as a captured group. + + case 2. /.../g (named group is not used, 'g' option) + + (...) is treated as a no-captured group (?:...). + + case 3. /..(?..)../ (named group is used, no option) + + (...) is treated as a no-captured group (?:...). + numbered-backref/call is not allowed. + + case 4. /..(?..)../G (named group is used, 'G' option) + + (...) is treated as a captured group. + numbered-backref/call is allowed. + + where + g: ONIG_OPTION_DONT_CAPTURE_GROUP + G: ONIG_OPTION_CAPTURE_GROUP + + ('g' and 'G' options are argued in ruby-dev ML) + + + +----------------------------- +A-1. Syntax depend options + + + ONIG_SYNTAX_RUBY + (?m): dot(.) match newline + + + ONIG_SYNTAX_PERL and ONIG_SYNTAX_JAVA + (?s): dot(.) match newline + (?m): ^ match after newline, $ match before newline + + +A-2. Original extensions + + + hexadecimal digit char type \h, \H + + named group (?...), (?'name'...) + + named backref \k + + subexp call \g, \g + + +A-3. Lacked features compare with perl 5.8.0 + + + \N{name} + + \l,\u,\L,\U, \X, \C + + (?{code}) + + (??{code}) + + (?(condition)yes-pat|no-pat) + + * \Q...\E + This is effective on ONIG_SYNTAX_PERL and ONIG_SYNTAX_JAVA. + + +A-4. Differences with Japanized GNU regex(version 0.12) of Ruby 1.8 + + + add character property (\p{property}, \P{property}) + + add hexadecimal digit char type (\h, \H) + + add look-behind + (?<=fixed-char-length-pattern), (?>]/ in EUC-JP encoding. + + effect range of isolated option is to next ')'. + ex. (?:(?i)a|b) is interpreted as (?:(?i:a|b)), not (?:(?i:a)|b). + + isolated option is not transparent to previous pattern. + ex. a(?i)* is a syntax error pattern. + + allowed incompleted left brace as an usual string. + ex. /{/, /({)/, /a{2,3/ etc... + + negative POSIX bracket [:^xxxx:] is supported. + + POSIX bracket [:ascii:] is added. + + repeat of look-ahead is not allowed. + ex. /(?=a)*/, /(?!b){5}/ + + Ignore case option is effective to numbered character. + ex. /\x61/i =~ "A" + + In the range quantifier, the number of the minimum is omissible. + /a{,n}/ == /a{0,n}/ + The simultanious abbreviation of the number of times of the minimum + and the maximum is not allowed. (/a{,}/) + + /a{n}?/ is not a non-greedy operator. + /a{n}?/ == /(?:a{n})?/ + + invalid back reference is checked and cause error. + /\1/, /(a)\2/ + + Zero-length match in infinite repeat stops the repeat, + then changes of the capture group status are checked as stop condition. + /(?:()|())*\1\2/ =~ "" + /(?:\1a|())*/ =~ "a" + + +A-5. Disabled functions by default syntax + + + capture history + + (?@...) and (?@...) + + ex. /(?@a)*/.match("aaa") ==> [<0-1>, <1-2>, <2-3>] + + see sample/listcap.c file. + + +A-6. Problems + + + Invalid encoding byte sequence is not checked. + + ex. UTF-8 + + * Invalid first byte is treated as a character. + /./u =~ "\xa3" + + * Incomplete byte sequence is not checked. + /\w+/ =~ "a\xf3\x8ec" + +// END diff --git a/doc/RE.ja b/doc/RE.ja new file mode 100644 index 0000000..abde849 --- /dev/null +++ b/doc/RE.ja @@ -0,0 +1,460 @@ +鬼車 正規表現 Version 5.9.1 2007/09/05 + +使用文法: ONIG_SYNTAX_RUBY (既定値) + + +1. 基本要素 + + \ 退避修飾 (エスケープ) 正規表現記号の有効/無効の制御 + | 選択子 + (...) 式集合 (グループ) + [...] 文字集合 (文字クラス) + + +2. 文字 + + \t 水平タブ (0x09) + \v 垂直タブ (0x0B) + \n 改行 (0x0A) + \r 復帰 (0x0D) + \b 後退空白 (0x08) + \f 改頁 (0x0C) + \a 鐘 (0x07) + \e 退避修飾 (0x1B) + \nnn 八進数表現 符号化バイト値(の一部) + \xHH 十六進数表現 符号化バイト値(の一部) + \x{7HHHHHHH} 拡張十六進数表現 コードポイント値 + \cx 制御文字表現 コードポイント値 + \C-x 制御文字表現 コードポイント値 + \M-x 超 (x|0x80) コードポイント値 + \M-\C-x 超 + 制御文字表現 コードポイント値 + + ※ \bは、文字集合内でのみ有効 + + +3. 文字種 + + . 任意文字 (改行を除く) + + \w 単語構成文字 + + Unicode以外の場合: + 英数字, "_" および 多バイト文字。 + + Unicodeの場合: + General_Category -- (Letter|Mark|Number|Connector_Punctuation) + + \W 非単語構成文字 + + \s 空白文字 + + Unicode以外の場合: + \t, \n, \v, \f, \r, \x20 + + Unicodeの場合: + 0009, 000A, 000B, 000C, 000D, 0085(NEL), + General_Category -- Line_Separator + -- Paragraph_Separator + -- Space_Separator + + \S 非空白文字 + + \d 10進数字 + + Unicodeの場合: General_Category -- Decimal_Number + + \D 非10進数字 + + \h 16進数字 [0-9a-fA-F] + + \H 非16進数字 + + + Character Property + + * \p{property-name} + * \p{^property-name} (negative) + * \P{property-name} (negative) + + property-name: + + + 全てのエンコーディングで有効 + Alnum, Alpha, Blank, Cntrl, Digit, Graph, Lower, + Print, Punct, Space, Upper, XDigit, Word, ASCII, + + + EUC-JP, Shift_JISで有効 + Hiragana, Katakana + + + UTF8, UTF16, UTF32で有効 + Any, Assigned, C, Cc, Cf, Cn, Co, Cs, L, Ll, Lm, Lo, Lt, Lu, + M, Mc, Me, Mn, N, Nd, Nl, No, P, Pc, Pd, Pe, Pf, Pi, Po, Ps, + S, Sc, Sk, Sm, So, Z, Zl, Zp, Zs, + Arabic, Armenian, Bengali, Bopomofo, Braille, Buginese, + Buhid, Canadian_Aboriginal, Cherokee, Common, Coptic, + Cypriot, Cyrillic, Deseret, Devanagari, Ethiopic, Georgian, + Glagolitic, Gothic, Greek, Gujarati, Gurmukhi, Han, Hangul, + Hanunoo, Hebrew, Hiragana, Inherited, Kannada, Katakana, + Kharoshthi, Khmer, Lao, Latin, Limbu, Linear_B, Malayalam, + Mongolian, Myanmar, New_Tai_Lue, Ogham, Old_Italic, Old_Persian, + Oriya, Osmanya, Runic, Shavian, Sinhala, Syloti_Nagri, Syriac, + Tagalog, Tagbanwa, Tai_Le, Tamil, Telugu, Thaana, Thai, Tibetan, + Tifinagh, Ugaritic, Yi + + + +4. 量指定子 + + 欲張り + + ? 一回または零回 + * 零回以上 + + 一回以上 + {n,m} n回以上m回以下 + {n,} n回以上 + {,n} 零回以上n回以下 ({0,n}) + {n} n回 + + 無欲 + + ?? 一回または零回 + *? 零回以上 + +? 一回以上 + {n,m}? n回以上m回以下 + {n,}? n回以上 + {,n}? 零回以上n回以下 (== {0,n}?) + + 強欲 (欲張りで、繰り返しに成功した後は回数を減らすような後退再試行をしない) + + ?+ 一回または零回 + *+ 零回以上 + ++ 一回以上 + + ({n,m}+, {n,}+, {n}+ は、ONIG_SYNTAX_JAVAでのみ強欲な指定子) + + 例. /a*+/ === /(?>a*)/ + + +5. 錨 + + ^ 行頭 + $ 行末 + \b 単語境界 + \B 非単語境界 + \A 文字列先頭 + \Z 文字列末尾、または文字列末尾の改行の直前 + \z 文字列末尾 + \G 照合開始位置 + + +6. 文字集合 + + ^... 否定 (最低優先度演算子) + x-y 範囲 (xからyまで) + [...] 集合 (文字集合内文字集合) + ..&&.. 積演算 (^の次に優先度が低い演算子) + + 例. [a-w&&[^c-g]z] ==> ([a-w] and ([^c-g] or z)) ==> [abh-w] + + ※ '[', '-', ']'を、文字集合内で通常文字の意味で使用したい場合には、 + これらの文字を'\'で退避修飾しなければならない。 + + + POSIXブラケット ([:xxxxx:], 否定 [:^xxxxx:]) + + Unicode以外の場合: + + alnum 英数字 + alpha 英字 + ascii 0 - 127 + blank \t, \x20 + cntrl + digit 0-9 + graph 多バイト文字全部を含む + lower + print 多バイト文字全部を含む + punct + space \t, \n, \v, \f, \r, \x20 + upper + xdigit 0-9, a-f, A-F + word 英数字, "_" および 多バイト文字 + + Unicodeの場合: + + alnum Letter | Mark | Decimal_Number + alpha Letter | Mark + ascii 0000 - 007F + blank Space_Separator | 0009 + cntrl Control | Format | Unassigned | Private_Use | Surrogate + digit Decimal_Number + graph [[:^space:]] && ^Control && ^Unassigned && ^Surrogate + lower Lowercase_Letter + print [[:graph:]] | [[:space:]] + punct Connector_Punctuation | Dash_Punctuation | Close_Punctuation | + Final_Punctuation | Initial_Punctuation | Other_Punctuation | + Open_Punctuation + space Space_Separator | Line_Separator | Paragraph_Separator | + 0009 | 000A | 000B | 000C | 000D | 0085 + upper Uppercase_Letter + xdigit 0030 - 0039 | 0041 - 0046 | 0061 - 0066 + (0-9, a-f, A-F) + word Letter | Mark | Decimal_Number | Connector_Punctuation + + + +7. 拡張式集合 + + (?#...) 注釈 + (?imx-imx) 孤立オプション + i: 大文字小文字照合 + m: 複数行 + x: 拡張形式 + (?imx-imx:式) 式オプション + + (式) 捕獲式集合 + (?:式) 非捕獲式集合 + + (?=式) 先読み + (?!式) 否定先読み + (?<=式) 戻り読み + (?式) 原子的式集合 + 式全体を通過したとき、式の中での後退再試行を行なわない + + (?式), (?'name'式) + 名前付き捕獲式集合 + 式集合に名前を割り当てる(定義する)。 + (名前は単語構成文字でなければならない。) + + 名前だけでなく、捕獲式集合と同様に番号も割り当てられる。 + 番号指定が禁止されていない状態 (10. 捕獲式集合 を参照) + のときは、名前を使わないで番号でも参照できる。 + + 複数の式集合に同じ名前を与えることは許されている。 + この場合には、この名前を使用した後方参照は可能であるが、 + 部分式呼出しはできない。 + + +8. 後方参照 + + \n 番号指定参照 (n >= 1) + \k 番号指定参照 (n >= 1) + \k'n' 番号指定参照 (n >= 1) + \k<-n> 相対番号指定参照 (n >= 1) + \k'-n' 相対番号指定参照 (n >= 1) + \k 名前指定参照 + \k'name' 名前指定参照 + + 名前指定参照で、その名前が複数の式集合で多重定義されている場合には、 + 番号の大きい式集合から優先的に参照される。 + (マッチしないときには番号の小さい式集合が参照される) + + ※ 番号指定参照は、名前付き捕獲式集合が定義され、 + かつ ONIG_OPTION_CAPTURE_GROUPが指定されていない場合には、 + 禁止される。(10. 捕獲式集合 を参照) + + + ネストレベル付き後方参照 + + level: 0, 1, 2, ... + + \k (n >= 1) + \k (n >= 1) + \k'n+level' (n >= 1) + \k'n-level' (n >= 1) + + \k + \k + \k'name+level' + \k'name-level' + + 後方参照の位置から相対的な部分式呼出しネストレベルを指定して、そのレベルでの + 捕獲値を参照する。 + + 例-1. + + /\A(?|.|(?:(?.)\g\k))\z/.match("reer") + + 例-2. + + r = Regexp.compile(<<'__REGEXP__'.strip, Regexp::EXTENDED) + (? \g \g* \g ){0} + (? < \g \s* > ){0} + (? [a-zA-Z_:]+ ){0} + (? [^<&]+ (\g | [^<&]+)* ){0} + (? >){0} + \g + __REGEXP__ + + p r.match('fbbbf').captures + + + +9. 部分式呼出し ("田中哲スペシャル") + + \g 名前指定呼出し + \g'name' 名前指定呼出し + \g 番号指定呼出し (n >= 1) + \g'n' 番号指定呼出し (n >= 1) + \g<-n> 相対番号指定呼出し (n >= 1) + \g'-n' 相対番号指定呼出し (n >= 1) + + ※ 最左位置での再帰呼出しは禁止される。 + 例. (?a|\gb) => error + (?a|b\gc) => OK + + ※ 番号指定呼出しは、名前付き捕獲式集合が定義され、 + かつ ONIG_OPTION_CAPTURE_GROUPが指定されていない場合には、 + 禁止される。 (10. 捕獲式集合 を参照) + + ※ 呼び出された式集合のオプション状態が呼出し側のオプション状態と異なっている + とき、呼び出された側のオプション状態が有効である。 + + 例. (?-i:\g)(?i:(?a)){0} は "A" に照合成功する。 + + +10. 捕獲式集合 + + 捕獲式集合(...)は、以下の条件に応じて振舞が変化する。 + (名前付き捕獲式集合は変化しない) + + case 1. /.../ (名前付き捕獲式集合は不使用、オプションなし) + + (...) は、捕獲式集合として扱われる。 + + case 2. /.../g (名前付き捕獲式集合は不使用、オプション 'g'を指定) + + (...) は、非捕獲式集合として扱われる。 + + case 3. /..(?..)../ (名前付き捕獲式集合は使用、オプションなし) + + (...) は、非捕獲式集合として扱われる。 + 番号指定参照/呼び出しは不許可。 + + case 4. /..(?..)../G (名前付き捕獲式集合は使用、オプション 'G'を指定) + + (...) は、捕獲式集合として扱われる。 + 番号指定参照/呼び出しは許可。 + + 但し + g: ONIG_OPTION_DONT_CAPTURE_GROUP + G: ONIG_OPTION_CAPTURE_GROUP + ('g'と'G'オプションは、ruby-dev MLで議論された。) + + これらの振舞の意味は、 + 名前付き捕獲と名前無し捕獲を同時に使用する必然性のある場面は少ないであろう + という理由から考えられたものである。 + + +----------------------------- +補記 1. 文法依存オプション + + + ONIG_SYNTAX_RUBY + (?m): 終止符記号(.)は改行と照合成功 + + + ONIG_SYNTAX_PERL と ONIG_SYNTAX_JAVA + (?s): 終止符記号(.)は改行と照合成功 + (?m): ^ は改行の直後に照合する、$ は改行の直前に照合する + + +補記 2. 独自拡張機能 + + + 16進数数字、非16進数字 \h, \H + + 名前付き捕獲式集合 (?...), (?'name'...) + + 名前指定後方参照 \k + + 部分式呼出し \g, \g + + +補記 3. Perl 5.8.0と比較して存在しない機能 + + + \N{name} + + \l,\u,\L,\U, \X, \C + + (?{code}) + + (??{code}) + + (?(condition)yes-pat|no-pat) + + * \Q...\E + 但しONIG_SYNTAX_PERLとONIG_SYNTAX_JAVAでは有効 + + +補記 4. Ruby 1.8 の日本語化 GNU regex(version 0.12)との違い + + + 文字Property機能追加 (\p{property}, \P{Property}) + + 16進数字タイプ追加 (\h, \H) + + 戻り読み機能を追加 + + 強欲な繰り返し指定子を追加 (?+, *+, ++) + + 文字集合の中の演算子を追加 ([...], &&) + ('[' は、文字集合の中で通常の文字として使用するときには + 退避修飾しなければならない) + + 名前付き捕獲式集合と、部分式呼出し機能追加 + + 多バイト文字コードが指定されているとき、 + 文字集合の中で八進数または十六進数表現の連続は、多バイト符合で表現された + 一個の文字と解釈される + (例. [\xa1\xa2], [\xa1\xa7-\xa4\xa1]) + + 文字集合の中で、一バイト文字と多バイト文字の範囲指定は許される。 + ex. /[a-あ]/ + + 孤立オプションの有効範囲は、その孤立オプションを含んでいる式集合の + 終わりまでである + 例. (?:(?i)a|b) は (?:(?i:a|b)) と解釈される、(?:(?i:a)|b)ではない + + 孤立オプションはその前の式に対して透過的ではない + 例. /a(?i)*/ は文法エラーとなる + + 不完全な繰り返し範囲指定子は通常の文字列として許可される + 例. /{/, /({)/, /a{2,3/ + + 否定的POSIXブラケット [:^xxxx:] を追加 + + POSIXブラケット [:ascii:] を追加 + + 先読みの繰り返しは不許可 + 例. /(?=a)*/, /(?!b){5}/ + + 数値で指定された文字に対しても、大文字小文字照合オプションは有効 + 例. /\x61/i =~ "A" + + 繰り返し回数指定で、最低回数の省略(0回)ができる + /a{,n}/ == /a{0,n}/ + 最低回数と最大回数の同時省略は許されない。(/a{,}/) + + /a{n}?/は無欲な演算子ではない。 + /a{n}?/ == /(?:a{n})?/ + + 無効な後方参照をチェックしてエラーにする。 + /\1/, /(a)\2/ + + 無限繰り返しの中で、長さ零での照合成功は繰り返しを中断させるが、 + このとき、中断すべきかどうかの判定として、捕獲式集合の捕獲状態の + 変化まで考慮している + /(?:()|())*\1\2/ =~ "" + /(?:\1a|())*/ =~ "a" + + + +補記 5. 実装されているが、既定値では有効にしていない機能 + + + 捕獲履歴参照 + + (?@...) と (?@...) + + 例. /(?@a)*/.match("aaa") ==> [<0-1>, <1-2>, <2-3>] + + 使用方法は、sample/listcap.cを参照 + + 有効にしていない理由は、どの程度役に立つかはっきりしないため。 + + +補記 6. 問題点 + + + エンコーディングバイト値が適正な価かどうかのチェックは行なっていない。 + + 例: UTF-8 + + * 先頭バイトとして不正なバイトを一文字とみなす + /./u =~ "\xa3" + + * 不完全なバイトシーケンスのチェックをしない + /\w+/u =~ "a\xf3\x8ec" + + これを調べることは可能ではあるが、遅くなるので行なわない。 + + 文字列として、そのようなバイト列を指定した場合の動作は保証しない。 + +終り -- cgit v1.2.3