1Callouts API Version 6.8.2 2018/06/08 2 3#include <oniguruma.h> 4 5(1) Callout functions 6(2) Set/Get functions for Callouts of contents 7(3) Set functions for Callouts of name 8(4) User data 9(5) Get values from OnigCalloutArgs 10(6) Tag 11(7) Callout data (used in callout functions) 12(8) Callout data (used in applications) 13(9) Miscellaneous functions 14 15 16(1) Callout functions 17 18 type: OnigCalloutFunc 19 20 typedef int (*OnigCalloutFunc)(OnigCalloutArgs* args, void* user_data); 21 22 If 0 (NULL) is set as a callout function value, never called. 23 24 25 * Callout function return value (int) 26 27 ONIG_CALLOUT_FAIL (== 1): fail 28 ONIG_CALLOUT_SUCCESS (== 0): success 29 less than -1: error code (terminate search/match) 30 31 ONIG_CALLOUT_FAIL/SUCCESS values are ignored in retractions, 32 because retraction is a part of recovery process after failure. 33 34 * Example of callout function 35 36 extern int always_success(OnigCalloutArgs* args, void* user_data) 37 { 38 return ONIG_CALLOUT_SUCCESS; 39 } 40 41 42 43(2) Set/Get functions for Callouts of contents 44 45# OnigCalloutFunc onig_get_progress_callout(void) 46 47 Get a function for callouts of contents in progress. 48 49 50# int onig_set_progress_callout(OnigCalloutFunc f) 51 52 Set a function for callouts of contents in progress. 53 This value set in onig_initialize_match_param() as a default 54 callout function. 55 56 normal return: ONIG_NORMAL 57 58 59# OnigCalloutFunc onig_get_retraction_callout(void) 60 61 Get a function for callouts of contents in retraction (backtrack). 62 63 64# int onig_set_retraction_callout(OnigCalloutFunc f) 65 66 Set a function for callouts of contents in retraction (backtrack). 67 This value set in onig_initialize_match_param() as a default 68 callout function. 69 70 normal return: ONIG_NORMAL 71 72 73# int onig_set_progress_callout_of_match_param(OnigMatchParam* mp, OnigCalloutFunc f) 74 75 Set a function for callouts of contents in progress. 76 77 arguments 78 1 mp: match-param pointer 79 2 f: function 80 81 normal return: ONIG_NORMAL 82 83 84# int onig_set_retraction_callout_of_match_param(OnigMatchParam* mp, OnigCalloutFunc f) 85 86 Set a function for callouts of contents in retraction (backtrack). 87 88 arguments 89 1 mp: match-param pointer 90 2 f: function 91 92 normal return: ONIG_NORMAL 93 94 95 96(3) Set functions for Callouts of name 97 98# 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[]) 99 100 Set a function for callouts of name. 101 Allowed name string characters: _ A-Z a-z 0-9 (* first character: _ A-Z a-z) 102 103 (enc, name) pair is used as key value to find callout function. 104 You have to call this function for every encoding used in your applications. 105 But if enc is ASCII compatible and (enc, name) entry is not found, 106 then (ASCII, name) entry is used. 107 Therefore, if you use ASCII compatible encodings only, it is enough to call 108 this function one time for (ASCII, name). 109 110 arguments 111 1 enc: character encoding 112 2 type: callout type (currently ONIG_CALLOUT_TYPE_SINGLE only supported) 113 3 name: name string address (the string is encoded by enc) 114 4 name_end: name string end address 115 5 callout_in: direction (ONIG_CALLOUT_IN_PROGRESS/RETRACTION/BOTH) 116 6 callout: callout function 117 7 end_callout: * not used currently (set 0) 118 8 arg_num: number of arguments (*limit by ONIG_CALLOUT_MAX_ARGS_NUM == 4) 119 9 arg_types: type array of arguments 120 10 opt_arg_num: number of optional arguments 121 11 opt_defaults: default values array of optional arguments 122 123 normal return: ONIG_NORMAL 124 error: 125 ONIGERR_INVALID_CALLOUT_NAME 126 ONIGERR_INVALID_ARGUMENT 127 ONIGERR_INVALID_CALLOUT_ARG 128 129 130 131(4) User data 132 133# int onig_set_callout_user_data_of_match_param(OnigMatchParam* param, void* user_data) 134 135 Set a user_data value which passed as second argument of callout. 136 137 normal return: ONIG_NORMAL 138 139 140 141(5) Get values from OnigCalloutArgs 142 143# int onig_get_callout_num_by_callout_args(OnigCalloutArgs* args) 144 145 Returns callout number of this callout. 146 "Callout number" is an identifier of callout in a regex pattern. 147 148 149# OnigCalloutIn onig_get_callout_in_by_callout_args(OnigCalloutArgs* args) 150 151 Returns the direction of this callout. 152 (ONIG_CALLOUT_IN_PROGRESS or ONIG_CALLOUT_IN_RETRACTION) 153 154 155# int onig_get_name_id_by_callout_args(OnigCalloutArgs* args) 156 157 Returns the name identifier of this callout. 158 If this callout is callout of contents, then returns ONIG_NON_NAME_ID. 159 160 161# const OnigUChar* onig_get_contents_by_callout_args(OnigCalloutArgs* args) 162 163 Returns the contents string of this callout. (NULL terminated string) 164 If this callout is callout of name, then returns NULL. 165 166 167# const OnigUChar* onig_get_contents_end_by_callout_args(OnigCalloutArgs* args) 168 169 Returns the end of contents string of this callout. 170 If this callout is callout of name, then returns NULL. 171 172 173# int onig_get_args_num_by_callout_args(OnigCalloutArgs* args) 174 175 Returns the number of args of this callout. 176 It includes optional arguments that doesn't passed in regex pattern. 177 If this callout is callout of contents, then returns 178 ONIGERR_INVALID_ARGUMENT. 179 180 181# int onig_get_passed_args_num_by_callout_args(OnigCalloutArgs* args) 182 183 Returns the number of args that passed really in regex pattern. 184 If this callout is callout of contents, then returns 185 ONIGERR_INVALID_ARGUMENT. 186 187 188# int onig_get_arg_by_callout_args(OnigCalloutArgs* args, int index, OnigType* type, OnigValue* val) 189 190 Returns a value and a type of the callout argument. 191 If this callout is callout of contents, then returns 192 ONIGERR_INVALID_ARGUMENT. 193 194 normal return: ONIG_NORMAL 195 196 197# const OnigUChar* onig_get_string_by_callout_args(OnigCalloutArgs* args) 198 199 Returns the subject string address. 200 This is the second argument(str) of onig_search(). 201 202 203# const OnigUChar* onig_get_string_end_by_callout_args(OnigCalloutArgs* args) 204 205 Returns the end address of subject string. 206 This is the third argument(end) of onig_search(). 207 208 209# const OnigUChar* onig_get_start_by_callout_args(OnigCalloutArgs* args) 210 211 Returns the start address of subject string in current match process. 212 213 214# const OnigUChar* onig_get_right_range_by_callout_args(OnigCalloutArgs* args) 215 216 Returns the right range address of subject string. 217 218 219# const OnigUChar* onig_get_current_by_callout_args(OnigCalloutArgs* args) 220 221 Returns the current address of subject string in current match process. 222 223 224# OnigRegex onig_get_regex_by_callout_args(OnigCalloutArgs* args) 225 226 Returns the regex object address of this callout. 227 228 229# unsigned long onig_get_retry_counter_by_callout_args(OnigCalloutArgs* args) 230 231 Returns the current counter value for retry-limit-in-match. 232 233 234 235(6) Tag 236 237 "Tag" is a name assigned to a callout in regexp pattern. 238 Allowed tag string characters: _ A-Z a-z 0-9 (* first character: _ A-Z a-z) 239 240 241# int onig_callout_tag_is_exist_at_callout_num(OnigRegex reg, int callout_num) 242 243 Returns 1 if tag is assigned for the callout, else returns 0. 244 245 246# int onig_get_callout_num_by_tag(OnigRegex reg, const OnigUChar* tag, const OnigUChar* tag_end) 247 248 Returns the callout number for the tag. 249 250 251# const OnigUChar* onig_get_callout_tag_start(OnigRegex reg, int callout_num) 252 253 Returns the start address of tag string for the callout. 254 (NULL terminated string) 255 256 257# const OnigUChar* onig_get_callout_tag_end(OnigRegex reg, int callout_num) 258 259 Returns the end address of tag string for the callout. 260 261 262 263(7) Callout data (used in callout functions) 264 265 "Callout data" is ONIG_CALLOUT_DATA_SLOT_NUM(5) values area 266 for each callout in each search process. 267 Each value area in a callout is indicated by "slot" number (0 - 4). 268 Callout data are used for any purpose by callout function implementers. 269 270 271# int onig_get_callout_data_by_callout_args(OnigCalloutArgs* args, int callout_num, int slot, OnigType* type, OnigValue* val) 272 273 Returns the callout data value/type for a callout slot indicated by 274 callout_num/slot. 275 276 normal return: ONIG_NORMAL 277 1: not yet set (type is ONIG_TYPE_VOID) 278 < 0: error code 279 280 281# int onig_get_callout_data_by_callout_args_self(OnigCalloutArgs* args, int slot, OnigType* type, OnigValue* val) 282 283 Returns self callout data value/type. 284 285 normal return: ONIG_NORMAL 286 1: not yet set (type is ONIG_TYPE_VOID) 287 < 0: error code 288 289 290# int onig_set_callout_data_by_callout_args(OnigCalloutArgs* args, int callout_num, int slot, OnigType type, OnigValue* val) 291 292 Set the callout data value/type for a callout slot indicated by callout_num/slot. 293 294 normal return: ONIG_NORMAL 295 < 0: error code 296 297 298# int onig_set_callout_data_by_callout_args_self(OnigCalloutArgs* args, int slot, OnigType type, OnigValue* val) 299 300 Set self callout data value/type for a callout slot indicated by slot. 301 302 normal return: ONIG_NORMAL 303 < 0: error code 304 305 306# int onig_get_callout_data_by_callout_args_self_dont_clear_old(OnigCalloutArgs* args, int slot, OnigType* type, OnigValue* val) 307 308 This function is almost same as onig_get_callout_data_by_callout_args_self(). 309 But this function doesn't clear values which set in previous failed match process. 310 Other onig_get_callout_data_xxxx() functions clear all values which set 311 in previous failed match process. 312 313 For example, Builtin callout (*TOTAL_COUNT) is implemented by using this 314 function for accumulate count of all of match processes in a search process. 315 Builtin callout (*COUNT) returns count in last success match process only, 316 because it doesn't use this function. 317 318 319(8) Callout data (used in apllications) 320 321# int onig_get_callout_data(OnigRegex reg, OnigMatchParam* mp, int callout_num, int slot, OnigType* type, OnigValue* val) 322 323 Returns the callout data value/type for a callout slot indicated by 324 callout_num/slot. 325 326 normal return: ONIG_NORMAL 327 1: not yet set (type is ONIG_TYPE_VOID) 328 < 0: error code 329 330 331# int onig_get_callout_data_by_tag(OnigRegex reg, OnigMatchParam* mp, const OnigUChar* tag, const OnigUChar* tag_end, int slot, OnigType* type, OnigValue* val) 332 333 Returns the callout data value/type for a callout slot indicated by tag/slot. 334 335 normal return: ONIG_NORMAL 336 1: not yet set (type is ONIG_TYPE_VOID) 337 < 0: error code 338 339 340# int onig_set_callout_data(OnigRegex reg, OnigMatchParam* mp, int callout_num, int slot, OnigType type, OnigValue* val) 341 342 Set the callout data value/type for a callout slot indicated by callout_num/slot. 343 344 normal return: ONIG_NORMAL 345 < 0: error code 346 347 348# int onig_set_callout_data_by_tag(OnigRegex reg, OnigMatchParam* mp, const OnigUChar* tag, const OnigUChar* tag_end, int slot, OnigType type, OnigValue* val) 349 350 Set the callout data value/type for a callout slot indicated by tag/slot. 351 352 normal return: ONIG_NORMAL 353 < 0: error code 354 355 356# int onig_get_callout_data_dont_clear_old(OnigRegex reg, OnigMatchParam* mp, int callout_num, int slot, OnigType* type, OnigValue* val) 357 358 No needs to use this function. 359 It will be abolished. 360 361 362 363(9) Miscellaneous functions 364 365# OnigUChar* onig_get_callout_name_by_name_id(int name_id) 366 367 Returns callout name of the name id. 368 if invalid name id is passed, return 0. 369 370 371# int onig_get_capture_range_in_callout(OnigCalloutArgs* args, int mem_num, int* begin, int* end) 372 373 Returns current capture range position. 374 Position is byte length offset from subject string. 375 For uncaptured mem_num, ONIG_REGION_NOTPOS is set. 376 377 378# int onig_get_used_stack_size_in_callout(OnigCalloutArgs* args, int* used_num, int* used_bytes) 379 380 Returns current used match-stack size. 381 382 used_num: number of match-stack elements 383 used_bytes: used byte size of match-stack 384 385//END 386
