Oniguruma API   2003/12/17

#include <oniguruma.h>


# int regex_init(void)

  Initialize library.

  You don't have to call it explicitly, because it is called in regex_new().


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

  Get error message string.
  If this function is used for regex_new() or regex_recompile(),
  don't call this after the pattern argument of regex_new() or
  regex_recompile() is freed.

  normal return: error message string length

  arguments
  1 err_buf:              error message string buffer.
                          (required size: REG_MAX_ERROR_MESSAGE_LEN)
  2 err_code:             error code returned by other API functions.
  3 err_info (optional):  error info returned by regex_new()
                          and regex_recompile().


# void regex_set_warn_func(RegWarnFunc 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 regex_set_verb_warn_func(RegWarnFunc func)

  Set verbose warning function.

  WARNING:
    redundant nested repeat operator.

  arguments
  1: func     function pointer.    void (*func)(char* warning_message)


# int regex_new(regex_t** reg, UChar* pattern, UChar* pattern_end,
            RegOptionType option, RegCharEncoding code, RegSyntaxType* syntax,
            RegErrorInfo* err_info)

  Create new regex object.

  normal return: REG_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.

      REG_OPTION_NONE               no option
      REG_OPTION_SINGLELINE         '^' -> '\A', '$' -> '\z', '\Z' -> '\z'
      REG_OPTION_MULTILINE          '.' match with newline
      REG_OPTION_IGNORECASE         ignore case (case-insensitive)
      REG_OPTION_EXTEND             extended pattern form
      REG_OPTION_FIND_LONGEST       find longest match
      REG_OPTION_FIND_NOT_EMPTY     ignore empty match
      REG_OPTION_NEGATE_SINGLELINE
                 clear REG_OPTION_SINGLELINE which is default on
                 in REG_SYNTAX_POSIX_XXX, REG_SYNTAX_PERL and REG_SYNTAX_JAVA.

      REG_OPTION_DONT_CAPTURE_GROUP only named group captured.  (/.../g)
      REG_OPTION_CAPTURE_GROUP      named and no-named group captured. (/.../G)

  5 code:        character encoding.

      REG_ENCODING_ASCII         ASCII
      REG_ENCODING_ISO_8859_1    ISO 8859-1
      REG_ENCODING_ISO_8859_15   ISO 8859-15
      REG_ENCODING_UTF8          UTF-8
      REG_ENCODING_EUC_JP        EUC-JP
      REG_ENCODING_SJIS          Shift_JIS
      REG_ENCODING_BIG5          Big5

      (* REGCODE_XXX was obsoleted. 2003/12/03)

  6 syntax:     address of pattern syntax definition.

      REG_SYNTAX_POSIX_BASIC       POSIX Basic RE
      REG_SYNTAX_POSIX_EXTENDED    POSIX Extended RE
      REG_SYNTAX_EMACS             Emacs
      REG_SYNTAX_GREP              grep
      REG_SYNTAX_GNU_REGEX         GNU regex
      REG_SYNTAX_JAVA              Java (Sun java.util.regex)
      REG_SYNTAX_PERL              Perl
      REG_SYNTAX_RUBY              Ruby
      REG_SYNTAX_DEFAULT           default (== Ruby)
                                   regex_set_default_syntax()

      or any RegSyntaxType data address defined by user.

  7 err_info: address for return optional error info.
              Use this value as 3rd argument of regex_error_code_to_str().


# void regex_free(regex_t* reg)

  Free memory used by regex object.

  arguments
  1 reg: regex object.


# int regex_recompile(regex_t* reg, UChar* pattern, UChar* pattern_end,
	  RegOptionType option, RegCharEncoding code, RegSyntaxType* syntax,
          RegErrorInfo* err_info)

  Recompile regex object.

  normal return: REG_NORMAL

  arguments
  1 reg: regex object.

  Another arguments are same with regex_new().


# int regex_search(regex_t* reg, UChar* str, UChar* end, UChar* start,
                   UChar* range, RegRegion* region, RegOptionType option)

  Search string and return search result and matching region.

  normal return: match position offset (i.e.  p - str >= 0)
  not found:     REG_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
  6 region: address for return group match range info (NULL is allowed)
  7 option: search time option

    REG_OPTION_NOTBOL        string head(str) isn't considered as begin of line
    REG_OPTION_NOTEOL        string end (end) isn't considered as end of line
    REG_OPTION_POSIX_REGION  region argument is regmatch_t[] of POSIX API.


