NAME

       PCRE2 - Perl-compatible regular expressions (revised API)

EXPERIMENTAL PATTERN CONVERSION FUNCTIONS

       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.

THE CONVERT CONTEXT

       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.

THE CONVERSION FUNCTION

       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:

         PCRE2_CONVERT_GLOB
         PCRE2_CONVERT_GLOB_NO_WILD_SEPARATOR
         PCRE2_CONVERT_GLOB_NO_STARSTAR
         PCRE2_CONVERT_POSIX_BASIC
         PCRE2_CONVERT_POSIX_EXTENDED

       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().

CONVERTING GLOBS

       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.

CONVERTING POSIX PATTERNS

       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).

AUTHOR

       Philip Hazel
       University Computing Service
       Cambridge, England.

REVISION

       Last updated: 28 June 2018
       Copyright (c) 1997-2018 University of Cambridge.

PCRE2 10.32                                       28 June 2018                                   PCRE2CONVERT(3)