Skip to content

Commit a23715d

Browse files
PhilipHazelPhilipHazel
committed
Document experimental pattern conversion functions and remove unimplemented
features.
1 parent 4f7a608 commit a23715d

32 files changed

+1235
-81
lines changed

‎ChangeLog‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -216,6 +216,9 @@ unit". Previously only non-anchored patterns did this.
216216
49. Update extended grapheme breaking rules to the latest set that are in
217217
Unicode Standard Annex #29.
218218

219+
50. Added experimental foreign pattern conversion facilities
220+
(pcre2_pattern_convert() and friends).
221+
219222

220223
Version 10.23 14-February-2017
221224
------------------------------

‎Makefile.am‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,10 @@ dist_html_DATA = \
3636
doc/html/pcre2_compile_context_create.html \
3737
doc/html/pcre2_compile_context_free.html \
3838
doc/html/pcre2_config.html \
39+
doc/html/pcre2_convert_context_copy.html \
40+
doc/html/pcre2_convert_context_create.html \
41+
doc/html/pcre2_convert_context_free.html \
42+
doc/html/pcre2_converted_pattern_free.html \
3943
doc/html/pcre2_dfa_match.html \
4044
doc/html/pcre2_general_context_copy.html \
4145
doc/html/pcre2_general_context_create.html \
@@ -59,6 +63,7 @@ dist_html_DATA = \
5963
doc/html/pcre2_match_data_create.html \
6064
doc/html/pcre2_match_data_create_from_pattern.html \
6165
doc/html/pcre2_match_data_free.html \
66+
doc/html/pcre2_pattern_convert.html \
6267
doc/html/pcre2_pattern_info.html \
6368
doc/html/pcre2_serialize_decode.html \
6469
doc/html/pcre2_serialize_encode.html \
@@ -70,6 +75,8 @@ dist_html_DATA = \
7075
doc/html/pcre2_set_compile_extra_options.html \
7176
doc/html/pcre2_set_compile_recursion_guard.html \
7277
doc/html/pcre2_set_depth_limit.html \
78+
doc/html/pcre2_set_glob_escape.html \
79+
doc/html/pcre2_set_glob_separator.html \
7380
doc/html/pcre2_set_heap_limit.html \
7481
doc/html/pcre2_set_match_limit.html \
7582
doc/html/pcre2_set_max_pattern_length.html \
@@ -94,6 +101,7 @@ dist_html_DATA = \
94101
doc/html/pcre2build.html \
95102
doc/html/pcre2callout.html \
96103
doc/html/pcre2compat.html \
104+
doc/html/pcre2convert.html \
97105
doc/html/pcre2demo.html \
98106
doc/html/pcre2grep.html \
99107
doc/html/pcre2jit.html \
@@ -121,6 +129,10 @@ dist_man_MANS = \
121129
doc/pcre2_compile_context_create.3 \
122130
doc/pcre2_compile_context_free.3 \
123131
doc/pcre2_config.3 \
132+
doc/pcre2_convert_context_copy.3 \
133+
doc/pcre2_convert_context_create.3 \
134+
doc/pcre2_convert_context_free.3 \
135+
doc/pcre2_converted_pattern_free.3 \
124136
doc/pcre2_dfa_match.3 \
125137
doc/pcre2_general_context_copy.3 \
126138
doc/pcre2_general_context_create.3 \
@@ -144,6 +156,7 @@ dist_man_MANS = \
144156
doc/pcre2_match_data_create.3 \
145157
doc/pcre2_match_data_create_from_pattern.3 \
146158
doc/pcre2_match_data_free.3 \
159+
doc/pcre2_pattern_convert.3 \
147160
doc/pcre2_pattern_info.3 \
148161
doc/pcre2_serialize_decode.3 \
149162
doc/pcre2_serialize_encode.3 \
@@ -155,6 +168,8 @@ dist_man_MANS = \
155168
doc/pcre2_set_compile_extra_options.3 \
156169
doc/pcre2_set_compile_recursion_guard.3 \
157170
doc/pcre2_set_depth_limit.3 \
171+
doc/pcre2_set_glob_escape.3 \
172+
doc/pcre2_set_glob_separator.3 \
158173
doc/pcre2_set_heap_limit.3 \
159174
doc/pcre2_set_match_limit.3 \
160175
doc/pcre2_set_max_pattern_length.3 \
@@ -179,6 +194,7 @@ dist_man_MANS = \
179194
doc/pcre2build.3 \
180195
doc/pcre2callout.3 \
181196
doc/pcre2compat.3 \
197+
doc/pcre2convert.3 \
182198
doc/pcre2demo.3 \
183199
doc/pcre2grep.1 \
184200
doc/pcre2jit.3 \

