onig 1.3.0

//! This crate provides a safe wrapper around the
//! [Oniguruma](https://github.com/kkos/oniguruma) regular expression library.
//!
//! # Examples
//!
//! ```rust
//! use onig::Regex;
//!
//! 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)
//!     }
//! }
//! ```
//!
//! # Match vs Search
//!
//! There are two basic things you can do with a `Regex` pattern; test
//! if the pattern matches the whole of a given string, and search for
//! occurences of the pattern within a string. Oniguruma exposes these
//! two concepts with the *match* and *search* APIs.
//!
//! In addition two these two base Onigurma APIs this crate exposes a
//! third *find* API, built on top of the *search* API.
//!
//! ```
//! # use onig::Regex;
//! let pattern = Regex::new("hello").unwrap();
//! assert_eq!(true, pattern.find("hello world").is_some());
//! assert_eq!(false, pattern.is_match("hello world"));
//! ```
//!
//! ## The *Match* API
//!
//! Functions in the match API check if a pattern matches the entire
//! string. The simplest of these is `Regex::is_match`. This retuns a
//! `true` if the pattern matches the string. For more complex useage
//! then `Regex::match_with_options` and `Regex::match_with_encoding`
//! can be used. These allow the capture groups to be inspected,
//! matching with different options, and matching sub-sections of a
//! given text.
//!
//! ## The *Search* API
//!
//! Function in the search API search for a pattern anywhere within a
//! string. The simplist of these is `Regex::find`. This returns the
//! offset of the first occurence of the pattern within the string.
//! For more complex useage `Regex::search_with_options` and
//! `Regex::search_with_encoding` can be used. These allow capture
//! groups to be inspected, searching with different options and
//! searching within subsections of a given text.
//!
//! ## The *Find* API
//!
//! The find API is built on top of the search API. Functions in this
//! API allow iteration across all matches of the pattern within a
//! string, not just the first one. The functions deal with some of
//! the complexities of this, such as zero-length matches.
//!
//! The simplest step-up from the basic search API `Regex::find` is
//! getting the captures relating to a match with the
//! `Regex::capturess` method. To find capture information for all
//! matches within a string `Regex::find_iter` and
//! `Regex::captures_iter` can be used. The former exposes the start
//! and end of the match as `Regex::find` does, the latter exposes the
//! whole capture group information as `Regex::captures` does.
//!
//! # The `std::pattern` API
//!
//! In addition to the main Oniguruma API it is possible to use the
//! `Regex` object with the
//! [`std::pattern`](https://doc.rust-lang.org/std/str/pattern/)
//! API. To enable support compile with the `std-pattern` feature. If
//! you're using Cargo you can do this by adding the following to your
//! Cargo.toml:
//!
//! ```toml
//! [dependencies.onig]
//! version = "1.2"
//! features = ["std-pattern"]
//! ```

#![cfg_attr(feature = "std-pattern", feature(pattern))]

#[macro_use]
extern crate bitflags;
#[macro_use]
extern crate lazy_static;
extern crate libc;
extern crate onig_sys;

mod find;
mod flags;
mod region;
mod replace;
mod names;
mod syntax;
mod tree;
mod utils;
mod buffers;

#[cfg(feature="std-pattern")]
mod pattern;

// re-export the onig types publically
pub use flags::*;
pub use names::CaptureNames;
pub use region::Region;
pub use find::{Captures, SubCaptures, SubCapturesPos, FindMatches, FindCaptures, RegexSplits,
               RegexSplitsN};
pub use buffers::{EncodedChars, EncodedBytes};
pub use replace::Replacer;
pub use tree::{CaptureTreeNode, CaptureTreeNodeIter};
pub use syntax::{Syntax, MetaChar};
pub use utils::{version, copyright, define_user_property};

use std::{error, fmt, str};
use std::sync::Mutex;
use std::mem::transmute;
use std::ptr::{null, null_mut};
use libc::c_int;

