capi: add rure_escape_must function

This commit exposes two new functions in regex's C API: rure_escape_must
and rure_cstring_free. These permit escaping a pattern such that it
contains no special regex meta characters.

Currently, we only expose a routine that will abort the process if it
fails, but we document the precise error conditions. A more flexible but
less convenient routine should ideally be exposed in the future, but
that needs a bit more API design than what's here.

Closes rust-lang#537

Author: marmeladema

regex-capi/ctest/test.c

@@ -531,6 +531,31 @@ bool test_regex_set_options() {
     return passed;
 }
 
+bool test_escape() {
+    bool passed = true;
+
+    const char *pattern = "^[a-z]+.*$";
+    const char *expected_escaped = "\\^\\[a\\-z\\]\\+\\.\\*\\$";
+
+    const char *escaped = rure_escape_must(pattern);
+    if (!escaped) {
+        if (DEBUG) {
+            fprintf(stderr,
+                    "[test_captures] expected escaped, but got no escaped\n");
+        }
+        passed = false;
+    } else if (strcmp(escaped, expected_escaped) != 0) {
+        if (DEBUG) {
+            fprintf(stderr,
+                    "[test_captures] expected \"%s\", but got \"%s\"\n",
+                    expected_escaped, escaped);
+        }
+        passed = false;
+    }
+    rure_cstring_free((char *) escaped);
+    return passed;
+}
+
 void run_test(bool (test)(), const char *name, bool *passed) {
     if (!test()) {
         *passed = false;
@@ -557,6 +582,7 @@ int main() {
     run_test(test_regex_set_options, "test_regex_set_options", &passed);
     run_test(test_regex_set_match_start, "test_regex_set_match_start",
              &passed);
+    run_test(test_escape, "test_escape", &passed);
 
     if (!passed) {
         exit(1);

regex-capi/include/rure.h

@@ -567,6 +567,29 @@ void rure_error_free(rure_error *err);
  */
 const char *rure_error_message(rure_error *err);
 
+/*
+ * rure_escape_must returns a NUL terminated string where all meta characters
+ * have been escaped. If escaping fails for any reason, an error message is
+ * printed to stderr and the process is aborted.
+ *
+ * The pattern given should be in UTF-8. For convenience, this accepts a C
+ * string, which means the pattern cannot contain a NUL byte. These correspond
+ * to the only two failure conditions of this function. That is, if the caller
+ * guarantees that the given pattern is valid UTF-8 and does not contain a
+ * NUL byte, then this is guaranteed to succeed (modulo out-of-memory errors).
+ *
+ * The pointer returned must not be freed directly. Instead, it should be freed
+ * by calling rure_cstring_free.
+ */
+const char *rure_escape_must(const char *pattern);
+
+/*
+ * rure_cstring_free frees the string given.
+ *
+ * This must be called at most once per string.
+ */
+void rure_cstring_free(char *s);
+
 #ifdef __cplusplus
 }
 #endif

regex-capi/src/error.rs

@@ -1,3 +1,4 @@
+use ::std::ffi;
 use ::std::ffi::CString;
 use ::std::fmt;
 use ::std::str;
@@ -16,6 +17,7 @@ pub enum ErrorKind {
     None,
     Str(str::Utf8Error),
     Regex(regex::Error),
+    Nul(ffi::NulError),
 }
 
 impl Error {
@@ -29,7 +31,7 @@ impl Error {
     pub fn is_err(&self) -> bool {
         match self.kind {
             ErrorKind::None => false,
-            ErrorKind::Str(_) | ErrorKind::Regex(_) => true,
+            ErrorKind::Str(_) | ErrorKind::Regex(_) | ErrorKind::Nul(_) => true,
         }
     }
 }
@@ -40,6 +42,7 @@ impl fmt::Display for Error {
             ErrorKind::None => write!(f, "no error"),
             ErrorKind::Str(ref e) => e.fmt(f),
             ErrorKind::Regex(ref e) => e.fmt(f),
+            ErrorKind::Nul(ref e) => e.fmt(f),
         }
     }
 }

regex-capi/src/macros.rs

@@ -1,4 +1,3 @@
-
 macro_rules! ffi_fn {
     (fn $name:ident($($arg:ident: $arg_ty:ty),*,) -> $ret:ty $body:block) => {
         ffi_fn!(fn $name($($arg: $arg_ty),*) -> $ret $body);
@@ -35,5 +34,3 @@ macro_rules! ffi_fn {
         ffi_fn!(fn $name($($arg: $arg_ty),*) -> () $body);
     };
 }
-
-

regex-capi/src/rure.rs

@@ -570,3 +570,63 @@ ffi_fn! {
         unsafe { (*re).len() }
     }
 }
+
+ffi_fn! {
+    fn rure_escape_must(pattern: *const c_char) -> *const c_char {
+        let len = unsafe { CStr::from_ptr(pattern).to_bytes().len() };
+        let pat = pattern as *const u8;
+        let mut err = Error::new(ErrorKind::None);
+        let esc = rure_escape(pat, len, &mut err);
+        if err.is_err() {
+            let _ = writeln!(&mut io::stderr(), "{}", err);
+            let _ = writeln!(
+                &mut io::stderr(), "aborting from rure_escape_must");
+            unsafe { abort() }
+        }
+        esc
+    }
+}
+
+/// A helper function that implements fallible escaping in a way that returns
+/// an error if escaping failed.
+///
+/// This should ideally be exposed, but it needs API design work. In
+/// particular, this should not return a C string, but a `const uint8_t *`
+/// instead, since it may contain a NUL byte.
+fn rure_escape(
+    pattern: *const u8,
+    length: size_t,
+    error: *mut Error
+) -> *const c_char {
+    let pat: &[u8] = unsafe { slice::from_raw_parts(pattern, length) };
+    let str_pat = match str::from_utf8(pat) {
+        Ok(val) => val,
+        Err(err) => {
+            unsafe {
+                if !error.is_null() {
+                    *error = Error::new(ErrorKind::Str(err));
+                }
+                return ptr::null();
+            }
+        }
+    };
+    let esc_pat = regex::escape(str_pat);
+    let c_esc_pat = match CString::new(esc_pat) {
+        Ok(val) => val,
+        Err(err) => {
+            unsafe {
+                if !error.is_null() {
+                    *error = Error::new(ErrorKind::Nul(err));
+                }
+                return ptr::null();
+            }
+        }
+    };
+    c_esc_pat.into_raw() as *const c_char
+}
+
+ffi_fn! {
+    fn rure_cstring_free(s: *mut c_char) {
+        unsafe { CString::from_raw(s); }
+    }
+}