‎doc/html/index.html‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,9 @@ <h1>Perl-compatible Regular Expressions (revised API: PCRE2)</h1>
3535
<tr><td><a href="pcre2compat.html">pcre2compat</a></td>
3636
<td>&nbsp;&nbsp;Compability with Perl</td></tr>
3737

38+
<tr><td><a href="pcre2convert.html">pcre2convert</a></td>
39+
<td>&nbsp;&nbsp;Experimental foreign pattern conversion functions</td></tr>
40+
3841
<tr><td><a href="pcre2demo.html">pcre2demo</a></td>
3942
<td>&nbsp;&nbsp;A demonstration C program that uses the PCRE2 library</td></tr>
4043

@@ -112,6 +115,18 @@ <h1>Perl-compatible Regular Expressions (revised API: PCRE2)</h1>
112115
<tr><td><a href="pcre2_config.html">pcre2_config</a></td>
113116
<td>&nbsp;&nbsp;Show build-time configuration options</td></tr>
114117

118+
<tr><td><a href="pcre2_convert_context_copy.html">pcre2_convert_context_copy</a></td>
119+
<td>&nbsp;&nbsp;Copy a convert context</td></tr>
120+
121+
<tr><td><a href="pcre2_convert_context_create.html">pcre2_convert_context_create</a></td>
122+
<td>&nbsp;&nbsp;Create a convert context</td></tr>
123+
124+
<tr><td><a href="pcre2_convert_context_free.html">pcre2_convert_context_free</a></td>
125+
<td>&nbsp;&nbsp;Free a convert context</td></tr>
126+
127+
<tr><td><a href="pcre2_converted_pattern_free.html">pcre2_converted_pattern_free</a></td>
128+
<td>&nbsp;&nbsp;Free converted foreign pattern</td></tr>
129+
115130
<tr><td><a href="pcre2_dfa_match.html">pcre2_dfa_match</a></td>
116131
<td>&nbsp;&nbsp;Match a compiled pattern to a subject string
117132
(DFA algorithm; <i>not</i> Perl compatible)</td></tr>
@@ -183,6 +198,9 @@ <h1>Perl-compatible Regular Expressions (revised API: PCRE2)</h1>
183198
<tr><td><a href="pcre2_match_data_free.html">pcre2_match_data_free</a></td>
184199
<td>&nbsp;&nbsp;Free a match data block</td></tr>
185200

201+
<tr><td><a href="pcre2_pattern_convert.html">pcre2_pattern_convert</a></td>
202+
<td>&nbsp;&nbsp;Experimental foreign pattern converter</td></tr>
203+
186204
<tr><td><a href="pcre2_pattern_info.html">pcre2_pattern_info</a></td>
187205
<td>&nbsp;&nbsp;Extract information about a pattern</td></tr>
188206

@@ -216,6 +234,12 @@ <h1>Perl-compatible Regular Expressions (revised API: PCRE2)</h1>
216234
<tr><td><a href="pcre2_set_depth_limit.html">pcre2_set_depth_limit</a></td>
217235
<td>&nbsp;&nbsp;Set the match backtracking depth limit</td></tr>
218236

237+
<tr><td><a href="pcre2_set_glob_escape.html">pcre2_set_glob_escape</a></td>
238+
<td>&nbsp;&nbsp;Set glob escape character</td></tr>
239+
240+
<tr><td><a href="pcre2_set_glob_separator.html">pcre2_set_glob_separator</a></td>
241+
<td>&nbsp;&nbsp;Set glob separator character</td></tr>
242+
219243
<tr><td><a href="pcre2_set_heap_limit.html">pcre2_set_heap_limit</a></td>
220244
<td>&nbsp;&nbsp;Set the match backtracking heap limit</td></tr>
221245

