progress: API and docs refresh

Author: BurntSushi

Cargo.toml

@@ -45,6 +45,15 @@ std = [
   "regex-automata/std",
   "regex-syntax/std",
 ]
+# This feature enables the 'log' crate to emit messages. This is usually
+# only useful for folks working on the regex crate itself, but can be useful
+# if you're trying hard to do some performance hacking on regex patterns
+# themselves. Note that you'll need to pair this with a crate like 'env_logger'
+# to actually emit the log messages somewhere.
+logging = [
+  "aho-corasick?/logging",
+  "regex-automata/logging",
+]
 # The 'use_std' feature is DEPRECATED. It will be removed in regex 2. Until
 # then, it is an alias for the 'std' feature.
 use_std = ["std"]
@@ -64,11 +73,6 @@ perf = [
   "perf-inline",
   "perf-literal",
 ]
-# Enables fast caching. (If disabled, caching is still used, but is slower.)
-# Currently, this feature has no effect. It used to remove the thread_local
-# dependency and use a slower internal cache, but now the default cache has
-# been improved and thread_local is no longer a dependency at all.
-perf-cache = []
 # Enables use of a lazy DFA when possible.
 perf-dfa = ["regex-automata/hybrid"]
 # Enables use of a fully compiled DFA when possible.
@@ -86,6 +90,11 @@ perf-literal = [
   "dep:memchr",
   "regex-automata/perf-literal",
 ]
+# Enables fast caching. (If disabled, caching is still used, but is slower.)
+# Currently, this feature has no effect. It used to remove the thread_local
+# dependency and use a slower internal cache, but now the default cache has
+# been improved and thread_local is no longer a dependency at all.
+perf-cache = []
 
 
 # UNICODE DATA FEATURES
@@ -151,7 +160,7 @@ unstable = ["pattern"]
 # by default if the unstable feature is enabled.
 pattern = []
 
-# For very fast prefix literal matching.
+# For very fast multi-prefix literal matching.
 [dependencies.aho-corasick]
 version = "1.0.0"
 optional = true
@@ -161,22 +170,22 @@ optional = true
 version = "2.5.0"
 optional = true
 
-# For parsing regular expressions.
-[dependencies.regex-syntax]
-path = "regex-syntax"
-version = "0.7.1"
-default-features = false
-
 # For the actual regex engines.
 [dependencies.regex-automata]
 path = "regex-automata"
 version = "0.3.0"
 default-features = false
 features = ["alloc", "syntax", "meta", "nfa-pikevm"]
 
+# For parsing regular expressions.
+[dependencies.regex-syntax]
+path = "regex-syntax"
+version = "0.7.1"
+default-features = false
+
 [dev-dependencies]
 # For examples.
-lazy_static = "1"
+once_cell = "1.17.1"
 # For property based tests.
 quickcheck = { version = "1.0.3", default-features = false }
 # To check README's example

regex-automata/src/hybrid/dfa.rs

