Add ExprBuilder, which can set the default values of flags when parsing.

Closes #172.

Author: BurntSushi

regex-syntax/src/lib.rs

@@ -82,10 +82,7 @@ use unicode::case_folding;
 use self::Expr::*;
 use self::Repeater::*;
 
-pub use parser::is_punct;
-
-/// The maximum number of nested expressions allowed.
-const NEST_LIMIT: usize = 200;
+use parser::{Flags, Parser};
 
 /// A regular expression abstract syntax tree.
 ///
@@ -236,10 +233,86 @@ pub struct ClassRange {
     pub end: char,
 }
 
+/// A builder for configuring regular expression parsing.
+///
+/// This allows setting the default values of flags and other options, such
+/// as the maximum nesting depth.
+#[derive(Clone, Debug)]
+pub struct ExprBuilder {
+    flags: Flags,
+    nest_limit: usize,
+}
+
+impl ExprBuilder {
+    /// Create a new builder for configuring expression parsing.
+    ///
+    /// Note that all flags are disabled by default.
+    pub fn new() -> ExprBuilder {
+        ExprBuilder {
+            flags: Flags {
+                casei: false,
+                multi: false,
+                dotnl: false,
+                swap_greed: false,
+                ignore_space: false,
+            },
+            nest_limit: 200,
+        }
+    }
+
+    /// Set the default value for the case insensitive (`i`) flag.
+    pub fn case_insensitive(mut self, yes: bool) -> ExprBuilder {
+        self.flags.casei = yes;
+        self
+    }
+
+    /// Set the default value for the multi-line matching (`m`) flag.
+    pub fn multi_line(mut self, yes: bool) -> ExprBuilder {
+        self.flags.multi = yes;
+        self
+    }
+
+    /// Set the default value for the any character (`s`) flag.
+    pub fn dot_matches_new_line(mut self, yes: bool) -> ExprBuilder {
+        self.flags.dotnl = yes;
+        self
+    }
+
+    /// Set the default value for the greedy swap (`U`) flag.
+    pub fn swap_greed(mut self, yes: bool) -> ExprBuilder {
+        self.flags.swap_greed = yes;
+        self
+    }
+
+    /// Set the default value for the ignore whitespace (`x`) flag.
+    pub fn ignore_whitespace(mut self, yes: bool) -> ExprBuilder {
+        self.flags.ignore_space = yes;
+        self
+    }
+
+    /// Set the nesting limit for regular expression parsing.
+    ///
+    /// Regular expressions that nest more than this limit will result in a
+    /// `StackExhausted` error.
+    pub fn nest_limit(mut self, limit: usize) -> ExprBuilder {
+        self.nest_limit = limit;
+        self
+    }
+
+    /// Parse a string as a regular expression using the current configuraiton.
+    pub fn parse(self, s: &str) -> Result<Expr> {
+        Parser::parse(s, self.flags).and_then(|e| e.simplify(self.nest_limit))
+    }
+}
+
 impl Expr {
     /// Parses a string in a regular expression syntax tree.
+    ///
+    /// This is a convenience method for parsing an expression using the
+    /// default configuration. To tweak parsing options (such as which flags
+    /// are enabled by default), use the `ExprBuilder` type.
     pub fn parse(s: &str) -> Result<Expr> {
-        parser::Parser::parse(s).and_then(|e| e.simplify())
+        ExprBuilder::new().parse(s)
     }
 
     /// Returns true iff the expression can be repeated by a quantifier.
@@ -257,7 +330,7 @@ impl Expr {
         }
     }
 
