Rust bindings for the Oniguruma regex library, a powerful and mature regular expression library with support for a wide range of character sets and language syntaxes. Oniguruma is written in C. This repository provides two crates: onig-sys
which provides the raw Rust FFI bindings, and onig
, which provides a safe Rust wrapper around them.
Check out the module documentation to find out all the features that are available. To see some example usage of this crate take a look a the examples folder. The examples can be run from the command line with cargo run --example <examplename>
.
Add the following to your Cargo.toml
file:
[dependencies]
onig = "3.2"
Add the following extern to your crate root:
extern crate onig;
You can compile simple regular expressions with Regex::new
, check if the pattern matches an entire &str
with Regex::is_match
and find matches within a &str
with Regex::find
. The onig
crate also supplies more powerful versions of these methods which expose the wide range of options Oniguruma provides.
use onig::*;
let regex = Regex::new("e(l+)").unwrap();
for (i, pos) in regex.captures("hello").unwrap().iter_pos().enumerate() {
match pos {
Some((beg, end)) =>
println!("Group {} captured in position {}:{}", i, beg, end),
None =>
println!("Group {} is not captured", i)
}
}
If a version of Oniguruma can be found by pkg-config
then that will be used. If not then Oniguruma will be compiled from source and linked to the onig-sys
crate.
By default rust-onig
will be statically linked to libonig
. If you would rather that dynamic linking is used then the environment variables RUSTONIG_STATIC_LIBONIG
and RUSTONIG_DYNAMIC_LIBONIG
can be set. On *nix:
$ RUSTONIG_DYNAMIC_LIBONING=1 cargo build
Or Windows:
> set RUSTONIG_DYNAMIC_LIBONIG=1
> cargo build
Sometimes it's useful to debug how Oniguruma parses, compiles, optimizes or executes a particular pattern.
When activating the print-debug
feature for this crate, Oniguruma is compiled
with debugging. Note that it's a compile-time setting, so you also need to make
rust-onig
not use the system Oniguruma by using RUSTONIG_SYSTEM_LIBONIG
.
With all that combined, here's an example command to debug the pattern a|b
:
RUSTONIG_SYSTEM_LIBONIG=0 cargo run --features print-debug --example capturedump 'a|b'
The contents of this repository are distributed under the MIT license. See LICENSE for more details. If you'd like to contribute take a look at our open easy issues.