...

<html>
<head>
<title>pcre2convert specification</title>
</head>
<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
<h1>pcre2convert man page</h1>

Return to the <a href="index.html">PCRE2 index page</a>.


This page is part of the PCRE2 HTML documentation. It was generated
automatically from the original man page. If there is any nonsense in it,
please consult the man page, in case the conversion went wrong.
 
<ul>
<li><a name="TOC1" href="#SEC1">EXPERIMENTAL PATTERN CONVERSION FUNCTIONS</a>
<li><a name="TOC2" href="#SEC2">THE CONVERT CONTEXT</a>
<li><a name="TOC3" href="#SEC3">THE CONVERSION FUNCTION</a>
<li><a name="TOC4" href="#SEC4">CONVERTING GLOBS</a>
<li><a name="TOC5" href="#SEC5">CONVERTING POSIX PATTERNS</a>
<li><a name="TOC6" href="#SEC6">AUTHOR</a>
<li><a name="TOC7" href="#SEC7">REVISION</a>
</ul>
 <a name="SEC1" href="#TOC1">EXPERIMENTAL PATTERN CONVERSION FUNCTIONS</a> 

This document describes a set of functions that can be used to convert
"foreign" patterns into PCRE2 regular expressions. This facility is currently
experimental, and may be changed in future releases. Two kinds of pattern,
globs and POSIX patterns, are supported.

 <a name="SEC2" href="#TOC1">THE CONVERT CONTEXT</a> 

pcre2_convert_context *pcre2_convert_context_create(
 pcre2_general_context *gcontext);
 
 
pcre2_convert_context *pcre2_convert_context_copy(
 pcre2_convert_context *cvcontext);
 
 
void pcre2_convert_context_free(pcre2_convert_context *cvcontext);
 
 
int pcre2_set_glob_escape(pcre2_convert_context *cvcontext,
 uint32_t escape_char);
 
 
int pcre2_set_glob_separator(pcre2_convert_context *cvcontext,
 uint32_t separator_char);
 
 
A convert context is used to hold parameters that affect the way that pattern
conversion works. Like all PCRE2 contexts, you need to use a context only if
you want to override the defaults. There are the usual create, copy, and free
functions. If custom memory management functions are set in a general context
that is passed to pcre2_convert_context_create(), they are used for all
memory management within the conversion functions.


There are only two parameters in the convert context at present. Both apply
only to glob conversions. The escape character defaults to grave accent under
Windows, otherwise backslash. It can be set to zero, meaning no escape
character, or to any punctuation character with a code point less than 256.
The separator character defaults to backslash under Windows, otherwise forward
slash. It can be set to forward slash, backslash, or dot.


The two setting functions return zero on success, or PCRE2_ERROR_BADDATA if
their second argument is invalid.

 <a name="SEC3" href="#TOC1">THE CONVERSION FUNCTION</a> 

int pcre2_pattern_convert(PCRE2_SPTR pattern, PCRE2_SIZE length,
 uint32_t options, PCRE2_UCHAR **buffer,
 PCRE2_SIZE *blength, pcre2_convert_context *cvcontext);
 
 
void pcre2_converted_pattern_free(PCRE2_UCHAR *converted_pattern);
 
 
The first two arguments of pcre2_pattern_convert() define the foreign
pattern that is to be converted. The length may be given as
PCRE2_ZERO_TERMINATED. The options argument defines how the pattern is to
be processed. If the input is UTF, the PCRE2_CONVERT_UTF option should be set.
PCRE2_CONVERT_NO_UTF_CHECK may also be set if you are sure the input is valid.
One or more of the glob options, or one of the following POSIX options must be
set to define the type of conversion that is required:
<pre>
 PCRE2_CONVERT_GLOB
 PCRE2_CONVERT_GLOB_NO_WILD_SEPARATOR
 PCRE2_CONVERT_GLOB_NO_STARSTAR
 PCRE2_CONVERT_POSIX_BASIC
 PCRE2_CONVERT_POSIX_EXTENDED
</pre>
Details of the conversions are given below. The buffer and blength
arguments define how the output is handled:


If buffer is NULL, the function just returns the length of the converted
pattern via blength. This is one less than the length of buffer needed,
because a terminating zero is always added to the output.


If buffer points to a NULL pointer, an output buffer is obtained using
the allocator in the context or malloc() if no context is supplied. A
pointer to this buffer is placed in the variable to which buffer points.
When no longer needed the output buffer must be freed by calling
pcre2_converted_pattern_free(). If this function is called with a NULL
argument, it returns immediately without doing anything.


If buffer points to a non-NULL pointer, blength must be set to the
actual length of the buffer provided (in code units).


In all cases, after successful conversion, the variable pointed to by
blength is updated to the length actually used (in code units), excluding
the terminating zero that is always added.


If an error occurs, the length (via blength) is set to the offset
within the input pattern where the error was detected. Only gross syntax errors
are caught; there are plenty of errors that will get passed on for
pcre2_compile() to discover.


The return from pcre2_pattern_convert() is zero on success or a non-zero
PCRE2 error code. Note that PCRE2 error codes may be positive or negative:
pcre2_compile() uses mostly positive codes and pcre2_match()
negative ones; pcre2_convert() uses existing codes of both kinds. A
textual error message can be obtained by calling
pcre2_get_error_message().

 <a name="SEC4" href="#TOC1">CONVERTING GLOBS</a> 

Globs are used to match file names, and consequently have the concept of a
"path separator", which defaults to backslash under Windows and forward slash
otherwise. If PCRE2_CONVERT_GLOB is set, the wildcards * and ? are not
permitted to match separator characters, but the double-star (**) feature
(which does match separators) is supported.


