pcre2

NOTE: This release is graded alpha and is likely to experience API changes up until the 1.0 release.

Overview

A V library module for processing Perl Compatible Regular Expressions (PCRE) using the PCRE2 library.

The pcre2 module is a wrapper for the PCRE2 8-bit runtime library.
Regex find_* methods search a subject string for regular expression matches.
Regex replace_* methods return a string in which matches in the subject string are replaced by a replacement string or the result of a replacement function.
Regex *_all_* methods process all matches; *_one_* methods process the first match.
The Regex replace_*_extended methods support the PCRE2 extended replacements string syntax (see PCRE2_SUBSTITUTE_EXTENDED in the pcre2api man page).
Currently there are no extraction methods for named subpatterns.
The pcre module (which uses the older PCRE library) was the inspiration and starting point for this project; the Go regex package also influenced the project.

Documentation

Examples

import srackham.pcre2

fn main() {
	// Match words starting with `d` or `n`.
	r := pcre2.must_compile(r'\b([dn].*?)\b')

	subject := 'Lorem nisi dis diam a cras placerat natoque'

	// Extract array of all matched strings.
	a := r.find_all(subject)
	println(a) // ['nisi', 'dis', 'diam', 'natoque']

	// Quote matched words.
	s1 := r.replace_all(subject, '"$1"')
	println(s1) // 'Lorem "nisi" "dis" "diam" a cras placerat "natoque"'

	// Replace all matched strings with upper case.
	s2 := r.replace_all_fn(subject, fn (m string) string {
		return m.to_upper()
	})
	println(s2) // 'Lorem NISI DIS DIAM a cras placerat NATOQUE'

	// Replace all matched strings with upper case (PCRE2 extended replacement syntax).
	s3 := r.replace_all_extended(subject, r'\U$1')
	println(s3) // 'Lorem NISI DIS DIAM a cras placerat NATOQUE'
}

For more examples see inside the examples directory and take a look at the module tests.

Dependencies

Install the PCRE2 library:

Arch Linux and Manjaro: pacman -S pcre2

Debian and Ubuntu: apt install libpcre2-dev

Fedora: yum install pcre2-devel

macOS: brew install pcre2

Windows †: pacman.exe -S mingw-w64-x86_64-pcre2

† Uses the MSYS2 package management tools.

Installation

v install srackham.pcre2

Test the installation by running:

v test $HOME/.vmodules/srackham/pcre2

Example installation and test workflows for Ubuntu, macOS and Windows can be found in the Github Actions workflow file.

Performance

Complex patterns can cause PCRE2 resource exhaustion. find_* library functions respond to such errors by raising a panic. The solution is to simplify the offending pattern. Unlike, for example, the Go regexp package, PCRE2 does not have linear-time performance and while they may not trigger a panic, pathalogical patterns can exhibit slow performance. See the PCRE2 pcre2perform man page.