tempbottle / rust-onig

Rust bindings for the Oniguruma regex library

Rust Onig

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.

Documentation

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>.

Getting Started

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)
    }
}

Linking

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

Debugging

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'

Rust-Onig is Open Source

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.