Repository: clap-rs/clap
Pull request #3724 (2022-05-12 10:10:42)

feat: Expose builder/parser modules
The top-level API for clap is getting a bit bloated.  By exposing these
modules, we'll be able to continue to add new, less commonly used types
while keeping the main API focused.


Patch:
diff --git a/src/build/app_settings.rs b/src/builder/app_settings.rs
similarity index 100%
rename from src/build/app_settings.rs
rename to src/builder/app_settings.rs
diff --git a/src/build/arg.rs b/src/builder/arg.rs
similarity index 99%
rename from src/build/arg.rs
rename to src/builder/arg.rs
index 9fdf2a1c..91fe5b4a 100644
--- a/src/build/arg.rs
+++ b/src/builder/arg.rs
@@ -17,8 +17,8 @@ use std::{env, ffi::OsString};
 use yaml_rust::Yaml;
 
 // Internal
-use crate::build::usage_parser::UsageParser;
-use crate::build::ArgPredicate;
+use crate::builder::usage_parser::UsageParser;
+use crate::builder::ArgPredicate;
 use crate::util::{Id, Key};
 use crate::PossibleValue;
 use crate::ValueHint;
@@ -26,7 +26,7 @@ use crate::INTERNAL_ERROR_MSG;
 use crate::{ArgFlags, ArgSettings};
 
 #[cfg(feature = "regex")]
-use crate::build::RegexRef;
+use crate::builder::RegexRef;
 
 /// The abstract representation of a command line argument. Used to set all the options and
 /// relationships that define a valid argument for the program.
diff --git a/src/build/arg_group.rs b/src/builder/arg_group.rs
similarity index 100%
rename from src/build/arg_group.rs
rename to src/builder/arg_group.rs
diff --git a/src/build/arg_predicate.rs b/src/builder/arg_predicate.rs
similarity index 100%
rename from src/build/arg_predicate.rs
rename to src/builder/arg_predicate.rs
diff --git a/src/build/arg_settings.rs b/src/builder/arg_settings.rs
similarity index 100%
rename from src/build/arg_settings.rs
rename to src/builder/arg_settings.rs
diff --git a/src/build/command.rs b/src/builder/command.rs
similarity index 99%
rename from src/build/command.rs
rename to src/builder/command.rs
index 1ba26291..fc806a40 100644
--- a/src/build/command.rs
+++ b/src/builder/command.rs
@@ -14,22 +14,22 @@ use std::path::Path;
 use yaml_rust::Yaml;
 
 // Internal
-use crate::build::app_settings::{AppFlags, AppSettings};
-use crate::build::arg_settings::ArgSettings;
-use crate::build::{arg::ArgProvider, Arg, ArgGroup, ArgPredicate};
+use crate::builder::app_settings::{AppFlags, AppSettings};
+use crate::builder::arg_settings::ArgSettings;
+use crate::builder::{arg::ArgProvider, Arg, ArgGroup, ArgPredicate};
 use crate::error::ErrorKind;
 use crate::error::Result as ClapResult;
 use crate::mkeymap::MKeyMap;
 use crate::output::fmt::Stream;
 use crate::output::{fmt::Colorizer, Help, HelpWriter, Usage};
-use crate::parse::{ArgMatcher, ArgMatches, Parser};
+use crate::parser::{ArgMatcher, ArgMatches, Parser};
 use crate::util::ChildGraph;
 use crate::util::{color::ColorChoice, Id, Key};
 use crate::PossibleValue;
 use crate::{Error, INTERNAL_ERROR_MSG};
 
 #[cfg(debug_assertions)]
-use crate::build::debug_asserts::assert_app;
+use crate::builder::debug_asserts::assert_app;
 
 /// Build a command-line interface.
 ///
diff --git a/src/build/debug_asserts.rs b/src/builder/debug_asserts.rs
similarity index 99%
rename from src/build/debug_asserts.rs
rename to src/builder/debug_asserts.rs
index 7b470d84..33db293d 100644
--- a/src/build/debug_asserts.rs
+++ b/src/builder/debug_asserts.rs
@@ -2,7 +2,7 @@ use std::cmp::Ordering;
 
 use clap_lex::RawOsStr;
 