/// This struture represents an error from the underlying Oniguruma libray.
pub struct Error {
    code: c_int,
    description: String,
}

/// This struct is a wrapper around an Oniguruma regular expression
/// pointer. This represents a compiled regex which can be used in
/// search and match operations.
#[derive(Debug, Eq, PartialEq)]
pub struct Regex {
    raw: onig_sys::OnigRegexMut,
}

impl Error {
    fn new(code: c_int, info: onig_sys::OnigErrorInfo) -> Error {
        let mut buff = &mut [0; onig_sys::ONIG_MAX_ERROR_MESSAGE_LEN as usize];
        let len = unsafe { onig_sys::onig_error_code_to_str(buff.as_mut_ptr(), code, &info) };
        let description = str::from_utf8(&buff[..len as usize]).unwrap();
        Error {
            code: code,
            description: description.to_owned(),
        }
    }

    /// Return Oniguruma engine error code.
    pub fn code(&self) -> i32 {
        self.code
    }

    /// Return error description provided by Oniguruma engine.
    pub fn description(&self) -> &str {
        &self.description
    }
}

impl error::Error for Error {
    fn description(&self) -> &str {
        &self.description
    }
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "Oniguruma error: {}", self.description())
    }
}

impl fmt::Debug for Error {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "Error({}, {})", self.code, self.description())
    }
}

lazy_static! {
    static ref REGEX_NEW_MUTEX: Mutex<()> = Mutex::new(());
}

impl Regex {
    /// Create a Regex
    ///
    /// Simple regular expression constructor. Compiles a new regular
    /// expression with the default options using the ruby syntax.
    /// Once compiled, it can be used repeatedly to search in a string. If an
    /// invalid expression is given, then an error is returned.
    ///
    /// # Arguments
    ///
    /// * `pattern` - The regex pattern to compile
    ///
    /// # Examples
    ///
    /// ```
    /// use onig::Regex;
    /// let r = Regex::new(r#"hello (\w+)"#);
    /// assert!(r.is_ok());
    /// ```
    pub fn new(pattern: &str) -> Result<Regex, Error> {
        Regex::with_encoding(pattern)
    }

    /// Create a Regex, Specifying an Encoding
    ///
    /// Attempts to compile `pattern` into a new `Regex`
    /// instance. Instead of assuming UTF-8 as the encoding scheme the
    /// encoding is inferred from the `pattern` buffer.
    ///
    /// # Arguments
    ///
    /// * `pattern` - The regex pattern to compile
    ///
    /// # Examples
    ///
    /// ```
    /// use onig::{Regex, EncodedBytes};
    /// let utf8 = Regex::with_encoding("hello");
    /// assert!(utf8.is_ok());
    /// let ascii = Regex::with_encoding(EncodedBytes::ascii(b"world"));
    /// assert!(ascii.is_ok());
    /// ```
    pub fn with_encoding<T>(pattern: T) -> Result<Regex, Error>
        where T: EncodedChars
    {
        Regex::with_options_and_encoding(pattern, REGEX_OPTION_NONE, Syntax::default())
    }

    /// Create a new Regex
    ///
    /// Attempts to compile a pattern into a new `Regex` instance.
    /// Once compiled, it can be used repeatedly to search in a string. If an
    /// invalid expression is given, then an error is returned.
    /// See [`onig_sys::onig_new`][regex_new] for more information.
    ///
    /// # Arguments
    ///
    ///  * `pattern` - The regex pattern to compile.
    ///  * `options` - The regex compilation options.
    ///  * `syntax`  - The syntax which the regex is written in.
    ///
    /// # Examples
    ///
    /// ```
    /// use onig::{Regex, Syntax, REGEX_OPTION_NONE};
    /// let r = Regex::with_options("hello.*world",
    ///                             REGEX_OPTION_NONE,
    ///                             Syntax::default());
    /// assert!(r.is_ok());
    /// ```
    ///
    /// [regex_new]: ./onig_sys/fn.onig_new.html
    pub fn with_options(pattern: &str,
                        option: RegexOptions,
                        syntax: &Syntax)
                        -> Result<Regex, Error> {
        Regex::with_options_and_encoding(pattern, option, syntax)
    }

