vale 0.0.0

A simple entity validation library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

#![cfg_attr(feature = "rocket", feature(decl_macro, proc_macro_hygiene))]
#![forbid(unsafe_code, missing_docs)]

//! Vale stands for Valid Entity, and is a simple library that provides entity validation through
//! either annotations, or through a Fluent-style implementation. At the core of the library is the
//! `vale::Validate` trait, which implies that a piece of data can be validated. The library also
//! offers supoort for the `rocket` webframework. If support for more webframeworks is desired, it
//! should be fairly trivial to implement support for those frameworks.
//!
//! ### Example
//! This example shows how to derive the validation trait
//! ```rust
//! # fn get_entity() -> Entity {
//! #     Entity::default()
//! # }
//! use vale::Validate;
//!
//! # #[derive(Default)]
//! #[derive(Validate)]
//! struct Entity {
//!     #[validate(gt(0))]
//!     id: i32,
//!     #[validate(len_lt(5), with(add_element))]
//!     others: Vec<i32>,
//!     #[validate(eq("hello world"))]
//!     msg: String,
//! }
//!
//! fn add_element(v: &mut Vec<i32>) -> bool {
//!     v.push(3);
//!     true
//! }
//!
//! fn main() {
//!     let mut e = get_entity();
//!     if let Err(errs) = e.validate() {
//!         println!("The following validations failed: {:?}", errs);
//!     }
//! }
//! ```
//!
//! It is also possible to use fluent-style validation:
//! ```rust
//! struct Entity {
//!     id: i32,
//!     others: Vec<i32>,
//!     msg: String,
//! }
//!
//! impl vale::Validate for Entity {
//!     #[vale::ruleset]
//!     fn validate(&mut self) -> vale::Result {
//!         vale::rule!(self.id > 0, "`id` is nonpositive!");
//!         vale::rule!(self.others.len() < 5, "Too many others");
//!     }
//! }
//! ```

#[cfg(feature = "rocket")]
mod rocket_impls;

#[cfg(feature = "rocket")]
pub use rocket_impls::Valid;
/// The rule macro is used to create new rules that dictate how a field of the validated entity
/// should be tranformed and validated.
///
/// ### Example
/// ```rust
/// struct MyStruct {
///     a: i32,
/// }
///
/// impl vale::Validate for MyStruct {
///     #[vale::ruleset]
///     fn validate(&mut self) -> vale::Result {
///         vale::rule!(self.a == 3, "A was not three!");
///         // if the second argument is omitted, a standard error message is returned.
///         vale::rule!(self.a % 3 == 0);
///     }
/// } 
/// ```
pub use vale_derive::rule;
/// Use this macro to annotate yout implementation of `vale::Validate` for your struct to help
/// write the error reporting boilerplate for you. See the documentation of `vale::rule` for usage
/// examples.
pub use vale_derive::ruleset;
/// A proc macro used to implement `Validate` automatically for a struct.
/// 
/// There are a couple of options for validating a structure. The are listed below:
///
/// * `lt`: Check if the value is less than the provided argument,
/// * `eq`: check if the value is equal to the provided argument,
/// * `gt`: check if the value is greater than the provided argument,
/// * `neq`: check if the `len()` of the value is not equal to the provided argument,
/// * `len_lt`: Check if the `len()` of the value is less than the provided argument,
/// * `len_eq`: check if the `len()` of the value is equal to the provided argument,
/// * `len_gt`: check if the `len()` of the value is greater than the provided argument,
/// * `len_neq`: check if the `len()` of the value is not equal to the provided argument,
/// * `with`: Rrn the provided function to perform validation,
/// * `trim`: always succeeds, and trims the string that is inputted,
/// * `to_lower_case`: convert the provided value to lowercase.
///
/// ### Example
/// ```rust,no_run
/// # use vale::Validate;
/// #[derive(vale::Validate)]
/// struct Struct {
///     #[validate(gt(10))]
///     value: u32,
///     #[validate(len_gt(3))]
///     string: String,
///     #[validate(eq(true))]
///     boolean: bool,
///     #[validate(with(is_even))]
///     even_value: i32,
///     #[validate(trim, len_lt(10), to_lower_case)]
///     transformer: String,
///     #[validate(len_lt(10), trim)]
///     transfailer: String,
/// }
///
/// fn is_even(num: &mut i32) -> bool {
///     *num % 2 == 0
/// }
/// ```
pub use vale_derive::Validate;

/// A type alias for the `Result` returned by the `Validate::validate` function.
pub type Result = std::result::Result<(), Vec<String>>;

/// The core trait of this library. Any entity that implements `Validate` can be validated by
/// running the `validate` function. This will either return an `Ok(())`, or an `Err` containing a
/// list of errors that were triggered during validation. It is also possible for `validate` to
/// perform tranformations on the entity that is being validated.
pub trait Validate {
    /// Performs the validation.
    fn validate(&mut self) -> Result;
}