docs(book): add regular expression validation

Author: DanielleHuisman

book/src/SUMMARY.md

@@ -10,7 +10,7 @@
     - [Email Address](./validations/email-address.md)
     - [Length](./validations/length.md)
     - [Phone Number](./validations/phone-number.md)
-    - [Regex]()
+    - [Regular Expression](./validations/regular-expression.md)
     - [URL](./validations/url.md)
 - [Integrations]()
     - [Serde]()

book/src/introduction.md

@@ -9,7 +9,7 @@ Schema validation.
     - Email address
     - Length
     - Phone number
-    - Regex
+    - Regular expression
     - URL
 - Support for Serde & Utoipa
 

book/src/validations/README.md

@@ -3,4 +3,5 @@
 - [Email Address](./email-address.md)
 - [Length](./length.md)
 - [Phone Number](./phone-number.md)
+- [Regular Expression](./regular-expression.md)
 - [URL](./url.md)

book/src/validations/email-address.md

@@ -7,9 +7,10 @@ Validate a string is an RFC-compliant email address using the [`email_address`](
 
 ```rust
 # extern crate fortifier;
-# use fortifier::Validate;
 #
-##[derive(Validate)]
+use fortifier::Validate;
+
+#[derive(Validate)]
 struct User {
     #[validate(email_address)]
     email_address: String
@@ -43,9 +44,10 @@ See [`Options::allow_display_text`](https://docs.rs/email_address/latest/email_a
 
 ```rust
 # extern crate fortifier;
-# use fortifier::Validate;
 #
-##[derive(Validate)]
+use fortifier::Validate;
+
+#[derive(Validate)]
 struct User<'a> {
     #[validate(email_address(allow_display_text = false))]
     email_address: &'a str
@@ -72,9 +74,10 @@ See [`Options::allow_domain_literal`](https://docs.rs/email_address/latest/email
 
 ```rust
 # extern crate fortifier;
-# use fortifier::Validate;
 #
-##[derive(Validate)]
+use fortifier::Validate;
+
+#[derive(Validate)]
 struct User<'a> {
     #[validate(email_address(allow_domain_literal = false))]
     email_address: &'a str
@@ -101,9 +104,10 @@ See [`Options::minimum_sub_domains`](https://docs.rs/email_address/latest/email_
 
 ```rust
 # extern crate fortifier;
-# use fortifier::Validate;
 #
-##[derive(Validate)]
+use fortifier::Validate;
+
+#[derive(Validate)]
 struct User<'a> {
     #[validate(email_address(minimum_sub_domains = 2))]
     email_address: &'a str

book/src/validations/length.md

@@ -4,9 +4,10 @@ Validate the length of a string or iterable.
 
 ```rust
 # extern crate fortifier;
-# use fortifier::Validate;
 #
-##[derive(Validate)]
+use fortifier::Validate;
+
+#[derive(Validate)]
 struct User {
     #[validate(length(min = 1, max = 256))]
     name: String
@@ -46,9 +47,10 @@ The length should be equal to the specified expression.
 
 ```rust
 # extern crate fortifier;
-# use fortifier::Validate;
 #
-##[derive(Validate)]
+use fortifier::Validate;
+
+#[derive(Validate)]
 struct User {
     #[validate(length(equal = 2))]
     country_code: String
@@ -61,9 +63,10 @@ The length should be equal to or greater than the specified expression.
 
 ```rust
 # extern crate fortifier;
-# use fortifier::Validate;
 #
-##[derive(Validate)]
+use fortifier::Validate;
+
+#[derive(Validate)]
 struct User {
     #[validate(length(min = 1))]
     name: String
@@ -76,9 +79,10 @@ The length should be equal to or less than the specified expression.
 
 ```rust
 # extern crate fortifier;
-# use fortifier::Validate;
 #
-##[derive(Validate)]
+use fortifier::Validate;
+
+#[derive(Validate)]
 struct User {
     #[validate(length(max = 256))]
     name: String

book/src/validations/phone-number.md

@@ -7,9 +7,10 @@ Validate a string is a specification-compliant phone number using the [`phonenum
 
 ```rust
 # extern crate fortifier;
-# use fortifier::Validate;
 #
-##[derive(Validate)]
+use fortifier::Validate;
+
+#[derive(Validate)]
 struct User {
     #[validate(phone_number)]
     phone_number: String
@@ -43,6 +44,7 @@ See [`phonenumber::country::Id`](https://docs.rs/phonenumber/latest/phonenumber/
 
 ```rust
 # extern crate fortifier;
+#
 use fortifier::{PhoneNumberCountry, Validate};
 
 #[derive(Validate)]
@@ -72,6 +74,7 @@ See [`phonenumber::country::Id`](https://docs.rs/phonenumber/latest/phonenumber/
 
 ```rust
 # extern crate fortifier;
+#
 use fortifier::{PhoneNumberCountry, Validate};
 
 #[derive(Validate)]

book/src/validations/regular-expression.md

@@ -0,0 +1,57 @@
+# Regular Expression
+
+> [!NOTE]
+> Requires the `regex` feature.
+
+Validate a string matches a regular expression using the [`regex`](https://docs.rs/regex/latest/regex/) crate.
+
+```rust
+# extern crate fortifier;
+#
+use std::sync::LazyLock;
+
+use fortifier::Validate;
+use regex::Regex;
+
+static COUNTRY_CODE_REGEX: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"[A-Z]{2}").expect("valid regex"));
+
+#[derive(Validate)]
+struct User {
+    #[validate(regex = &COUNTRY_CODE_REGEX)]
+    country_code: String,
+}
+```
+
+## Types
+
+### String
+
+- [`str`](https://doc.rust-lang.org/std/primitive.str.html)
+- [`String`](https://doc.rust-lang.org/std/string/struct.String.html)
+
+Validate the string matches the specified regular expression.
+
+## Options
+
+### `expression`
+
+The regular expression to match against.
+
+The recommended approach for global regular expressions is to use a static [`LazyLock`](https://doc.rust-lang.org/std/sync/struct.LazyLock.html).
+
+```rust
+# extern crate fortifier;
+#
+use std::sync::LazyLock;
+
+use fortifier::Validate;
+use regex::Regex;
+
+static COUNTRY_CODE_REGEX: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"[A-Z]{2}").expect("valid regex"));
+
+#[derive(Validate)]
+struct User {
+    #[validate(regex(expression = &COUNTRY_CODE_REGEX))]
+    country_code: String,
+}
+```

book/src/validations/url.md

@@ -7,9 +7,10 @@ Validate a string is a specification-compliant URL using the [`url`](https://doc
 
 ```rust
 # extern crate fortifier;
-# use fortifier::Validate;
 #
-##[derive(Validate)]
+use fortifier::Validate;
+
+#[derive(Validate)]
 struct User {
     #[validate(url)]
     url: String