    /// Create a new Regex, Specifying Options and Ecoding
    ///
    /// Attempts to comile the given `pattern` into a new `Regex`
    /// instance. Instead of assuming UTF-8 as the encoding scheme the
    /// encoding is inferred from the `pattern` buffer. If the regex
    /// fails to compile the returned `Error` value from
    /// [`onig_new`][regex_new] contains more information.
    ///
    /// [regex_new]: ./onig_sys/fn.onig_new.html
    ///
    /// # Arguments
    ///
    ///  * `pattern` - The regex pattern to compile.
    ///  * `options` - The regex compilation options.
    ///  * `syntax`  - The syntax which the regex is written in.
    ///
    /// # Examples
    /// ```
    /// use onig::{Regex, Syntax, EncodedBytes, REGEX_OPTION_SINGLELINE};
    /// let pattern = EncodedBytes::ascii(b"hello");
    /// let r = Regex::with_options_and_encoding(pattern,
    ///                                          REGEX_OPTION_SINGLELINE,
    ///                                          Syntax::default());
    /// assert!(r.is_ok());
    /// ```
    pub fn with_options_and_encoding<T>(pattern: T,
                                        option: RegexOptions,
                                        syntax: &Syntax)
                                        -> Result<Regex, Error>
        where T: EncodedChars
    {
        // Convert the rust types to those required for the call to
        // `onig_new`.
        let mut reg: onig_sys::OnigRegexMut = null_mut();
        let reg_ptr = &mut reg as *mut onig_sys::OnigRegexMut;

        // We can use this later to get an error message to pass back
        // if regex creation fails.
        let mut error = onig_sys::OnigErrorInfo {
            enc: null(),
            par: null(),
            par_end: null(),
        };


        let err = unsafe {
            // Grab a lock to make sure that `onig_new` isn't called by
            // more than one thread at a time.
            let _guard = REGEX_NEW_MUTEX.lock().unwrap();
            onig_sys::onig_new(reg_ptr,
                               pattern.start_ptr(),
                               pattern.limit_ptr(),
                               option.bits(),
                               pattern.encoding(),
                               transmute(syntax),
                               &mut error)
        };

        if err == onig_sys::ONIG_NORMAL {
            Ok(Regex { raw: reg })
        } else {
            Err(Error::new(err, error))
        }
    }

    /// Match String
    ///
    /// Try to match the regex against the given string slice,
    /// starting at a given offset. This method works the same way as
    /// `match_with_encoding`, but the encoding is always utf-8.
    ///
    /// For more information see [Match vs
    /// Search](index.html#match-vs-search)
    ///
    /// # Arguments
    ///
    /// * `str` - The string slice to match against.
    /// * `at` - The byte index in the passed slice to start matching
    /// * `options` - The regex match options.
    /// * `region` - The region for return group match range info
    ///
    /// # Returns
    ///
    /// `Some(len)` if the regex matched, with `len` being the number
    /// of bytes matched. `None` if the regex doesn't match.
    ///
    /// # Examples
    ///
    /// ```
    /// use onig::{Regex, SEARCH_OPTION_NONE};
    ///
    /// let r = Regex::new(".*").unwrap();
    /// let res = r.match_with_options("hello", 0, SEARCH_OPTION_NONE, None);
    /// assert!(res.is_some()); // it matches
    /// assert!(res.unwrap() == 5); // 5 characters matched
    /// ```
    pub fn match_with_options(&self,
                              str: &str,
                              at: usize,
                              options: SearchOptions,
                              region: Option<&mut Region>)
                              -> Option<usize> {
        self.match_with_encoding(str, at, options, region)
    }

