From 6054c988a0157029a0f907445c2c5f3617dfe4cc Mon Sep 17 00:00:00 2001 From: Nilstrieb <48135649+Nilstrieb@users.noreply.github.com> Date: Wed, 15 Dec 2021 21:42:58 +0100 Subject: [PATCH 1/2] improve docs --- src/macros.rs | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/src/macros.rs b/src/macros.rs index 746d98a..f149cc8 100644 --- a/src/macros.rs +++ b/src/macros.rs @@ -52,21 +52,25 @@ macro_rules! arg { /// This macro lets you specify your arguments in a flat list, and then converts them into /// nested tuples for you, since that's what's internally used. /// ``` -/// # use badargs::arg; -/// # arg!(Force: "force", 'f' -> bool); -/// # arg!(OutFile: "outfile", 't' -> bool); -/// # arg!(SetUpstream: "set-upstream", 'x' -> bool); -/// # fn main() { -/// let args = badargs::badargs!(Force, OutFile, SetUpstream); -/// # } +/// use badargs::arg; +/// arg!(Force: "force", 'f' -> bool); +/// arg!(OutFile: "outfile", 't' -> bool); +/// arg!(SetUpstream: "set-upstream", 'x' -> bool); +/// +/// fn main() { +/// let args = badargs::badargs!(Force, OutFile, SetUpstream); +/// } /// ``` /// will be expanded into /// ``` -/// # use badargs::arg; -/// # arg!(Force: "force", 'f' -> bool); -/// # arg!(OutFile: "outfile", 't' -> bool); -/// # arg!(SetUpstream: "set-upstream", 'x' -> bool); -/// let args = badargs::badargs::<(Force, (OutFile, SetUpstream))>(); +/// use badargs::arg; +/// arg!(Force: "force", 'f' -> bool); +/// arg!(OutFile: "outfile", 't' -> bool); +/// arg!(SetUpstream: "set-upstream", 'x' -> bool); +/// +/// fn main() { +/// let args = badargs::badargs::<(Force, (OutFile, SetUpstream))>(); +/// } /// ``` /// This only provides a minor benefit for programs with a small amount of args, but is /// very useful for larger arg amounts. @@ -82,7 +86,6 @@ macro_rules! badargs { { #[allow(unused_parens)] // allow this because there might only be one arg { - $crate::badargs::<($crate::badargs!(@inner $($tail),+))>() } } From 0619bdf16b2684c5064a87dad4af07c89137272f Mon Sep 17 00:00:00 2001 From: Nilstrieb <48135649+Nilstrieb@users.noreply.github.com> Date: Wed, 15 Dec 2021 22:07:54 +0100 Subject: [PATCH 2/2] add support for visibility in `arg!` macro --- Cargo.toml | 2 +- src/lib.rs | 35 +++++++++++++++++++++-------------- src/macros.rs | 32 +++++++++++++++++++++++--------- 3 files changed, 45 insertions(+), 24 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 3a59b88..43f61da 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "badargs" -version = "0.1.2" +version = "0.2.0" edition = "2018" license = "MIT" description = "Type safe zero-dependency argument parser" diff --git a/src/lib.rs b/src/lib.rs index 7cf9502..bd7f8a6 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -5,29 +5,34 @@ //! //! Declare your arguments with structs. You probably want to use the macro for that //! ``` -//! # use badargs::arg; +//! use badargs::arg; +//! //! arg!(Force: "force", 'f' -> bool); //! arg!(OutFile: "output", 'o' -> String); //! ``` -//! Then you call the [`badargs`] function with all of your declared arguments. You probably -//! want to use a macro for that too. //! -//! You can also use the [`badargs!`] macro if you have many arguments and don't want to nest -//! the tuples manually +//! The recommended way to use `badargs` is by invoking the macro [`badargs!`] //! ``` -//! # use badargs::arg; -//! # arg!(Force: "force", 'f' -> bool); -//! # arg!(OutFile: "output", 'o' -> String); +//! use badargs::arg; +//! +//! arg!(Force: "force", 'f' -> bool); +//! arg!(OutFile: "output", 'o' -> String); +//! //! let args = badargs::badargs!(Force, OutFile); //! ``` -//! You can then get values using your declared arguments +//! +//! You can also invoke the [`badargs()`] function directly +//! +//! Getting the values is done using the [`BadArgs::get`] function //! ``` -//! # use badargs::arg; -//! # arg!(Force: "force", 'f' -> bool); -//! # arg!(OutFile: "output", 'o' -> String); -//! # let args = badargs::badargs!(Force, OutFile); +//! use badargs::arg; +//! arg!(Force: "force", 'f' -> bool); +//! arg!(OutFile: "output", 'o' -> String); +//! +//! let args = badargs::badargs!(Force, OutFile); +//! //! let force: Option<&bool> = args.get::(); -//! let out_file: Option<&String> = args.get::(); +//! let out_file = args.get::(); //! ``` mod macros; @@ -138,7 +143,9 @@ mod error { /// Invalid schema #[derive(Debug, Clone, Eq, PartialEq)] pub enum SchemaError { + /// The argument name was already provided for a different argument NameAlreadyExists(String), + /// Currently not used InvalidSchema(String), } diff --git a/src/macros.rs b/src/macros.rs index f149cc8..b708e44 100644 --- a/src/macros.rs +++ b/src/macros.rs @@ -1,12 +1,25 @@ /// /// Declare your arguments using this macro. +/// +/// Possible patterns: /// ``` -/// # use badargs::arg; +/// use badargs::arg; +/// +/// arg!(LongOrShort: "long-or-short", 's' -> bool); +/// arg!(OnlyLong: "only-long" -> bool); +/// arg!(pub OtherModule: "other-module" -> bool); +/// ``` +/// +/// +/// ``` +/// use badargs::arg; +/// /// arg!(Force: "force", 'f' -> bool); /// ``` /// is a shorthand for /// ``` -/// # use badargs::{arg, CliArg}; +/// use badargs::{arg, CliArg}; +/// /// struct Force; /// /// impl CliArg for Force { @@ -23,15 +36,15 @@ /// ``` #[macro_export] macro_rules! arg { - ($name:ident: $long:literal, $short:literal -> $result:ty) => { - arg!(@$name: ($long, ::std::option::Option::Some($short)) -> $result); + ($vis:vis $name:ident: $long:literal, $short:literal -> $result:ty) => { + arg!(@$vis $name: ($long, ::std::option::Option::Some($short)) -> $result); }; - ($name:ident: $long:literal -> $result:ty) => { - arg!(@$name: ($long, ::std::option::Option::None) -> $result); + ($vis:vis $name:ident: $long:literal -> $result:ty) => { + arg!(@$vis $name: ($long, ::std::option::Option::None) -> $result); }; - (@$name:ident: ($long:literal, $short:expr) -> $result:ty) => { + (@$vis:vis $name:ident: ($long:literal, $short:expr) -> $result:ty) => { #[derive(Default)] - struct $name; + $vis struct $name; impl $crate::CliArg for $name { type Content = $result; @@ -48,7 +61,8 @@ macro_rules! arg { } /// -/// A shorthand for calling the [`badargs::badargs`] main function +/// A shorthand for calling the [`badargs`](crate::badargs()) main function +/// /// This macro lets you specify your arguments in a flat list, and then converts them into /// nested tuples for you, since that's what's internally used. /// ```