1 //! ## Validation 2 //! 3 //! 1. [Enumerated values](#enumerated-values) 4 //! 2. [Validated values](#validated-values) 5 //! 3. [Argument Relations](#argument-relations) 6 //! 4. [Custom Validation](#custom-validation) 7 //! 8 //! An appropriate default parser/validator will be selected for the field's type. See 9 //! [`value_parser!`][crate::value_parser!] for more details. 10 //! 11 //! ### Enumerated values 12 //! 13 //! If you have arguments of specific values you want to test for, you can use the 14 //! [`PossibleValuesParser`][crate::builder::PossibleValuesParser] or [`Arg::value_parser(["val1", 15 //! ...])`][crate::Arg::value_parser] for short. 16 //! 17 //! This allows you specify the valid values for that argument. If the user does not use one of 18 //! those specific values, they will receive a graceful exit with error message informing them 19 //! of the mistake, and what the possible valid values are 20 //! 21 //! ```rust 22 #![doc = include_str!("../../examples/tutorial_builder/04_01_possible.rs")] 23 //! ``` 24 #![doc = include_str!("../../examples/tutorial_builder/04_01_possible.md")] 25 //! 26 //! When enabling the [`derive` feature][crate::_features], you can use 27 //! [`ValueEnum`][crate::ValueEnum] to take care of the boiler plate for you, giving the same 28 //! results. 29 //! 30 //! ```rust 31 #![doc = include_str!("../../examples/tutorial_builder/04_01_enum.rs")] 32 //! ``` 33 #![doc = include_str!("../../examples/tutorial_builder/04_01_enum.md")] 34 //! 35 //! ### Validated values 36 //! 37 //! More generally, you can validate and parse into any data type with [`Arg::value_parser`]. 38 //! 39 //! ```rust 40 #![doc = include_str!("../../examples/tutorial_builder/04_02_parse.rs")] 41 //! ``` 42 #![doc = include_str!("../../examples/tutorial_builder/04_02_parse.md")] 43 //! 44 //! A [custom parser][TypedValueParser] can be used to improve the error messages or provide additional validation: 45 //! 46 //! ```rust 47 #![doc = include_str!("../../examples/tutorial_builder/04_02_validate.rs")] 48 //! ``` 49 #![doc = include_str!("../../examples/tutorial_builder/04_02_validate.md")] 50 //! 51 //! See [`Arg::value_parser`][crate::Arg::value_parser] for more details. 52 //! 53 //! ### Argument Relations 54 //! 55 //! You can declare dependencies or conflicts between [`Arg`][crate::Arg]s or even 56 //! [`ArgGroup`][crate::ArgGroup]s. 57 //! 58 //! [`ArgGroup`][crate::ArgGroup]s make it easier to declare relations instead of having to list 59 //! each individually, or when you want a rule to apply "any but not all" arguments. 60 //! 61 //! Perhaps the most common use of [`ArgGroup`][crate::ArgGroup]s is to require one and *only* one 62 //! argument to be present out of a given set. Imagine that you had multiple arguments, and you 63 //! want one of them to be required, but making all of them required isn't feasible because perhaps 64 //! they conflict with each other. 65 //! 66 //! ```rust 67 #![doc = include_str!("../../examples/tutorial_builder/04_03_relations.rs")] 68 //! ``` 69 #![doc = include_str!("../../examples/tutorial_builder/04_03_relations.md")] 70 //! 71 //! ### Custom Validation 72 //! 73 //! As a last resort, you can create custom errors with the basics of clap's formatting. 74 //! 75 //! ```rust 76 #![doc = include_str!("../../examples/tutorial_builder/04_04_custom.rs")] 77 //! ``` 78 #![doc = include_str!("../../examples/tutorial_builder/04_04_custom.md")] 79 #![allow(unused_imports)] 80 use crate::builder::*; 81 82 pub use super::chapter_2 as previous; 83 pub use super::chapter_4 as next; 84 pub use crate::_tutorial as table_of_contents; 85