Blame doc/CALLOUTS.API

Packit b89d10
Callouts API  Version 6.8.2 2018/04/14
Packit b89d10
Packit b89d10
#include <oniguruma.h>
Packit b89d10
Packit b89d10
(1) Callout functions
Packit b89d10
(2) Set/Get functions for Callouts of contents
Packit b89d10
(3) Set functions for Callouts of name
Packit b89d10
(4) User data
Packit b89d10
(5) Get values from OnigCalloutArgs
Packit b89d10
(6) Tag
Packit b89d10
(7) Callout data (used in callout functions)
Packit b89d10
(8) Callout data (used in applications)
Packit b89d10
(9) Miscellaneous functions
Packit b89d10
Packit b89d10
Packit b89d10
(1) Callout functions
Packit b89d10
Packit b89d10
  type: OnigCalloutFunc
Packit b89d10
Packit b89d10
  typedef int (*OnigCalloutFunc)(OnigCalloutArgs* args, void* user_data);
Packit b89d10
Packit b89d10
  If 0 (NULL) is set as a callout function value, never called.
Packit b89d10
Packit b89d10
Packit b89d10
  * Callout function return value (int)
Packit b89d10
Packit b89d10
    ONIG_CALLOUT_FAIL(1):     fail
Packit b89d10
    ONIG_CALLOUT_SUCCESS(0):  success
Packit b89d10
    less than -1:             error code (terminate search/match)
Packit b89d10
Packit b89d10
    ONIG_CALLOUT_FAIL/SUCCESS values are ignored in retractions,
Packit b89d10
    because retraction is a part of recovery process after failure.
Packit b89d10
Packit b89d10
  * Example of callout function
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) Set/Get functions for Callouts of contents
Packit b89d10
Packit b89d10
# OnigCalloutFunc onig_get_progress_callout(void)
Packit b89d10
Packit b89d10
  Get a function for callouts of contents in progress.
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_set_progress_callout(OnigCalloutFunc f)
Packit b89d10
Packit b89d10
  Set a function for callouts of contents in progress.
Packit b89d10
  This value set in onig_initialize_match_param() as a default
Packit b89d10
  callout function.
Packit b89d10
Packit b89d10
  normal return: ONIG_NORMAL
Packit b89d10
Packit b89d10
Packit b89d10
# OnigCalloutFunc onig_get_retraction_callout(void)
Packit b89d10
Packit b89d10
  Get a function for callouts of contents in retraction (backtrack).
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_set_retraction_callout(OnigCalloutFunc f)
Packit b89d10
Packit b89d10
  Set a function for callouts of contents in retraction (backtrack).
Packit b89d10
  This value set in onig_initialize_match_param() as a default
Packit b89d10
  callout function.
Packit b89d10
Packit b89d10
  normal return: ONIG_NORMAL
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_set_progress_callout_of_match_param(OnigMatchParam* mp, OnigCalloutFunc f)
Packit b89d10
Packit b89d10
  Set a function for callouts of contents in progress.
Packit b89d10
Packit b89d10
  arguments
Packit b89d10
  1 mp: match-param pointer
Packit b89d10
  2 f: function
Packit b89d10
Packit b89d10
  normal return: ONIG_NORMAL
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_set_retraction_callout_of_match_param(OnigMatchParam* mp, OnigCalloutFunc f)
Packit b89d10
Packit b89d10
  Set a function for callouts of contents in retraction (backtrack).
Packit b89d10
Packit b89d10
  arguments
Packit b89d10
  1 mp: match-param pointer
Packit b89d10
  2 f: function
Packit b89d10
Packit b89d10
  normal return: ONIG_NORMAL
Packit b89d10
Packit b89d10
Packit b89d10
Packit b89d10
(3) Set functions for Callouts of name
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
  Set a function for callouts of name.
Packit b89d10
  Allowed name string characters: _ A-Z a-z 0-9   (* first character: _ A-Z a-z)
Packit b89d10
Packit b89d10
  (enc, name) pair is used as key value to find callout function.
Packit b89d10
  You have to call this function for every encoding used in your applications.
Packit b89d10
  But if enc is ASCII compatible and (enc, name) entry is not found,
Packit b89d10
  then (ASCII, name) entry is used.
Packit b89d10
  Therefore, if you use ASCII compatible encodings only, it is enough to call
Packit b89d10
  this function one time for (ASCII, name).
Packit b89d10
Packit b89d10
  arguments
Packit b89d10
   1 enc:         character encoding
Packit b89d10
   2 type:        callout type (currently ONIG_CALLOUT_TYPE_SINGLE only supported)