    /// Match String with Encoding
    ///
    /// Match the regex against a string. This method will start at
    /// the offset `at` into the string and try and match the
    /// regex. If the regex matches then the return value is the
    /// number of characers which matched. If the regex doesn't match
    /// the return is `None`.
    ///
    /// For more information see [Match vs
    /// Search](index.html#match-vs-search)
    ///
    /// The contents of `chars` must have the same encoding that was
    /// used to construct the regex.
    ///
    /// # Arguments
    ///
    /// * `chars` - The buffer to match against.
    /// * `at` - The byte index in the passed buffer to start matching
    /// * `options` - The regex match options.
    /// * `region` - The region for return group match range info
    ///
    /// # Returns
    ///
    /// `Some(len)` if the regex matched, with `len` being the number
    /// of bytes matched. `None` if the regex doesn't match.
    ///
    /// # Examples
    ///
    /// ```
    /// use onig::{Regex, EncodedBytes, SEARCH_OPTION_NONE};
    ///
    /// let r = Regex::with_encoding(EncodedBytes::ascii(b".*")).unwrap();
    /// let res = r.match_with_encoding(EncodedBytes::ascii(b"world"),
    ///                                 0, SEARCH_OPTION_NONE, None);
    /// assert!(res.is_some()); // it matches
    /// assert!(res.unwrap() == 5); // 5 characters matched
    /// ```
    pub fn match_with_encoding<T>(&self,
                                  chars: T,
                                  at: usize,
                                  options: SearchOptions,
                                  region: Option<&mut Region>)
                                  -> Option<usize>
        where T: EncodedChars
    {
        assert_eq!(chars.encoding(), self.encoding());
        let r = unsafe {
            let offset = chars.start_ptr().offset(at as isize);
            assert!(offset <= chars.limit_ptr());
            onig_sys::onig_match(self.raw,
                                 chars.start_ptr(),
                                 chars.limit_ptr(),
                                 offset,
                                 match region {
                                     Some(region) => transmute(region),
                                     None => 0 as *mut onig_sys::OnigRegion,
                                 },
                                 options.bits())
        };

        if r >= 0 {
            Some(r as usize)
        } else if r == onig_sys::ONIG_MISMATCH {
            None
        } else {
            panic!("Onig: Internal error during regex match");
        }
    }

    /// Search pattern in string
    ///
    /// Search for matches the regex in a string. This method will return the
    /// index of the first match of the regex within the string, if
    /// there is one. If `from` is less than `to`, then search is performed
    /// in forward order, otherwice – in backward order.
    ///
    /// For more information see [Match vs
    /// Search](index.html#match-vs-search)
    ///
    /// # Arguments
    ///
    ///  * `str` - The string to search in.
    ///  * `from` - The byte index in the passed slice to start search
    ///  * `to` - The byte index in the passed slice to finish search
    ///  * `options` - The options for the search.
    ///  * `region` - The region for return group match range info
    ///
    /// # Returns
    ///
    /// `Some(pos)` if the regex matches, where `pos` is the
    /// byte-position of the start of the match. `None` if the regex
    /// doesn't match anywhere in `str`.
    ///
    /// # Examples
    ///
    /// ```
    /// use onig::{Regex, SEARCH_OPTION_NONE};
    ///
    /// let r = Regex::new("l{1,2}").unwrap();
    /// let res = r.search_with_options("hello", 0, 5, SEARCH_OPTION_NONE, None);
    /// assert!(res.is_some()); // it matches
    /// assert!(res.unwrap() == 2); // match starts at character 3
    /// ```
    pub fn search_with_options(&self,
                               str: &str,
                               from: usize,
                               to: usize,
                               options: SearchOptions,
                               region: Option<&mut Region>)
                               -> Option<usize> {
        self.search_with_encoding(str, from, to, options, region)
    }