PCRE2_CONVERT_GLOB_NO_WILD_SEPARATOR matches globs with wildcards allowed to
match separator characters. PCRE2_CONVERT_GLOB_NO_STARSTAR matches globs with
the double-star feature disabled. These options may be given together.

 <a name="SEC5" href="#TOC1">CONVERTING POSIX PATTERNS</a> 

POSIX defines two kinds of regular expression pattern: basic and extended.
These can be processed by setting PCRE2_CONVERT_POSIX_BASIC or
PCRE2_CONVERT_POSIX_EXTENDED, respectively.


In POSIX patterns, backslash is not special in a character class. Unmatched
closing parentheses are treated as literals.


In basic patterns, ? + | {} and () must be escaped to be recognized
as metacharacters outside a character class. If the first character in the
pattern is * it is treated as a literal. ^ is a metacharacter only at the start
of a branch.


In extended patterns, a backslash not in a character class always
makes the next character literal, whatever it is. There are no backreferences.


Note: POSIX mandates that the longest possible match at the first matching
position must be found. This is not what pcre2_match() does; it yields
the first match that is found. An application can use pcre2_dfa_match()
to find the longest match, but that does not support backreferences (but then
neither do POSIX extended patterns).

 <a name="SEC6" href="#TOC1">AUTHOR</a> 

Philip Hazel
 
University Computing Service
 
Cambridge, England.
 

 <a name="SEC7" href="#TOC1">REVISION</a> 

Last updated: 28 June 2018
 
Copyright &copy; 1997-2018 University of Cambridge.
 

Return to the <a href="index.html">PCRE2 index page</a>.

.	Edit
..	Edit
NON-AUTOTOOLS-BUILD.txt	Edit
README.txt	Edit
index.html	Edit
pcre2-config.html	Edit
pcre2.html	Edit
pcre2_callout_enumerate.html	Edit
pcre2_code_copy.html	Edit
pcre2_code_copy_with_tables.html	Edit
pcre2_code_free.html	Edit
pcre2_compile.html	Edit
pcre2_compile_context_copy.html	Edit
pcre2_compile_context_create.html	Edit
pcre2_compile_context_free.html	Edit
pcre2_config.html	Edit
pcre2_convert_context_copy.html	Edit
pcre2_convert_context_create.html	Edit
pcre2_convert_context_free.html	Edit
pcre2_converted_pattern_free.html	Edit
pcre2_dfa_match.html	Edit
pcre2_general_context_copy.html	Edit
pcre2_general_context_create.html	Edit
pcre2_general_context_free.html	Edit
pcre2_get_error_message.html	Edit
pcre2_get_mark.html	Edit
pcre2_get_match_data_size.html	Edit
pcre2_get_ovector_count.html	Edit
pcre2_get_ovector_pointer.html	Edit
pcre2_get_startchar.html	Edit
pcre2_jit_compile.html	Edit
pcre2_jit_free_unused_memory.html	Edit
pcre2_jit_match.html	Edit
pcre2_jit_stack_assign.html	Edit
pcre2_jit_stack_create.html	Edit
pcre2_jit_stack_free.html	Edit
pcre2_maketables.html	Edit
pcre2_maketables_free.html	Edit
pcre2_match.html	Edit
pcre2_match_context_copy.html	Edit
pcre2_match_context_create.html	Edit
pcre2_match_context_free.html	Edit
pcre2_match_data_create.html	Edit
pcre2_match_data_create_from_pattern.html	Edit
pcre2_match_data_free.html	Edit
pcre2_pattern_convert.html	Edit
pcre2_pattern_info.html	Edit
pcre2_serialize_decode.html	Edit
pcre2_serialize_encode.html	Edit
pcre2_serialize_free.html	Edit
pcre2_serialize_get_number_of_codes.html	Edit
pcre2_set_bsr.html	Edit
pcre2_set_callout.html	Edit
pcre2_set_character_tables.html	Edit
pcre2_set_compile_extra_options.html	Edit
pcre2_set_compile_recursion_guard.html	Edit
pcre2_set_depth_limit.html	Edit
pcre2_set_glob_escape.html	Edit
pcre2_set_glob_separator.html	Edit
pcre2_set_heap_limit.html	Edit
pcre2_set_match_limit.html	Edit
pcre2_set_max_pattern_length.html	Edit
pcre2_set_newline.html	Edit
pcre2_set_offset_limit.html	Edit
pcre2_set_parens_nest_limit.html	Edit
pcre2_set_recursion_limit.html	Edit
pcre2_set_recursion_memory_management.html	Edit
pcre2_set_substitute_callout.html	Edit
pcre2_substitute.html	Edit
pcre2_substring_copy_byname.html	Edit
pcre2_substring_copy_bynumber.html	Edit
pcre2_substring_free.html	Edit
pcre2_substring_get_byname.html	Edit
pcre2_substring_get_bynumber.html	Edit
pcre2_substring_length_byname.html	Edit
pcre2_substring_length_bynumber.html	Edit
pcre2_substring_list_free.html	Edit
pcre2_substring_list_get.html	Edit
pcre2_substring_nametable_scan.html	Edit
pcre2_substring_number_from_name.html	Edit
pcre2api.html	Edit
pcre2build.html	Edit
pcre2callout.html	Edit
pcre2compat.html	Edit
pcre2convert.html	Edit
pcre2demo.html	Edit
pcre2grep.html	Edit
pcre2jit.html	Edit
pcre2limits.html	Edit
pcre2matching.html	Edit
pcre2partial.html	Edit
pcre2pattern.html	Edit
pcre2perform.html	Edit
pcre2posix.html	Edit
pcre2sample.html	Edit
pcre2serialize.html	Edit
pcre2syntax.html	Edit
pcre2test.html	Edit
pcre2unicode.html	Edit