-use crate::build::arg::ArgProvider;
+use crate::builder::arg::ArgProvider;
 use crate::mkeymap::KeyType;
 use crate::util::Id;
 use crate::{AppSettings, Arg, Command, ValueHint};
diff --git a/src/build/macros.rs b/src/builder/macros.rs
similarity index 100%
rename from src/build/macros.rs
rename to src/builder/macros.rs
diff --git a/src/build/mod.rs b/src/builder/mod.rs
similarity index 93%
rename from src/build/mod.rs
rename to src/builder/mod.rs
index ae8c46b6..b38f95e1 100644
--- a/src/build/mod.rs
+++ b/src/builder/mod.rs
@@ -1,3 +1,5 @@
+//! Define [`Command`] line [arguments][`Arg`]
+
 #[macro_use]
 mod macros;
 
diff --git a/src/build/possible_value.rs b/src/builder/possible_value.rs
similarity index 100%
rename from src/build/possible_value.rs
rename to src/builder/possible_value.rs
diff --git a/src/build/regex.rs b/src/builder/regex.rs
similarity index 100%
rename from src/build/regex.rs
rename to src/builder/regex.rs
diff --git a/src/build/tests.rs b/src/builder/tests.rs
similarity index 100%
rename from src/build/tests.rs
rename to src/builder/tests.rs
diff --git a/src/build/usage_parser.rs b/src/builder/usage_parser.rs
similarity index 99%
rename from src/build/usage_parser.rs
rename to src/builder/usage_parser.rs
index ccfad66b..85d0d304 100644
--- a/src/build/usage_parser.rs
+++ b/src/builder/usage_parser.rs
@@ -1,10 +1,9 @@
 #![allow(deprecated)]
 
 // Internal