Packit b89d10
   3 name:        name string address (the string is encoded by enc)
Packit b89d10
   4 name_end:    name string end address
Packit b89d10
   5 callout_in:  direction (ONIG_CALLOUT_IN_PROGRESS/RETRACTION/BOTH)
Packit b89d10
   6 callout:     callout function
Packit b89d10
   7 end_callout: * not used currently (set 0)
Packit b89d10
   8 arg_num:     number of arguments (*limit by ONIG_CALLOUT_MAX_ARGS_NUM == 4)
Packit b89d10
   9 arg_types:   type array of arguments
Packit b89d10
  10 opt_arg_num: number of optional arguments
Packit b89d10
  11 opt_defaults: default values array of optional arguments
Packit b89d10
Packit b89d10
  normal return: 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) User data
Packit b89d10
Packit b89d10
# int onig_set_callout_user_data_of_match_param(OnigMatchParam* param, void* user_data)
Packit b89d10
Packit b89d10
  Set a user_data value which passed as second argument of callout.
Packit b89d10
Packit b89d10
  normal return: ONIG_NORMAL
Packit b89d10
Packit b89d10
Packit b89d10
Packit b89d10
(5) Get values from OnigCalloutArgs
Packit b89d10
Packit b89d10
# int onig_get_callout_num_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  Returns callout number of this callout.
Packit b89d10
  "Callout number" is an identifier of callout in a regex pattern.
Packit b89d10
Packit b89d10
Packit b89d10
# OnigCalloutIn onig_get_callout_in_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  Returns the direction of this callout.
Packit b89d10
  (ONIG_CALLOUT_IN_PROGRESS or ONIG_CALLOUT_IN_RETRACTION)
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_get_name_id_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  Returns the name identifier of this callout.
Packit b89d10
  If this callout is callout of contents, then returns ONIG_NON_NAME_ID.
Packit b89d10
Packit b89d10
Packit b89d10
# const OnigUChar* onig_get_contents_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  Returns the contents string of this callout. (NULL terminated string)
Packit b89d10
  If this callout is callout of name, then returns NULL.
Packit b89d10
Packit b89d10
Packit b89d10
# const OnigUChar* onig_get_contents_end_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  Returns the end of contents string of this callout.
Packit b89d10
  If this callout is callout of name, then returns NULL.
Packit b89d10
Packit b89d10
Packit b89d10
# int onig_get_args_num_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  Returns the number of args of this callout.
Packit b89d10
  It includes optional arguments that doesn't passed in regex pattern.
Packit b89d10
  If this callout is callout of contents, then returns
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
  Returns the number of args that passed really in regex pattern.
Packit b89d10
  If this callout is callout of contents, then returns
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
  Returns a value and a type of the callout argument.
Packit b89d10
  If this callout is callout of contents, then returns
Packit b89d10
  ONIGERR_INVALID_ARGUMENT.
Packit b89d10
Packit b89d10
  normal return: ONIG_NORMAL
Packit b89d10
Packit b89d10
Packit b89d10
# const OnigUChar* onig_get_string_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  Returns the subject string adress.
Packit b89d10
  This is the second argument(str) of onig_search().
Packit b89d10
Packit b89d10
Packit b89d10
# const OnigUChar* onig_get_string_end_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  Returns the end address of subject string.
Packit b89d10
  This is the third argument(end) of onig_search().
Packit b89d10
Packit b89d10
Packit b89d10
# const OnigUChar* onig_get_start_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  Returns the start address of subject string in current match process.
Packit b89d10
Packit b89d10
Packit b89d10
# const OnigUChar* onig_get_right_range_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  Returns the right range address of subject string.
Packit b89d10
Packit b89d10
Packit b89d10
# const OnigUChar* onig_get_current_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  Returns the current address of subject string in current match process.
Packit b89d10
Packit b89d10
Packit b89d10
# OnigRegex onig_get_regex_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  Returns the regex object address of this callout.
Packit b89d10
Packit b89d10
Packit b89d10
# unsigned long onig_get_retry_counter_by_callout_args(OnigCalloutArgs* args)
Packit b89d10
Packit b89d10
  Returns the current counter value for retry-limit-in-match.
Packit b89d10
Packit b89d10
Packit b89d10
Packit b89d10
(6) Tag
Packit b89d10
Packit b89d10
  "Tag" is a name assigned to a callout in regexp pattern.