    /// Search for a Pattern in a String with an Encoding
    ///
    /// Search for matches the regex in a string. This method will
    /// return the index of the first match of the regex within the
    /// string, if there is one. If `from` is less than `to`, then
    /// search is performed in forward order, otherwice – in backward
    /// order.
    ///
    /// For more information see [Match vs
    /// Search](index.html#match-vs-search)
    ///
    /// The encoding of the buffer passed to search in must match the
    /// encoding of the regex.
    ///
    /// # Arguments
    ///
    ///  * `chars` - The character buffer to search in.
    ///  * `from` - The byte index in the passed slice to start search
    ///  * `to` - The byte index in the passed slice to finish search
    ///  * `options` - The options for the search.
    ///  * `region` - The region for return group match range info
    ///
    /// # Returns
    ///
    /// `Some(pos)` if the regex matches, where `pos` is the
    /// byte-position of the start of the match. `None` if the regex
    /// doesn't match anywhere in `chars`.
    ///
    /// # Examples
    ///
    /// ```
    /// use onig::{Regex,EncodedBytes,SEARCH_OPTION_NONE};
    ///
    /// let r = Regex::with_encoding(EncodedBytes::ascii(b"l{1,2}")).unwrap();
    /// let res = r.search_with_encoding(EncodedBytes::ascii(b"hello"),
    ///                                  0, 5, SEARCH_OPTION_NONE, None);
    /// assert!(res.is_some()); // it matches
    /// assert!(res.unwrap() == 2); // match starts at character 3
    /// ```
    pub fn search_with_encoding<T>(&self,
                                   chars: T,
                                   from: usize,
                                   to: usize,
                                   options: SearchOptions,
                                   region: Option<&mut Region>)
                                   -> Option<usize>
        where T: EncodedChars
    {
        let (beg, end) = (chars.start_ptr(), chars.limit_ptr());
        assert_eq!(self.encoding(), chars.encoding());
        let r = unsafe {
            let start = beg.offset(from as isize);
            let range = beg.offset(to as isize);
            assert!(start <= end);
            assert!(range <= end);
            onig_sys::onig_search(self.raw,
                                  beg,
                                  end,
                                  start,
                                  range,
                                  match region {
                                      Some(region) => transmute(region),
                                      None => 0 as *mut onig_sys::OnigRegion,
                                  },
                                  options.bits())
        };

        if r >= 0 {
            Some(r as usize)
        } else if r == onig_sys::ONIG_MISMATCH {
            None
        } else {
            panic!("Onig: Internal error during regex search");
        }
    }

    /// Returns true if and only if the regex matches the string given.
    ///
    /// For more information see [Match vs
    /// Search](index.html#match-vs-search)
    ///
    /// # Arguments
    ///  * `text` - The string slice to test against the pattern.
    ///
    /// # Returns
    ///
    /// `true` if the pattern matches the whole of `text`, `false` otherwise.
    pub fn is_match(&self, text: &str) -> bool {
        self.match_with_options(text, 0, SEARCH_OPTION_NONE, None)
            .map(|r| r == text.len())
            .unwrap_or(false)
    }

    /// Find a Match in a Buffer, With Encoding
    ///
    /// Finds the first match of the regular expression within the
    /// buffer.
    ///
    /// Note that this should only be used if you want to discover the
    /// position of the match within a string. Testing if a pattern
    /// matches the whole string is faster if you use `is_match`.  For
    /// more information see [Match vs
    /// Search](index.html#match-vs-search)
    ///
    /// # Arguments
    ///  * `text` - The text to search in.
    ///
    /// # Returns
    ///
    ///  The offset of the start and end of the first match. If no
    ///  match exists `None` is returned.
    pub fn find(&self, text: &str) -> Option<(usize, usize)> {
        self.find_with_encoding(text)
    }

