DOCSEARCHbyAlgolia
Submit Docs

PCRE2 Documentation

repository·main·Indexed 23 days ago

https://github.com/pcre2project/pcre2

A highly portable, self-contained C library for Perl-Compatible Regular Expression pattern matching. PCRE2 supports Unicode, multiple character encodings (8-bit, 16-bit, and 32-bit), and provides three matching engines: a feature-rich Backtracking engine, a high-performance JIT (Just-In-Time) engine, and a DFA engine for worst-case polynomial matching time.

Tokens
62.6K
Snippets
58
Records
313
Agent score
74%

What's inside PCRE2

  2. Understanding PCRE2 matching engines

    main

    PCRE2 provides three distinct matching engines depending on your requirements:

    1. Backtracking Engine (Default): Uses a depth-first tree search with backtracking. It is highly feature-rich and supports the full Perl-style syntax. Because it can have worst-case exponential time, you can set a limit on the maximum number of steps to prevent excessive execution time.
    2. JIT (Just-In-Time) Engine: Compiles the regular expression into native machine code for significantly improved performance. This is an optional feature that requires fetching the Git submodule during installation.
    3. DFA Engine: Generally slower than the JIT engine but offers worst-case polynomial matching time. It is capable of finding the POSIX-style "leftmost-longest" match.

  3. Customize or generate character tables in PCRE2

    main

    PCRE2 uses four internal tables to identify and manipulate characters with code points less than 256. You can manage these in three ways:

    1. Dynamic Creation: Use pcre2_maketables() to create a new set of tables in the current locale at runtime. These tables are then passed to PCRE2 via pcre2_set_character_tables().
    2. Build-time Rebuilding: If you specify --enable-rebuild-chartables during ./configure, the pcre2_dftables program will build a new pcre2_chartables.c using the system's default C locale (via functions like isalnum(), isalpha(), etc.).
    3. Binary Tables: You can use pcre2_dftables with the -b flag to generate tables in binary format instead of C source code. These binary tables are hardware-endianness independent and can be bundled with your application and passed to pcre2_compile() just like dynamically created tables.

    To manually run pcre2_dftables with a specific locale using the -L option:

    ./pcre2_dftables -L pcre2_chartables.c.special output_file

  4. Handle partial matches with PCRE2_PARTIAL_SOFT and PCRE2_PARTIAL_HARD

    main

    Partial matching occurs when the end of the subject is reached before a complete match is found, but the pattern has already inspected characters or contains lookbehinds.

    • PCRE2_PARTIAL_SOFT: The matcher will continue to test other alternatives in the pattern. It only returns PCRE2_ERROR_PARTIAL if no complete match is possible.
    • PCRE2_PARTIAL_HARD: The matcher returns PCRE2_ERROR_PARTIAL immediately upon encountering a partial match, even if an alternative complete match might exist later. This overrides SOFT mode.

  5. Quickstart: Compile and run a PCRE2 demo

    main

    To verify your installation, you can compile and run a simple C demo. This example assumes you have built PCRE2 using CMake and have the build directory available.

    1. Create a demo.c file with the provided source code.
    2. Compile the demo, linking against lpcre2-8 and including the build directory for headers.
    3. Run the executable with a pattern and a subject string.

    Example Command:

    gcc -g -I./pcre2/build -L./pcre2/build demo.c -o demo -lpcre2-8
./demo 'c.t' 'dogs and cats'
    gcc -g -I./pcre2/build -L./pcre2/build demo.c -o demo -lpcre2-8
./demo 'c.t' 'dogs and cats'

  7. Build PCRE2 with custom character tables at build time

    main

    To ensure PCRE2 uses the character tables of your system's default locale instead of the default ASCII tables, use the --enable-rebuild-chartables flag with ./configure.

    If you want to provide your own custom tables, the recommended method is to move src/pcre2_chartables.c.dist out of the way and replace it with your customized version before building, to prevent the build process from automatically regenerating it.

  8. Install and build PCRE2

    main

    You can obtain PCRE2 via Git clone, downloading a release tarball, or using package managers like vcpkg.

    Important: If you use git clone, you must initialize the Git submodules to use the JIT matching engine.

    Building with CMake (Linux/Windows/macOS)

    cd pcre2/
cmake -B build .
cmake --build build/

    Building with Autoconf (Linux/Unix)

    cd pcre2/
./configure
make
    git clone https://github.com/PCRE2Project/pcre2.git
git submodule update --init

  10. Use binary character tables for cross-platform consistency

    main
    To ensure consistent character handling across different environments, you can generate binary character tables using the pcre2_dftables utility with the -b flag. These tables are independent of hardware endianness and can be loaded into memory and passed to pcre2_compile().

  11. PCRE2 Regular Expression Syntax Summary

    main
    This document provides a quick-reference summary of the pattern syntax supported by PCRE2. For full syntax and semantics, refer to the pcre2pattern documentation. PCRE2 supports Perl-compatible regular expressions with various extensions for Unicode, backtracking control, and advanced character classes.

  12. What is partial matching in PCRE2?

    main

    Partial matching is a PCRE2-specific feature (not Perl-compatible) used when a match is interrupted by the end of the subject string. Instead of returning PCRE2_ERROR_NOMATCH, PCRE2 can return PCRE2_ERROR_PARTIAL, indicating that adding more characters to the subject might result in a complete match.

    This is useful for:

    • Multi-segment matching: Processing very long strings segment by segment.
    • Real-time input validation: Providing instant feedback as a user types a string to ensure it conforms to a format.