Packit b89d10
  Allowed tag string characters: _ A-Z a-z 0-9   (* first character: _ 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
  Returns 1 if tag is assigned for the callout, else returns 0.
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
  Returns the callout number for the tag.
Packit b89d10
Packit b89d10
Packit b89d10
# const OnigUChar* onig_get_callout_tag_start(OnigRegex reg, int callout_num)
Packit b89d10
Packit b89d10
  Returns the start address of tag string for the callout.
Packit b89d10
  (NULL terminated string)
Packit b89d10
Packit b89d10
Packit b89d10
# const OnigUChar* onig_get_callout_tag_end(OnigRegex reg, int callout_num)
Packit b89d10
Packit b89d10
  Returns the end address of tag string for the callout.
Packit b89d10
Packit b89d10
Packit b89d10
Packit b89d10
(7) Callout data (used in callout functions)
Packit b89d10
Packit b89d10
  "Callout data" is ONIG_CALLOUT_DATA_SLOT_NUM(5) values area
Packit b89d10
  for each callout in each search process.
Packit b89d10
  Each value area in a callout is indicated by "slot" number (0 - 4).
Packit b89d10
  Callout data are used for any purpose by callout function implementers.
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
  Returns the callout data value/type for a callout slot indicated by
Packit b89d10
  callout_num/slot.
Packit b89d10
Packit b89d10
  normal return: ONIG_NORMAL
Packit b89d10
              1: not yet set (type is ONIG_TYPE_VOID)
Packit b89d10
            < 0: error code
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
  Returns self callout data value/type.
Packit b89d10
Packit b89d10
  normal return: ONIG_NORMAL
Packit b89d10
              1: not yet set (type is ONIG_TYPE_VOID)
Packit b89d10
            < 0: error code
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
  Set the callout data value/type for a callout slot indicated by callout_num/slot.
Packit b89d10
Packit b89d10
  normal return: ONIG_NORMAL
Packit b89d10
            < 0: error code
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
  Set self callout data value/type for a callout slot indicated by slot.
Packit b89d10
Packit b89d10
  normal return: ONIG_NORMAL
Packit b89d10
            < 0: error code
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
  This function is almost same as onig_get_callout_data_by_callout_args_self().
Packit b89d10
  But this function doesn't clear values which set in previous failed match process.
Packit b89d10
  Other onig_get_callout_data_xxxx() functions clear all values which set
Packit b89d10
  in previous failed match process.
Packit b89d10
Packit b89d10
  For example, Builtin callout (*TOTAL_COUNT) is implemented by using this
Packit b89d10
  function for accumulate count of all of match processes in a search process.
Packit b89d10
  Builtin callout (*COUNT) returns count in last success match process only,
Packit b89d10
  because it doesn't use this function.
Packit b89d10
Packit b89d10
Packit b89d10
(8) Callout data (used in apllications)
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
  Returns the callout data value/type for a callout slot indicated by
Packit b89d10
  callout_num/slot.
Packit b89d10
Packit b89d10
  normal return: ONIG_NORMAL
Packit b89d10
              1: not yet set (type is ONIG_TYPE_VOID)
Packit b89d10
            < 0: error code
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
  Returns the callout data value/type for a callout slot indicated by tag/slot.
Packit b89d10
Packit b89d10
  normal return: ONIG_NORMAL
Packit b89d10
              1: not yet set (type is ONIG_TYPE_VOID)
Packit b89d10
            < 0: error code
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
  Set the callout data value/type for a callout slot indicated by callout_num/slot.
Packit b89d10
Packit b89d10
  normal return: ONIG_NORMAL
Packit b89d10
            < 0: error code
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
  Set the callout data value/type for a callout slot indicated by tag/slot.
Packit b89d10
Packit b89d10
  normal return: ONIG_NORMAL
Packit b89d10
            < 0: error code
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
  No needs to use this function.
Packit b89d10
  It will be abolished.
Packit b89d10
Packit b89d10
Packit b89d10
Packit b89d10
(9) Miscellaneous functions
Packit b89d10
Packit b89d10
# OnigUChar* onig_get_callout_name_by_name_id(int name_id)
Packit b89d10
Packit b89d10
  Returns callout name of the name id.
Packit b89d10
  if invalid name id is passed, return 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
  Returns current capture range position.
Packit b89d10
  Position is byte length offset from subject string.
Packit b89d10
  For uncaptured mem_num, ONIG_REGION_NOTPOS is set.
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
  Returns current used match-stack size.
Packit b89d10
Packit b89d10
  used_num:   number of match-stack elements
Packit b89d10
  used_bytes: used byte size of match-stack
Packit b89d10
Packit b89d10
//END