    /// Find a Match in a Buffer, With Encoding
    ///
    /// Finds the first match of the regular expression within the
    /// buffer.
    ///
    /// For more information see [Match vs
    /// Search](index.html#match-vs-search)
    ///
    /// # Arguments
    ///  * `text` - The text to search in.
    ///
    /// # Returns
    ///
    ///  The offset of the start and end of the first match. If no
    ///  match exists `None` is returned.
    pub fn find_with_encoding<T>(&self, text: T) -> Option<(usize, usize)>
        where T: EncodedChars
    {
        let mut region = Region::new();
        let len = text.len();
        self.search_with_encoding(text, 0, len, SEARCH_OPTION_NONE, Some(&mut region))
            .and_then(|_| region.pos(0))
    }


    /// Get the Encoding of the Regex
    ///
    /// # Returns
    ///
    /// Returns a reference to an oniguruma encoding which was used
    /// when this regex was created.
    pub fn encoding(&self) -> onig_sys::OnigEncoding {
        unsafe { onig_sys::onig_get_encoding(self.raw) }
    }

    pub fn captures_len(&self) -> usize {
        unsafe { onig_sys::onig_number_of_captures(self.raw) as usize }
    }

    pub fn capture_histories_len(&self) -> usize {
        unsafe { onig_sys::onig_number_of_capture_histories(self.raw) as usize }
    }
}

impl Drop for Regex {
    fn drop(&mut self) {
        unsafe {
            onig_sys::onig_free(self.raw);
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_regex_create() {
        Regex::with_options(".*", REGEX_OPTION_NONE, Syntax::default()).unwrap();

        Regex::new(r#"a \w+ word"#).unwrap();
    }

    #[test]
    fn test_regex_invalid() {
        let e = Regex::new("\\p{foo}").unwrap_err();
        assert_eq!(e.code(), -223);
        assert_eq!(e.description(), "invalid character property name {foo}");
    }

    #[test]
    fn test_failed_match() {
        let regex = Regex::new("foo").unwrap();
        let res = regex.match_with_options("bar", 0, SEARCH_OPTION_NONE, None);
        assert!(res.is_none());
    }

    #[test]
    fn test_regex_search_with_options() {
        let mut region = Region::new();
        let regex = Regex::new("e(l+)").unwrap();

        let r = regex.search_with_options("hello", 0, 5, SEARCH_OPTION_NONE, Some(&mut region));

        assert!(region.tree().is_none());
        assert_eq!(r, Some(1));
        assert_eq!(region.len(), 2);
        let pos1 = region.pos(0).unwrap();
        let pos2 = region.pos(1).unwrap();
        assert_eq!(pos1, (1, 4));
        assert_eq!(pos2, (2, 4));

        // test cloning here since we already have a filled region
        let cloned_region = region.clone();
        let pos1_clone = cloned_region.pos(0).unwrap();
        assert_eq!(pos1_clone, pos1);
    }

    #[test]
    fn test_regex_match_with_options() {
        let mut region = Region::new();
        let regex = Regex::new("he(l+)").unwrap();

        let r = regex.match_with_options("hello", 0, SEARCH_OPTION_NONE, Some(&mut region));

        assert!(region.tree().is_none());
        assert_eq!(r, Some(4));
        assert_eq!(region.len(), 2);
        let pos1 = region.pos(0).unwrap();
        let pos2 = region.pos(1).unwrap();
        assert_eq!(pos1, (0, 4));
        assert_eq!(pos2, (2, 4));
    }

    #[test]
    fn test_regex_is_match() {
        let regex = Regex::new("he(l+)o").unwrap();
        assert!(regex.is_match("hello"));
        assert!(!regex.is_match("hello 2.0"));
    }

    #[test]
    fn test_regex_find() {
        let regex = Regex::new("he(l+)o").unwrap();
        assert_eq!(regex.find("hey, hello!"), Some((5, 10)));
        assert_eq!(regex.find("hey, honey!"), None);
    }

    #[test]
    fn test_regex_captures_len() {
        let regex = Regex::new("(he)(l+)(o)").unwrap();
        assert_eq!(regex.captures_len(), 3);
    }
}