‎doc/html/pcre2_convert_context_copy.html‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
<html>
2+
<head>
3+
<title>pcre2_convert_context_copy specification</title>
4+
</head>
5+
<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
6+
<h1>pcre2_convert_context_copy man page</h1>
7+
<p>
8+
Return to the <a href="index.html">PCRE2 index page</a>.
9+
</p>
10+
<p>
11+
This page is part of the PCRE2 HTML documentation. It was generated
12+
automatically from the original man page. If there is any nonsense in it,
13+
please consult the man page, in case the conversion went wrong.
14+
<br>
15+
<br><b>
16+
SYNOPSIS
17+
</b><br>
18+
<P>
19+
<b>#include &#60;pcre2.h&#62;</b>
20+
</P>
21+
<P>
22+
<b>pcre2_convert_context *pcre2_convert_context_copy(</b>
23+
<b> pcre2_convert_context *<i>cvcontext</i>);</b>
24+
</P>
25+
<br><b>
26+
DESCRIPTION
27+
</b><br>
28+
<P>
29+
This function is part of an experimental set of pattern conversion functions.
30+
It makes a new copy of a convert context, using the memory allocation function
31+
that was used for the original context. The result is NULL if the memory cannot
32+
be obtained.
33+
</P>
34+
<P>
35+
The pattern conversion functions are described in the
36+
<a href="pcre2convert.html"><b>pcre2convert</b></a>
37+
documentation.
38+
<p>
39+
Return to the <a href="index.html">PCRE2 index page</a>.
40+
</p>

‎doc/html/pcre2_convert_context_create.html‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
<html>
2+
<head>
3+
<title>pcre2_convert_context_create specification</title>
4+
</head>
5+
<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
6+
<h1>pcre2_convert_context_create man page</h1>
7+
<p>
8+
Return to the <a href="index.html">PCRE2 index page</a>.
9+
</p>
10+
<p>
11+
This page is part of the PCRE2 HTML documentation. It was generated
12+
automatically from the original man page. If there is any nonsense in it,
13+
please consult the man page, in case the conversion went wrong.
14+
<br>
15+
<br><b>
16+
SYNOPSIS
17+
</b><br>
18+
<P>
19+
<b>#include &#60;pcre2.h&#62;</b>
20+
</P>
21+
<P>
22+
<b>pcre2_convert_context *pcre2_convert_context_create(</b>
23+
<b> pcre2_general_context *<i>gcontext</i>);</b>
24+
</P>
25+
<br><b>
26+
DESCRIPTION
27+
</b><br>
28+
<P>
29+
This function is part of an experimental set of pattern conversion functions.
30+
It creates and initializes a new convert context. If its argument is
31+
NULL, <b>malloc()</b> is used to get the necessary memory; otherwise the memory
32+
allocation function within the general context is used. The result is NULL if
33+
the memory could not be obtained.
34+
</P>
35+
<P>
36+
The pattern conversion functions are described in the
37+
<a href="pcre2convert.html"><b>pcre2convert</b></a>
38+
documentation.
39+
<p>
40+
Return to the <a href="index.html">PCRE2 index page</a>.
41+
</p>

‎doc/html/pcre2_convert_context_free.html‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
<html>
2+
<head>
3+
<title>pcre2_convert_context_free specification</title>
4+
</head>
5+
<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
6+
<h1>pcre2_convert_context_free man page</h1>
7+
<p>
8+
Return to the <a href="index.html">PCRE2 index page</a>.
9+
</p>
10+
<p>
11+
This page is part of the PCRE2 HTML documentation. It was generated
12+
automatically from the original man page. If there is any nonsense in it,
13+
please consult the man page, in case the conversion went wrong.
14+
<br>
15+
<br><b>
16+
SYNOPSIS
17+
</b><br>
18+
<P>
19+
<b>#include &#60;pcre2.h&#62;</b>
20+
</P>
21+
<P>
22+
<b>void pcre2_convert_context_free(pcre2_convert_context *<i>cvcontext</i>);</b>
23+
</P>
24+
<br><b>
25+
DESCRIPTION
26+
</b><br>
27+
<P>
28+
This function is part of an experimental set of pattern conversion functions.
29+
It frees the memory occupied by a convert context, using the memory
30+
freeing function from the general context with which it was created, or
31+
<b>free()</b> if that was not set.
32+
</P>
33+
<P>
34+
The pattern conversion functions are described in the
35+
<a href="pcre2convert.html"><b>pcre2convert</b></a>
36+
documentation.
37+
<p>
38+
Return to the <a href="index.html">PCRE2 index page</a>.
39+
</p>