-    fn simplify(self) -> Result<Expr> {
+    fn simplify(self, nest_limit: usize) -> Result<Expr> {
         fn combine_literals(es: &mut Vec<Expr>, e: Expr) {
             match (es.pop(), e) {
                 (None, e) => es.push(e),
@@ -277,15 +350,15 @@ impl Expr {
                 }
             }
         }
-        fn simp(expr: Expr, recurse: usize) -> Result<Expr> {
-            if recurse > NEST_LIMIT {
+        fn simp(expr: Expr, recurse: usize, limit: usize) -> Result<Expr> {
+            if recurse > limit {
                 return Err(Error {
                     pos: 0,
                     surround: "".to_owned(),
                     kind: ErrorKind::StackExhausted,
                 });
             }
-            let simplify = |e| simp(e, recurse + 1);
+            let simplify = |e| simp(e, recurse + 1, limit);
             Ok(match expr {
                 Repeat { e, r, greedy } => Repeat {
                     e: Box::new(try!(simplify(*e))),
@@ -321,7 +394,7 @@ impl Expr {
                 e => e,
             })
         }
-        simp(self, 0)
+        simp(self, 0, nest_limit)
     }
 
     /// Returns true if and only if the expression is required to match from
@@ -1044,7 +1117,7 @@ mod properties;
 
 #[cfg(test)]
 mod tests {
-    use {NEST_LIMIT, CharClass, ClassRange, Expr};
+    use {CharClass, ClassRange, Expr};
 
     fn class(ranges: &[(char, char)]) -> CharClass {
         let ranges = ranges.iter().cloned()
@@ -1060,12 +1133,12 @@ mod tests {
     fn stack_exhaustion() {
         use std::iter::repeat;
 
-        let open: String = repeat('(').take(NEST_LIMIT).collect();
-        let close: String = repeat(')').take(NEST_LIMIT).collect();
+        let open: String = repeat('(').take(200).collect();
+        let close: String = repeat(')').take(200).collect();
         assert!(Expr::parse(&format!("{}a{}", open, close)).is_ok());
 
-        let open: String = repeat('(').take(NEST_LIMIT + 1).collect();
-        let close: String = repeat(')').take(NEST_LIMIT + 1).collect();
+        let open: String = repeat('(').take(200 + 1).collect();
+        let close: String = repeat(')').take(200 + 1).collect();
         assert!(Expr::parse(&format!("{}a{}", open, close)).is_err());
     }
 

regex-syntax/src/parser.rs

@@ -33,7 +33,22 @@ pub struct Parser {
     flags: Flags,
 }
 
-/// An empheral type for representing the expression stack.
+/// Flag state used in the parser.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct Flags {
+    /// i
+    pub casei: bool,
+    /// m
+    pub multi: bool,
+    /// s
+    pub dotnl: bool,
+    /// U
+    pub swap_greed: bool,
+    /// x
+    pub ignore_space: bool,
+}
+
+/// An ephemeral type for representing the expression stack.
 ///
 /// Everything on the stack is either a regular expression or a marker
 /// indicating the opening of a group (possibly non-capturing). The opening
@@ -50,32 +65,16 @@ enum Build {
     },
 }
 
-/// Flag state.
-#[derive(Clone, Copy, Debug)]
-struct Flags {
-    casei: bool,
-    multi: bool,
-    dotnl: bool,
-    swap_greed: bool,
-    ignore_space: bool,
-}
-
 // Primary expression parsing routines.
 impl Parser {
-    pub fn parse(s: &str) -> Result<Expr> {
+    pub fn parse(s: &str, flags: Flags) -> Result<Expr> {
         Parser {
             chars: s.chars().collect(),
             chari: 0,
             stack: vec![],
             caps: 0,
             names: vec![],
-            flags: Flags {
-                casei: false,
-                multi: false,
-                dotnl: false,
-                swap_greed: false,
-                ignore_space: false,
-            },
+            flags: flags,
         }.parse_expr()
     }
 
@@ -1048,7 +1047,6 @@ fn is_valid_capture_char(c: char) -> bool {
 }
 
 /// Returns true if the give character has significance in a regex.
-#[doc(hidden)]
 pub fn is_punct(c: char) -> bool {
     match c {
         '\\' | '.' | '+' | '*' | '?' | '(' | ')' | '|' |
@@ -1134,14 +1132,14 @@ const XDIGIT: Class = &[('0', '9'), ('A', 'F'), ('a', 'f')];
 mod tests {
     use { CharClass, ClassRange, Expr, Repeater, ErrorKind };
     use unicode::regex::{PERLD, PERLS, PERLW};
-    use super::Parser;
-    use super::{LOWER, UPPER};
+    use super::{LOWER, UPPER, Flags, Parser};
 
     static YI: &'static [(char, char)] = &[
         ('\u{a000}', '\u{a48c}'), ('\u{a490}', '\u{a4c6}'),
     ];
 
-    fn p(s: &str) -> Expr { Parser::parse(s).unwrap() }
+    fn p(s: &str) -> Expr { Parser::parse(s, Flags::default()).unwrap() }
+    fn pf(s: &str, flags: Flags) -> Expr { Parser::parse(s, flags).unwrap() }
     fn lit(c: char) -> Expr { Expr::Literal { chars: vec![c], casei: false } }
     fn liti(c: char) -> Expr { Expr::Literal { chars: vec![c], casei: true } }
     fn b<T>(v: T) -> Box<T> { Box::new(v) }
@@ -1539,6 +1537,40 @@ mod tests {
         ]));
     }
 
+    #[test]
+    fn flags_default_casei() {
+        let flags = Flags { casei: true, .. Flags::default() };
+        assert_eq!(pf("a", flags), liti('a'));
+    }
+
+    #[test]
+    fn flags_default_multi() {
+        let flags = Flags { multi: true, .. Flags::default() };
+        assert_eq!(pf("^", flags), Expr::StartLine);
+    }
+
+    #[test]
+    fn flags_default_dotnl() {
+        let flags = Flags { dotnl: true, .. Flags::default() };
+        assert_eq!(pf(".", flags), Expr::AnyChar);
+    }
+
+    #[test]
+    fn flags_default_swap_greed() {
+        let flags = Flags { swap_greed: true, .. Flags::default() };
+        assert_eq!(pf("a+", flags), Expr::Repeat {
+            e: b(lit('a')),
+            r: Repeater::OneOrMore,
+            greedy: false,
+        });
+    }
+
+    #[test]
+    fn flags_default_ignore_space() {
+        let flags = Flags { ignore_space: true, .. Flags::default() };
+        assert_eq!(pf(" a ", flags), lit('a'));
+    }
+
     #[test]
     fn escape_simple() {
         assert_eq!(p(r"\a\f\t\n\r\v"), c(&[
@@ -1907,6 +1939,11 @@ mod tests {
                    Expr::Class(class(&[('x', 'x')]).case_fold().negate()));
     }
 
+    #[test]
+    fn ignore_space_empty() {
+        assert_eq!(p("(?x) "), Expr::Empty);
+    }
+
     #[test]
     fn ignore_space_literal() {
         assert_eq!(p("(?x) a b c"), Expr::Concat(vec![
@@ -1992,7 +2029,7 @@ mod tests {
 
     macro_rules! test_err {
         ($re:expr, $pos:expr, $kind:expr) => {{
-            let err = Parser::parse($re).unwrap_err();
+            let err = Parser::parse($re, Flags::default()).unwrap_err();
             assert_eq!($pos, err.pos);
             assert_eq!($kind, err.kind);
             assert!($re.contains(&err.surround));

regex-syntax/src/properties.rs

@@ -129,7 +129,7 @@ fn parser_never_panics() {
 impl Arbitrary for Expr {
     fn arbitrary<G: Gen>(g: &mut G) -> Expr {
         let e = fix_capture_indices(gen_expr(g, 0, ExprType::Anything));
-        e.simplify().unwrap()
+        e.simplify(200).unwrap()
     }
 
     fn shrink(&self) -> Box<Iterator<Item=Expr>> {
@@ -193,7 +193,7 @@ impl Arbitrary for Expr {
                            }))
             }
         };
-        Box::new(es.map(|e| fix_capture_indices(e).simplify().unwrap()))
+        Box::new(es.map(|e| fix_capture_indices(e).simplify(200).unwrap()))
     }
 }
 

src/re.rs

@@ -35,14 +35,7 @@ const REPLACE_EXPAND: &'static str = r"(?x)
 /// The string returned may be safely used as a literal in a regular
 /// expression.
 pub fn quote(text: &str) -> String {
-    let mut quoted = String::with_capacity(text.len());
-    for c in text.chars() {
-        if syntax::is_punct(c) {
-            quoted.push('\\')
-        }
-        quoted.push(c);
-    }
-    quoted
+    syntax::quote(text)
 }
 
 /// Tests if the given regular expression matches somewhere in the text given.