-use crate::{
-    build::{Arg, ArgSettings},
-    INTERNAL_ERROR_MSG,
-};
+use crate::builder::Arg;
+use crate::builder::ArgSettings;
+use crate::INTERNAL_ERROR_MSG;
 
 #[derive(PartialEq, Debug)]
 enum UsageToken {
@@ -245,7 +244,7 @@ fn default_value_end(b: u8) -> bool {
 mod test {
     #![allow(deprecated)]
 
-    use crate::build::{Arg, ArgSettings};
+    use crate::builder::{Arg, ArgSettings};
 
     #[allow(clippy::cognitive_complexity)]
     #[test]
diff --git a/src/build/value_hint.rs b/src/builder/value_hint.rs
similarity index 100%
rename from src/build/value_hint.rs
rename to src/builder/value_hint.rs
diff --git a/src/error/mod.rs b/src/error/mod.rs
index 5c8a18e3..14a014be 100644
--- a/src/error/mod.rs
+++ b/src/error/mod.rs
@@ -12,14 +12,13 @@ use std::{
 };
 
 // Internal
-use crate::{
-    build::Arg,
-    output::fmt::Colorizer,
-    output::fmt::Stream,
-    parse::features::suggestions,
-    util::{color::ColorChoice, safe_exit, SUCCESS_CODE, USAGE_CODE},
-    AppSettings, Command,
-};
+use crate::output::fmt::Colorizer;
+use crate::output::fmt::Stream;
+use crate::parser::features::suggestions;
+use crate::util::{color::ColorChoice, safe_exit, SUCCESS_CODE, USAGE_CODE};
+use crate::AppSettings;
+use crate::Arg;
+use crate::Command;
 
 mod context;
 mod kind;
diff --git a/src/lib.rs b/src/lib.rs
index dc92f873..18b1e2d3 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -26,12 +26,10 @@
 #[cfg(not(feature = "std"))]
 compile_error!("`std` feature is currently required to build `clap`");
 
-pub use crate::build::Command;
-pub use crate::build::{
-    AppFlags, AppSettings, Arg, ArgFlags, ArgGroup, ArgSettings, PossibleValue, ValueHint,
-};
+pub use crate::builder::Command;
+pub use crate::builder::{Arg, ArgGroup};
 pub use crate::error::Error;
-pub use crate::parse::{ArgMatches, Indices, OsValues, ValueSource, Values};
+pub use crate::parser::ArgMatches;
 #[cfg(feature = "color")]
 pub use crate::util::color::ColorChoice;
 #[cfg(not(feature = "color"))]
@@ -40,10 +38,11 @@ pub(crate) use crate::util::color::ColorChoice;
 
 pub use crate::derive::{ArgEnum, Args, CommandFactory, FromArgMatches, Parser, Subcommand};
 
-pub use crate::error::{ErrorKind, Result};
-
 #[allow(deprecated)]
-pub use crate::build::App;
+pub use crate::builder::App;
+pub use crate::builder::{AppFlags, AppSettings, ArgFlags, ArgSettings, PossibleValue, ValueHint};
+pub use crate::error::{ErrorKind, Result};
+pub use crate::parser::{Indices, OsValues, ValueSource, Values};
 
 #[cfg(feature = "yaml")]
 #[doc(hidden)]
@@ -77,14 +76,14 @@ mod macros;
 mod derive;
 
 #[cfg(feature = "regex")]
-pub use crate::build::RegexRef;
+pub use crate::builder::RegexRef;
 
+pub mod builder;
 pub mod error;
+pub mod parser;
 
-mod build;
 mod mkeymap;
 mod output;
-mod parse;
 mod util;
 
 const INTERNAL_ERROR_MSG: &str = "Fatal internal error. Please consider filing a bug \
diff --git a/src/mkeymap.rs b/src/mkeymap.rs
index 8ba3dcb3..97ecdda7 100644
--- a/src/mkeymap.rs
+++ b/src/mkeymap.rs
@@ -1,6 +1,10 @@
-use crate::{build::Arg, util::Id, INTERNAL_ERROR_MSG};
+use std::iter::Iterator;
+use std::ops::Index;
+use std::{ffi::OsStr, ffi::OsString};
 
-use std::{ffi::OsStr, ffi::OsString, iter::Iterator, ops::Index};
+use crate::util::Id;
+use crate::Arg;
+use crate::INTERNAL_ERROR_MSG;
 
 #[derive(PartialEq, Eq, Debug, Clone)]
 pub(crate) struct Key {
diff --git a/src/output/help.rs b/src/output/help.rs
index 85ba7d13..f7401118 100644
--- a/src/output/help.rs
+++ b/src/output/help.rs
@@ -1,18 +1,14 @@
 // Std
-use std::{
-    borrow::Cow,
-    cmp,
-    fmt::Write as _,
-    io::{self, Write},
-    usize,
-};
+use std::borrow::Cow;
+use std::cmp;
+use std::fmt::Write as _;
+use std::io::{self, Write};
+use std::usize;
 
 // Internal
-use crate::{
-    build::{display_arg_val, Arg, Command},
-    output::{fmt::Colorizer, Usage},
-    PossibleValue,
-};
+use crate::builder::{display_arg_val, Arg, Command};
+use crate::output::{fmt::Colorizer, Usage};
+use crate::PossibleValue;
 
 // Third party
 use indexmap::IndexSet;
diff --git a/src/output/usage.rs b/src/output/usage.rs
index f223d9c1..5cd6ba9e 100644
--- a/src/output/usage.rs
+++ b/src/output/usage.rs
@@ -1,9 +1,9 @@
 use indexmap::IndexSet;
 
 // Internal
-use crate::build::AppSettings as AS;
-use crate::build::{Arg, ArgPredicate, Command};
-use crate::parse::ArgMatcher;
+use crate::builder::AppSettings as AS;
+use crate::builder::{Arg, ArgPredicate, Command};
+use crate::parser::ArgMatcher;
 use crate::util::ChildGraph;
 use crate::util::Id;
 use crate::INTERNAL_ERROR_MSG;
diff --git a/src/parse/arg_matcher.rs b/src/parser/arg_matcher.rs
similarity index 97%
rename from src/parse/arg_matcher.rs
rename to src/parser/arg_matcher.rs
index 31804a46..167e6e0e 100644
--- a/src/parse/arg_matcher.rs
+++ b/src/parser/arg_matcher.rs
@@ -1,12 +1,13 @@
 // Std
-use std::{collections::HashMap, ffi::OsString, mem, ops::Deref};
+use std::collections::HashMap;
+use std::ffi::OsString;
+use std::mem;
+use std::ops::Deref;
 
 // Internal
-use crate::{
-    build::{Arg, ArgPredicate, Command},
-    parse::{ArgMatches, MatchedArg, SubCommand, ValueSource},
-    util::Id,
-};
+use crate::builder::{Arg, ArgPredicate, Command};
+use crate::parser::{ArgMatches, MatchedArg, SubCommand, ValueSource};
+use crate::util::Id;
 
 // Third party
 use indexmap::map::Entry;
diff --git a/src/parse/features/mod.rs b/src/parser/features/mod.rs
similarity index 100%
rename from src/parse/features/mod.rs
rename to src/parser/features/mod.rs
diff --git a/src/parse/features/suggestions.rs b/src/parser/features/suggestions.rs
similarity index 99%
rename from src/parse/features/suggestions.rs
rename to src/parser/features/suggestions.rs
index 77ba8c7a..9e46f3c9 100644
--- a/src/parse/features/suggestions.rs
+++ b/src/parser/features/suggestions.rs
@@ -2,7 +2,7 @@
 use std::cmp::Ordering;
 
 // Internal
-use crate::build::Command;
+use crate::builder::Command;
 
 /// Produces multiple strings from a given list of possible values which are similar
 /// to the passed in value `v` within a certain confidence by least confidence.
diff --git a/src/parse/matches/arg_matches.rs b/src/parser/matches/arg_matches.rs
similarity index 99%
rename from src/parse/matches/arg_matches.rs
rename to src/parser/matches/arg_matches.rs
index a2fa6237..50757e77 100644
--- a/src/parse/matches/arg_matches.rs
+++ b/src/parser/matches/arg_matches.rs
@@ -1,19 +1,17 @@
 // Std
-use std::{
-    borrow::Cow,
-    ffi::{OsStr, OsString},
-    fmt::{Debug, Display},
-    iter::{Cloned, Flatten, Map},
-    slice::Iter,
-    str::FromStr,
-};
+use std::borrow::Cow;
+use std::ffi::{OsStr, OsString};
+use std::fmt::{Debug, Display};
+use std::iter::{Cloned, Flatten, Map};
+use std::slice::Iter;
+use std::str::FromStr;
 
 // Third Party
 use indexmap::IndexMap;
 
 // Internal
-use crate::parse::MatchedArg;
-use crate::parse::ValueSource;
+use crate::parser::MatchedArg;
+use crate::parser::ValueSource;
 use crate::util::{Id, Key};
 use crate::{Error, INVALID_UTF8};
 
diff --git a/src/parse/matches/matched_arg.rs b/src/parser/matches/matched_arg.rs
similarity index 99%
rename from src/parse/matches/matched_arg.rs
rename to src/parser/matches/matched_arg.rs
index 55326ecd..002920f5 100644
--- a/src/parse/matches/matched_arg.rs
+++ b/src/parser/matches/matched_arg.rs
@@ -5,8 +5,8 @@ use std::{
     slice::Iter,
 };
 
-use crate::build::ArgPredicate;
-use crate::parse::ValueSource;
+use crate::builder::ArgPredicate;
+use crate::parser::ValueSource;
 use crate::util::eq_ignore_case;
 use crate::INTERNAL_ERROR_MSG;
 
diff --git a/src/parse/matches/mod.rs b/src/parser/matches/mod.rs
similarity index 100%
rename from src/parse/matches/mod.rs
rename to src/parser/matches/mod.rs
diff --git a/src/parse/matches/value_source.rs b/src/parser/matches/value_source.rs
similarity index 100%
rename from src/parse/matches/value_source.rs
rename to src/parser/matches/value_source.rs
diff --git a/src/parse/mod.rs b/src/parser/mod.rs
similarity index 71%
rename from src/parse/mod.rs
rename to src/parser/mod.rs
index 298862e1..1bfc48c8 100644
--- a/src/parse/mod.rs
+++ b/src/parser/mod.rs
@@ -1,9 +1,12 @@
+//! [`Command`][crate::Command] line argument parser
+
 mod arg_matcher;
+mod matches;
+#[allow(clippy::module_inception)]
 mod parser;
 mod validator;
 
-pub mod features;
-pub mod matches;
+pub(crate) mod features;
 
 pub(crate) use self::arg_matcher::ArgMatcher;
 pub(crate) use self::matches::{MatchedArg, SubCommand};
diff --git a/src/parse/parser.rs b/src/parser/parser.rs
similarity index 99%
rename from src/parse/parser.rs
rename to src/parser/parser.rs
index 6262d18d..76895a44 100644
--- a/src/parse/parser.rs
+++ b/src/parser/parser.rs
@@ -8,16 +8,16 @@ use std::{
 use clap_lex::RawOsStr;
 
 // Internal
-use crate::build::AppSettings as AS;
-use crate::build::{Arg, Command};
+use crate::builder::AppSettings as AS;
+use crate::builder::{Arg, Command};
 use crate::error::Error as ClapError;
 use crate::error::Result as ClapResult;
 use crate::mkeymap::KeyType;
 use crate::output::fmt::Stream;
 use crate::output::{fmt::Colorizer, Usage};
-use crate::parse::features::suggestions;
-use crate::parse::{ArgMatcher, SubCommand};
-use crate::parse::{Validator, ValueSource};
+use crate::parser::features::suggestions;
+use crate::parser::{ArgMatcher, SubCommand};
+use crate::parser::{Validator, ValueSource};
 use crate::util::Id;
 use crate::{INTERNAL_ERROR_MSG, INVALID_UTF8};
 
@@ -1255,10 +1255,10 @@ impl<'help, 'cmd> Parser<'help, 'cmd> {
                 for (id, val, default) in arg.default_vals_ifs.iter() {
                     let add = if let Some(a) = matcher.get(id) {
                         match val {
-                            crate::build::ArgPredicate::Equals(v) => {
+                            crate::builder::ArgPredicate::Equals(v) => {
                                 a.vals_flatten().any(|value| v == value)
                             }
-                            crate::build::ArgPredicate::IsPresent => true,
+                            crate::builder::ArgPredicate::IsPresent => true,
                         }
                     } else {
                         false
diff --git a/src/parse/validator.rs b/src/parser/validator.rs
similarity index 99%
rename from src/parse/validator.rs
rename to src/parser/validator.rs
index 2e2766f6..bc5db760 100644
--- a/src/parse/validator.rs
+++ b/src/parser/validator.rs
@@ -1,9 +1,9 @@
 // Internal
-use crate::build::{AppSettings, Arg, ArgPredicate, Command, PossibleValue};
+use crate::builder::{AppSettings, Arg, ArgPredicate, Command, PossibleValue};
 use crate::error::{Error, Result as ClapResult};
 use crate::output::fmt::Stream;
 use crate::output::Usage;
-use crate::parse::{ArgMatcher, MatchedArg, ParseState};
+use crate::parser::{ArgMatcher, MatchedArg, ParseState};
 use crate::util::ChildGraph;
 use crate::util::Id;
 use crate::{INTERNAL_ERROR_MSG, INVALID_UTF8};


Test patch:
diff --git a/tests/derive_ui/next/tuple_struct.stderr b/tests/derive_ui/next/tuple_struct.stderr
index a6f160fe..33ffa0da 100644
--- a/tests/derive_ui/next/tuple_struct.stderr
+++ b/tests/derive_ui/next/tuple_struct.stderr
@@ -17,4 +17,4 @@ error[E0599]: no function or associated item named `parse` found for struct `Opt
    |
    = help: items from traits can only be used if the trait is implemented and in scope
    = note: the following trait defines an item `parse`, perhaps you need to implement it:
-           candidate #1: `StructOpt`
+           candidate #1: `Parser`