1onig_new
2
3 SYNOPSIS
4  Create an instance of a regular-expression
5
6 USAGE
7  Onig_Type onig_new (pattern [,options [,encoding [,syntax]]])
8
9   String_Type pattern;
10   Int_Type options;
11   String_Type encoding;
12   String_Type syntax;
13
14
15 DESCRIPTION
16 The `onig_new' function compiles the specified regular
17 expression (`pattern') and returns the result.  The other
18 parameters are optional and may be used to specify compilation
19 options, the character-set encoding, and the regular expression
20 syntax. Upon success, this function returns an Onig_Type
21 object representing the compiled pattern.  If compilation fails, a
22 `OnigError' exception will be thrown.
23
24 The `options' parameters is a bit mapped value that may be
25 formed from the bitwise-or of zero or more of the following constants:
26
27   ONIG_OPTION_NONE
28   ONIG_OPTION_IGNORECASE
29   ONIG_OPTION_EXTEND
30   ONIG_OPTION_MULTILINE
31   ONIG_OPTION_SINGLELINE
32   ONIG_OPTION_FIND_LONGEST
33   ONIG_OPTION_FIND_NOT_EMPTY
34   ONIG_OPTION_NEGATE_SINGLELINE
35   ONIG_OPTION_DONT_CAPTURE_GROUP
36   ONIG_OPTION_CAPTURE_GROUP
37
38
39 The character-set encoding may be specified using one of the
40 following strings:
41
42  "ascii"         "iso_8859_1"     "iso_8859_2"   "iso_8859_3"
43  "iso_8859_4"    "iso_8859_5"     "iso_8859_6"   "iso_8859_7"
44  "iso_8859_8",   "iso_8859_9"     "iso_8859_10"  "iso_8859_11"
45  "iso_8859_13"   "iso_8859_14"    "iso_8859_15"  "iso_8859_16"
46  "utf8"          "utf16_be"       "utf16_le"     "utf32_be"
47  "utf32_le"      "euc_jp"         "euc_tw"       "euc_kr"
48  "euc_cn"        "sjis"           "koi8_r"       "cp1251"
49  "big5"          "gb18030"
50
51 If not specified, "utf8" will be used if the interpreter is UTF-8
52 mode and "iso_8859_1" if not in UTF-8 mode.
53
54 The regular expression syntax of the pattern may be specified by
55 setting the `syntax' parameter to one of the following:
56
57  "asis"    "posix_basic"  "posix_extended"  "emacs"
58  "grep"    "gnu_regex"    "java"            "perl"
59  "perl_ng" "ruby"
60
61 If unspecified, the syntax defaults to `"perl"'.
62
63 SEE ALSO
64  onig_search, onig_nth_match, onig_nth_substr
65
66--------------------------------------------------------------
67
68onig_search
69
70 SYNOPSIS
71  Search a string using an Onig compiled pattern
72
73 USAGE
74  Int_Type onig_search (p, str [,start_pos, end_pos] [,option])
75
76   Onig_Type p;
77   String_Type str;
78   Int_Type start_pos, end_pos;
79
80
81 DESCRIPTION
82 The `onig_search' function applies a pre-compiled pattern `p' to a
83 string `str' and returns the result of the match.  The optional
84 third and fourth arguments may be used to constrain the search region
85 to the specified byte-offsets in the string.  The `option'
86 parameter is also optional and may be used to control how the search
87 is to be performed.  Its value may be specified as a bitwise-or of zero or
88 more of the following flags:
89
90   ONIG_OPTION_NOTBOL
91   ONIG_OPTION_NOTEOL
92   ONIG_OPTION_POSIX_REGION
93
94 See the onig library documentation for more information about the meaning
95 of these flags.
96
97 Upon success, this function returns a positive integer equal to 1 plus the
98 number of so-called captured substrings.  It will return 0 if the pattern
99 failed to match the string.
100
101 SEE ALSO
102  onig_new, onig_nth_match, onig_nth_substr
103
104--------------------------------------------------------------
105
106onig_nth_match
107
108 SYNOPSIS
109  Return the location of the nth match of an onig regular expression
110
111 USAGE
112  Int_Type[2] onig_nth_match (Onig_Type p, Int_Type nth)
113
114 DESCRIPTION
115 The `onig_nth_match' function returns an integer array whose
116 values specify the locations as byte-offsets to the beginning and end
117 of the `nth' captured substring of the most recent call to
118 `onig_search' with the compiled pattern.  A value of `nth'
119 equal to 0 represents the substring representing the entire match of
120 the pattern.
121
122 If the `nth' match did not take place, the function returns NULL.
123
124 EXAMPLE
125 After the execution of:
126
127    str = "Error in file foo.c, line 127, column 10";
128    pattern = "file ([^,]+), line ([0-9]+)";
129    p = onig_new (pattern);
130    if (onig_search (p, str))
131      {
132         match_pos = onig_nth_match (p, 0);
133         file_pos = onig_nth_match (p, 1);
134         line_pos = onig_nth_match (p, 2);
135      }
136
137 `match_pos' will be set to `[9,29]', `file_pos' to `[14,19,]'
138 and `line_pos' to `[26,29]'.  These integer arrays may be used to
139 extract the substrings matched by the pattern, e.g.,
140
141     file = substr (str, file_pos[0]+1, file_pos[1]-file_pos[0]);
142     line = str[[line_pos[0]:line_pos[1]-1]];
143
144 Alternatively, the function `onig_nth_substr' may be used to get the
145 matched substrings:
146
147     file = onig_nth_substr (p, str, 0);
148
149
150 SEE ALSO
151  onig_new, onig_search, onig_nth_substr
152
153--------------------------------------------------------------
154
155onig_nth_substr
156
157 SYNOPSIS
158  Extract the nth matched substring from an Onig regular expression search
159
160 USAGE
161  String_Type onig_nth_substr (Onig_Type p, String_Type str, Int_Type nth)
162
163 DESCRIPTION
164 This function may be used to extract the `nth' captured substring
165 resulting from the most recent use of the compiled pattern `p' by
166 the `onig_search' function.  Unlike `onig_nth_match', this
167 function returns the specified captured substring itself and not the
168 position of the substring. For this reason, the subject string of the
169 pattern is a required argument.
170
171 SEE ALSO
172  onig_new, onig_search, onig_nth_match
173
174--------------------------------------------------------------
175