@@ -1954,7 +1954,7 @@ impl Cache {
     /// This panics if no search has been started by [`Cache::search_start`].
     #[inline]
     pub fn search_update(&mut self, at: usize) {
-        let mut p =
+        let p =
             self.progress.as_mut().expect("no in-progress search to update");
         p.at = at;
     }

regex-automata/src/meta/regex.rs

@@ -2819,6 +2819,12 @@ impl Config {
     ///
     /// By default, `\n` is the line terminator.
     ///
+    /// **Warning**: This does not change the behavior of `.`. To do that,
+    /// you'll need to configure the syntax option
+    /// [`syntax::Config::line_terminator`](crate::util::syntax::Config::line_terminator)
+    /// in addition to this. Otherwise, `.` will continue to match any
+    /// character other than `\n`.
+    ///
     /// # Example
     ///
     /// ```

regex-automata/src/util/syntax.rs

@@ -147,6 +147,7 @@ pub struct Config {
     multi_line: bool,
     dot_matches_new_line: bool,
     crlf: bool,
+    line_terminator: u8,
     swap_greed: bool,
     ignore_whitespace: bool,
     unicode: bool,
@@ -164,6 +165,7 @@ impl Config {
             multi_line: false,
             dot_matches_new_line: false,
             crlf: false,
+            line_terminator: b'\n',
             swap_greed: false,
             ignore_whitespace: false,
             unicode: true,
@@ -239,6 +241,31 @@ impl Config {
         self
     }
 
+    /// Sets the line terminator for use with `(?u-s:.)` and `(?-us:.)`.
+    ///
+    /// Namely, instead of `.` (by default) matching everything except for `\n`,
+    /// this will cause `.` to match everything except for the byte given.
+    ///
+    /// If `.` is used in a context where Unicode mode is enabled and this byte
+    /// isn't ASCII, then an error will be returned. When Unicode mode is
+    /// disabled, then any byte is permitted, but will return an error if UTF-8
+    /// mode is enabled and it is a non-ASCII byte.
+    ///
+    /// In short, any ASCII value for a line terminator is always okay. But a
+    /// non-ASCII byte might result in an error depending on whether Unicode
+    /// mode or UTF-8 mode are enabled.
+    ///
+    /// Note that if `R` mode is enabled then it always takes precedence and
+    /// the line terminator will be treated as `\r` and `\n` simultaneously.
+    ///
+    /// Note also that this *doesn't* impact the look-around assertions
+    /// `(?m:^)` and `(?m:$)`. That's usually controlled by additional
+    /// configuration in the regex engine itself.
+    pub fn line_terminator(mut self, byte: u8) -> Config {
+        self.line_terminator = byte;
+        self
+    }
+
     /// Enable or disable the "swap greed" flag by default.
     ///
     /// When this is enabled, `.*` (for example) will become ungreedy and `.*?`
@@ -377,6 +404,11 @@ impl Config {
         self.crlf
     }
 
+    /// Returns the line terminator in this syntax configuration.
+    pub fn get_line_terminator(&self) -> u8 {
+        self.line_terminator
+    }
+
     /// Returns whether "swap greed" mode is enabled.
     pub fn get_swap_greed(&self) -> bool {
         self.swap_greed
@@ -410,6 +442,7 @@ impl Config {
             .multi_line(self.multi_line)
             .dot_matches_new_line(self.dot_matches_new_line)
             .crlf(self.crlf)
+            .line_terminator(self.line_terminator)
             .swap_greed(self.swap_greed)
             .ignore_whitespace(self.ignore_whitespace)
             .utf8(self.utf8)
@@ -436,6 +469,7 @@ impl Config {
             .multi_line(self.multi_line)
             .crlf(self.crlf)
             .dot_matches_new_line(self.dot_matches_new_line)
+            .line_terminator(self.line_terminator)
             .swap_greed(self.swap_greed)
             .utf8(self.utf8);
     }

regex-automata/tests/dfa/onepass/suite.rs

@@ -193,4 +193,5 @@ fn config_syntax(test: &RegexTest) -> syntax::Config {
         .case_insensitive(test.case_insensitive())
         .unicode(test.unicode())
         .utf8(test.utf8())
+        .line_terminator(test.line_terminator())
 }

regex-automata/tests/dfa/suite.rs

@@ -391,6 +391,7 @@ fn config_syntax(test: &RegexTest) -> syntax::Config {
         .case_insensitive(test.case_insensitive())
         .unicode(test.unicode())
         .utf8(test.utf8())
+        .line_terminator(test.line_terminator())
 }
 
 /// Execute an overlapping search, and for each match found, also find its

regex-automata/tests/hybrid/suite.rs

@@ -281,6 +281,7 @@ fn config_syntax(test: &RegexTest) -> syntax::Config {
         .case_insensitive(test.case_insensitive())
         .unicode(test.unicode())
         .utf8(test.utf8())
+        .line_terminator(test.line_terminator())
 }
 
 /// Execute an overlapping search, and for each match found, also find its

regex-automata/tests/meta/suite.rs

@@ -196,4 +196,5 @@ fn config_syntax(test: &RegexTest) -> syntax::Config {
         .case_insensitive(test.case_insensitive())
         .unicode(test.unicode())
         .utf8(test.utf8())
+        .line_terminator(test.line_terminator())
 }

regex-automata/tests/nfa/thompson/backtrack/suite.rs

@@ -209,4 +209,5 @@ fn config_syntax(test: &RegexTest) -> syntax::Config {
         .case_insensitive(test.case_insensitive())
         .unicode(test.unicode())
         .utf8(test.utf8())
+        .line_terminator(test.line_terminator())
 }

regex-automata/tests/nfa/thompson/pikevm/suite.rs

@@ -158,4 +158,5 @@ fn config_syntax(test: &RegexTest) -> syntax::Config {
         .case_insensitive(test.case_insensitive())
         .unicode(test.unicode())
         .utf8(test.utf8())
+        .line_terminator(test.line_terminator())
 }

regex-lite/tests/lib.rs

@@ -2,8 +2,6 @@ mod fuzz;
 mod string;
 
 const BLACKLIST: &[&str] = &[
-    // CRLF-aware line anchors aren't supported in regex API yet.
-    "crlf",
     // Custom line terminators aren't supported in regex-lite. We could add it,
     // but it didn't seem worth it.
     "line-terminator",

regex-syntax/src/hir/mod.rs

@@ -88,6 +88,9 @@ pub enum ErrorKind {
     /// This error occurs when translating a pattern that could match a byte
     /// sequence that isn't UTF-8 and `utf8` was enabled.
     InvalidUtf8,
+    /// This error occurs when one uses a non-ASCII byte for a line terminator,
+    /// but where Unicode mode is enabled and UTF-8 mode is disabled.
+    InvalidLineTerminator,
     /// This occurs when an unrecognized Unicode property name could not
     /// be found.
     UnicodePropertyNotFound,
@@ -120,6 +123,7 @@ impl core::fmt::Display for ErrorKind {
         let msg = match *self {
             UnicodeNotAllowed => "Unicode not allowed here",
             InvalidUtf8 => "pattern can match invalid UTF-8",
+            InvalidLineTerminator => "invalid line terminator, must be ASCII",
             UnicodePropertyNotFound => "Unicode property not found",
             UnicodePropertyValueNotFound => "Unicode property value not found",
             UnicodePerlClassNotFound => {
@@ -648,6 +652,12 @@ impl Hir {
                 cls.push(ClassBytesRange::new(b'\0', b'\xFF'));
                 Hir::class(Class::Bytes(cls))
             }
+            Dot::AnyCharExcept(ch) => {
+                let mut cls =
+                    ClassUnicode::new([ClassUnicodeRange::new(ch, ch)]);
+                cls.negate();
+                Hir::class(Class::Unicode(cls))
+            }
             Dot::AnyCharExceptLF => {
                 let mut cls = ClassUnicode::empty();
                 cls.push(ClassUnicodeRange::new('\0', '\x09'));
@@ -661,6 +671,12 @@ impl Hir {
                 cls.push(ClassUnicodeRange::new('\x0E', '\u{10FFFF}'));
                 Hir::class(Class::Unicode(cls))
             }
+            Dot::AnyByteExcept(byte) => {
+                let mut cls =
+                    ClassBytes::new([ClassBytesRange::new(byte, byte)]);
+                cls.negate();
+                Hir::class(Class::Bytes(cls))
+            }
             Dot::AnyByteExceptLF => {
                 let mut cls = ClassBytes::empty();
                 cls.push(ClassBytesRange::new(b'\0', b'\x09'));
@@ -1772,6 +1788,18 @@ pub enum Dot {
     ///
     /// This is equivalent to `(?s-u:.)` and also `(?-u:[\x00-\xFF])`.
     AnyByte,
+    /// Matches the UTF-8 encoding of any Unicode scalar value except for the
+    /// `char` given.
+    ///
+    /// This is equivalent to using `(?u-s:.)` with the line terminator set
+    /// to a particular ASCII byte. (Because of peculiarities in the regex
+    /// engines, a line terminator must be a single byte. It follows that when
+    /// UTF-8 mode is enabled, this single byte must also be a Unicode scalar
+    /// value. That is, ti must be ASCII.)
+    ///
+    /// (This and `AnyCharExceptLF` both exist because of legacy reasons.
+    /// `AnyCharExceptLF` will be dropped in the next breaking change release.)
+    AnyCharExcept(char),
     /// Matches the UTF-8 encoding of any Unicode scalar value except for `\n`.
     ///
     /// This is equivalent to `(?u-s:.)` and also `[\p{any}--\n]`.
@@ -1781,6 +1809,17 @@ pub enum Dot {
     ///
     /// This is equivalent to `(?uR-s:.)` and also `[\p{any}--\r\n]`.
     AnyCharExceptCRLF,
+    /// Matches any byte value except for the `u8` given.
+    ///
+    /// This is equivalent to using `(?-us:.)` with the line terminator set
+    /// to a particular ASCII byte. (Because of peculiarities in the regex
+    /// engines, a line terminator must be a single byte. It follows that when
+    /// UTF-8 mode is enabled, this single byte must also be a Unicode scalar
+    /// value. That is, ti must be ASCII.)
+    ///
+    /// (This and `AnyByteExceptLF` both exist because of legacy reasons.
+    /// `AnyByteExceptLF` will be dropped in the next breaking change release.)
+    AnyByteExcept(u8),
     /// Matches any byte value except for `\n`.
     ///
     /// This is equivalent to `(?-su:.)` and also `(?-u:[[\x00-\xFF]--\n])`.