From c44ff6803eade320955f784eb65084006024564f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABlle=20Huisman?= Date: Sun, 14 Dec 2025 17:08:46 +0100 Subject: [PATCH] docs(book): add regular expression validation --- .github/workflows/website.yml | 8 +-- book/src/SUMMARY.md | 2 +- book/src/introduction.md | 2 +- book/src/validations/README.md | 1 + book/src/validations/email-address.md | 20 +++++--- book/src/validations/length.md | 20 +++++--- book/src/validations/phone-number.md | 7 ++- book/src/validations/regular-expression.md | 59 ++++++++++++++++++++++ book/src/validations/url.md | 5 +- 9 files changed, 98 insertions(+), 26 deletions(-) create mode 100644 book/src/validations/regular-expression.md diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml index 827ad18..13fb25b 100644 --- a/.github/workflows/website.yml +++ b/.github/workflows/website.yml @@ -29,11 +29,11 @@ jobs: - name: Install mdBook run: cargo binstall --force -y mdbook mdbook-tabs - - name: Clean Fortifier - run: cargo clean -p fortifier + - name: Clean dependencies + run: cargo clean -p fortifier -p regex - - name: Build Fortifier - run: cargo build -p fortifier --features all-validations + - name: Build dependencies + run: cargo build -p fortifier --features all-validations -p regex - name: Run tests run: mdbook test -L ../target/debug/deps diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index f2d282a..dd1f01e 100644 --- a/book/src/SUMMARY.md +++ b/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]() diff --git a/book/src/introduction.md b/book/src/introduction.md index 54127ae..1b93cbe 100644 --- a/book/src/introduction.md +++ b/book/src/introduction.md @@ -9,7 +9,7 @@ Schema validation. - Email address - Length - Phone number - - Regex + - Regular expression - URL - Support for Serde & Utoipa diff --git a/book/src/validations/README.md b/book/src/validations/README.md index 7053418..50591da 100644 --- a/book/src/validations/README.md +++ b/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) diff --git a/book/src/validations/email-address.md b/book/src/validations/email-address.md index 4641e53..cc2e7e5 100644 --- a/book/src/validations/email-address.md +++ b/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 diff --git a/book/src/validations/length.md b/book/src/validations/length.md index 593ead1..3eb98e1 100644 --- a/book/src/validations/length.md +++ b/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 diff --git a/book/src/validations/phone-number.md b/book/src/validations/phone-number.md index 11a785c..da22ec8 100644 --- a/book/src/validations/phone-number.md +++ b/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)] diff --git a/book/src/validations/regular-expression.md b/book/src/validations/regular-expression.md new file mode 100644 index 0000000..f3a2d66 --- /dev/null +++ b/book/src/validations/regular-expression.md @@ -0,0 +1,59 @@ +# 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; +# extern crate regex; +# +use std::sync::LazyLock; + +use fortifier::Validate; +use regex::Regex; + +static COUNTRY_CODE_REGEX: LazyLock = 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; +# extern crate regex; +# +use std::sync::LazyLock; + +use fortifier::Validate; +use regex::Regex; + +static COUNTRY_CODE_REGEX: LazyLock = LazyLock::new(|| Regex::new(r"[A-Z]{2}").expect("valid regex")); + +#[derive(Validate)] +struct User { + #[validate(regex(expression = &COUNTRY_CODE_REGEX))] + country_code: String, +} +``` diff --git a/book/src/validations/url.md b/book/src/validations/url.md index ad8c147..18beed5 100644 --- a/book/src/validations/url.md +++ b/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