usage_rs/
lib.rs

1//! The facade for building compiled Rust CLIs with usage.
2//!
3//! Depend on `usage-rs` under the short crate name `usage`. That is the one package an
4//! application needs: derive macros, the argv runtime, help, and clap-shaped errors ship in the
5//! defaults. Completions stay behind a feature; low-level adopters that want only the binding
6//! runtime keep depending on `usage-argv` directly.
7//!
8//! ```toml
9//! [dependencies]
10//! usage = { package = "usage-rs", version = "6" }
11//! ```
12//!
13//! What happens after a parse can come from the same declaration: a command implements [`Run`],
14//! the subcommand enum says `#[usage(run)]`, and the `match` that routes argv to the code
15//! carrying it out is generated rather than written. [`RunWith`] under `#[usage(run_with)]` hands
16//! each command shared state, and [`RunAsync`] / [`RunAsyncWith`] under `#[usage(run_async)]` /
17//! `#[usage(run_async_with)]` are the async pair. Nothing about any of it reaches the spec.
18//!
19//! Enable portable expression validation only when a CLI declares `validate` rules:
20//!
21//! ```toml
22//! usage = { package = "usage-rs", version = "6", features = ["validation"] }
23//! ```
24//!
25//! ```
26//! use usage_rs as usage;
27//! # #[cfg(feature = "spec")]
28//! use usage::Cli;
29//!
30//! # #[cfg(not(feature = "spec"))]
31//! # fn main() {}
32//! # #[cfg(feature = "spec")]
33//! # fn main() {
34//! #[derive(Cli)]
35//! #[usage(bin = "ex")]
36//! struct Ex {
37//!     #[usage(long, value_hint = usage::ValueHint::FilePath)]
38//!     file: Option<std::path::PathBuf>,
39//! }
40//!
41//! let argv = [std::ffi::OsStr::new("--file"), std::ffi::OsStr::new("input.txt")];
42//! let ex = Ex::parse_from(&argv).expect("valid command line");
43//! assert_eq!(ex.file.as_deref(), Some(std::path::Path::new("input.txt")));
44//! # }
45//! ```
46
47#![forbid(unsafe_code)]
48
49// Generated absolute paths must also work if a derive is used inside this crate. Integration
50// targets already receive this name through Cargo; the library target needs the self alias.
51extern crate self as usage_rs;
52
53pub use usage_argv as argv;
54pub use usage_argv::*;
55#[cfg(feature = "config")]
56pub use usage_config as config;
57#[cfg(feature = "config")]
58pub use usage_derive::Config;
59#[cfg(feature = "spec")]
60pub use usage_derive::{ArgGroup, Args, Cli, Subcommands, ValueEnum};
61#[cfg(feature = "test")]
62pub use usage_test as test;
63#[cfg(feature = "validation")]
64pub use usage_validation as validation;
65
66#[cfg(all(test, feature = "spec"))]
67mod tests {
68    #[derive(crate::Cli)]
69    #[usage(bin = "internal")]
70    struct Internal {}
71
72    #[cfg(feature = "validation")]
73    #[derive(Debug, crate::Cli)]
74    #[usage(bin = "validated")]
75    struct Validated {
76        #[usage(
77            long,
78            validate = "int(value) >= 1 && int(value) <= 65535",
79            validate_error = "must be a valid port"
80        )]
81        port: Option<u16>,
82    }
83
84    #[cfg(feature = "validation")]
85    #[derive(Debug, crate::Args)]
86    struct ValidatedArgs {
87        #[usage(long, validate = "value == 'ok'", validate_error = "must be ok")]
88        token: Option<String>,
89    }
90
91    #[cfg(feature = "validation")]
92    #[derive(Debug, crate::Cli)]
93    #[usage(bin = "validated-args")]
94    struct ValidatedArgsCli {
95        #[usage(flatten)]
96        args: ValidatedArgs,
97    }
98
99    #[test]
100    fn derives_resolve_the_facade_from_inside_the_facade() {
101        assert_eq!(Internal::spec().bin, Some("internal"));
102    }
103
104    #[cfg(feature = "config")]
105    #[derive(crate::Config)]
106    struct InternalSettings {
107        /// How many jobs to run at once
108        #[usage(env = "INTERNAL_JOBS", default = 4)]
109        jobs: u64,
110    }
111
112    #[cfg(feature = "config")]
113    #[test]
114    fn the_config_derive_resolves_the_facade_from_inside_the_facade() {
115        let resolved = crate::config::resolve(
116            InternalSettings::SETTINGS_REGISTRY,
117            crate::config::Layers::new(),
118        )
119        .expect("resolves");
120        let settings = InternalSettings::read(&resolved).expect("reads");
121        assert_eq!(settings.jobs, 4);
122        assert!(InternalSettings::spec_kdl().contains(r#"prop "jobs""#));
123    }
124
125    #[cfg(feature = "validation")]
126    #[test]
127    fn derives_evaluate_portable_validation_expressions() {
128        let valid = [
129            ::std::ffi::OsStr::new("--port"),
130            ::std::ffi::OsStr::new("9229"),
131        ];
132        assert_eq!(Validated::parse_from(&valid).unwrap().port, Some(9229));
133
134        let invalid = [
135            ::std::ffi::OsStr::new("--port"),
136            ::std::ffi::OsStr::new("0"),
137        ];
138        let crate::Error::InvalidValue(error) = Validated::parse_from(&invalid).unwrap_err() else {
139            panic!("expected invalid value");
140        };
141        assert_eq!(error.reason, "must be a valid port");
142
143        let invalid_args = [
144            ::std::ffi::OsStr::new("--token"),
145            ::std::ffi::OsStr::new("bad"),
146        ];
147        let crate::Error::InvalidValue(error) =
148            ValidatedArgsCli::parse_from(&invalid_args).unwrap_err()
149        else {
150            panic!("expected invalid value from flattened Args");
151        };
152        assert_eq!(error.reason, "must be ok");
153
154        let valid_args = [
155            ::std::ffi::OsStr::new("--token"),
156            ::std::ffi::OsStr::new("ok"),
157        ];
158        assert_eq!(
159            ValidatedArgsCli::parse_from(&valid_args)
160                .unwrap()
161                .args
162                .token
163                .as_deref(),
164            Some("ok")
165        );
166
167        let kdl = Validated::to_kdl();
168        assert!(
169            kdl.contains(r#"validate="int(value) >= 1 && int(value) <= 65535""#),
170            "{kdl}"
171        );
172    }
173}
usage_rs/lib.rs

usage_rs/
lib.rs
