api: add regex! macro for lazy compilation

Add a wrapper around `regex_automata`'s  `Lazy` as a simple way to
construct a `Regex` that is compiled once but used multiple times.
Sample usage:

    if regex!(r"\d+").is_match("123") { /* ... */ }
    let re: &Regex = regex!(r"\d+");

This idea has been discussed in #709. To address a few of the concerns
from that issue:

1. More than 1 `regex!` can be used in a block (for the anonymous
   version, the name is in a scope).
2. Using `regex_automata`'s `Lazy` means there are no MSRV concerns, and
   this works without std.
3. There is no compile-time checking. The docs make it clear that
   `regex!` should not be used with invalid regex and suggest enabling
   the clippy lint, leaving the door somewhat open for e.g. a `const fn`
   syntax validator in the future (though this seems unlikely).

A `regex::bytes::regex!` version is also included.

Closes #709

Author: tgross35

CHANGELOG.md

@@ -1,4 +1,37 @@
-1.12.4 (2025-06-09)
+1.13.0 (2026-07-09)
+===================
+This release includes a new API, a `regex!` macro, for lazy compilation of
+a regex from a string literal. If you use regexes a lot, it's likely you've
+already written one exactly like it. The new macro can be used like this:
+
+```rust
+use regex::regex;
+
+fn is_match(line: &str) -> bool {
+    // The regex will be compiled approximately once and reused automatically.
+    // This avoids the footgun of using `Regex::new` here, which would
+    // guarantee that it would be compiled every time this routine is called.
+    // This would likely make this routine much slower than it needs to be.
+    regex!(r"bar|baz").is_match(line)
+}
+
+let hay = "\
+path/to/foo:54:Blue Harvest
+path/to/bar:90:Something, Something, Something, Dark Side
+path/to/baz:3:It's a Trap!
+";
+
+let matches = hay.lines().filter(|line| is_match(line)).count();
+assert_eq!(matches, 2);
+```
+
+Improvements:
+
+* [#709](https://github.com/rust-lang/regex/issues/709):
+Add a new `regex!` macro for efficient and automatic reuse of a compiled regex.
+
+
+1.12.4 (2026-06-09)
 ===================
 This release includes a performance optimization for compilation of regexes
 with very large character classes.
@@ -9,7 +42,7 @@ Improvements:
 Avoid re-canonicalizing the entire interval set when pushing new class ranges.
 
 
-1.12.3 (2025-02-03)
+1.12.3 (2026-02-03)
 ===================
 This release excludes some unnecessary things from the archive published to
 crates.io. Specifically, fuzzing data and various shell scripts are now

README.md

@@ -105,8 +105,11 @@ fn main() {
 Specifically, in this example, the regex will be compiled when it is used for
 the first time. On subsequent uses, it will reuse the previous compilation.
 
+The [`regex!`] macro can also be used, which handles lazy compilation.
+
 [`std::sync::LazyLock`]: https://doc.rust-lang.org/std/sync/struct.LazyLock.html
 [`once_cell`]: https://crates.io/crates/once_cell
+[`regex!`]: https://docs.rs/regex/*/regex/macro.regex.html
 
 ### Usage: match regular expressions on `&[u8]`
 

src/bytes.rs

@@ -89,3 +89,7 @@ In general, one should expect performance on `&[u8]` to be roughly similar to
 performance on `&str`.
 */
 pub use crate::{builders::bytes::*, regex::bytes::*, regexset::bytes::*};
+
+// Re-export the public but hidden macro to make it usable as `bytes::regex`.
+#[doc(inline)]
+pub use crate::__bytes_regex as regex;

src/lib.rs

@@ -35,6 +35,31 @@ assert_eq!(results, vec![
 # Ok::<(), Box<dyn std::error::Error>>(())
 ```
 
+Or, make use of the [`regex!`](crate::regex) macro to compile the regex once
+and re-use that same regex automatically. This is useful inside functions.
+For example:
+
+```rust
+use regex::regex;
+
+fn is_match(line: &str) -> bool {
+    // The regex will be compiled approximately once and reused automatically.
+    // This avoids the footgun of using `Regex::new` here, which would
+    // guarantee that it would be compiled every time this routine is called.
+    // This would likely make this routine much slower than it needs to be.
+    regex!(r"bar|baz").is_match(line)
+}
+
+let hay = "\
+path/to/foo:54:Blue Harvest
+path/to/bar:90:Something, Something, Something, Dark Side
+path/to/baz:3:It's a Trap!
+";
+
+let matches = hay.lines().filter(|line| is_match(line)).count();
+assert_eq!(matches, 2);
+```
+
 # Overview
 
 The primary type in this crate is a [`Regex`]. Its most important methods are
@@ -498,6 +523,8 @@ Specifically, in this example, the regex will be compiled when it is used for
 the first time. On subsequent uses, it will reuse the previously built `Regex`.
 Notice how one can define the `Regex` locally to a specific function.
 
+The [`regex!`] macro can also be used, which handles lazy compilation.
+
 [`std::sync::LazyLock`]: https://doc.rust-lang.org/std/sync/struct.LazyLock.html
 [`once_cell`]: https://crates.io/crates/once_cell
 
@@ -1351,3 +1378,9 @@ mod regexset;
 pub fn escape(pattern: &str) -> alloc::string::String {
     regex_syntax::escape(pattern)
 }
+
+/// Public-but-unstable API for macro support.
+#[doc(hidden)]
+pub mod __private {
+    pub use regex_automata::util::lazy::Lazy;
+}

src/regex/bytes.rs

@@ -4,6 +4,59 @@ use regex_automata::{meta, util::captures, Input, PatternID};
 
 use crate::{bytes::RegexBuilder, error::Error};
 
+/// A convenient way to construct regex patterns from string literals.
+///
+/// This macro can be used to construct reusable instances of [`Regex`] with
+/// reduced boilerplate. The constructed `Regex` is stored in a static so the
+/// pattern is compiled approximately once, even when called multiple times.
+///
+/// There is *no compile-time checking of patterns* with `regex!`. Instead,
+/// invalid patterns will panic the first time the regex is used. Invalid
+/// patterns should still not be used with `regex!`; if compile-time checking
+/// becomes feasible in the future, it may be added within a non-semver-breaking
+/// release. In the meantime, consider enabling [`clippy::invalid_regex`].
+///
+/// # Examples
+///
+/// ```
+/// use regex::bytes::{Regex, regex};
+///
+/// assert!(regex!("[a-z]").is_match(b"a"));
+/// assert!(regex!("(inconceivable!|classic blunder)").is_match(b"inconceivable!"));
+///
+/// let re: &Regex = regex!(r"(\d{3})-(\d{4})");
+/// assert_eq!(&re.captures(b"867-5309").unwrap()[1], b"867");
+/// ```
+///
+/// An invalid pattern will panic when it is first used:
+///
+/// ```should_panic
+/// use regex::bytes::regex;
+///
+/// let re = regex!("invalid -> ("); // no panic here
+/// re.is_match(b"invalid -> (");    // panic!
+/// ```
+///
+/// [`clippy::invalid_regex`]: https://rust-lang.github.io/rust-clippy/master/#invalid_regex
+// `macro_export` always makes the macro available at crate root. We hide
+// from documentation there and instead re-export it in `crate::bytes` to get
+// the desired behavior.
+#[macro_export]
+#[doc(hidden)]
+macro_rules! __bytes_regex {
+    ($re:literal) => {{
+        static REGEX: $crate::__private::Lazy<$crate::bytes::Regex> =
+            $crate::__private::Lazy::new(|| {
+                $crate::bytes::Regex::new($re).expect("invalid regex pattern")
+            });
+
+        // Coerce returned type from `&Lazy<Regex>` to `&Regex` to avoid making the
+        // inner type public.
+        let re: &$crate::bytes::Regex = &REGEX;
+        re
+    }};
+}
+
 /// A compiled regular expression for searching Unicode haystacks.
 ///
 /// A `Regex` can be used to search haystacks, split haystacks into substrings

src/regex/string.rs

@@ -4,6 +4,55 @@ use regex_automata::{meta, util::captures, Input, PatternID};
 
 use crate::{error::Error, RegexBuilder};
 
+/// A convenient way to construct regex patterns from string literals.
+///
+/// This macro can be used to construct reusable instances of [`Regex`] with
+/// reduced boilerplate. The constructed `Regex` is stored in a static so the
+/// pattern is compiled approximately once, even when called multiple times.
+///
+/// There is *no compile-time checking of patterns* with `regex!`. Instead,
+/// invalid patterns will panic the first time the regex is used. Invalid
+/// patterns should still not be used with `regex!`; if compile-time checking
+/// becomes feasible in the future, it may be added within a non-semver-breaking
+/// release. In the meantime, consider enabling [`clippy::invalid_regex`].
+///
+/// # Examples
+///
+/// ```
+/// use regex::{Regex, regex};
+///
+/// assert!(regex!("[a-z]").is_match("a"));
+/// assert!(regex!("(inconceivable!|classic blunder)").is_match("inconceivable!"));
+///
+/// let re: &Regex = regex!(r"(\d{3})-(\d{4})");
+/// assert_eq!(&re.captures("867-5309").unwrap()[1], "867");
+/// ```
+///
+/// An invalid pattern will panic when it is first used:
+///
+/// ```should_panic
+/// use regex::regex;
+///
+/// let re = regex!("invalid -> ("); // no panic here
+/// re.is_match("invalid -> (");     // panic!
+/// ```
+///
+/// [`clippy::invalid_regex`]: https://rust-lang.github.io/rust-clippy/master/#invalid_regex
+#[macro_export]
+macro_rules! regex {
+    ($re:literal) => {{
+        static REGEX: $crate::__private::Lazy<$crate::Regex> =
+            $crate::__private::Lazy::new(|| {
+                $crate::Regex::new($re).expect("invalid regex pattern")
+            });
+
+        // Coerce returned type from `&Lazy<Regex>` to `&Regex` to avoid making the
+        // inner type public.
+        let re: &$crate::Regex = &REGEX;
+        re
+    }};
+}
+
 /// A compiled regular expression for searching Unicode haystacks.
 ///
 /// A `Regex` can be used to search haystacks, split haystacks into substrings

tests/misc.rs

@@ -1,10 +1,4 @@
-use regex::Regex;
-
-macro_rules! regex {
-    ($pattern:expr) => {
-        regex::Regex::new($pattern).unwrap()
-    };
-}
+use regex::{bytes, regex, Regex};
 
 #[test]
 fn unclosed_group_error() {
@@ -141,3 +135,27 @@ fn dfa_handles_pathological_case() {
     };
     assert!(re.is_match(&text));
 }
+
+#[test]
+fn re_macro() {
+    // >1 regex! should work in a scope since the static is in a block
+    assert!(regex!("foo").is_match("foo"));
+    assert!(regex!("bar").is_match("bar"));
+
+    let re: &Regex = regex!("foo");
+    ensure_static(re);
+
+    fn ensure_static(_re: &'static Regex) {}
+}
+
+#[test]
+fn re_bytes_macro() {
+    // >1 regex! should work in a scope since the static is in a block
+    assert!(bytes::regex!("foo").is_match(b"foo"));
+    assert!(bytes::regex!("bar").is_match(b"bar"));
+
+    let re: &bytes::Regex = bytes::regex!("foo");
+    ensure_static(re);
+
+    fn ensure_static(_re: &'static bytes::Regex) {}
+}