# int regex_match(regex_t* reg, UChar* str, UChar* end, UChar* at,
			 RegRegion* region, RegOptionType option)

  Match string and return result and matching region.

  normal return: match length (i.e.  p - at >= 0)
  not match:     REG_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

    REG_OPTION_NOTBOL        string head(str) isn't considered as begin of line
    REG_OPTION_NOTEOL        string end (end) isn't considered as end of line
    REG_OPTION_POSIX_REGION  region argument is regmatch_t[] of POSIX API.


# RegRegion* regex_region_new(void)

  Create a region.


# void regex_region_free(RegRegion* 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 regex_region_copy(RegRegion* to, RegRegion* from)

  Copy contents of region.

  arguments
  1 to: target region
  2 from: source region


# void regex_region_clear(RegRegion* region)

  Clear contents of region.

  arguments
  1 region: target region


# int regex_region_resize(RegRegion* region, int n)

  Resize group range area of region.

  normal return: REG_NORMAL

  arguments
  1 region: target region
  2 n:      new size


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

  Return the group number list of the name.
  Named subexp is defined by (?<name>....).

  normal return:  number of groups for the name.
                  (ex. /(?<x>..)...(?<x>..)/  ==>  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 regex_name_to_backref_number(regex_t* reg, UChar* name, UChar* name_end,
                                   RegRegion *region)

  Return the group number corresponding to the named backref (\k<name>).
  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 regex_foreach_name(regex_t* reg,
                         int (*func)(UChar*,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, <number of groups>, <group number's list>,
                  reg, arg);
             if func return non 0 value, iteration is stopped.
  3 arg:     argument for func.


# int regex_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.


# RegCharEncoding regex_get_encoding(regex_t* reg)
# RegOptionType regex_get_options(regex_t* reg)
# RegSyntaxType* regex_get_syntax(regex_t* reg)

  Return the value.

  arguments
  1 reg:     regex object.


# UChar* enc_get_prev_char_head(RegCharEncoding code, UChar* start, UChar* s)

  Return previous character head address.

  arguments
  1 code: character encoding
  2 start: string address
  3 s:     target address of string


# UChar* enc_get_left_adjust_char_head(RegCharEncoding code,
                                       UChar* start, UChar* s)

  Return left-adjusted head address of a character.

  arguments
  1 code:  character encoding
  2 start: string address
  3 s:     target address of string


# UChar* enc_get_right_adjust_char_head(RegCharEncoding code,
                                        UChar* start, UChar* s)

  Return right-adjusted head address of a character.

  arguments
  1 code:  character encoding
  2 start: string address
  3 s:     target address of string


# int regex_set_default_syntax(RegSyntaxType* syntax)

  Set default syntax.

  arguments
  1 syntax: address of pattern syntax definition.


# void regex_copy_syntax(RegSyntaxType* to, RegSyntaxType* from)

  Copy syntax.

  arguments
  1 to:   destination address.
  2 from: source address.


# int regex_set_meta_char(unsigned int what, unsigned int c)

  Set meta characters.
  Except for an escape character, this meta characters specification
  is not work, if REG_SYN_OP_VARIABLE_META_CHARACTERS is not effective
  by the syntax. (Build-in syntaxes are not effective.)

  normal return: REG_NORMAL

  arguments
  1 what: specifies which meta character it is.

          REG_META_CHAR_ESCAPE
          REG_META_CHAR_ANYCHAR
          REG_META_CHAR_ANYTIME
          REG_META_CHAR_ZERO_OR_ONE_TIME
          REG_META_CHAR_ONE_OR_MORE_TIME
          REG_META_CHAR_ANYCHAR_ANYTIME

  2 c:    meta character or REG_INEFFECTIVE_META_CHAR.


# int regex_end(void)

  The use of this library is finished.

  normal return: REG_NORMAL


# const char* regex_version(void)

  Return version string.  (ex. "1.9.2")

// END
