compile-time check of regexes, utility macros

Author: Canop

CHANGELOG.md

@@ -1,3 +1,10 @@
+<a name="v2.0.0"></a>
+### v2.0.0 - 2021-05-17
+- regular expressions are now checked at compile time
+- regex_is_match!
+- regex_find!
+- regex_captures!
+
 <a name="v1.1.0"></a>
 ### v1.1.0 - 2021-05-08
 - no more complementary import needed

Cargo.toml

@@ -1,9 +1,9 @@
 [package]
 name = "lazy-regex"
-version = "1.1.0"
+version = "2.0.0"
 authors = ["Canop <[email protected]>"]
 edition = "2018"
-description = "a macro to reduce regex creation boilerplate"
+description = "lazy static regular expressions checked at compile time"
 keywords = ["macro", "lazy", "static", "regex"]
 license = "MIT"
 categories = ["text-processing"]
@@ -12,5 +12,12 @@ readme = "README.md"
 
 [dependencies]
 once_cell = "1.7"
-regex = "1.4"
+regex = "1.5"
 
+[dependencies.proc_macros]
+package = "lazy-regex-proc_macros"
+path = "src/proc_macros"
+version = "2.0.0"
+
+[workspace]
+members = ["src/proc_macros", "examples/regexes"]

README.md

@@ -1,53 +1,82 @@
 # lazy-regex
-a macro for when you're tired of the regex creation boilerplate
 
-## What it does
+Use the  `regex!` macro to build regexes:
 
-It's a shortcut to write static lazily compiled regular expressions as is usually done with lazy_static or once_cell.
+* they're checked at compile time
+* they're wrapped in `once_cell` lazy static initializers so that they're compiled only once
+* they can hold flags with a familiar suffix syntax: `let case_insensitive_regex = regex!("ab*"i);`
+* regex creation is less verbose
 
-It lets you replace
+This macro builds normal instances of `regex::Regex` so all the usual features are available.
 
+You may also use shortcut macros for testing a match or capturing groups as substrings:
+
+* `regex_is_match!`
+* `regex_find!`
+* `regex_captures!`
+
+# Build Regexes
 
 ```
-fn some_helper_function(text: &str) -> bool {
-    lazy_static! {
-        static ref RE: Regex = Regex::new("...").unwrap();
-    }
-    RE.is_match(text)
-}
-```
+use lazy_regex::regex;
 
-with
+// build a simple regex
+let r = regex!("sa+$");
+assert_eq!(r.is_match("Saa"), false);
 
+// build a regex with flag(s)
+let r = regex!("sa+$"i);
+assert_eq!(r.is_match("Saa"), true);
 
-```
-fn some_helper_function(text: &str) -> bool {
-    regex!("...").is_match(text)
-}
-```
+// supported regex flags: 'i', 'm', 's', 'x', 'U'
+// see https://docs.rs/regex/1.5.4/regex/struct.RegexBuilder.html
 
