Awesome

Wildcards

Wildcards is a simple C++ header-only template library which implements a general purpose algorithm for matching using wildcards. It supports both runtime and compile time execution.

Basic usage

The following examples of the basic usage are functionaly equivalent.

#include <wildcards.hpp>

int main()
{
  {
    using wildcards::match;

    static_assert(match("Hello, World!", "H*World?"), "");
  }

  {
    using wildcards::make_matcher;

    static_assert(make_matcher("H*World?").matches("Hello, World!"), "");
  }

  {
    using namespace wildcards::literals;

    static_assert("H*World?"_wc.matches("Hello, World!"), "");
  }

  return 0;
}

Advanced usage

The following examples of the advanced usage are functionaly equivalent.

#include <wildcards.hpp>

int main()
{
  {
    using wildcards::match;

    static_assert(match("Hello, World!", "H%World_", {'%', '_', '\\'}), "");
  }

  {
    using wildcards::make_matcher;

    static_assert(make_matcher("H%World_", {'%', '_', '\\'}).matches("Hello, World!"), "");
  }

  return 0;
}

See more useful and complex examples and try them online! See also the tests to learn more.

Demonstration on Compiler Explorer

Check compilers output of the following example on Compiler Explorer.

#include <wildcards.hpp>

using namespace wildcards::literals;

constexpr auto pattern = "*.[hc](pp|)"_wc;

// returns true
bool test1()
{
  constexpr auto res = pattern.matches("source.c");

  static_assert(res, "must be true");

  return res;
}

// returns false
bool test2()
{
  constexpr auto res = pattern.matches("source.cc");

  static_assert(!res, "must be false");

  return res;
}

Integration

1. Single-header approach

   • Copy wildcards.hpp from single_include directory to your project's header search path.
   • Add #include <wildcards.hpp> to your source file.
   • Use wildcards::match() or wildcards::make_matcher(). You can also use operator ""_wc from wildcards::literals namespace.

2. Multi-header approach

   • Add include directory to your project's header search path.
   • Add #include <wildcards.hpp> to your source file.
   • Use wildcards::match() or wildcards::make_matcher(). You can also use operator ""_wc from wildcards::literals namespace.

Portability

The library requires at least a C++11 compiler to build. It has no external dependencies.

The following compilers are continuously tested at Travis CI and Appveyor CI.

License

This project is licensed under the Boost 1.0.

Details

Syntax

• Set cannot be empty. Any special character loses its special meaning in it.
• Alternative can contain more than two or just one sequence.
• The use of Sets and Alternatives can be switched off.
• Special characters are predefined for char, char16_t, char32_t and wchar_t, but can be redefined.

Technical Notes

• Wildcards depends on two components which originate from external sources and were made part of the repository:

  • cpp_feature.hpp taken from here,
  • catch.hpp taken from here.

• Wildcards uses a recursive approach. Hence you can simply run out of stack (during runtime execution) or you can exceed the maximum depth of constexpr evaluation (during compile time execution). If so, try making the input sequence shorter or the pattern less complex. You can also try to build using the C++14 standard since the C++14 implementation of the library is more effective and consumes less resources.

• Place more specific sequences in Alternatives first. This becomes important when Alternatives are nested. E.g. match("source.cpp", "(*.[hc](pp|))") will work as expected but match("source.cpp", "(*.[hc](|pp))") will not. Fixing that would make Wildcards unreasonably complex.

• The cx library is a byproduct created during the development of Wildcards which uses some pieces from its functionality internally. More of the cx is used in tests and examples. You can use this library in exactly the same way as you use Wildcards (single-header / multi-header approach) but if you are interested only in Wildcards, you don't need to care about the cx at all. This library might become a separate project in the future.