regex_utils library

This library contains useful utilities to handle all regex related tasks.

Regex to Wildcard Translator

Goal

Performs a best-effort translation to turn a regex string to an equivalent wildcard string.

CLP currently only recognizes three meta-characters in the wildcard syntax:

• ? Matches any single character

• * Matches zero or more characters

• \ Suppresses the special meaning of meta characters (including itself)

If the regex query can actually be expressed as a wildcard query only deploying the three metacharacters above, CLP should use the wildcard version.

Includes

• The translator function returns a Result<std::string, std::error_code> type, which can either contain a value or an error code.

To use the translator:

#include <regex_utils/regex_translation_utils.hpp>

using clp::regex_utils::regex_to_wildcard;

// Other code

auto result{regex_to_wildcard(wildcard_str)};
if (result.has_error()) {
    auto err_code{result.error()};
    // Handle error
} else {
    auto regex_str{result.value()};
    // Do things with the translated string
}

• To add custom configuration to the translator:

#include <regex_utils/RegexToWildcardTranslatorConfig.hpp>

RegexToWildcardTranslatorConfig config{true, false, /*...other booleans*/};
auto result{regex_to_wildcard(wildcard_str, config)};

// Same as above

For a detailed description on the options order and usage, see the Custom Configuration section.

Functionalities

• Wildcards

  • Turn . into ?

  • Turn .* into *

  • Turn .+ into ?*

  • E.g. abc.*def.ghi.+ will get translated to abc*def?ghi?*

• Metacharacter escape sequences

  • An escaped regex metacharacter is treated as a literal and appended to the wildcard output.

    • The list of characters that require escaping to have their special meanings suppressed is [\/^$.|?*+(){}.

    • Superfluous escape characters are ignored for the following characters: ],<>-_=!.

    • E.g. a\[\+b\-\_c-_d will get translated to a[+b-_c-_d

    • Note: generally, any non-alphanumeric character can be escaped to use it as a literal. The list this utils library supports is non-exhaustive and can be expanded when necessary.

  • For metacharacters shared by both syntaxes, keep the escape backslashes.

    • The list of characters that fall into this category is *?\. All wildcard metacharacters are also regex metacharacters.

    • E.g. a\*b\?c\\d will get translated to a\*b\?c\\d (no change)

  • Escape sequences with alphanumeric characters are disallowed.

    • E.g. Special utility escape sequences \Q, \E, \A etc. and back references \1 \2 etc. cannot be translated.

• Character set

  • Reduces a character set into a single character if possible.

    • A trivial character set containing a single character or a single escaped metacharacter.

      • E.g. [a] into a, [\^] into ^

    • If the case_insensitive_wildcard config is turned on, the translator can also reduce the case-insensitive style character set patterns into a single lowercase character:

      • E.g. [aA] into a, [Bb] into b, [xX][Yy][zZ] into xyz

Custom configuration

The RegexToWildcardTranslatorConfig class objects are currently immutable once instantiated. By default, all of the options are set to false.

The constructor takes the following option arguments in order:

• case_insensitive_wildcard: see Character set bullet point in the Functionalities section.

• add_prefix_suffix_wildcards: in the absence of regex anchors, add prefix or suffix wildcards so the query becomes a substring query.

  • E.g. info.*system gets translated into *info*system* which makes the original query a substring query.