-The first code comes from the regex documentation.
+// you can use a raw literal
+let r = regex!(r#"^"+$"#);
+assert_eq!(r.is_match("\"\""), true);
 
+// or a raw literal with flag(s)
+let r = regex!(r#"^\s*("[a-t]*"\s*)+$"#i);
+assert_eq!(r.is_match(r#" "Aristote" "Platon" "#), true);
 
-## FAQ
+// this line wouldn't compile:
+// let r = regex!("(unclosed");
 
-### Is it really useful ?
+```
 
-Regarding the binary, it's as using lazy_static or once_cell.
-It just makes some code a little easier to read. You're judge.
+# Test a match
 
-### Can I have several `regex!` in the same function ? On the same Line ?
+```
+use lazy_regex::regex_is_match;
 
-Yes, no problem.
+let b = regex_is_match!("[ab]+", "car");
+assert_eq!(b, true);
+```
 
-### It hides the `unwrap()`, isn't it concerning ?
+# Extract a value
 
-Not so much in my opinion as the macro only accepts a litteral: you won't hide a failure occuring on a dynamic string.
+```
+use lazy_regex::regex_find;
 
-### I'd like to have flags too
+let f_word = regex_find!(r#"\bf\w+\b"#, "The fox jumps.").unwrap();
+assert_eq!(f_word, "fox");
+```
 
-You mean something like `regex!("somestring", "i")` ? Cool. I was just waiting for somebody's else to ask for it. Create an issue and I'll see if I can easily wrap `RegexBuilder` to handle flags ala JavaScript.
+# Capture
 
-### What's the licence ?
+```
+use lazy_regex::regex_captures;
+
+let (_, letter) = regex_captures!(r#"([a-z])\d+"#i, "form A42").unwrap();
+assert_eq!(letter, "A");
+
+let (whole, name, version) = regex_captures!(
+    r#"(\w+)-([0-9.]+)"#, // a literal regex
+    "This is lazy_regex-2.0!", // any expression
+).unwrap();
+assert_eq!(whole, "lazy_regex-2.0");
+assert_eq!(name, "lazy_regex");
+assert_eq!(version, "2.0");
+```
 
-It's MIT. No attribution is needed.
+The size of the tupple is checked at compile time and ensures you have the right number of capturing groups.

examples/regexes/.gitignore

@@ -0,0 +1,10 @@
+# Generated by Cargo
+# will have compiled files and executables
+/target/
+
+# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
+# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
+Cargo.lock
+
+# These are backup files generated by rustfmt
+**/*.rs.bk

examples/regexes/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "regexes"
+version = "1.0.0"
+authors = ["dystroy <[email protected]>"]
+edition = "2018"
+description = "An example for lazy-regex"
+license = "MIT"
+readme = "README.md"
+
+[dependencies]
+lazy-regex = { path = "../.." }
+regex = "1.4"

examples/regexes/README.md

@@ -0,0 +1,22 @@
+
+You may launch this example in this repository with
+
+```
+cargo run
+```
+
+and that would do nothing.
+
+If you want some log, set the env var `SMALL_APP_LOG`, for example with
+
+```
+SMALL_APP_LOG=info cargo run
+```
+
+or
+
+```
+SMALL_APP_LOG=debug cargo run
+```
+
+A `small-app.log` file would thus be created.

examples/regexes/src/main.rs

@@ -0,0 +1,55 @@
+use {
+    lazy_regex::*,
+};
+
+fn example_builds() {
+
+    // build a simple regex
+    let r = regex!("sa+$");
+    assert_eq!(r.is_match("Saa"), false);
+
+    // build a regex with flag(s)
+    let r = regex!("sa+$"i);
+    assert_eq!(r.is_match("Saa"), true);
+
+    // you can use a raw literal
+    let r = regex!(r#"^"+$"#);
+    assert_eq!(r.is_match("\"\""), true);
+
+    // and a raw literal with flag(s)
+    let r = regex!(r#"^\s*("[a-t]*"\s*)+$"#i);
+    assert_eq!(r.is_match(r#" "Aristote" "Platon" "#), true);
+
+    // this line wouldn't compile:
+    // let r = regex!("(unclosed");
+
+}
+
+fn example_is_match() {
+    let b = regex_is_match!("[ab]+", "car");
+    assert_eq!(b, true);
+}
+
+fn example_captures() {
+    let (whole, name, version) = regex_captures!(
+        r#"(\w+)-([0-9.]+)"#, // a literal regex
+        "This is lazy_regex-2.0!", // any expression
+    ).unwrap();
+    assert_eq!(whole, "lazy_regex-2.0");
+    assert_eq!(name, "lazy_regex");
+    assert_eq!(version, "2.0");
+}
+
+fn main() {
+
+    // the regular expressions will be built only once
+    for _ in 0..10 {
+        example_builds();
+    }
+
+    example_is_match();
+
+    for _ in 0..10 {
+        example_captures();
+    }
+}

src/lib.rs

@@ -1,38 +1,97 @@
 /*!
 
-This crate introduces the `regex!` macro which is a shortcut to write static lazily compiled regular expressions as is usually done with lazy_static or once_cell.
+Use the  [regex!] macro to build regexes:
 
-It lets you replace
+* they're checked at compile time
+* they're wrapped in `once_cell` lazy static initializers so that they're compiled only once
+* they can hold flags with a familiar suffix syntax: `let case_insensitive_regex = regex!("ab*"i);`
+* regex creation is less verbose
 
+This macro builds normal instances of [regex::Regex] so all the usual features are available.
 
-```not-executable
-fn some_helper_function(text: &str) -> bool {
-    lazy_static! {
-        static ref RE: Regex = Regex::new("...").unwrap();
-    }
-    RE.is_match(text)
-}
+You may also use shortcut macros for testing a match or capturing groups as substrings:
 
+* [regex_is_match!]
+* [regex_find!]
+* [regex_captures!]
+
+# Build Regexes
+
+```
+use lazy_regex::regex;
+
+// build a simple regex
+let r = regex!("sa+$");
+assert_eq!(r.is_match("Saa"), false);
+
+// build a regex with flag(s)
+let r = regex!("sa+$"i);
+assert_eq!(r.is_match("Saa"), true);
+
+
+// you can use a raw literal
+let r = regex!(r#"^"+$"#);
+assert_eq!(r.is_match("\"\""), true);
+
+// or a raw literal with flag(s)
+let r = regex!(r#"^\s*("[a-t]*"\s*)+$"#i);
+assert_eq!(r.is_match(r#" "Aristote" "Platon" "#), true);
+
+// this line wouldn't compile because the regex is invalid:
+// let r = regex!("(unclosed");
+
+```
+Supported regex flags: 'i', 'm', 's', 'x', 'U'.
+
+See [regex::RegexBuilder].
+
+# Test a match
+
+```
+use lazy_regex::regex_is_match;
+
+let b = regex_is_match!("[ab]+", "car");
+assert_eq!(b, true);
+```
+
+# Extract a value
+
+```
+use lazy_regex::regex_find;
+
+let f_word = regex_find!(r#"\bf\w+\b"#, "The fox jumps.").unwrap();
+assert_eq!(f_word, "fox");
 ```
 
-with
+# Capture
 
+```
+use lazy_regex::regex_captures;
+
+let (_, letter) = regex_captures!(r#"([a-z])\d+"#i, "form A42").unwrap();
+assert_eq!(letter, "A");
 
-```not-executable
-fn some_helper_function(text: &str) -> bool {
-    regex!("...").is_match(text)
-}
+let (whole, name, version) = regex_captures!(
+    r#"(\w+)-([0-9.]+)"#, // a literal regex
+    "This is lazy_regex-2.0!", // any expression
+).unwrap();
+assert_eq!(whole, "lazy_regex-2.0");
+assert_eq!(name, "lazy_regex");
+assert_eq!(version, "2.0");
 ```
 
+There's no limit to the size of the tupple.
+It's checked at compile time to ensure you have the right number of capturing groups.
+
 */
 
-pub use once_cell;
+pub use {
+    once_cell,
+    proc_macros::{
+        regex,
+        regex_captures,
+        regex_find,
+        regex_is_match,
+    },
+};
 
-#[macro_export]
-macro_rules! regex {
-    ($s: literal) => {{
-        use lazy_regex::once_cell::sync::OnceCell;
-        static RE: OnceCell::<regex::Regex> = OnceCell::new();
-        RE.get_or_init(|| regex::Regex::new($s).unwrap())
-    }};
-}

src/proc_macros/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "lazy-regex-proc_macros"
+version = "2.0.0"
+authors = ["Canop <[email protected]>"]
+edition = "2018"
+
+[dependencies]
+syn = "1.0"
+proc-macro2 = "1.0"
+quote = "1.0"
+regex = "1.4"
+
+[lib]
+proc-macro = true
+path = "mod.rs"