‎doc/html/pcre2_converted_pattern_free.html‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
<html>
2+
<head>
3+
<title>pcre2_converted_pattern_free specification</title>
4+
</head>
5+
<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
6+
<h1>pcre2_converted_pattern_free man page</h1>
7+
<p>
8+
Return to the <a href="index.html">PCRE2 index page</a>.
9+
</p>
10+
<p>
11+
This page is part of the PCRE2 HTML documentation. It was generated
12+
automatically from the original man page. If there is any nonsense in it,
13+
please consult the man page, in case the conversion went wrong.
14+
<br>
15+
<br><b>
16+
SYNOPSIS
17+
</b><br>
18+
<P>
19+
<b>#include &#60;pcre2.h&#62;</b>
20+
</P>
21+
<P>
22+
<b>void pcre2_converted_pattern_free(PCRE2_UCHAR *<i>converted_pattern</i>);</b>
23+
</P>
24+
<br><b>
25+
DESCRIPTION
26+
</b><br>
27+
<P>
28+
This function is part of an experimental set of pattern conversion functions.
29+
It frees the memory occupied by a converted pattern that was obtained by
30+
calling <b>pcre2_pattern_convert()</b> with arguments that caused it to place
31+
the converted pattern into newly obtained heap memory.
32+
</P>
33+
<P>
34+
The pattern conversion functions are described in the
35+
<a href="pcre2convert.html"><b>pcre2convert</b></a>
36+
documentation.
37+
<p>
38+
Return to the <a href="index.html">PCRE2 index page</a>.
39+
</p>

‎doc/html/pcre2_pattern_convert.html‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
<html>
2+
<head>
3+
<title>pcre2_pattern_convert specification</title>
4+
</head>
5+
<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
6+
<h1>pcre2_pattern_convert man page</h1>
7+
<p>
8+
Return to the <a href="index.html">PCRE2 index page</a>.
9+
</p>
10+
<p>
11+
This page is part of the PCRE2 HTML documentation. It was generated
12+
automatically from the original man page. If there is any nonsense in it,
13+
please consult the man page, in case the conversion went wrong.
14+
<br>
15+
<br><b>
16+
SYNOPSIS
17+
</b><br>
18+
<P>
19+
<b>#include &#60;pcre2.h&#62;</b>
20+
</P>
21+
<P>
22+
<b>int pcre2_pattern_convert(PCRE2_SPTR <i>pattern</i>, PCRE2_SIZE <i>length</i>,</b>
23+
<b> uint32_t <i>options</i>, PCRE2_UCHAR **<i>buffer</i>,</b>
24+
<b> PCRE2_SIZE *<i>blength</i>, pcre2_convert_context *<i>cvcontext</i>);</b>
25+
</P>
26+
<br><b>
27+
DESCRIPTION
28+
</b><br>
29+
<P>
30+
This function is part of an experimental set of pattern conversion functions.
31+
It converts a foreign pattern (for example, a glob) into a PCRE2 regular
32+
expression pattern. Its arguments are:
33+
<pre>
34+
<i>pattern</i> The foreign pattern
35+
<i>length</i> The length of the input pattern or PCRE2_ZERO_TERMINATED
36+
<i>options</i> Option bits
37+
<i>buffer</i> Pointer to pointer to output buffer, or NULL
38+
<i>blength</i> Pointer to output length field
39+
<i>cvcontext</i> Pointer to a convert context or NULL
40+
</pre>
41+
The length of the converted pattern (excluding the terminating zero) is
42+
returned via <i>blength</i>. If <i>buffer</i> is NULL, the function just returns
43+
the output length. If <i>buffer</i> points to a NULL pointer, heap memory is
44+
obtained for the converted pattern, using the allocator in the context if
45+
present (or else <b>malloc()</b>), and the field pointed to by <i>buffer</i> is
46+
updated. If <i>buffer</i> points to a non-NULL field, that must point to a
47+
buffer whose size is in the variable pointed to by <i>blength</i>. This value is
48+
updated.
49+
</P>
50+
<P>
51+
The option bits are:
52+
<pre>
53+
PCRE2_CONVERT_UTF Input is UTF
54+
PCRE2_CONVERT_NO_UTF_CHECK Do not check UTF validity
55+
PCRE2_CONVERT_POSIX_BASIC Convert POSIX basic pattern
56+
PCRE2_CONVERT_POSIX_EXTENDED Convert POSIX extended pattern
57+
PCRE2_CONVERT_GLOB ) Convert
58+
PCRE2_CONVERT_GLOB_NO_WILD_SEPARATOR ) various types
59+
PCRE2_CONVERT_GLOB_NO_STARSTAR ) of glob
60+
</pre>
61+
The return value from <b>pcre2_pattern_convert()</b> is zero on success or a
62+
non-zero PCRE2 error code.
63+
</P>
64+
<P>
65+
The pattern conversion functions are described in the
66+
<a href="pcre2convert.html"><b>pcre2convert</b></a>
67+
documentation.
68+
<p>
69+
Return to the <a href="index.html">PCRE2 index page</a>.
70+
</p>

0 commit comments

Comments
 (0)