1pcre_compile
2
3 SYNOPSIS
4  Compile a PCRE regular expression
5
6 USAGE
7  PCRE_Type pcre_compile (String_Type pattern [, Int_Type options])
8
9 DESCRIPTION
10 The `pcre_compile' function compiles a PCRE style regular expression
11 and returns the result.  The optional `options' argument may be used
12 to provide addition information affecting the compilation of the pattern.
13 Specifically, it is a bit-mapped value formed from the logical-or of zero
14 or more of the following symbolic constants:
15
16    PCRE_ANCHORED     Force the match to be at the start of a string
17    PCRE_CASELESS     Matches are to be case-insensitive
18    PCRE_DOLLAR_ENDONLY (See PCRE docs for more information)
19    PCRE_DOTALL       The dot pattern matches all characters
20    PCRE_EXTENDED     Ignore whitespace in the pattern
21    PCRE_EXTRA        (See PCRE docs for features this activates)
22    PCRE_MULTILINE    Treat the subject string as multi-lines
23    PCRE_UNGREEDY     Make the matches not greedy
24    PCRE_UTF8         Regard the pattern and subject strings as UTF-8
25
26 Many of these flags may be set within the pattern itself.   See the PCRE
27 library documentation for more information about the precise details
28 of these flags and the supported regular expressions.
29
30 Upon success, this function returns a PCRE_Type object representing
31 the compiled patterned.  If compilation fails, a `ParseError'
32 exception will be thrown.
33
34 SEE ALSO
35  pcre_exec, pcre_nth_match, pcre_nth_substr, pcre_matches
36
37--------------------------------------------------------------
38
39pcre_exec
40
41 SYNOPSIS
42  Match a string against a compiled PCRE pattern
43
44 USAGE
45  Int_Type pcre_exec(p, str [,pos [,options]]);
46
47   PCRE_Type p;
48   String_Type str;
49   Int_Type pos, options;
50
51
52 DESCRIPTION
53 The `pcre_exec' function applies a pre-compiled pattern `p' to a
54 string `str' and returns the result of the match.  The optional third
55 argument `pos' may be used to specify the point, as an offset from the
56 start of the string, where matching is to start.  The fourth argument, if
57 present, may be used to provide additional information about how matching
58 is to take place.  Its value may be specified as a logical-or of zero or
59 more of the following flags:
60
61   PCRE_NOTBOL
62        The first character in the string is not at the beginning of a line.
63   PCRE_NOTEOL
64        The last character in the string is not at the end of a line.
65   PCRE_NOTEMPTY
66        An empty string is not a valid match.
67
68 See the PCRE library documentation for more information about the meaning
69 of these flags.
70
71 Upon success, this function returns a positive integer equal to 1 plus the
72 number of so-called captured substrings.  It returns 0 if the pattern
73 fails to match the string.
74
75 SEE ALSO
76  pcre_compile, pcre_nth_match, pcre_nth_substr, pcre_matches
77
78--------------------------------------------------------------
79
80pcre_matches
81
82 SYNOPSIS
83  Match a PCRE to a string and return the matches
84
85 USAGE
86  String_Type[] = pcre_matches (regexp, str [,pcre_exec_options])
87
88 DESCRIPTION
89  This function combines the `pcre_exec' and
90 `pcre_nth_substr' functions into simple to use function that
91 matches the specified regular expression `regexp' to the string
92 `string' and returns matched substrings as an array.  If
93 `regexp' is a string, the function will first compile the
94 pattern using the `pcre_compile' function.  The third parameter
95 is optional and, if provided, will be passed as the `options'
96 parameter to `pcre_exec'.
97
98 If no match is found, the function will return NULL.
99
100 QUALIFIERS
101 The following qualifiers are supported:
102
103   options=int        Options to pass to pcre_compile
104   offset=int         Start matching offset in bytes for pcre_exec
105
106
107 EXAMPLE
108 After the execution of:
109
110    str = "Error in file foo.c, line 127, column 10";
111    pattern = "file ([^,]+), line (\\d+)";
112    matches = pcre_matches (pattern, str);
113
114 the value of the matches variable will be the array:
115
116    [ "file foo.c, line 127",
117      "foo.c",
118      127
119    ]
120
121
122 SEE ALSO
123  pcre_compile, pcre_exec, pcre_nth_substr, pcre_nth_match
124
125--------------------------------------------------------------
126
127pcre_nth_match
128
129 SYNOPSIS
130  Return the location of the nth match of a PCRE
131
132 USAGE
133  Int_Type[2] pcre_nth_match (PCRE_Type p, Int_Type nth)
134
135 DESCRIPTION
136 The `pcre_nth_match' function returns an integer array whose values
137 specify the locations of the beginning and end of the `nth' captured
138 substrings of the most recent call to `pcre_exec' with the compiled
139 pattern.  A value of `nth' equal to 0 represents the substring
140 representing the entire match of the pattern.
141
142 If the `nth' match did not take place, the function returns NULL.
143
144 EXAMPLE
145 After the execution of:
146
147    str = "Error in file foo.c, line 127, column 10";
148    pattern = "file ([^,]+), line (\\d+)";
149    p = pcre_compile (pattern);
150    if (pcre_exec (p, str))
151      {
152         match_pos = pcre_nth_match (p, 0);
153         file_pos = pcre_nth_match (p, 1);
154         line_pos = pcre_nth_match (p, 2);
155      }
156
157 `match_pos' will be set to `[9,29]', `file_pos' to `[14,19,]'
158 and `line_pos' to `[26,29]'.  These integer arrays may be used to
159 extract the substrings matched by the pattern, e.g.,
160
161     file = substr (str, file_pos[0]+1, file_pos[1]-file_pos[0]);
162     line = str[[line_pos[0]:line_pos[1]-1]];
163
164 Alternatively, the function `pcre_nth_substr' may be used to get the
165 matched substrings:
166
167     file = pcre_nth_substr (p, str, 0);
168
169
170 SEE ALSO
171  pcre_compile, pcre_exec, pcre_nth_substr, pcre_matches
172
173--------------------------------------------------------------
174
175pcre_nth_substr
176
177 SYNOPSIS
178  Extract the nth substring from a PCRE match
179
180 USAGE
181  String_Type pcre_nth_substr (PCRE_Type p, String_Type str, Int_Type nth)
182
183 DESCRIPTION
184 This function may be used to extract the `nth' captured substring
185 resulting from the most recent use of the compiled pattern `p' by the
186 `pcre_exec' function.  Unlike `pcre_nth_match', this function returns
187 the specified captured substring itself and not the position of the substring.
188 For this reason, the subject string of the pattern is a required argument.
189
190 SEE ALSO
191  pcre_matches, pcre_compile, pcre_exec, pcre_nth_match
192
193--------------------------------------------------------------
194
195slang_to_pcre
196
197 SYNOPSIS
198  Convert a S-Lang regular expression to a PCRE one
199
200 USAGE
201  String_Type slang_to_pcre (String_Type pattern)
202
203 DESCRIPTION
204 This function may be used to convert a slang regular expression to a PCRE
205 compatible one.  The converted pattern is returned.
206
207 SEE ALSO
208  pcre_compile, string_match
209
210--------------------------------------------------------------
211