vouched-derive 0.1.0

Proc macros for vouched.
Documentation

vouched

vouched provides a derive macro for tuple-struct newtypes whose values are vouched for after validation.

Install

[dependencies]
vouched = "0.1"

Quick start

use vouched::Vouched;

#[derive(Debug, PartialEq, Eq, Vouched)]
#[vouched(len(1..=64), chars('a'..='z', '0'..='9', '_'))]
struct Slug(String);
impl Slug {
    fn as_str(&self) -> &str {
        &self.0
    }
}

let slug = Slug::try_from("hello_123".to_owned())?;
assert_eq!(slug.as_str(), "hello_123");

Examples

See crates/vouched/examples for more detailed, executable examples.

cargo run -p vouched --example <name>

Supported Markers

  • len(range): validates string length by Unicode scalar value count. Leading and trailing whitespace count.
  • range(range): validates numeric bounds for i8, i16, i32, i64, i128, u8, u16, u32, u64, and u128.
  • chars(...): validates allowed characters by string literal, char literal, or inclusive char range.
  • cast(try_from(...)): adds extra fallible integer TryFrom implementations before validation.

len(...), range(...), and chars(...) can each be specified at most once. To combine character sets, put all sources in one marker, such as chars('a'..='z', '0'..='9', '_').

range(...) type-checks the bound expressions against the inner integer type and generates runtime validation. It does not guarantee the range is non-empty; for example, a contradictory range remains the user's constraint.

Validation returns the first error encountered. When multiple markers or multiple constraints fail, the exact evaluation order is an implementation detail. The implementation may move expensive whole-string validations later to reduce validation cost.

Generated API

#[derive(Vouched)] generates TryFrom impls, a <TypeName>VouchedError enum, Display, core::error::Error, and vouched::VouchedError. The default error enum visibility matches the derived type visibility. Use #[vouched(error(name = CustomErrorName, vis = pub(crate)), ...)] to override the generated error enum name or visibility. Rust visibility rules still apply: if a public derived type exposes a less-visible error type through TryFrom::Error, rustc rejects the generated impl.

Feature flags

features crate mode available
default / std std derive macro, core errors, generated errors, erased Error
alloc without default no_std + alloc derive macro, core errors, generated errors, erased Error
no default features no_std derive macro, core errors, generated errors; no erased Error
valuable no_std + alloc all alloc items plus valuable::Valuable impls for structured error observation

std enables alloc. valuable also enables alloc.

Limitations

  • Only tuple structs with exactly one field are supported.
  • The default generated error enum name is <TypeName>VouchedError; use error(name = CustomErrorName) to avoid local name collisions.
  • cast(try_from(...)) supports only i8, i16, i32, i64, i128, u8, u16, u32, u64, and u128.
  • range(...) supports the same integer types as cast(try_from(...)); isize, usize, floats, and custom ordered types are not supported.
  • len(...) works on AsRef<str> values and measures untrimmed Unicode scalar values, not bytes.
  • chars(...) works on AsRef<str> values and validates untrimmed Unicode scalar values.

Versioning

While vouched is in 0.x, breaking changes to public APIs, generated APIs, or documented behavior require a minor version bump. Patch releases are limited to bug fixes, documentation updates, and non-breaking additions.

The current MSRV is Rust 1.86. MSRV changes are not shipped in patch releases; while vouched is in 0.x, an MSRV bump is treated as a possibly-breaking compatibility change and shipped in a minor release with release notes.

After 1.0.0, vouched follows SemVer for public APIs and documented behavior.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.