Home

Awesome

Effcee

Effcee is a C++ library for stateful pattern matching of strings, inspired by LLVM's FileCheck command.

Effcee:

Example

The following is from examples/main.cc:


    #include <iostream>
    #include <sstream>

    #include "effcee/effcee.h"

    // Checks standard input against the list of checks provided as command line
    // arguments.
    //
    // Example:
    //    cat <<EOF >sample_data.txt
    //    Bees
    //    Make
    //    Delicious Honey
    //    EOF
    //    effcee-example <sample_data.txt "CHECK: Bees" "CHECK-NOT:Sting" "CHECK: Honey"
    int main(int argc, char* argv[]) {
      // Read the command arguments as a list of check rules.
      std::ostringstream checks_stream;
      for (int i = 1; i < argc; ++i) {
        checks_stream << argv[i] << "\n";
      }
      // Read stdin as the input to match.
      std::stringstream input_stream;
      std::cin >> input_stream.rdbuf();

      // Attempt to match.  The input and checks arguments can be provided as
      // std::string or pointer to char.
      auto result = effcee::Match(input_stream.str(), checks_stream.str(),
                                  effcee::Options().SetChecksName("checks"));

      // Successful match result converts to true.
      if (result) {
        std::cout << "The input matched your check list!" << std::endl;
      } else {
        // Otherwise, you can get a status code and a detailed message.
        switch (result.status()) {
          case effcee::Result::Status::NoRules:
            std::cout << "error: Expected check rules as command line arguments\n";
            break;
          case effcee::Result::Status::Fail:
            std::cout << "The input failed to match your check rules:\n";
            break;
          default:
            break;
        }
        std::cout << result.message() << std::endl;
        return 1;
      }
      return 0;
    }

For more examples, see the matching tests in effcee/match_test.cc.

Status

Effcee is mature enough to be relied upon by third party projects, but could be improved.

What works:

What is left to do:

What is left to do, but lower priority:

Licensing and contributing

Effcee is licensed under terms of the Apache 2.0 license. If you are interested in contributing to this project, please see CONTRIBUTING.md.

This is not an official Google product (experimental or otherwise), it is just code that happens to be owned by Google. That may change if Effcee gains contributions from others. See the CONTRIBUTING.md file for more information. See also the AUTHORS and CONTRIBUTORS files.

File organization

Effcee depends on:

Effcee tests depend on Googletest and Python 3.

In the following sections, $SOURCE_DIR is the directory containing the Effcee source code.

Getting and building Effcee

  1. Check out the source code:
git clone https://github.com/google/effcee $SOURCE_DIR
cd $SOURCE_DIR/third_party
git clone https://github.com/google/googletest.git
git clone https://github.com/google/re2.git
git clone https://github.com/abseil/abseil-cpp.git
cd $SOURCE_DIR/

Note: There are two other ways to manage third party sources:

  1. Ensure you have the requisite tools -- see the tools subsection below.

  2. Decide where to place the build output. In the following steps, we'll call it $BUILD_DIR. Any new directory should work. We recommend building outside the source tree, but it is also common to build in a (new) subdirectory of $SOURCE_DIR, such as $SOURCE_DIR/build.

4a) Build and test with Ninja on Linux or Windows:

cd $BUILD_DIR
cmake -GNinja -DCMAKE_BUILD_TYPE={Debug|Release|RelWithDebInfo} $SOURCE_DIR
ninja
ctest

4b) Or build and test with MSVC on Windows:

cd $BUILD_DIR
cmake $SOURCE_DIR
cmake --build . --config {Release|Debug|MinSizeRel|RelWithDebInfo}
ctest -C {Release|Debug|MinSizeRel|RelWithDebInfo}

4c) Or build with MinGW on Linux for Windows: (Skip building threaded unit tests due to Googletest bug 606)

cd $BUILD_DIR
cmake -GNinja -DCMAKE_BUILD_TYPE={Debug|Release|RelWithDebInfo} $SOURCE_DIR \
   -DCMAKE_TOOLCHAIN_FILE=$SOURCE_DIR/cmake/linux-mingw-toolchain.cmake \
   -Dgtest_disable_pthreads=ON
ninja

4d) Or build with Bazel on Linux:

cd $SOURCE_DIR
bazel build -c opt :all

After a successful build, you should have a libeffcee library under the $BUILD_DIR/effcee/ directory (or $SOURCE_DIR/bazel-bin when building with Bazel).

The default behavior on MSVC is to link with the static CRT. If you would like to change this behavior -DEFFCEE_ENABLE_SHARED_CRT may be passed on the cmake configure line.

Tests

By default, Effcee registers two tests with ctest:

Running ctest without arguments will run the tests for Effcee as well as for RE2.

You can disable Effcee's tests by using -DEFFCEE_BUILD_TESTING=OFF at configuration time:

cmake -GNinja -DEFFCEE_BUILD_TESTING=OFF ...

The RE2 tests run much longer, so if you're working on Effcee alone, we suggest limiting ctest to tests with prefix effcee:

ctest -R effcee

Alternately, you can turn off RE2 tests entirely by using -DRE2_BUILD_TESTING=OFF at configuration time:

cmake -GNinja -DRE2_BUILD_TESTING=OFF ...

Tools you'll need

For building, testing, and profiling Effcee, the following tools should be installed regardless of your OS:

On Linux, if cross compiling to Windows: - MinGW: A GCC-based cross compiler targeting Windows so that generated executables use the Microsoft C runtime libraries.

On Windows, the following tools should be installed and available on your path:

Build options

Third party source locations:

Compilation options:

Controlling samples and tests:

Bug tracking

We track bugs using GitHub -- click on the "Issues" button on the project's GitHub page.

What uses Effcee?

References