diff --git a/Cargo.lock b/Cargo.lock index 8032cdf4033..ef0ac63d092 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -177,25 +177,17 @@ dependencies = [ name = "clap" version = "4.1.13" dependencies = [ - "backtrace", - "bitflags", + "clap_builder", "clap_derive", - "clap_lex 0.3.3", "humantime", - "is-terminal", "once_cell", "rustversion", "shlex", "snapbox", "static_assertions", - "strsim", - "termcolor", - "terminal_size", "trybuild", "trycmd", "unic-emoji-char", - "unicase", - "unicode-width", ] [[package]] @@ -207,6 +199,30 @@ dependencies = [ "lazy_static", ] +[[package]] +name = "clap_builder" +version = "4.1.13" +dependencies = [ + "backtrace", + "bitflags", + "clap_lex 0.3.3", + "humantime", + "is-terminal", + "once_cell", + "rustversion", + "shlex", + "snapbox", + "static_assertions", + "strsim", + "termcolor", + "terminal_size", + "trybuild", + "trycmd", + "unic-emoji-char", + "unicase", + "unicode-width", +] + [[package]] name = "clap_complete" version = "4.1.5" diff --git a/Cargo.toml b/Cargo.toml index efce9d36544..219e0af8b56 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,7 @@ [workspace] members = [ "clap_bench", + "clap_builder", "clap_derive", "clap_lex", "clap_complete", @@ -70,45 +71,37 @@ default = [ "error-context", "suggestions", ] -debug = ["clap_derive?/debug", "dep:backtrace"] # Enables debug messages -unstable-doc = ["derive", "cargo", "wrap_help", "env", "unicode", "string", "unstable-replace"] # for docs.rs +debug = ["clap_builder/debug", "clap_derive?/debug"] # Enables debug messages +unstable-doc = ["clap_builder/unstable-doc", "derive"] # for docs.rs # Used in default -std = [] # support for no_std in a backwards-compatible way -color = ["dep:is-terminal", "dep:termcolor"] -help = [] -usage = [] -error-context = [] -suggestions = ["dep:strsim", "error-context"] +std = ["clap_builder/std"] # support for no_std in a backwards-compatible way +color = ["clap_builder/color"] +help = ["clap_builder/help"] +usage = ["clap_builder/usage"] +error-context = ["clap_builder/error-context"] +suggestions = ["clap_builder/suggestions"] # Optional -deprecated = ["clap_derive?/deprecated"] # Guided experience to prepare for next breaking release (at different stages of development, this may become default) +deprecated = ["clap_builder/deprecated", "clap_derive?/deprecated"] # Guided experience to prepare for next breaking release (at different stages of development, this may become default) derive = ["dep:clap_derive", "dep:once_cell"] -cargo = ["dep:once_cell"] # Disable if you're not using Cargo, enables Cargo-env-var-dependent macros -wrap_help = ["help", "dep:terminal_size"] -env = [] # Use environment variables during arg parsing -unicode = ["dep:unicode-width", "dep:unicase"] # Support for unicode characters in arguments and help messages -string = [] # Allow runtime generated strings +cargo = ["clap_builder/cargo"] # Disable if you're not using Cargo, enables Cargo-env-var-dependent macros +wrap_help = ["clap_builder/wrap_help"] +env = ["clap_builder/env"] # Use environment variables during arg parsing +unicode = ["clap_builder/unicode"] # Support for unicode characters in arguments and help messages +string = ["clap_builder/string"] # Allow runtime generated strings # In-work features -unstable-replace = [] -unstable-grouped = [] -unstable-v5 = ["clap_derive?/unstable-v5", "deprecated"] +unstable-replace = ["clap_builder/unstable-replace"] +unstable-grouped = ["clap_builder/unstable-grouped"] +unstable-v5 = ["clap_builder/unstable-v5", "clap_derive?/unstable-v5", "deprecated"] [lib] bench = false [dependencies] +clap_builder = { path = "./clap_builder", version = "=4.1.13", default-features = false } clap_derive = { path = "./clap_derive", version = "=4.1.12", optional = true } -clap_lex = { path = "./clap_lex", version = "0.3.0" } -bitflags = "1.2.0" -unicase = { version = "2.6.0", optional = true } -strsim = { version = "0.10.0", optional = true } -is-terminal = { version = "0.4.1", optional = true } -termcolor = { version = "1.1.1", optional = true } -terminal_size = { version = "0.2.1", optional = true } -backtrace = { version = "0.3.67", optional = true } -unicode-width = { version = "0.1.9", optional = true } once_cell = { version = "1.12.0", optional = true } [dev-dependencies] diff --git a/clap_builder/CONTRIBUTING.md b/clap_builder/CONTRIBUTING.md new file mode 100644 index 00000000000..2eadb8a1e09 --- /dev/null +++ b/clap_builder/CONTRIBUTING.md @@ -0,0 +1,3 @@ +# How to Contribute + +See the [clap-wide CONTRIBUTING.md](../CONTRIBUTING.md). This will contain `clap_builder` specific notes. diff --git a/clap_builder/Cargo.toml b/clap_builder/Cargo.toml new file mode 100644 index 00000000000..df7ae60ec97 --- /dev/null +++ b/clap_builder/Cargo.toml @@ -0,0 +1,89 @@ +[package] +name = "clap_builder" +version = "4.1.13" +description = "A simple to use, efficient, and full-featured Command Line Argument Parser" +repository = "https://github.com/clap-rs/clap" +categories = ["command-line-interface"] +keywords = [ + "argument", + "cli", + "arg", + "parser", + "parse" +] +license.workspace = true +edition.workspace = true +rust-version.workspace = true +include.workspace = true + +[package.metadata.docs.rs] +features = ["unstable-doc"] +rustdoc-args = ["--cfg", "docsrs"] +cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"] + +[package.metadata.playground] +features = ["unstable-doc"] + +[package.metadata.release] +shared-version = true +dependent-version = "upgrade" +tag-name = "v{{version}}" + +[features] +default = [ + "std", + "color", + "help", + "usage", + "error-context", + "suggestions", +] +debug = ["dep:backtrace"] # Enables debug messages +unstable-doc = ["cargo", "wrap_help", "env", "unicode", "string", "unstable-replace"] # for docs.rs + +# Used in default +std = [] # support for no_std in a backwards-compatible way +color = ["dep:is-terminal", "dep:termcolor"] +help = [] +usage = [] +error-context = [] +suggestions = ["dep:strsim", "error-context"] + +# Optional +deprecated = [] # Guided experience to prepare for next breaking release (at different stages of development, this may become default) +cargo = ["dep:once_cell"] # Disable if you're not using Cargo, enables Cargo-env-var-dependent macros +wrap_help = ["help", "dep:terminal_size"] +env = [] # Use environment variables during arg parsing +unicode = ["dep:unicode-width", "dep:unicase"] # Support for unicode characters in arguments and help messages +string = [] # Allow runtime generated strings + +# In-work features +unstable-replace = [] +unstable-grouped = [] +unstable-v5 = ["deprecated"] + +[lib] +bench = false + +[dependencies] +clap_lex = { path = "../clap_lex", version = "0.3.0" } +bitflags = "1.2.0" +unicase = { version = "2.6.0", optional = true } +strsim = { version = "0.10.0", optional = true } +is-terminal = { version = "0.4.1", optional = true } +termcolor = { version = "1.1.1", optional = true } +terminal_size = { version = "0.2.1", optional = true } +backtrace = { version = "0.3.67", optional = true } +unicode-width = { version = "0.1.9", optional = true } +once_cell = { version = "1.12.0", optional = true } + +[dev-dependencies] +trybuild = "1.0.77" +rustversion = "1.0.12" +# Cutting out `filesystem` feature +trycmd = { version = "0.14.15", default-features = false, features = ["color-auto", "diff", "examples"] } +humantime = "2.1.0" +snapbox = "0.4.10" +shlex = "1.1.0" +static_assertions = "1.1.0" +unic-emoji-char = "0.9.0" diff --git a/clap_builder/LICENSE-APACHE b/clap_builder/LICENSE-APACHE new file mode 100644 index 00000000000..261eeb9e9f8 --- /dev/null +++ b/clap_builder/LICENSE-APACHE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/clap_builder/LICENSE-MIT b/clap_builder/LICENSE-MIT new file mode 100644 index 00000000000..7b05b8453e9 --- /dev/null +++ b/clap_builder/LICENSE-MIT @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2015-2022 Kevin B. Knapp and Clap Contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/clap_builder/README.md b/clap_builder/README.md new file mode 100644 index 00000000000..6fcc659af8d --- /dev/null +++ b/clap_builder/README.md @@ -0,0 +1,24 @@ +# clap_builder + +Builder implementation for clap. + +[docs.rs](https://docs.rs/clap) +- [Derive Tutorial](https://docs.rs/clap/latest/clap/_derive/_tutorial/index.html) +- [Derive Reference](https://docs.rs/clap/latest/clap/_derive/index.html) + +## License + +Licensed under either of + +- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or ) +- MIT license ([LICENSE-MIT](LICENSE-MIT) or ) + +at your option. + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in the work by you, as defined in the Apache-2.0 license, shall be +dual licensed as above, without any additional terms or conditions. + +See [CONTRIBUTING](CONTRIBUTING.md) for more details. diff --git a/src/builder/action.rs b/clap_builder/src/builder/action.rs similarity index 97% rename from src/builder/action.rs rename to clap_builder/src/builder/action.rs index 6f4c6b030c3..becdeda0ec6 100644 --- a/src/builder/action.rs +++ b/clap_builder/src/builder/action.rs @@ -4,6 +4,7 @@ /// /// ```rust /// # #[cfg(feature = "help")] { +/// # use clap_builder as clap; /// # use clap::Command; /// # use clap::Arg; /// let cmd = Command::new("mycmd") @@ -35,6 +36,7 @@ pub enum ArgAction { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// # use clap::Arg; /// let cmd = Command::new("mycmd") @@ -57,6 +59,7 @@ pub enum ArgAction { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// # use clap::Arg; /// let cmd = Command::new("mycmd") @@ -88,6 +91,7 @@ pub enum ArgAction { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// # use clap::Arg; /// let cmd = Command::new("mycmd") @@ -115,6 +119,7 @@ pub enum ArgAction { /// You can use [`TypedValueParser::map`][crate::builder::TypedValueParser::map] to have the /// flag control an application-specific type: /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// # use clap::Arg; /// # use clap::builder::TypedValueParser as _; @@ -161,6 +166,7 @@ pub enum ArgAction { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// # use clap::Arg; /// let cmd = Command::new("mycmd") @@ -195,6 +201,7 @@ pub enum ArgAction { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// # use clap::Arg; /// let cmd = Command::new("mycmd") @@ -227,6 +234,7 @@ pub enum ArgAction { /// /// ```rust /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; /// # use clap::Command; /// # use clap::Arg; /// let cmd = Command::new("mycmd") @@ -253,6 +261,7 @@ pub enum ArgAction { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// # use clap::Arg; /// let cmd = Command::new("mycmd") diff --git a/src/builder/app_settings.rs b/clap_builder/src/builder/app_settings.rs similarity index 100% rename from src/builder/app_settings.rs rename to clap_builder/src/builder/app_settings.rs diff --git a/src/builder/arg.rs b/clap_builder/src/builder/arg.rs similarity index 97% rename from src/builder/arg.rs rename to clap_builder/src/builder/arg.rs index 8992d0bb080..577d968267c 100644 --- a/src/builder/arg.rs +++ b/clap_builder/src/builder/arg.rs @@ -39,6 +39,7 @@ use crate::INTERNAL_ERROR_MSG; /// # Examples /// /// ```rust +/// # use clap_builder as clap; /// # use clap::{Arg, arg, ArgAction}; /// // Using the traditional builder pattern and setting each option manually /// let cfg = Arg::new("config") @@ -99,6 +100,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// Arg::new("config") /// # ; @@ -130,6 +132,7 @@ impl Arg { /// argument via a single hyphen (`-`) such as `-c`: /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("config") @@ -144,6 +147,7 @@ impl Arg { /// /// To use `-h` for your own flag and still have help: /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .disable_help_flag(true) @@ -190,6 +194,7 @@ impl Arg { /// Setting `long` allows using the argument via a double hyphen (`--`) such as `--config` /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("cfg") @@ -216,6 +221,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("test") @@ -245,6 +251,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("test") @@ -275,6 +282,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("test") @@ -303,6 +311,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("test") @@ -332,6 +341,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("test") @@ -361,6 +371,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("test") @@ -390,6 +401,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("test") @@ -416,6 +428,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("test") @@ -460,6 +473,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// Arg::new("config") /// .index(1) @@ -467,6 +481,7 @@ impl Arg { /// ``` /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("mode") @@ -507,6 +522,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, arg}; /// let m = Command::new("myprog") /// .arg(arg!( ... "commands to run").trailing_var_arg(true)) @@ -552,6 +568,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Arg, ArgAction}; /// Arg::new("args") /// .action(ArgAction::Set) @@ -563,6 +580,7 @@ impl Arg { /// and requires that the `--` syntax be used to access it early. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("first")) @@ -584,6 +602,7 @@ impl Arg { /// failing to use the `--` syntax results in an error. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("first")) @@ -625,6 +644,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Arg; /// Arg::new("config") /// .required(true) @@ -634,6 +654,7 @@ impl Arg { /// Setting required requires that the argument be used at runtime. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -650,6 +671,7 @@ impl Arg { /// Setting required and then *not* supplying that argument at runtime is an error. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -682,6 +704,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Arg; /// Arg::new("config") /// .requires("input") @@ -693,6 +716,7 @@ impl Arg { /// required /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -710,6 +734,7 @@ impl Arg { /// Setting [`Arg::requires(name)`] and *not* supplying that argument is an error. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -742,6 +767,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Arg; /// Arg::new("config") /// .exclusive(true) @@ -752,6 +778,7 @@ impl Arg { /// is an error. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("exclusive") @@ -792,6 +819,7 @@ impl Arg { /// want to clutter the source with three duplicate [`Arg`] definitions. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("verb") @@ -861,6 +889,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// # use clap::Arg; /// let cmd = Command::new("mycmd") @@ -901,6 +930,7 @@ impl Arg { /// The default value is [`ValueParser::string`][crate::builder::ValueParser::string]. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::ArgAction; /// let mut cmd = clap::Command::new("raw") /// .arg( @@ -979,6 +1009,7 @@ impl Arg { /// /// Option: /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let m = Command::new("prog") /// .arg(Arg::new("mode") @@ -993,6 +1024,7 @@ impl Arg { /// /// Flag/option hybrid (see also [default_missing_value][Arg::default_missing_value]) /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let cmd = Command::new("prog") /// .arg(Arg::new("mode") @@ -1022,6 +1054,7 @@ impl Arg { /// /// Tuples /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let cmd = Command::new("prog") /// .arg(Arg::new("file") @@ -1048,6 +1081,7 @@ impl Arg { /// A common mistake is to define an option which allows multiple values and a positional /// argument. /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let cmd = Command::new("prog") /// .arg(Arg::new("file") @@ -1076,6 +1110,7 @@ impl Arg { /// A solution for the example above is to limit how many values with a maximum, or specific /// number, or to say [`ArgAction::Append`] is ok, but multiple values are not. /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("file") @@ -1118,6 +1153,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// Arg::new("cfg") /// .long("config") @@ -1126,6 +1162,7 @@ impl Arg { /// ``` /// /// ```rust + /// # use clap_builder as clap; /// # #[cfg(feature = "help")] { /// # use clap::{Command, Arg}; /// let m = Command::new("prog") @@ -1182,6 +1219,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// Arg::new("speed") /// .short('s') @@ -1189,6 +1227,7 @@ impl Arg { /// ``` /// /// ```rust + /// # use clap_builder as clap; /// # #[cfg(feature = "help")] { /// # use clap::{Command, Arg}; /// let m = Command::new("prog") @@ -1231,7 +1270,8 @@ impl Arg { /// /// For example, to take a username as argument: /// - /// ``` + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Arg, ValueHint}; /// Arg::new("user") /// .short('u') @@ -1241,7 +1281,8 @@ impl Arg { /// /// To take a full command line and its arguments (for example, when writing a command wrapper): /// - /// ``` + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ValueHint, ArgAction}; /// Command::new("prog") /// .trailing_var_arg(true) @@ -1273,6 +1314,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("pv") /// .arg(Arg::new("option") @@ -1290,6 +1332,7 @@ impl Arg { /// This setting also works when multiple values can be defined: /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("pv") /// .arg(Arg::new("option") @@ -1338,6 +1381,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("pat") @@ -1355,6 +1399,7 @@ impl Arg { /// hyphen is an error. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("pat") @@ -1388,6 +1433,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let res = Command::new("myprog") /// .arg(Arg::new("num").allow_negative_numbers(true)) @@ -1419,6 +1465,7 @@ impl Arg { /// it and the associated value. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -1436,6 +1483,7 @@ impl Arg { /// error. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -1484,6 +1532,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let m = Command::new("prog") /// .arg(Arg::new("config") @@ -1520,6 +1569,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// Arg::new("vals") /// .action(ArgAction::Set) @@ -1532,6 +1582,7 @@ impl Arg { /// to perform them /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("cmds") @@ -1610,6 +1661,7 @@ impl Arg { /// First we use the default value without providing any value at runtime. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, parser::ValueSource}; /// let m = Command::new("prog") /// .arg(Arg::new("opt") @@ -1627,6 +1679,7 @@ impl Arg { /// Next we provide a value at runtime to override the default. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, parser::ValueSource}; /// let m = Command::new("prog") /// .arg(Arg::new("opt") @@ -1704,6 +1757,7 @@ impl Arg { /// /// For POSIX style `--color`: /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, parser::ValueSource}; /// fn cli() -> Command { /// Command::new("prog") @@ -1742,6 +1796,7 @@ impl Arg { /// /// For bool literals: /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, parser::ValueSource, value_parser}; /// fn cli() -> Command { /// Command::new("prog") @@ -1849,6 +1904,7 @@ impl Arg { /// In this example, we show the variable coming from the environment: /// /// ```rust + /// # use clap_builder as clap; /// # use std::env; /// # use clap::{Command, Arg, ArgAction}; /// @@ -1875,6 +1931,7 @@ impl Arg { /// `false`. Anything else will considered as `true`. /// /// ```rust + /// # use clap_builder as clap; /// # use std::env; /// # use clap::{Command, Arg, ArgAction}; /// # use clap::builder::FalseyValueParser; @@ -1910,6 +1967,7 @@ impl Arg { /// In this example, we show the variable coming from an option on the CLI: /// /// ```rust + /// # use clap_builder as clap; /// # use std::env; /// # use clap::{Command, Arg, ArgAction}; /// @@ -1931,6 +1989,7 @@ impl Arg { /// presence of a default: /// /// ```rust + /// # use clap_builder as clap; /// # use std::env; /// # use clap::{Command, Arg, ArgAction}; /// @@ -1952,6 +2011,7 @@ impl Arg { /// In this example, we show the use of multiple values in a single environment variable: /// /// ```rust + /// # use clap_builder as clap; /// # use std::env; /// # use clap::{Command, Arg, ArgAction}; /// @@ -2017,6 +2077,7 @@ impl Arg { /// /// ```rust /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let m = Command::new("prog") /// .arg(Arg::new("cfg") @@ -2068,6 +2129,7 @@ impl Arg { /// /// ```rust /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let m = Command::new("prog") /// .arg(Arg::new("cfg") @@ -2127,6 +2189,7 @@ impl Arg { /// /// ```rust /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("a") // Typically args are grouped alphabetically by name. @@ -2195,6 +2258,7 @@ impl Arg { /// /// ```rust /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("opt") @@ -2247,6 +2311,7 @@ impl Arg { /// /// ```rust /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let m = Command::new("prog") /// .arg(Arg::new("cfg") @@ -2293,6 +2358,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("mode") @@ -2322,6 +2388,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("connect") /// .arg(Arg::new("host") @@ -2351,6 +2418,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("mode") @@ -2380,6 +2448,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("connect") /// .arg(Arg::new("host") @@ -2413,6 +2482,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// Arg::new("debug") /// .hide_short_help(true); @@ -2422,6 +2492,7 @@ impl Arg { /// /// ```rust /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let m = Command::new("prog") /// .arg(Arg::new("cfg") @@ -2450,6 +2521,7 @@ impl Arg { /// /// ```rust /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let m = Command::new("prog") /// .arg(Arg::new("cfg") @@ -2497,6 +2569,7 @@ impl Arg { /// /// ```rust /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let m = Command::new("prog") /// .arg(Arg::new("cfg") @@ -2525,6 +2598,7 @@ impl Arg { /// /// ```rust /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let m = Command::new("prog") /// .arg(Arg::new("cfg") @@ -2567,6 +2641,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// Arg::new("debug") /// .long("debug") @@ -2579,6 +2654,7 @@ impl Arg { /// was one of said arguments. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("debug") @@ -2611,6 +2687,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// Arg::new("debug") /// .long("debug") @@ -2623,6 +2700,7 @@ impl Arg { /// was one of said arguments. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("debug") @@ -2665,6 +2743,7 @@ impl Arg { /// First we use the default value only if another arg is present at runtime. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// # use clap::builder::{ArgPredicate}; /// let m = Command::new("prog") @@ -2684,6 +2763,7 @@ impl Arg { /// Next we run the same test, but without providing `--flag`. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("flag") @@ -2702,6 +2782,7 @@ impl Arg { /// Now lets only use the default value if `--opt` contains the value `special`. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("opt") @@ -2721,6 +2802,7 @@ impl Arg { /// default value. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("opt") @@ -2740,6 +2822,7 @@ impl Arg { /// value of some other Arg. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("flag") @@ -2799,6 +2882,7 @@ impl Arg { /// First we use the default value only if another arg is present at runtime. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("flag") @@ -2823,6 +2907,7 @@ impl Arg { /// Next we run the same test, but without providing `--flag`. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("prog") /// .arg(Arg::new("flag") @@ -2845,6 +2930,7 @@ impl Arg { /// true, only the first evaluated "wins" /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// # use clap::builder::ArgPredicate; /// let m = Command::new("prog") @@ -2912,6 +2998,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Arg; /// Arg::new("config") /// .required_unless_present("debug") @@ -2922,6 +3009,7 @@ impl Arg { /// but it's not an error because the `unless` arg has been supplied. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -2941,6 +3029,7 @@ impl Arg { /// Setting `Arg::required_unless_present(name)` and *not* supplying `name` or this arg is an error. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -2979,6 +3068,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Arg; /// Arg::new("config") /// .required_unless_present_all(["cfg", "dbg"]) @@ -2989,6 +3079,7 @@ impl Arg { /// because *all* of the `names` args have been supplied. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -3012,6 +3103,7 @@ impl Arg { /// either *all* of `unless` args or the `self` arg is an error. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -3055,6 +3147,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Arg; /// Arg::new("config") /// .required_unless_present_any(["cfg", "dbg"]) @@ -3067,6 +3160,7 @@ impl Arg { /// have been supplied. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -3090,6 +3184,7 @@ impl Arg { /// or this arg is an error. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -3127,6 +3222,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Arg; /// Arg::new("config") /// .required_if_eq("other_arg", "value") @@ -3134,6 +3230,7 @@ impl Arg { /// ``` /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -3214,6 +3311,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Arg; /// Arg::new("config") /// .required_if_eq_any([ @@ -3228,6 +3326,7 @@ impl Arg { /// anything other than `val`, this argument isn't required. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -3254,6 +3353,7 @@ impl Arg { /// value of `val` but *not* using this arg is an error. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -3297,6 +3397,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Arg; /// Arg::new("config") /// .required_if_eq_all([ @@ -3311,6 +3412,7 @@ impl Arg { /// anything other than `val`, this argument isn't required. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -3337,6 +3439,7 @@ impl Arg { /// value of `val` but *not* using this arg is an error. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -3379,6 +3482,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Arg; /// Arg::new("config") /// .requires_if("val", "arg") @@ -3390,6 +3494,7 @@ impl Arg { /// `val`, the other argument isn't required. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -3408,6 +3513,7 @@ impl Arg { /// `arg` is an error. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -3439,6 +3545,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Arg; /// Arg::new("config") /// .requires_ifs([ @@ -3453,6 +3560,7 @@ impl Arg { /// than `val`, `arg` isn't required. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -3478,6 +3586,7 @@ impl Arg { /// arguments is an error. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction, builder::ArgPredicate}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -3538,6 +3647,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Arg; /// Arg::new("config") /// .conflicts_with("debug") @@ -3547,6 +3657,7 @@ impl Arg { /// Setting conflicting argument, and having both arguments present at runtime is an error. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -3592,6 +3703,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Arg; /// Arg::new("config") /// .conflicts_with_all(["debug", "input"]) @@ -3602,6 +3714,7 @@ impl Arg { /// conflicting argument is an error. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("cfg") @@ -3640,6 +3753,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, arg}; /// let m = Command::new("prog") /// .arg(arg!(-f --flag "some flag") @@ -3679,6 +3793,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, arg}; /// let m = Command::new("prog") /// .arg(arg!(-f --flag "some flag") @@ -3722,6 +3837,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Arg; /// let arg = Arg::new("foo").long_help("long help"); /// assert_eq!(Some("long help".to_owned()), arg.get_long_help().map(|s| s.to_string())); @@ -3904,6 +4020,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use std::ffi::OsStr; /// # use clap::Arg; /// let arg = Arg::new("foo").env("ENVIRONMENT"); @@ -3919,6 +4036,7 @@ impl Arg { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Arg; /// let arg = Arg::new("foo").default_value("default value"); /// assert_eq!(arg.get_default_values(), &["default value"]); @@ -3931,7 +4049,8 @@ impl Arg { /// /// # Examples /// - /// ``` + /// ```rust + /// # use clap_builder as clap; /// # use clap::Arg; /// let arg = Arg::new("foo"); /// assert_eq!(arg.is_positional(), true); @@ -3977,6 +4096,7 @@ impl Arg { /// # Example /// /// ```rust + /// # use clap_builder as clap; /// let cmd = clap::Command::new("raw") /// .arg( /// clap::Arg::new("port") diff --git a/src/builder/arg_group.rs b/clap_builder/src/builder/arg_group.rs similarity index 97% rename from src/builder/arg_group.rs rename to clap_builder/src/builder/arg_group.rs index a6386a1c03a..d3a37c1bfb3 100644 --- a/src/builder/arg_group.rs +++ b/clap_builder/src/builder/arg_group.rs @@ -35,6 +35,7 @@ use crate::util::Id; /// the arguments from the specified group is present at runtime. /// /// ```rust +/// # use clap_builder as clap; /// # use clap::{Command, arg, ArgGroup, error::ErrorKind}; /// let result = Command::new("cmd") /// .arg(arg!(--"set-ver" "set the version manually")) @@ -53,6 +54,7 @@ use crate::util::Id; /// /// This next example shows a passing parse of the same scenario /// ```rust +/// # use clap_builder as clap; /// # use clap::{Command, arg, ArgGroup, Id}; /// let result = Command::new("cmd") /// .arg(arg!(--"set-ver" "set the version manually")) @@ -102,6 +104,7 @@ impl ArgGroup { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, ArgGroup}; /// ArgGroup::new("config") /// # ; @@ -115,6 +118,7 @@ impl ArgGroup { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, ArgGroup}; /// ArgGroup::default().id("config") /// # ; @@ -130,6 +134,7 @@ impl ArgGroup { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgGroup, ArgAction}; /// let m = Command::new("myprog") /// .arg(Arg::new("flag") @@ -163,6 +168,7 @@ impl ArgGroup { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgGroup, ArgAction}; /// let m = Command::new("myprog") /// .arg(Arg::new("flag") @@ -193,6 +199,7 @@ impl ArgGroup { /// # Example /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{ArgGroup}; /// let args: Vec<&str> = vec!["a1".into(), "a4".into()]; /// let grp = ArgGroup::new("program").args(&args); @@ -213,6 +220,7 @@ impl ArgGroup { /// group /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgGroup, ArgAction}; /// let m = Command::new("myprog") /// .arg(Arg::new("flag") @@ -232,6 +240,7 @@ impl ArgGroup { /// an error if more than one of the args in the group was used. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgGroup, error::ErrorKind, ArgAction}; /// let result = Command::new("myprog") /// .arg(Arg::new("flag") @@ -263,6 +272,7 @@ impl ArgGroup { /// # Example /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{ArgGroup}; /// let mut group = ArgGroup::new("myprog") /// .args(["f", "c"]) @@ -290,6 +300,7 @@ impl ArgGroup { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgGroup, error::ErrorKind, ArgAction}; /// let result = Command::new("myprog") /// .arg(Arg::new("flag") @@ -329,6 +340,7 @@ impl ArgGroup { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgGroup, error::ErrorKind, ArgAction}; /// let result = Command::new("myprog") /// .arg(Arg::new("flag") @@ -373,6 +385,7 @@ impl ArgGroup { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgGroup, error::ErrorKind, ArgAction}; /// let result = Command::new("myprog") /// .arg(Arg::new("flag") @@ -418,6 +431,7 @@ impl ArgGroup { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgGroup, error::ErrorKind, ArgAction}; /// let result = Command::new("myprog") /// .arg(Arg::new("flag") @@ -459,6 +473,7 @@ impl ArgGroup { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgGroup, error::ErrorKind, ArgAction}; /// let result = Command::new("myprog") /// .arg(Arg::new("flag") diff --git a/src/builder/arg_predicate.rs b/clap_builder/src/builder/arg_predicate.rs similarity index 100% rename from src/builder/arg_predicate.rs rename to clap_builder/src/builder/arg_predicate.rs diff --git a/src/builder/arg_settings.rs b/clap_builder/src/builder/arg_settings.rs similarity index 100% rename from src/builder/arg_settings.rs rename to clap_builder/src/builder/arg_settings.rs diff --git a/src/builder/command.rs b/clap_builder/src/builder/command.rs similarity index 97% rename from src/builder/command.rs rename to clap_builder/src/builder/command.rs index f76c40cfd47..acbfae28cdd 100644 --- a/src/builder/command.rs +++ b/clap_builder/src/builder/command.rs @@ -52,6 +52,7 @@ use crate::builder::debug_asserts::assert_app; /// # Examples /// /// ```no_run +/// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let m = Command::new("My Program") /// .author("Me, me@mail.com") @@ -120,7 +121,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// Command::new("My Program") /// # ; @@ -144,7 +146,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, arg, Arg}; /// Command::new("myprog") /// // Adding a single "flag" argument with a short and help text, using Arg::new() @@ -186,11 +189,12 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, arg, Arg}; /// Command::new("myprog") /// .args([ - /// arg!("[debug] -d 'turns on debugging info'"), + /// arg!(-d --debug "turns on debugging info"), /// Arg::new("input").help("the input file to use") /// ]) /// # ; @@ -215,6 +219,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// /// let mut cmd = Command::new("foo") @@ -261,6 +266,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// /// let mut cmd = Command::new("foo") @@ -313,13 +319,14 @@ impl Command { /// The following example demonstrates using an [`ArgGroup`] to ensure that one, and only one, /// of the arguments from the specified group is present at runtime. /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, arg, ArgGroup}; /// Command::new("cmd") - /// .arg(arg!("--set-ver [ver] 'set the version manually'")) - /// .arg(arg!("--major 'auto increase major'")) - /// .arg(arg!("--minor 'auto increase minor'")) - /// .arg(arg!("--patch 'auto increase patch'")) + /// .arg(arg!(--"set-ver" "set the version manually").required(false)) + /// .arg(arg!(--major "auto increase major")) + /// .arg(arg!(--minor "auto increase minor")) + /// .arg(arg!(--patch "auto increase patch")) /// .group(ArgGroup::new("vers") /// .args(["set-ver", "major", "minor","patch"]) /// .required(true)) @@ -336,15 +343,16 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, arg, ArgGroup}; /// Command::new("cmd") - /// .arg(arg!("--set-ver [ver] 'set the version manually'")) - /// .arg(arg!("--major 'auto increase major'")) - /// .arg(arg!("--minor 'auto increase minor'")) - /// .arg(arg!("--patch 'auto increase patch'")) - /// .arg(arg!("-c [FILE] 'a config file'")) - /// .arg(arg!("-i [IFACE] 'an interface'")) + /// .arg(arg!(--"set-ver" "set the version manually").required(false)) + /// .arg(arg!(--major "auto increase major")) + /// .arg(arg!(--minor "auto increase minor")) + /// .arg(arg!(--patch "auto increase patch")) + /// .arg(arg!(-c "a config file").required(false)) + /// .arg(arg!(-i "an interface").required(false)) /// .groups([ /// ArgGroup::new("vers") /// .args(["set-ver", "major", "minor","patch"]) @@ -374,12 +382,13 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, arg}; /// Command::new("myprog") /// .subcommand(Command::new("config") /// .about("Controls configuration features") - /// .arg(arg!(" 'Required configuration file to use'"))) + /// .arg(arg!( "Required configuration file to use"))) /// # ; /// ``` #[inline] @@ -404,6 +413,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, }; /// # Command::new("myprog") /// .subcommands( [ @@ -434,6 +444,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// fn cmd() -> Command { /// Command::new("foo") @@ -461,6 +472,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, error::ErrorKind}; /// let mut cmd = Command::new("myprog"); /// let err = cmd.error(ErrorKind::InvalidValue, "Some failure case"); @@ -478,6 +490,7 @@ impl Command { /// # Examples /// /// ```no_run + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let matches = Command::new("myprog") /// // Args and options go here... @@ -501,6 +514,7 @@ impl Command { /// # Examples /// /// ```no_run + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let mut cmd = Command::new("myprog") /// // Args and options go here... @@ -528,6 +542,7 @@ impl Command { /// # Examples /// /// ```no_run + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let matches = Command::new("myprog") /// // Args and options go here... @@ -560,6 +575,7 @@ impl Command { /// # Examples /// /// ```no_run + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let arg_vec = vec!["my_prog", "some", "args", "to", "parse"]; /// @@ -598,6 +614,7 @@ impl Command { /// # Examples /// /// ```no_run + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let arg_vec = vec!["my_prog", "some", "args", "to", "parse"]; /// @@ -643,6 +660,7 @@ impl Command { /// # Examples /// /// ```no_run + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let arg_vec = vec!["my_prog", "some", "args", "to", "parse"]; /// @@ -715,6 +733,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// let mut cmd = Command::new("myprog"); /// cmd.print_help(); @@ -739,6 +758,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// let mut cmd = Command::new("myprog"); /// cmd.print_long_help(); @@ -766,6 +786,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// use std::io; /// let mut cmd = Command::new("myprog"); @@ -792,6 +813,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// use std::io; /// let mut cmd = Command::new("myprog"); @@ -852,6 +874,7 @@ impl Command { /// ### Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// use std::io; /// let cmd = Command::new("myprog"); @@ -876,6 +899,7 @@ impl Command { /// ### Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// use std::io; /// let cmd = Command::new("myprog"); @@ -894,6 +918,7 @@ impl Command { /// ### Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// use std::io; /// let mut cmd = Command::new("myprog"); @@ -925,6 +950,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, arg}; /// let m = Command::new("myprog") /// .no_binary_name(true) @@ -951,6 +977,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, arg}; /// let cmd = Command::new("cmd") /// .ignore_errors(true) @@ -1007,6 +1034,7 @@ impl Command { /// # Examples /// /// ```no_run + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// Command::new("myprog") /// .dont_delimit_trailing_values(true) @@ -1032,6 +1060,7 @@ impl Command { /// # Examples /// /// ```no_run + /// # use clap_builder as clap; /// # use clap::{Command, ColorChoice}; /// Command::new("myprog") /// .color(ColorChoice::Never) @@ -1062,11 +1091,12 @@ impl Command { /// /// **NOTE:** This setting applies globally and *not* on a per-command basis. /// - /// **NOTE:** This requires the [`wrap_help` feature][crate::_features] + /// **NOTE:** This requires the `wrap_help` feature /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// Command::new("myprog") /// .term_width(80) @@ -1089,11 +1119,12 @@ impl Command { /// /// **NOTE:** This setting applies globally and *not* on a per-command basis. /// - /// **NOTE:** This requires the [`wrap_help` feature][crate::_features] + /// **NOTE:** This requires the `wrap_help` feature /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// Command::new("myprog") /// .max_term_width(100) @@ -1112,6 +1143,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, error::ErrorKind}; /// let res = Command::new("myprog") /// .disable_version_flag(true) @@ -1139,6 +1171,7 @@ impl Command { /// # Examples /// /// ```no_run + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// Command::new("myprog") /// .version("v1.1") @@ -1166,6 +1199,7 @@ impl Command { /// # Examples /// /// ```no_run + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// Command::new("myprog") /// .next_line_help(true) @@ -1187,6 +1221,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, error::ErrorKind}; /// let res = Command::new("myprog") /// .disable_help_flag(true) @@ -1210,6 +1245,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, error::ErrorKind}; /// let res = Command::new("myprog") /// .disable_help_subcommand(true) @@ -1240,6 +1276,7 @@ impl Command { /// # Examples /// /// ```no_run + /// # use clap_builder as clap; /// # use clap::Command; /// Command::new("myprog") /// .disable_colored_help(true) @@ -1264,6 +1301,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// Command::new("myprog") /// .help_expected(true) @@ -1277,6 +1315,7 @@ impl Command { /// # Panics /// /// ```rust,no_run + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// Command::new("myapp") /// .help_expected(true) @@ -1363,6 +1402,7 @@ impl Command { /// # Examples /// /// ```no_run + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let m = Command::new("prog") /// .infer_subcommands(true) @@ -1422,7 +1462,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// Command::new("My Program") /// .bin_name("my_binary") @@ -1438,7 +1479,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// Command::new("My Program") /// .display_name("my_program") @@ -1461,7 +1503,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// Command::new("myprog") /// .author("Me, me@mymain.com") @@ -1484,7 +1527,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// Command::new("myprog") /// .about("Does really amazing things for great people") @@ -1505,7 +1549,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// Command::new("myprog") /// .long_about( @@ -1530,7 +1575,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// Command::new("myprog") /// .after_help("Does really amazing things for great people... but be careful with -R!") @@ -1552,7 +1598,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// Command::new("myprog") /// .after_long_help("Does really amazing things to great people... but be careful with -R, \ @@ -1573,7 +1620,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// Command::new("myprog") /// .before_help("Some info I'd like to appear before the help info") @@ -1593,7 +1641,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// Command::new("myprog") /// .before_long_help("Some verbose and long info I'd like to appear before the help info") @@ -1615,7 +1664,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// Command::new("myprog") /// .version("v0.1.24") @@ -1637,7 +1687,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// Command::new("myprog") /// .long_version( @@ -1670,7 +1721,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// Command::new("myprog") /// .override_usage("myapp [-clDas] ") @@ -1679,7 +1731,8 @@ impl Command { /// /// Or for multiple usage lines: /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// Command::new("myprog") /// .override_usage( @@ -1708,7 +1761,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// Command::new("myapp") /// .override_help("myapp v1.0\n\ @@ -1768,7 +1822,8 @@ impl Command { /// /// For a very brief help: /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// Command::new("myprog") /// .version("1.0") @@ -1778,7 +1833,8 @@ impl Command { /// /// For showing more application context: /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// Command::new("myprog") /// .version("1.0") @@ -1899,6 +1955,7 @@ impl Command { /// end up getting parsed as if the user typed the entire incantation. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// let m = Command::new("cmd") /// .subcommand(Command::new("module") @@ -1932,6 +1989,7 @@ impl Command { /// need to change! /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("cmd") /// .arg(Arg::new("save-context") @@ -1954,6 +2012,7 @@ impl Command { /// above to enforce this: /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("cmd") /// .arg(Arg::new("save-context") @@ -1995,6 +2054,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command}; /// Command::new("myprog") /// .arg_required_else_help(true); @@ -2084,6 +2144,7 @@ impl Command { /// Style number one from above: /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// // Assume there is an external subcommand named "subcmd" /// let m = Command::new("myprog") @@ -2102,6 +2163,7 @@ impl Command { /// Now the same example, but using a default value for the first optional positional argument /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// // Assume there is an external subcommand named "subcmd" /// let m = Command::new("myprog") @@ -2121,6 +2183,7 @@ impl Command { /// Style number two from above: /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// // Assume there is an external subcommand named "subcmd" /// let m = Command::new("myprog") @@ -2140,6 +2203,7 @@ impl Command { /// Now nofice if we don't specify `foo` or `baz` but use the `--` operator. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// // Assume there is an external subcommand named "subcmd" /// let m = Command::new("myprog") @@ -2176,6 +2240,7 @@ impl Command { /// # Examples /// /// ``` + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let matches = Command::new("pacman") /// .subcommand( @@ -2212,7 +2277,8 @@ impl Command { /// `--` such as `--sync` they will be stripped. Hyphens in the middle of the word; however, /// will *not* be stripped (i.e. `sync-file` is allowed). /// - /// ``` + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let matches = Command::new("pacman") /// .subcommand( @@ -2255,6 +2321,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, }; /// let m = Command::new("myprog") /// .subcommand(Command::new("test") @@ -2281,7 +2348,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, }; /// let m = Command::new("myprog") /// .subcommand(Command::new("test").short_flag('t') @@ -2308,7 +2376,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, }; /// let m = Command::new("myprog") /// .subcommand(Command::new("test").long_flag("test") @@ -2343,6 +2412,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let m = Command::new("myprog") /// .subcommand(Command::new("test") @@ -2370,6 +2440,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, }; /// let m = Command::new("myprog") /// .subcommand(Command::new("test").short_flag('t') @@ -2398,6 +2469,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, }; /// let m = Command::new("myprog") /// .subcommand(Command::new("test").long_flag("test") @@ -2434,7 +2506,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let m = Command::new("myprog") /// .subcommand(Command::new("test") @@ -2463,7 +2536,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, }; /// let m = Command::new("myprog") /// .subcommand(Command::new("test").short_flag('t') @@ -2493,7 +2567,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, }; /// let m = Command::new("myprog") /// .subcommand(Command::new("test").long_flag("test") @@ -2530,7 +2605,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, }; /// let m = Command::new("myprog") /// .subcommand(Command::new("test") @@ -2552,7 +2628,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, }; /// let m = Command::new("myprog") /// .subcommand(Command::new("test").short_flag('b') @@ -2576,7 +2653,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, }; /// let m = Command::new("myprog") /// .subcommand(Command::new("test").long_flag("test") @@ -2610,6 +2688,7 @@ impl Command { /// /// ```rust /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; /// # use clap::{Command, }; /// let m = Command::new("cust-ord") /// .subcommand(Command::new("alpha") // typically subcommands are grouped @@ -2657,6 +2736,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// Command::new("myprog") /// .subcommand( @@ -2680,6 +2760,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, error::ErrorKind}; /// let err = Command::new("myprog") /// .subcommand_required(true) @@ -2716,6 +2797,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use std::ffi::OsString; /// # use clap::Command; /// // Assume there is an external subcommand named "subcmd" @@ -2759,6 +2841,7 @@ impl Command { /// /// ```rust /// # #[cfg(unix)] { + /// # use clap_builder as clap; /// # use std::ffi::OsString; /// # use clap::Command; /// # use clap::value_parser; @@ -2782,7 +2865,8 @@ impl Command { /// # } /// ``` /// - /// ``` + /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// # use clap::value_parser; /// // Assume there is an external subcommand named "subcmd" @@ -2829,6 +2913,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// Command::new("myprog") /// .args_conflicts_with_subcommands(true); @@ -2866,6 +2951,7 @@ impl Command { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let cmd = Command::new("cmd").subcommand(Command::new("sub")).arg( /// Arg::new("arg") @@ -2916,6 +3002,7 @@ impl Command { /// This first example shows that it is an error to not use a required argument /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind}; /// let err = Command::new("myprog") /// .subcommand_negates_reqs(true) @@ -2933,6 +3020,7 @@ impl Command { /// valid subcommand is used. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind}; /// let noerr = Command::new("myprog") /// .subcommand_negates_reqs(true) @@ -3017,6 +3105,7 @@ impl Command { /// This does not allow the subcommand to be passed as the first non-path argument. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, error::ErrorKind}; /// let mut cmd = Command::new("hostname") /// .multicall(true) @@ -3044,6 +3133,7 @@ impl Command { /// and as subcommands of the "main" applet. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// fn applet_commands() -> [Command; 2] { /// [Command::new("true"), Command::new("false")] @@ -3087,7 +3177,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// Command::new("myprog") /// .subcommand(Command::new("sub1")) @@ -3113,7 +3204,8 @@ impl Command { /// /// but usage of `subcommand_value_name` /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// Command::new("myprog") /// .subcommand(Command::new("sub1")) @@ -3151,7 +3243,8 @@ impl Command { /// /// # Examples /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// Command::new("myprog") /// .subcommand(Command::new("sub1")) @@ -3177,7 +3270,8 @@ impl Command { /// /// but usage of `subcommand_help_heading` /// - /// ```no_run + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// Command::new("myprog") /// .subcommand(Command::new("sub1")) @@ -3693,6 +3787,7 @@ impl Command { /// # Example /// /// ```rust + /// # use clap_builder as clap; /// let cmd = clap::Command::new("raw") /// .external_subcommand_value_parser(clap::value_parser!(String)); /// let value_parser = cmd.get_external_subcommand_value_parser(); diff --git a/src/builder/debug_asserts.rs b/clap_builder/src/builder/debug_asserts.rs similarity index 99% rename from src/builder/debug_asserts.rs rename to clap_builder/src/builder/debug_asserts.rs index 86e36778cff..dbd8bbbc674 100644 --- a/src/builder/debug_asserts.rs +++ b/clap_builder/src/builder/debug_asserts.rs @@ -274,28 +274,20 @@ pub(crate) fn assert_app(cmd: &Command) { } for group in cmd.get_groups() { - let derive_hint = if cfg!(feature = "derive") { - " (note: `Args` implicitly creates `ArgGroup`s; disable with `#[group(skip)]`" - } else { - "" - }; - // Name conflicts assert!( cmd.get_groups().filter(|x| x.id == group.id).count() < 2, - "Command {}: Argument group name must be unique\n\n\t'{}' is already in use{}", + "Command {}: Argument group name must be unique\n\n\t'{}' is already in use", cmd.get_name(), group.get_id(), - derive_hint ); // Groups should not have naming conflicts with Args assert!( !cmd.get_arguments().any(|x| x.get_id() == group.get_id()), - "Command {}: Argument group name '{}' must not conflict with argument name{}", + "Command {}: Argument group name '{}' must not conflict with argument name", cmd.get_name(), group.get_id(), - derive_hint ); for arg in &group.args { diff --git a/src/builder/mod.rs b/clap_builder/src/builder/mod.rs similarity index 100% rename from src/builder/mod.rs rename to clap_builder/src/builder/mod.rs diff --git a/src/builder/os_str.rs b/clap_builder/src/builder/os_str.rs similarity index 99% rename from src/builder/os_str.rs rename to clap_builder/src/builder/os_str.rs index bb2370debc2..6bd9282ece2 100644 --- a/src/builder/os_str.rs +++ b/clap_builder/src/builder/os_str.rs @@ -2,8 +2,8 @@ use crate::builder::Str; /// A UTF-8-encoded fixed string /// -/// **NOTE:** To support dynamic values (i.e. `OsString`), enable the [`string` -/// feature][crate::_features] +/// **NOTE:** To support dynamic values (i.e. `OsString`), enable the `string` +/// feature #[derive(Default, Clone, Eq, PartialEq, PartialOrd, Ord, Hash)] pub struct OsStr { name: Inner, diff --git a/src/builder/possible_value.rs b/clap_builder/src/builder/possible_value.rs similarity index 96% rename from src/builder/possible_value.rs rename to clap_builder/src/builder/possible_value.rs index 7a313ad2585..b0282e593dd 100644 --- a/src/builder/possible_value.rs +++ b/clap_builder/src/builder/possible_value.rs @@ -16,6 +16,7 @@ use crate::util::eq_ignore_case; /// # Examples /// /// ```rust +/// # use clap_builder as clap; /// # use clap::{Arg, builder::PossibleValue, ArgAction}; /// let cfg = Arg::new("config") /// .action(ArgAction::Set) @@ -50,6 +51,7 @@ impl PossibleValue { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::builder::PossibleValue; /// PossibleValue::new("fast") /// # ; @@ -72,6 +74,7 @@ impl PossibleValue { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::builder::PossibleValue; /// PossibleValue::new("slow") /// .help("not fast") @@ -92,6 +95,7 @@ impl PossibleValue { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::builder::PossibleValue; /// PossibleValue::new("secret") /// .hide(true) @@ -110,6 +114,7 @@ impl PossibleValue { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::builder::PossibleValue; /// PossibleValue::new("slow") /// .alias("not-fast") @@ -130,6 +135,7 @@ impl PossibleValue { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::builder::PossibleValue; /// PossibleValue::new("slow") /// .aliases(["not-fast", "snake-like"]) @@ -208,6 +214,7 @@ impl PossibleValue { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::builder::PossibleValue; /// let arg_value = PossibleValue::new("fast").alias("not-slow"); /// diff --git a/src/builder/range.rs b/clap_builder/src/builder/range.rs similarity index 98% rename from src/builder/range.rs rename to clap_builder/src/builder/range.rs index 6ecf05369a5..a403915454d 100644 --- a/src/builder/range.rs +++ b/clap_builder/src/builder/range.rs @@ -26,7 +26,8 @@ impl ValueRange { /// /// # Examples /// - /// ``` + /// ```rust + /// # use clap_builder as clap; /// # use clap::builder::ValueRange; /// let range = ValueRange::new(5); /// let range = ValueRange::new(5..10); @@ -38,6 +39,7 @@ impl ValueRange { /// /// While this will panic: /// ```should_panic + /// # use clap_builder as clap; /// # use clap::builder::ValueRange; /// let range = ValueRange::new(10..5); // Panics! /// ``` @@ -67,7 +69,8 @@ impl ValueRange { /// /// # Examples /// - /// ``` + /// ```rust + /// # use clap_builder as clap; /// # use clap::builder::ValueRange; /// let range = ValueRange::new(5); /// assert!(range.takes_values()); diff --git a/src/builder/resettable.rs b/clap_builder/src/builder/resettable.rs similarity index 99% rename from src/builder/resettable.rs rename to clap_builder/src/builder/resettable.rs index e0b82b11b48..057274012c7 100644 --- a/src/builder/resettable.rs +++ b/clap_builder/src/builder/resettable.rs @@ -19,6 +19,7 @@ use crate::builder::ValueRange; /// # Example /// /// ```rust +/// # use clap_builder as clap; /// # use clap::Command; /// # use clap::Arg; /// fn common() -> Command { diff --git a/src/builder/str.rs b/clap_builder/src/builder/str.rs similarity index 99% rename from src/builder/str.rs rename to clap_builder/src/builder/str.rs index be69c3f6ee6..9bded8147fe 100644 --- a/src/builder/str.rs +++ b/clap_builder/src/builder/str.rs @@ -1,7 +1,7 @@ /// A UTF-8-encoded fixed string /// -/// **NOTE:** To support dynamic values (i.e. `String`), enable the [`string` -/// feature][crate::_features] +/// **NOTE:** To support dynamic values (i.e. `String`), enable the `string` +/// feature #[derive(Default, Clone, Eq, PartialEq, PartialOrd, Ord, Hash)] pub struct Str { name: Inner, diff --git a/src/builder/styled_str.rs b/clap_builder/src/builder/styled_str.rs similarity index 100% rename from src/builder/styled_str.rs rename to clap_builder/src/builder/styled_str.rs diff --git a/src/builder/tests.rs b/clap_builder/src/builder/tests.rs similarity index 100% rename from src/builder/tests.rs rename to clap_builder/src/builder/tests.rs diff --git a/src/builder/value_hint.rs b/clap_builder/src/builder/value_hint.rs similarity index 100% rename from src/builder/value_hint.rs rename to clap_builder/src/builder/value_hint.rs diff --git a/src/builder/value_parser.rs b/clap_builder/src/builder/value_parser.rs similarity index 98% rename from src/builder/value_parser.rs rename to clap_builder/src/builder/value_parser.rs index 3d2643938c2..d4a1a7ab7cb 100644 --- a/src/builder/value_parser.rs +++ b/clap_builder/src/builder/value_parser.rs @@ -18,6 +18,7 @@ use crate::parser::AnyValueId; /// # Example /// /// ```rust +/// # use clap_builder as clap; /// let mut cmd = clap::Command::new("raw") /// .arg( /// clap::Arg::new("color") @@ -83,6 +84,7 @@ impl ValueParser { /// # Example /// /// ```rust + /// # use clap_builder as clap; /// type EnvVar = (String, Option); /// fn parse_env_var(env: &str) -> Result { /// if let Some((var, value)) = env.split_once('=') { @@ -120,6 +122,7 @@ impl ValueParser { /// # Example /// /// ```rust + /// # use clap_builder as clap; /// let mut cmd = clap::Command::new("raw") /// .arg( /// clap::Arg::new("download") @@ -146,6 +149,7 @@ impl ValueParser { /// # Example /// /// ```rust + /// # use clap_builder as clap; /// let mut cmd = clap::Command::new("raw") /// .arg( /// clap::Arg::new("port") @@ -168,6 +172,7 @@ impl ValueParser { /// /// ```rust /// # #[cfg(unix)] { + /// # use clap_builder as clap; /// # use clap::{Command, Arg, builder::ValueParser}; /// use std::ffi::OsString; /// use std::os::unix::ffi::{OsStrExt,OsStringExt}; @@ -198,6 +203,7 @@ impl ValueParser { /// # Example /// /// ```rust + /// # use clap_builder as clap; /// # use std::path::PathBuf; /// # use std::path::Path; /// let mut cmd = clap::Command::new("raw") @@ -263,6 +269,7 @@ impl ValueParser { /// # Example /// /// ```rust +/// # use clap_builder as clap; /// let mut cmd = clap::Command::new("raw") /// .arg( /// clap::Arg::new("hostname") @@ -304,6 +311,7 @@ impl From<_AnonymousValueParser> for ValueParser { /// # Examples /// /// ```rust +/// # use clap_builder as clap; /// let mut cmd = clap::Command::new("raw") /// .arg( /// clap::Arg::new("port") @@ -334,6 +342,7 @@ impl From> for ValueParser { /// # Examples /// /// ```rust +/// # use clap_builder as clap; /// let mut cmd = clap::Command::new("raw") /// .arg( /// clap::Arg::new("port") @@ -364,6 +373,7 @@ impl From> for ValueParser { /// # Examples /// /// ```rust +/// # use clap_builder as clap; /// let mut cmd = clap::Command::new("raw") /// .arg( /// clap::Arg::new("port") @@ -394,6 +404,7 @@ impl From> for ValueParser { /// # Examples /// /// ```rust +/// # use clap_builder as clap; /// let mut cmd = clap::Command::new("raw") /// .arg( /// clap::Arg::new("port") @@ -424,6 +435,7 @@ impl From> for ValueParser { /// # Examples /// /// ```rust +/// # use clap_builder as clap; /// let mut cmd = clap::Command::new("raw") /// .arg( /// clap::Arg::new("port") @@ -454,6 +466,7 @@ impl From> for ValueParser { /// # Examples /// /// ```rust +/// # use clap_builder as clap; /// let mut cmd = clap::Command::new("raw") /// .arg( /// clap::Arg::new("port") @@ -483,6 +496,7 @@ impl From for ValueParser { /// # Examples /// /// ```rust +/// # use clap_builder as clap; /// let mut cmd = clap::Command::new("raw") /// .arg( /// clap::Arg::new("color") @@ -517,6 +531,7 @@ where /// # Examples /// /// ```rust +/// # use clap_builder as clap; /// let possible = vec!["always", "auto", "never"]; /// let mut cmd = clap::Command::new("raw") /// .arg( @@ -647,6 +662,7 @@ where /// /// ```rust /// # #[cfg(feature = "error-context")] { +/// # use clap_builder as clap; /// # use clap::error::ErrorKind; /// # use clap::error::ContextKind; /// # use clap::error::ContextValue; @@ -725,6 +741,7 @@ pub trait TypedValueParser: Clone + Send + Sync + 'static { /// # Example /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// # use clap::Arg; /// # use clap::builder::TypedValueParser as _; @@ -769,6 +786,7 @@ pub trait TypedValueParser: Clone + Send + Sync + 'static { /// # Example /// /// ```rust + /// # use clap_builder as clap; /// # use std::ffi::OsString; /// # use std::ffi::OsStr; /// # use std::path::PathBuf; @@ -993,6 +1011,7 @@ impl Default for PathBufValueParser { /// # Example /// /// ```rust +/// # use clap_builder as clap; /// # use std::ffi::OsStr; /// # use clap::ColorChoice; /// # use clap::builder::TypedValueParser; @@ -1111,6 +1130,7 @@ impl Default for EnumValueP /// /// Usage: /// ```rust +/// # use clap_builder as clap; /// let mut cmd = clap::Command::new("raw") /// .arg( /// clap::Arg::new("color") @@ -1126,6 +1146,7 @@ impl Default for EnumValueP /// /// Semantics: /// ```rust +/// # use clap_builder as clap; /// # use std::ffi::OsStr; /// # use clap::builder::TypedValueParser; /// # let cmd = clap::Command::new("test"); @@ -1220,6 +1241,7 @@ where /// /// Usage: /// ```rust +/// # use clap_builder as clap; /// let mut cmd = clap::Command::new("raw") /// .arg( /// clap::Arg::new("port") @@ -1237,6 +1259,7 @@ where /// /// Semantics: /// ```rust +/// # use clap_builder as clap; /// # use std::ffi::OsStr; /// # use clap::builder::TypedValueParser; /// # let cmd = clap::Command::new("test"); @@ -1418,6 +1441,7 @@ impl + Clone + Send + Sync> Default for RangedI64V /// /// Usage: /// ```rust +/// # use clap_builder as clap; /// let mut cmd = clap::Command::new("raw") /// .arg( /// clap::Arg::new("port") @@ -1435,6 +1459,7 @@ impl + Clone + Send + Sync> Default for RangedI64V /// /// Semantics: /// ```rust +/// # use clap_builder as clap; /// # use std::ffi::OsStr; /// # use clap::builder::TypedValueParser; /// # let cmd = clap::Command::new("test"); @@ -1682,6 +1707,7 @@ impl Default for BoolValueParser { /// /// Usage: /// ```rust +/// # use clap_builder as clap; /// let mut cmd = clap::Command::new("raw") /// .arg( /// clap::Arg::new("append") @@ -1697,6 +1723,7 @@ impl Default for BoolValueParser { /// /// Semantics: /// ```rust +/// # use clap_builder as clap; /// # use std::ffi::OsStr; /// # use clap::builder::TypedValueParser; /// # let cmd = clap::Command::new("test"); @@ -1775,6 +1802,7 @@ impl Default for FalseyValueParser { /// /// Usage: /// ```rust +/// # use clap_builder as clap; /// let mut cmd = clap::Command::new("raw") /// .arg( /// clap::Arg::new("append") @@ -1790,6 +1818,7 @@ impl Default for FalseyValueParser { /// /// Semantics: /// ```rust +/// # use clap_builder as clap; /// # use std::ffi::OsStr; /// # use clap::builder::TypedValueParser; /// # let cmd = clap::Command::new("test"); @@ -1873,6 +1902,7 @@ impl Default for BoolishValueParser { /// /// Usage: /// ```rust +/// # use clap_builder as clap; /// let mut cmd = clap::Command::new("raw") /// .arg( /// clap::Arg::new("append") @@ -1888,6 +1918,7 @@ impl Default for BoolishValueParser { /// /// Semantics: /// ```rust +/// # use clap_builder as clap; /// # use std::ffi::OsStr; /// # use clap::builder::TypedValueParser; /// # let cmd = clap::Command::new("test"); @@ -2060,6 +2091,7 @@ where /// # Example /// /// ```rust +/// # use clap_builder as clap; /// #[derive(Copy, Clone, Debug)] /// pub struct Custom(u32); /// @@ -2328,6 +2360,7 @@ pub mod via_prelude { /// /// Usage: /// ```rust +/// # use clap_builder as clap; /// # use std::path::PathBuf; /// # use std::path::Path; /// let mut cmd = clap::Command::new("raw") @@ -2345,6 +2378,7 @@ pub mod via_prelude { /// /// Example mappings: /// ```rust +/// # use clap_builder as clap; /// # use clap::ColorChoice; /// // Built-in types /// let parser = clap::value_parser!(String); diff --git a/src/derive.rs b/clap_builder/src/derive.rs similarity index 80% rename from src/derive.rs rename to clap_builder/src/derive.rs index 3ad72766d48..71c0e825193 100644 --- a/src/derive.rs +++ b/clap_builder/src/derive.rs @@ -1,5 +1,5 @@ //! This module contains traits that are usable with the `#[derive(...)].` -//! macros in [`clap_derive`]. +//! macros in `clap_derive`. use crate::builder::PossibleValue; use crate::{ArgMatches, Command, Error}; @@ -20,63 +20,7 @@ use std::ffi::OsString; /// /// See also [`Subcommand`] and [`Args`]. /// -/// See the [derive reference](crate::_derive) for attributes and best practices. -/// -/// **NOTE:** Deriving requires the [`derive` feature flag][crate::_features] -/// -/// # Examples -/// -/// The following example creates a `Context` struct that would be used -/// throughout the application representing the normalized values coming from -/// the CLI. -/// -/// ```rust -/// # #[cfg(feature = "derive")] { -/// /// My super CLI -/// #[derive(clap::Parser)] -/// #[command(name = "demo")] -/// struct Context { -/// /// More verbose output -/// #[arg(long)] -/// verbose: bool, -/// /// An optional name -/// #[arg(short, long)] -/// name: Option, -/// } -/// # } -/// ``` -/// -/// The equivalent [`Command`] struct + `From` implementation: -/// -/// ```rust -/// # use clap::{Command, Arg, ArgMatches, ArgAction}; -/// Command::new("demo") -/// .about("My super CLI") -/// .arg(Arg::new("verbose") -/// .long("verbose") -/// .action(ArgAction::SetTrue) -/// .help("More verbose output")) -/// .arg(Arg::new("name") -/// .long("name") -/// .short('n') -/// .help("An optional name") -/// .action(ArgAction::Set)); -/// -/// struct Context { -/// verbose: bool, -/// name: Option, -/// } -/// -/// impl From for Context { -/// fn from(m: ArgMatches) -> Self { -/// Context { -/// verbose: m.get_flag("verbose"), -/// name: m.get_one::("name").cloned(), -/// } -/// } -/// } -/// ``` -/// +/// **NOTE:** Deriving requires the `derive` feature flag pub trait Parser: FromArgMatches + CommandFactory + Sized { /// Parse from `std::env::args_os()`, exit on error fn parse() -> Self { @@ -266,27 +210,7 @@ pub trait FromArgMatches: Sized { /// `Args`. /// - `Variant(ChildArgs)`: No attribute is used with enum variants that impl `Args`. /// -/// See the [derive reference](crate::_derive) for attributes and best practices. -/// -/// **NOTE:** Deriving requires the [`derive` feature flag][crate::_features] -/// -/// # Example -/// -/// ```rust -/// # #[cfg(feature = "derive")] { -/// #[derive(clap::Parser)] -/// struct Args { -/// #[command(flatten)] -/// logging: LogArgs, -/// } -/// -/// #[derive(clap::Args)] -/// struct LogArgs { -/// #[arg(long, short = 'v', action = clap::ArgAction::Count)] -/// verbose: u8, -/// } -/// # } -/// ``` +/// **NOTE:** Deriving requires the `derive` feature flag pub trait Args: FromArgMatches + Sized { /// Report the [`ArgGroup::id`][crate::ArgGroup::id] for this set of arguments fn group_id() -> Option { @@ -313,27 +237,7 @@ pub trait Args: FromArgMatches + Sized { /// - `#[command(flatten)] Variant(SubCmd)`: Attribute can only be used with enum variants that impl /// `Subcommand`. /// -/// See the [derive reference](crate::_derive) for attributes and best practices. -/// -/// **NOTE:** Deriving requires the [`derive` feature flag][crate::_features] -/// -/// # Example -/// -/// ```rust -/// # #[cfg(feature = "derive")] { -/// #[derive(clap::Parser)] -/// struct Args { -/// #[command(subcommand)] -/// action: Action, -/// } -/// -/// #[derive(clap::Subcommand)] -/// enum Action { -/// Add, -/// Remove, -/// } -/// # } -/// ``` +/// **NOTE:** Deriving requires the `derive` feature flag pub trait Subcommand: FromArgMatches + Sized { /// Append to [`Command`] so it can instantiate `Self`. /// @@ -356,29 +260,7 @@ pub trait Subcommand: FromArgMatches + Sized { /// - Call [`EnumValueParser`][crate::builder::EnumValueParser] /// - Allowing using the `#[arg(default_value_t)]` attribute without implementing `Display`. /// -/// See the [derive reference](crate::_derive) for attributes and best practices. -/// -/// **NOTE:** Deriving requires the [`derive` feature flag][crate::_features] -/// -/// # Example -/// -/// ```rust -/// # #[cfg(feature = "derive")] { -/// #[derive(clap::Parser)] -/// struct Args { -/// #[arg(value_enum)] -/// level: Level, -/// } -/// -/// #[derive(clap::ValueEnum, Clone)] -/// enum Level { -/// Debug, -/// Info, -/// Warning, -/// Error, -/// } -/// # } -/// ``` +/// **NOTE:** Deriving requires the `derive` feature flag pub trait ValueEnum: Sized + Clone { /// All possible argument values, in display order. fn value_variants<'a>() -> &'a [Self]; diff --git a/src/error/context.rs b/clap_builder/src/error/context.rs similarity index 100% rename from src/error/context.rs rename to clap_builder/src/error/context.rs diff --git a/src/error/format.rs b/clap_builder/src/error/format.rs similarity index 99% rename from src/error/format.rs rename to clap_builder/src/error/format.rs index d3ce6c64c19..f399cd01e46 100644 --- a/src/error/format.rs +++ b/clap_builder/src/error/format.rs @@ -22,7 +22,7 @@ pub trait ErrorFormatter: Sized { /// /// No context is included. /// -/// **NOTE:** Consider removing the [`error-context`][crate::_features] default feature if using this to remove all +/// **NOTE:** Consider removing the `error-context` default feature if using this to remove all /// overhead for [`RichFormatter`]. #[non_exhaustive] pub struct KindFormatter; diff --git a/src/error/kind.rs b/clap_builder/src/error/kind.rs similarity index 96% rename from src/error/kind.rs rename to clap_builder/src/error/kind.rs index 55fac3b973f..a9d576c6f5d 100644 --- a/src/error/kind.rs +++ b/clap_builder/src/error/kind.rs @@ -8,6 +8,7 @@ pub enum ErrorKind { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind}; /// let result = Command::new("prog") /// .arg(Arg::new("speed") @@ -23,6 +24,7 @@ pub enum ErrorKind { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, arg, error::ErrorKind}; /// let result = Command::new("prog") /// .arg(arg!(--flag "some flag")) @@ -41,6 +43,7 @@ pub enum ErrorKind { /// /// ```rust /// # #[cfg(feature = "suggestions")] { + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, }; /// let result = Command::new("prog") /// .subcommand(Command::new("config") @@ -61,6 +64,7 @@ pub enum ErrorKind { /// sign to provide values. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let res = Command::new("prog") /// .arg(Arg::new("color") @@ -79,6 +83,7 @@ pub enum ErrorKind { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, value_parser}; /// fn is_numeric(val: &str) -> Result<(), String> { /// match val.parse::() { @@ -102,6 +107,7 @@ pub enum ErrorKind { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind}; /// let result = Command::new("prog") /// .arg(Arg::new("arg") @@ -119,6 +125,7 @@ pub enum ErrorKind { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind}; /// let result = Command::new("prog") /// .arg(Arg::new("some_opt") @@ -138,6 +145,7 @@ pub enum ErrorKind { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let result = Command::new("prog") /// .arg(Arg::new("some_opt") @@ -159,6 +167,7 @@ pub enum ErrorKind { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// let result = Command::new("prog") /// .arg(Arg::new("debug") @@ -179,6 +188,7 @@ pub enum ErrorKind { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind}; /// let result = Command::new("prog") /// .arg(Arg::new("debug") @@ -195,6 +205,7 @@ pub enum ErrorKind { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, error::ErrorKind}; /// let err = Command::new("prog") /// .subcommand_required(true) @@ -225,6 +236,7 @@ pub enum ErrorKind { /// /// ```rust /// # #[cfg(unix)] { + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, ArgAction}; /// # use std::os::unix::ffi::OsStringExt; /// # use std::ffi::OsString; @@ -254,6 +266,7 @@ pub enum ErrorKind { /// /// ```rust /// # #[cfg(feature = "help")] { + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind}; /// let result = Command::new("prog") /// .try_get_matches_from(vec!["prog", "--help"]); @@ -270,6 +283,7 @@ pub enum ErrorKind { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind, }; /// let result = Command::new("prog") /// .arg_required_else_help(true) @@ -292,6 +306,7 @@ pub enum ErrorKind { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, error::ErrorKind}; /// let result = Command::new("prog") /// .version("3.0") diff --git a/src/error/mod.rs b/clap_builder/src/error/mod.rs similarity index 99% rename from src/error/mod.rs rename to clap_builder/src/error/mod.rs index 84c50ea916a..adbe183fe98 100644 --- a/src/error/mod.rs +++ b/clap_builder/src/error/mod.rs @@ -108,6 +108,7 @@ impl Error { /// /// ```rust /// # #[cfg(feature = "error-context")] { + /// # use clap_builder as clap; /// # use clap::error::ErrorKind; /// # use clap::error::ContextKind; /// # use clap::error::ContextValue; @@ -153,6 +154,7 @@ impl Error { /// # Example /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// # use clap::Arg; /// # use clap::error::KindFormatter; @@ -229,6 +231,7 @@ impl Error { /// /// # Example /// ```no_run + /// # use clap_builder as clap; /// use clap::Command; /// /// match Command::new("Command").try_get_matches() { @@ -259,6 +262,7 @@ impl Error { /// /// # Example /// ```no_run + /// # use clap_builder as clap; /// use clap::Command; /// /// match Command::new("Command").try_get_matches() { diff --git a/clap_builder/src/lib.rs b/clap_builder/src/lib.rs new file mode 100644 index 00000000000..a8c1201e0e4 --- /dev/null +++ b/clap_builder/src/lib.rs @@ -0,0 +1,69 @@ +// Copyright ⓒ 2015-2016 Kevin B. Knapp and [`clap-rs` contributors](https://github.com/clap-rs/clap/graphs/contributors). +// Licensed under the MIT license +// (see LICENSE or ) All files in the project carrying such +// notice may not be copied, modified, or distributed except according to those terms. + +#![cfg_attr(docsrs, feature(doc_auto_cfg))] +#![doc = include_str!("../README.md")] +#![doc(html_logo_url = "https://raw.githubusercontent.com/clap-rs/clap/master/assets/clap.png")] +#![warn( + missing_docs, + missing_debug_implementations, + missing_copy_implementations, + trivial_casts, + unused_allocation, + trivial_numeric_casts, + clippy::single_char_pattern +)] +#![forbid(unsafe_code)] +// HACK https://github.com/rust-lang/rust-clippy/issues/7290 +#![allow(clippy::single_component_path_imports)] +#![allow(clippy::branches_sharing_code)] +// Doesn't allow for debug statements, etc to be unique +#![allow(clippy::if_same_then_else)] +// Breaks up parallelism that clarifies intent +#![allow(clippy::collapsible_else_if)] + +#[cfg(not(feature = "std"))] +compile_error!("`std` feature is currently required to build `clap`"); + +pub use crate::builder::ArgAction; +pub use crate::builder::Command; +pub use crate::builder::ValueHint; +pub use crate::builder::{Arg, ArgGroup}; +pub use crate::parser::ArgMatches; +pub use crate::util::color::ColorChoice; +pub use crate::util::Id; + +/// Command Line Argument Parser Error +/// +/// See [`Command::error`] to create an error. +/// +/// [`Command::error`]: crate::Command::error +pub type Error = crate::error::Error; + +pub use crate::derive::{Args, CommandFactory, FromArgMatches, Parser, Subcommand, ValueEnum}; + +#[doc(hidden)] +pub mod __macro_refs { + #[cfg(feature = "cargo")] + #[doc(hidden)] + pub use once_cell; +} + +#[macro_use] +#[allow(missing_docs)] +mod macros; + +mod derive; + +pub mod builder; +pub mod error; +pub mod parser; + +mod mkeymap; +mod output; +mod util; + +const INTERNAL_ERROR_MSG: &str = "Fatal internal error. Please consider filing a bug \ + report at https://github.com/clap-rs/clap/issues"; diff --git a/src/macros.rs b/clap_builder/src/macros.rs similarity index 98% rename from src/macros.rs rename to clap_builder/src/macros.rs index 9b4949a5746..82a8811984f 100644 --- a/src/macros.rs +++ b/clap_builder/src/macros.rs @@ -4,14 +4,12 @@ /// # Examples /// /// ```no_run -/// # #[macro_use] -/// # extern crate clap; +/// # use clap_builder as clap; +/// # use clap::crate_version; /// # use clap::Command; -/// # fn main() { /// let m = Command::new("cmd") /// .version(crate_version!()) /// .get_matches(); -/// # } /// ``` #[cfg(feature = "cargo")] #[macro_export] @@ -33,14 +31,12 @@ macro_rules! crate_version { /// # Examples /// /// ```no_run -/// # #[macro_use] -/// # extern crate clap; +/// # use clap_builder as clap; +/// # use clap::crate_authors; /// # use clap::Command; -/// # fn main() { /// let m = Command::new("cmd") /// .author(crate_authors!("\n")) /// .get_matches(); -/// # } /// ``` #[cfg(feature = "cargo")] #[macro_export] @@ -66,14 +62,12 @@ macro_rules! crate_authors { /// # Examples /// /// ```no_run -/// # #[macro_use] -/// # extern crate clap; +/// # use clap_builder as clap; +/// # use clap::crate_description; /// # use clap::Command; -/// # fn main() { /// let m = Command::new("cmd") /// .about(crate_description!()) /// .get_matches(); -/// # } /// ``` #[cfg(feature = "cargo")] #[macro_export] @@ -94,13 +88,11 @@ macro_rules! crate_description { /// # Examples /// /// ```no_run -/// # #[macro_use] -/// # extern crate clap; +/// # use clap_builder as clap; +/// # use clap::crate_name; /// # use clap::Command; -/// # fn main() { /// let m = Command::new(crate_name!()) /// .get_matches(); -/// # } /// ``` #[cfg(feature = "cargo")] #[macro_export] @@ -122,11 +114,9 @@ macro_rules! crate_name { /// # Examples /// /// ```no_run -/// # #[macro_use] -/// # extern crate clap; -/// # fn main() { +/// # use clap_builder as clap; +/// # use clap::command; /// let m = command!().get_matches(); -/// # } /// ``` #[cfg(feature = "cargo")] #[macro_export] @@ -508,6 +498,7 @@ macro_rules! arg_impl { /// # Examples /// /// ```rust +/// # use clap_builder as clap; /// # use clap::{Command, Arg, arg}; /// let cmd = Command::new("prog") /// .args(&[ diff --git a/src/mkeymap.rs b/clap_builder/src/mkeymap.rs similarity index 100% rename from src/mkeymap.rs rename to clap_builder/src/mkeymap.rs diff --git a/src/output/fmt.rs b/clap_builder/src/output/fmt.rs similarity index 100% rename from src/output/fmt.rs rename to clap_builder/src/output/fmt.rs diff --git a/src/output/help.rs b/clap_builder/src/output/help.rs similarity index 100% rename from src/output/help.rs rename to clap_builder/src/output/help.rs diff --git a/src/output/help_template.rs b/clap_builder/src/output/help_template.rs similarity index 100% rename from src/output/help_template.rs rename to clap_builder/src/output/help_template.rs diff --git a/src/output/mod.rs b/clap_builder/src/output/mod.rs similarity index 100% rename from src/output/mod.rs rename to clap_builder/src/output/mod.rs diff --git a/src/output/textwrap/core.rs b/clap_builder/src/output/textwrap/core.rs similarity index 100% rename from src/output/textwrap/core.rs rename to clap_builder/src/output/textwrap/core.rs diff --git a/src/output/textwrap/mod.rs b/clap_builder/src/output/textwrap/mod.rs similarity index 100% rename from src/output/textwrap/mod.rs rename to clap_builder/src/output/textwrap/mod.rs diff --git a/src/output/textwrap/word_separators.rs b/clap_builder/src/output/textwrap/word_separators.rs similarity index 100% rename from src/output/textwrap/word_separators.rs rename to clap_builder/src/output/textwrap/word_separators.rs diff --git a/src/output/textwrap/wrap_algorithms.rs b/clap_builder/src/output/textwrap/wrap_algorithms.rs similarity index 100% rename from src/output/textwrap/wrap_algorithms.rs rename to clap_builder/src/output/textwrap/wrap_algorithms.rs diff --git a/src/output/usage.rs b/clap_builder/src/output/usage.rs similarity index 100% rename from src/output/usage.rs rename to clap_builder/src/output/usage.rs diff --git a/src/parser/arg_matcher.rs b/clap_builder/src/parser/arg_matcher.rs similarity index 100% rename from src/parser/arg_matcher.rs rename to clap_builder/src/parser/arg_matcher.rs diff --git a/src/parser/error.rs b/clap_builder/src/parser/error.rs similarity index 100% rename from src/parser/error.rs rename to clap_builder/src/parser/error.rs diff --git a/src/parser/features/mod.rs b/clap_builder/src/parser/features/mod.rs similarity index 100% rename from src/parser/features/mod.rs rename to clap_builder/src/parser/features/mod.rs diff --git a/src/parser/features/suggestions.rs b/clap_builder/src/parser/features/suggestions.rs similarity index 100% rename from src/parser/features/suggestions.rs rename to clap_builder/src/parser/features/suggestions.rs diff --git a/src/parser/matches/any_value.rs b/clap_builder/src/parser/matches/any_value.rs similarity index 100% rename from src/parser/matches/any_value.rs rename to clap_builder/src/parser/matches/any_value.rs diff --git a/src/parser/matches/arg_matches.rs b/clap_builder/src/parser/matches/arg_matches.rs similarity index 98% rename from src/parser/matches/arg_matches.rs rename to clap_builder/src/parser/matches/arg_matches.rs index 4ca5c80bad7..c70770b7e3a 100644 --- a/src/parser/matches/arg_matches.rs +++ b/clap_builder/src/parser/matches/arg_matches.rs @@ -26,6 +26,7 @@ use crate::INTERNAL_ERROR_MSG; /// # Examples /// /// ```no_run +/// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// # use clap::parser::ValueSource; /// let matches = Command::new("MyApp") @@ -93,6 +94,7 @@ impl ArgMatches { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, value_parser, ArgAction}; /// let m = Command::new("myapp") /// .arg(Arg::new("port") @@ -122,6 +124,7 @@ impl ArgMatches { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// # use clap::Arg; /// let cmd = Command::new("mycmd") @@ -156,6 +159,7 @@ impl ArgMatches { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::Command; /// # use clap::Arg; /// let cmd = Command::new("mycmd") @@ -200,6 +204,7 @@ impl ArgMatches { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, value_parser, ArgAction}; /// let m = Command::new("myprog") /// .arg(Arg::new("ports") @@ -241,6 +246,7 @@ impl ArgMatches { /// /// # Examples /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command,Arg, ArgAction, value_parser}; /// let m = Command::new("myprog") /// .arg(Arg::new("x") @@ -278,6 +284,7 @@ impl ArgMatches { /// /// ```rust /// # #[cfg(unix)] { + /// # use clap_builder as clap; /// # use clap::{Command, arg, value_parser}; /// # use std::ffi::{OsStr,OsString}; /// # use std::os::unix::ffi::{OsStrExt,OsStringExt}; @@ -327,6 +334,7 @@ impl ArgMatches { /// /// ```rust /// # #[cfg(unix)] { + /// # use clap_builder as clap; /// # use clap::{Command, arg, value_parser, ArgAction, Arg}; /// # use std::ffi::{OsStr,OsString}; /// # use std::os::unix::ffi::{OsStrExt,OsStringExt}; @@ -381,6 +389,7 @@ impl ArgMatches { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, value_parser, ArgAction}; /// let mut m = Command::new("myprog") /// .arg(Arg::new("file") @@ -416,6 +425,7 @@ impl ArgMatches { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, value_parser, ArgAction}; /// let mut m = Command::new("myprog") /// .arg(Arg::new("file") @@ -456,6 +466,7 @@ impl ArgMatches { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, value_parser, ArgAction}; /// let mut m = Command::new("myprog") /// .arg(Arg::new("x") @@ -489,6 +500,7 @@ impl ArgMatches { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("myprog") /// .arg(Arg::new("debug") @@ -510,7 +522,8 @@ impl ArgMatches { /// /// # Examples /// - /// ``` + /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, arg, value_parser}; /// /// let m = Command::new("myprog") @@ -538,6 +551,7 @@ impl ArgMatches { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let mut cmd = Command::new("myapp") /// .arg(Arg::new("output") @@ -576,6 +590,7 @@ impl ArgMatches { /// /// # Examples /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command,Arg, ArgAction}; /// let m = Command::new("myprog") /// .arg(Arg::new("exec") @@ -614,6 +629,7 @@ impl ArgMatches { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// # use clap::parser::ValueSource; /// let m = Command::new("myprog") @@ -664,6 +680,7 @@ impl ArgMatches { /// in an `ArgMatches` struct for querying. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("myapp") /// .arg(Arg::new("flag") @@ -683,6 +700,7 @@ impl ArgMatches { /// Now notice, if we use one of the other styles of options: /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("myapp") /// .arg(Arg::new("flag") @@ -703,6 +721,7 @@ impl ArgMatches { /// flags. Let's also throw in the final option style for good measure. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("myapp") /// .arg(Arg::new("flag") @@ -732,6 +751,7 @@ impl ArgMatches { /// One final combination of flags/options to see how they combine: /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("myapp") /// .arg(Arg::new("flag") @@ -761,6 +781,7 @@ impl ArgMatches { /// The last part to mention is when values are sent in multiple groups with a [delimiter]. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let m = Command::new("myapp") /// .arg(Arg::new("option") @@ -803,6 +824,7 @@ impl ArgMatches { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg}; /// let m = Command::new("myapp") /// .arg(Arg::new("option") @@ -820,6 +842,7 @@ impl ArgMatches { /// Another quick example is when flags and options are used together /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("myapp") /// .arg(Arg::new("option") @@ -843,6 +866,7 @@ impl ArgMatches { /// index. /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("myapp") /// .arg(Arg::new("option") @@ -881,6 +905,7 @@ impl ArgMatches { /// # Examples /// /// ```no_run + /// # use clap_builder as clap; /// # use clap::{Command, Arg, }; /// let app_m = Command::new("git") /// .subcommand(Command::new("clone")) @@ -901,6 +926,7 @@ impl ArgMatches { /// with pattern matching! /// /// ```rust + /// # use clap_builder as clap; /// # use std::ffi::OsString; /// # use std::ffi::OsStr; /// # use clap::Command; @@ -938,6 +964,7 @@ impl ArgMatches { /// # Examples /// /// ```no_run + /// # use clap_builder as clap; /// # use clap::{Command, Arg, }; /// let mut app_m = Command::new("git") /// .subcommand(Command::new("clone")) @@ -960,6 +987,7 @@ impl ArgMatches { /// with pattern matching! /// /// ```rust + /// # use clap_builder as clap; /// # use std::ffi::OsString; /// # use clap::Command; /// // Assume there is an external subcommand named "subcmd" @@ -1000,6 +1028,7 @@ impl ArgMatches { /// # Examples /// /// ```rust + /// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let app_m = Command::new("myprog") /// .arg(Arg::new("debug") @@ -1037,6 +1066,7 @@ impl ArgMatches { /// # Examples /// /// ```no_run + /// # use clap_builder as clap; /// # use clap::{Command, Arg, }; /// let app_m = Command::new("git") /// .subcommand(Command::new("clone")) @@ -1353,7 +1383,8 @@ pub(crate) struct SubCommand { /// /// # Examples /// -/// ``` +/// ```rust +/// # use clap_builder as clap; /// # use clap::{Command, arg, value_parser}; /// /// let m = Command::new("myprog") @@ -1398,6 +1429,7 @@ impl<'a> ExactSizeIterator for IdsRef<'a> {} /// # Examples /// /// ```rust +/// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let mut m = Command::new("myapp") /// .arg(Arg::new("output") @@ -1454,6 +1486,7 @@ impl Default for Values { /// # Examples /// /// ```rust +/// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("myapp") /// .arg(Arg::new("output") @@ -1512,6 +1545,7 @@ impl<'a, T: 'a> Default for ValuesRef<'a, T> { /// /// ```rust /// # #[cfg(unix)] { +/// # use clap_builder as clap; /// # use clap::{Command, arg, value_parser}; /// use std::ffi::OsString; /// use std::os::unix::ffi::{OsStrExt,OsStringExt}; @@ -1820,6 +1854,7 @@ impl<'a> ExactSizeIterator for RawOccurrenceValues<'a> {} /// # Examples /// /// ```rust +/// # use clap_builder as clap; /// # use clap::{Command, Arg, ArgAction}; /// let m = Command::new("myapp") /// .arg(Arg::new("output") diff --git a/src/parser/matches/matched_arg.rs b/clap_builder/src/parser/matches/matched_arg.rs similarity index 100% rename from src/parser/matches/matched_arg.rs rename to clap_builder/src/parser/matches/matched_arg.rs diff --git a/src/parser/matches/mod.rs b/clap_builder/src/parser/matches/mod.rs similarity index 100% rename from src/parser/matches/mod.rs rename to clap_builder/src/parser/matches/mod.rs diff --git a/src/parser/matches/value_source.rs b/clap_builder/src/parser/matches/value_source.rs similarity index 100% rename from src/parser/matches/value_source.rs rename to clap_builder/src/parser/matches/value_source.rs diff --git a/src/parser/mod.rs b/clap_builder/src/parser/mod.rs similarity index 100% rename from src/parser/mod.rs rename to clap_builder/src/parser/mod.rs diff --git a/src/parser/parser.rs b/clap_builder/src/parser/parser.rs similarity index 100% rename from src/parser/parser.rs rename to clap_builder/src/parser/parser.rs diff --git a/src/parser/validator.rs b/clap_builder/src/parser/validator.rs similarity index 100% rename from src/parser/validator.rs rename to clap_builder/src/parser/validator.rs diff --git a/src/util/color.rs b/clap_builder/src/util/color.rs similarity index 96% rename from src/util/color.rs rename to clap_builder/src/util/color.rs index 4c583cb386a..7a0e837e74c 100644 --- a/src/util/color.rs +++ b/clap_builder/src/util/color.rs @@ -16,6 +16,7 @@ pub enum ColorChoice { /// /// ```rust /// # #[cfg(feature = "color")] { + /// # use clap_builder as clap; /// # use clap::{Command, ColorChoice}; /// Command::new("myprog") /// .color(ColorChoice::Auto) @@ -34,6 +35,7 @@ pub enum ColorChoice { /// /// ```rust /// # #[cfg(feature = "color")] { + /// # use clap_builder as clap; /// # use clap::{Command, ColorChoice}; /// Command::new("myprog") /// .color(ColorChoice::Always) @@ -52,6 +54,7 @@ pub enum ColorChoice { /// /// ```rust /// # #[cfg(feature = "color")] { + /// # use clap_builder as clap; /// # use clap::{Command, ColorChoice}; /// Command::new("myprog") /// .color(ColorChoice::Never) diff --git a/src/util/flat_map.rs b/clap_builder/src/util/flat_map.rs similarity index 100% rename from src/util/flat_map.rs rename to clap_builder/src/util/flat_map.rs diff --git a/src/util/flat_set.rs b/clap_builder/src/util/flat_set.rs similarity index 100% rename from src/util/flat_set.rs rename to clap_builder/src/util/flat_set.rs diff --git a/src/util/graph.rs b/clap_builder/src/util/graph.rs similarity index 100% rename from src/util/graph.rs rename to clap_builder/src/util/graph.rs diff --git a/src/util/id.rs b/clap_builder/src/util/id.rs similarity index 100% rename from src/util/id.rs rename to clap_builder/src/util/id.rs diff --git a/src/util/mod.rs b/clap_builder/src/util/mod.rs similarity index 100% rename from src/util/mod.rs rename to clap_builder/src/util/mod.rs diff --git a/src/util/str_to_bool.rs b/clap_builder/src/util/str_to_bool.rs similarity index 100% rename from src/util/str_to_bool.rs rename to clap_builder/src/util/str_to_bool.rs diff --git a/clap_derive/src/item.rs b/clap_derive/src/item.rs index 22df4b6038e..3aab7ccc992 100644 --- a/clap_derive/src/item.rs +++ b/clap_derive/src/item.rs @@ -565,7 +565,7 @@ impl Item { .any(|a| a.magic == Some(MagicAttrName::ValueEnum)) { quote_spanned!(attr.name.clone().span()=> { - static DEFAULT_VALUE: clap::__macro_refs::once_cell::sync::Lazy = clap::__macro_refs::once_cell::sync::Lazy::new(|| { + static DEFAULT_VALUE: clap::__derive_refs::once_cell::sync::Lazy = clap::__derive_refs::once_cell::sync::Lazy::new(|| { let val: #ty = #val; clap::ValueEnum::to_possible_value(&val).unwrap().get_name().to_owned() }); @@ -574,7 +574,7 @@ impl Item { }) } else { quote_spanned!(attr.name.clone().span()=> { - static DEFAULT_VALUE: clap::__macro_refs::once_cell::sync::Lazy = clap::__macro_refs::once_cell::sync::Lazy::new(|| { + static DEFAULT_VALUE: clap::__derive_refs::once_cell::sync::Lazy = clap::__derive_refs::once_cell::sync::Lazy::new(|| { let val: #ty = #val; ::std::string::ToString::to_string(&val) }); @@ -633,11 +633,11 @@ impl Item { }) } - static DEFAULT_STRINGS: clap::__macro_refs::once_cell::sync::Lazy> = clap::__macro_refs::once_cell::sync::Lazy::new(|| { + static DEFAULT_STRINGS: clap::__derive_refs::once_cell::sync::Lazy> = clap::__derive_refs::once_cell::sync::Lazy::new(|| { iter_to_vals(#expr).collect() }); - static DEFAULT_VALUES: clap::__macro_refs::once_cell::sync::Lazy> = clap::__macro_refs::once_cell::sync::Lazy::new(|| { + static DEFAULT_VALUES: clap::__derive_refs::once_cell::sync::Lazy> = clap::__derive_refs::once_cell::sync::Lazy::new(|| { DEFAULT_STRINGS.iter().map(::std::string::String::as_str).collect() }); DEFAULT_VALUES.iter().copied() @@ -653,11 +653,11 @@ impl Item { iterable.into_iter().map(|val| val.borrow().to_string()) } - static DEFAULT_STRINGS: clap::__macro_refs::once_cell::sync::Lazy> = clap::__macro_refs::once_cell::sync::Lazy::new(|| { + static DEFAULT_STRINGS: clap::__derive_refs::once_cell::sync::Lazy> = clap::__derive_refs::once_cell::sync::Lazy::new(|| { iter_to_vals(#expr).collect() }); - static DEFAULT_VALUES: clap::__macro_refs::once_cell::sync::Lazy> = clap::__macro_refs::once_cell::sync::Lazy::new(|| { + static DEFAULT_VALUES: clap::__derive_refs::once_cell::sync::Lazy> = clap::__derive_refs::once_cell::sync::Lazy::new(|| { DEFAULT_STRINGS.iter().map(::std::string::String::as_str).collect() }); DEFAULT_VALUES.iter().copied() @@ -697,7 +697,7 @@ impl Item { .any(|a| a.magic == Some(MagicAttrName::ValueEnum)) { quote_spanned!(attr.name.clone().span()=> { - static DEFAULT_VALUE: clap::__macro_refs::once_cell::sync::Lazy<::std::ffi::OsString> = clap::__macro_refs::once_cell::sync::Lazy::new(|| { + static DEFAULT_VALUE: clap::__derive_refs::once_cell::sync::Lazy<::std::ffi::OsString> = clap::__derive_refs::once_cell::sync::Lazy::new(|| { let val: #ty = #val; clap::ValueEnum::to_possible_value(&val).unwrap().get_name().to_owned() }); @@ -706,7 +706,7 @@ impl Item { }) } else { quote_spanned!(attr.name.clone().span()=> { - static DEFAULT_VALUE: clap::__macro_refs::once_cell::sync::Lazy<::std::ffi::OsString> = clap::__macro_refs::once_cell::sync::Lazy::new(|| { + static DEFAULT_VALUE: clap::__derive_refs::once_cell::sync::Lazy<::std::ffi::OsString> = clap::__derive_refs::once_cell::sync::Lazy::new(|| { let val: #ty = #val; ::std::ffi::OsString::from(val) }); @@ -765,11 +765,11 @@ impl Item { }) } - static DEFAULT_OS_STRINGS: clap::__macro_refs::once_cell::sync::Lazy> = clap::__macro_refs::once_cell::sync::Lazy::new(|| { + static DEFAULT_OS_STRINGS: clap::__derive_refs::once_cell::sync::Lazy> = clap::__derive_refs::once_cell::sync::Lazy::new(|| { iter_to_vals(#expr).collect() }); - static DEFAULT_VALUES: clap::__macro_refs::once_cell::sync::Lazy> = clap::__macro_refs::once_cell::sync::Lazy::new(|| { + static DEFAULT_VALUES: clap::__derive_refs::once_cell::sync::Lazy> = clap::__derive_refs::once_cell::sync::Lazy::new(|| { DEFAULT_OS_STRINGS.iter().map(::std::ffi::OsString::as_os_str).collect() }); DEFAULT_VALUES.iter().copied() @@ -785,11 +785,11 @@ impl Item { iterable.into_iter().map(|val| val.borrow().into()) } - static DEFAULT_OS_STRINGS: clap::__macro_refs::once_cell::sync::Lazy> = clap::__macro_refs::once_cell::sync::Lazy::new(|| { + static DEFAULT_OS_STRINGS: clap::__derive_refs::once_cell::sync::Lazy> = clap::__derive_refs::once_cell::sync::Lazy::new(|| { iter_to_vals(#expr).collect() }); - static DEFAULT_VALUES: clap::__macro_refs::once_cell::sync::Lazy> = clap::__macro_refs::once_cell::sync::Lazy::new(|| { + static DEFAULT_VALUES: clap::__derive_refs::once_cell::sync::Lazy> = clap::__derive_refs::once_cell::sync::Lazy::new(|| { DEFAULT_OS_STRINGS.iter().map(::std::ffi::OsString::as_os_str).collect() }); DEFAULT_VALUES.iter().copied() diff --git a/src/lib.rs b/src/lib.rs index c70c1c2672c..8e6d1fd6e69 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -95,26 +95,7 @@ // Breaks up parallelism that clarifies intent #![allow(clippy::collapsible_else_if)] -#[cfg(not(feature = "std"))] -compile_error!("`std` feature is currently required to build `clap`"); - -pub use crate::builder::ArgAction; -pub use crate::builder::Command; -pub use crate::builder::ValueHint; -pub use crate::builder::{Arg, ArgGroup}; -pub use crate::parser::ArgMatches; -pub use crate::util::color::ColorChoice; -pub use crate::util::Id; - -/// Command Line Argument Parser Error -/// -/// See [`Command::error`] to create an error. -/// -/// [`Command::error`]: crate::Command::error -pub type Error = crate::error::Error; - -pub use crate::derive::{Args, CommandFactory, FromArgMatches, Parser, Subcommand, ValueEnum}; - +pub use clap_builder::*; #[cfg(feature = "derive")] #[doc(hidden)] pub use clap_derive::{self, *}; @@ -131,25 +112,8 @@ pub mod _features; pub mod _tutorial; #[doc(hidden)] -pub mod __macro_refs { - #[cfg(any(feature = "derive", feature = "cargo"))] +#[cfg(feature = "derive")] +pub mod __derive_refs { #[doc(hidden)] pub use once_cell; } - -#[macro_use] -#[allow(missing_docs)] -mod macros; - -mod derive; - -pub mod builder; -pub mod error; -pub mod parser; - -mod mkeymap; -mod output; -mod util; - -const INTERNAL_ERROR_MSG: &str = "Fatal internal error. Please consider filing a bug \ - report at https://github.com/clap-rs/clap/issues"; diff --git a/tests/derive/groups.rs b/tests/derive/groups.rs index 1c9bcb50762..a4750e2e9c4 100644 --- a/tests/derive/groups.rs +++ b/tests/derive/groups.rs @@ -96,7 +96,7 @@ fn skip_group_avoids_duplicate_ids() { #[should_panic = "\ Command clap: Argument group name must be unique -\t'Compose' is already in use (note: `Args` implicitly creates `ArgGroup`s; disable with `#[group(skip)]`"] +\t'Compose' is already in use"] fn helpful_panic_on_duplicate_groups() { #[derive(Parser, Debug)] struct Opt {