diff options
Diffstat (limited to 'vendor/xflags')
| -rw-r--r-- | vendor/xflags/.cargo-checksum.json | 2 | ||||
| -rw-r--r-- | vendor/xflags/Cargo.lock | 6 | ||||
| -rw-r--r-- | vendor/xflags/Cargo.toml | 9 | ||||
| -rw-r--r-- | vendor/xflags/LICENSE-APACHE | 201 | ||||
| -rw-r--r-- | vendor/xflags/LICENSE-MIT | 23 | ||||
| -rw-r--r-- | vendor/xflags/README.md | 49 | ||||
| -rw-r--r-- | vendor/xflags/examples/hello-generated.rs | 13 | ||||
| -rw-r--r-- | vendor/xflags/examples/hello.rs | 3 | ||||
| -rw-r--r-- | vendor/xflags/examples/immediate-mode.rs | 16 | ||||
| -rw-r--r-- | vendor/xflags/examples/longer.rs | 7 | ||||
| -rw-r--r-- | vendor/xflags/examples/non-utf8.rs | 3 | ||||
| -rw-r--r-- | vendor/xflags/src/lib.rs | 172 | ||||
| -rw-r--r-- | vendor/xflags/src/rt.rs | 14 |
13 files changed, 172 insertions, 346 deletions
diff --git a/vendor/xflags/.cargo-checksum.json b/vendor/xflags/.cargo-checksum.json index c5fd48200..1fa4dd9e5 100644 --- a/vendor/xflags/.cargo-checksum.json +++ b/vendor/xflags/.cargo-checksum.json @@ -1 +1 @@ -{"files":{"Cargo.lock":"76747bdf0a7c1643e62a7c8db6e65572906908415ba87daaa7444917cdf1d35b","Cargo.toml":"32dc60919f757b61d4a6602da24bdd59b77b76f284a1b55712a78e1159e2d249","LICENSE-APACHE":"a60eea817514531668d7e00765731449fe14d059d3249e0bc93b36de45f759f2","LICENSE-MIT":"23f18e03dc49df91622fe2a76176497404e46ced8a715d9d2b67a7446571cca3","README.md":"d34d354ca65973ca9120ed16af11e188c91af2ede6894e0e842c10c874780f7b","examples/hello-generated.rs":"ac2d4864e238e664fb1b18db66aed75ac5a425877bc00729fed1135fb410b969","examples/hello.rs":"c1a5656bee529c3ef96a3afc3531e02bc9d5d309e1bcd60b76e6758fb4c2a95d","examples/longer.rs":"18ad0d00215fdf245830a581df32fbf9533f5ab47e736659e598b4ecd2d96e1a","examples/non-utf8.rs":"a9d4a03adb05c8b46c3251647b8dbf4e860277db995e14192cd8d445f3434186","src/lib.rs":"21843e64aba8010dcc877418927e5b0ad3615ff6e18020285849bbf4391f4ed0","src/rt.rs":"c3cb2d6c80ec9c0586a6e64441cee4c237d2fb420891dec2acb96d5b0c7d6937"},"package":"3f14fe1ed41a5a2b5ef3f565586c4a8a559ee55d3953faab360a771135bdee00"}
\ No newline at end of file +{"files":{"Cargo.lock":"bff2ffbef3ca253bcde1624bfc2c2afd244ca39b44e7dd3f4b463873904129c7","Cargo.toml":"faa866c2c32635dfa6d600103595777c330520df5e73aa0461d6f34eb21bbd9a","examples/hello-generated.rs":"3bf7922435ae84e2b8ae022aba1d693fc4e523b354d3141cc62a183864531f31","examples/hello.rs":"235426d1a69eeba790d1e4fc2ac4fa8f30ca16952edb2a026cf6f4b8c78d6fec","examples/immediate-mode.rs":"dcae135769b6104801de7b91fd220fb28ddae097ba7b0474fe32c28a90c4dfef","examples/longer.rs":"b55684fdde16a8462e1c1afaa9f30e75e3472abfcabe950403733c767dd7de96","examples/non-utf8.rs":"23b563180d1d616f81e224890192799a06fdbc21f3ccb7e4234ca51b3c467a9a","src/lib.rs":"780d7be977abefaa4c7229733a916d88480c9228ddb0f9bc2a25aaa626f7f7d7","src/rt.rs":"b80e6b1e180b0bd0fd523a6bc74d6bba40da7af461de37c33c3735bfb3c66254"},"package":"cbf19f5031a1a812e96fede16f8161218883079946cea87619d3613db1efd268"}
\ No newline at end of file diff --git a/vendor/xflags/Cargo.lock b/vendor/xflags/Cargo.lock index 37ff98bb9..e2020eb16 100644 --- a/vendor/xflags/Cargo.lock +++ b/vendor/xflags/Cargo.lock @@ -4,13 +4,13 @@ version = 3 [[package]] name = "xflags" -version = "0.2.4" +version = "0.3.0" dependencies = [ "xflags-macros", ] [[package]] name = "xflags-macros" -version = "0.2.4" +version = "0.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "45d11d5fc2a97287eded8b170ca80533b3c42646dd7fa386a5eb045817921022" +checksum = "2afbd7f2039bb6cad2dd45f0c5dff49c0d4e26118398768b7a605524d4251809" diff --git a/vendor/xflags/Cargo.toml b/vendor/xflags/Cargo.toml index 542701052..091002385 100644 --- a/vendor/xflags/Cargo.toml +++ b/vendor/xflags/Cargo.toml @@ -10,14 +10,15 @@ # See Cargo.toml.orig for the original contents. [package] -edition = "2018" +edition = "2021" name = "xflags" -version = "0.2.4" +version = "0.3.0" authors = ["Aleksey Kladov <aleksey.kladov@gmail.com>"] -exclude = [".github/", "bors.toml", "rustfmt.toml"] description = "Moderately simple command line arguments parser." categories = ["command-line-interface"] license = "MIT OR Apache-2.0" repository = "https://github.com/matklad/xflags" +resolver = "1" + [dependencies.xflags-macros] -version = "=0.2.4" +version = "=0.3.0" diff --git a/vendor/xflags/LICENSE-APACHE b/vendor/xflags/LICENSE-APACHE deleted file mode 100644 index 16fe87b06..000000000 --- a/vendor/xflags/LICENSE-APACHE +++ /dev/null @@ -1,201 +0,0 @@ - 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/vendor/xflags/LICENSE-MIT b/vendor/xflags/LICENSE-MIT deleted file mode 100644 index 31aa79387..000000000 --- a/vendor/xflags/LICENSE-MIT +++ /dev/null @@ -1,23 +0,0 @@ -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/vendor/xflags/README.md b/vendor/xflags/README.md deleted file mode 100644 index bfebfb0c8..000000000 --- a/vendor/xflags/README.md +++ /dev/null @@ -1,49 +0,0 @@ -[](https://docs.rs/xflags/) - -# xflags - -Moderately simple command line arguments parsing: - -```rust -mod flags { - use std::path::PathBuf; - - xflags::xflags! { - src "./examples/basic.rs" - - cmd my-command - required path: PathBuf - { - optional -v, --verbose - } - } - - // generated start - // The following code is generated by `xflags` macro. - // Run `env UPDATE_XFLAGS=1 cargo build` to regenerate. - #[derive(Debug)] - pub struct MyCommand { - pub path: PathBuf, - - pub verbose: bool, - } - - impl MyCommand { - pub const HELP: &'static str = Self::HELP_; - - pub fn from_env() -> xflags::Result<Self> { - Self::from_env_() - } - - pub fn from_vec(args: Vec<std::ffi::OsString>) -> xflags::Result<Self> { - Self::from_vec_(args) - } - } - // generated end -} - -fn main() { - let flags = flags::MyCommand::from_env(); - println!("{:#?}", flags); -} -``` diff --git a/vendor/xflags/examples/hello-generated.rs b/vendor/xflags/examples/hello-generated.rs index b82884859..cb74acbd7 100644 --- a/vendor/xflags/examples/hello-generated.rs +++ b/vendor/xflags/examples/hello-generated.rs @@ -5,10 +5,10 @@ mod flags { src "./examples/hello-generated.rs" /// Prints a greeting. - cmd hello + cmd hello { /// Whom to greet. required name: String - { + /// Use non-ascii symbols in the output. optional -e, --emoji } @@ -25,12 +25,12 @@ mod flags { } impl Hello { - pub const HELP: &'static str = Self::HELP_; - + #[allow(dead_code)] pub fn from_env() -> xflags::Result<Self> { Self::from_env_() } + #[allow(dead_code)] pub fn from_vec(args: Vec<std::ffi::OsString>) -> xflags::Result<Self> { Self::from_vec_(args) } @@ -44,9 +44,6 @@ fn main() { let bang = if flags.emoji { "❣️" } else { "!" }; println!("Hello {}{}", flags.name, bang); } - Err(err) => { - eprintln!("{}\n\n{}", err, flags::Hello::HELP); - std::process::exit(1) - } + Err(err) => err.exit(), } } diff --git a/vendor/xflags/examples/hello.rs b/vendor/xflags/examples/hello.rs index 98a19099f..91dc3fd8a 100644 --- a/vendor/xflags/examples/hello.rs +++ b/vendor/xflags/examples/hello.rs @@ -1,8 +1,7 @@ mod flags { xflags::xflags! { - cmd hello + cmd hello { required name: String - { optional -e, --emoji } } diff --git a/vendor/xflags/examples/immediate-mode.rs b/vendor/xflags/examples/immediate-mode.rs new file mode 100644 index 000000000..ee3baa3de --- /dev/null +++ b/vendor/xflags/examples/immediate-mode.rs @@ -0,0 +1,16 @@ +use std::path::PathBuf; + +fn main() { + let flags = xflags::parse_or_exit! { + /// Remove directories and their contents recursively. + optional -r,--recursive + /// File or directory to remove + required path: PathBuf + }; + + println!( + "removing {}{}", + flags.path.display(), + if flags.recursive { "recursively" } else { "" }, + ) +} diff --git a/vendor/xflags/examples/longer.rs b/vendor/xflags/examples/longer.rs index 7ea9e18d5..199cca042 100644 --- a/vendor/xflags/examples/longer.rs +++ b/vendor/xflags/examples/longer.rs @@ -24,10 +24,9 @@ mod flags { } /// Benchmark specific analysis operation - cmd analysis-bench + cmd analysis-bench { /// Directory with Cargo.toml optional path: PathBuf - { /// Compute syntax highlighting for this file required --highlight path: PathBuf /// Compute highlighting for this line @@ -72,12 +71,12 @@ mod flags { } impl RustAnalyzer { - pub const HELP: &'static str = Self::HELP_; - + #[allow(dead_code)] pub fn from_env() -> xflags::Result<Self> { Self::from_env_() } + #[allow(dead_code)] pub fn from_vec(args: Vec<std::ffi::OsString>) -> xflags::Result<Self> { Self::from_vec_(args) } diff --git a/vendor/xflags/examples/non-utf8.rs b/vendor/xflags/examples/non-utf8.rs index d355b24f6..28b1e98be 100644 --- a/vendor/xflags/examples/non-utf8.rs +++ b/vendor/xflags/examples/non-utf8.rs @@ -4,11 +4,10 @@ mod flags { use std::{ffi::OsString, path::PathBuf}; xflags::xflags! { - cmd Cmd + cmd Cmd { required a: OsString required b: PathBuf required c: String - { } } } diff --git a/vendor/xflags/src/lib.rs b/vendor/xflags/src/lib.rs index ae347f511..0eda9dec4 100644 --- a/vendor/xflags/src/lib.rs +++ b/vendor/xflags/src/lib.rs @@ -1,12 +1,65 @@ -//! This crates provides a procedural macro for parsing command line arguments. +//! `xflags` provides a procedural macro for parsing command line arguments. //! //! It is intended for use in development tools, so it emphasizes fast compile //! times and convenience at the expense of features. //! -//! If you need something more fancy, consider using -//! [`clap`](https://docs.rs/clap/2.33.3/clap/) instead. +//! Rough decision tree for picking an argument parsing library: //! -//! ## Example +//! * if you need all of the features and don't care about minimalism, use +//! [clap](https://github.com/clap-rs/clap) +//! * if you want to be maximally minimal, need only basic features (eg, no help +//! generation), and want to be pedantically correct, use +//! [lexopt](https://github.com/blyxxyz/lexopt) +//! * if you want to get things done fast (eg, you want auto help, but not at +//! the cost of waiting for syn to compile), consider this crate. +//! +//! The secret sauce of xflags is that it is the opposite of a derive macro. +//! Rather than generating a command line grammar from a Rust struct, `xflags` +//! generates Rust structs based on input grammar. The grammar definition is +//! both shorter and simpler to write, and is lighter on compile times. +//! +//! Here's a complete example of `parse_or_exit!` macro which parses arguments +//! into an "anonymous" struct: +//! +//! ```no_run +//! use std::path::PathBuf; +//! +//! fn main() { +//! let flags = xflags::parse_or_exit! { +//! /// Remove directories and their contents recursively. +//! optional -r,--recursive +//! /// File or directory to remove +//! required path: PathBuf +//! }; +//! +//! println!( +//! "removing {}{}", +//! flags.path.display(), +//! if flags.recursive { "recursively" } else { "" }, +//! ) +//! } +//! ``` +//! +//! The above program, when run with `--help` argument, generates the following +//! help: +//! +//! ```text +//! ARGS: +//! <path> +//! File or directory to remove +//! +//! OPTIONS: +//! -r, --recursive +//! Remove directories and their contents recursively. +//! +//! -h, --help +//! Prints help information. +//! ``` +//! +//! For larger programs, you'd typically want to use `xflags!` macro, which +//! generates _named_ structs for you. Unlike a typical macro, `xflags` writes +//! generated code into the source file, to make it easy to understand the rust +//! types at a glance. //! //! ``` //! mod flags { @@ -15,9 +68,8 @@ //! xflags::xflags! { //! src "./examples/basic.rs" //! -//! cmd my-command +//! cmd my-command { //! required path: PathBuf -//! { //! optional -v, --verbose //! } //! } @@ -28,17 +80,16 @@ //! #[derive(Debug)] //! pub struct MyCommand { //! pub path: PathBuf, -//! //! pub verbose: bool, //! } //! //! impl MyCommand { -//! pub const HELP: &'static str = Self::HELP_; -//! +//! pub fn from_env_or_exit() -> Self { +//! Self::from_env_or_exit_() +//! } //! pub fn from_env() -> xflags::Result<Self> { //! Self::from_env_() //! } -//! //! pub fn from_vec(args: Vec<std::ffi::OsString>) -> xflags::Result<Self> { //! Self::from_vec_(args) //! } @@ -52,15 +103,15 @@ //! } //! ``` //! -//! To make the macro less opaque, `xflag` can generate `struct` describing the -//! CLI in-place. To disable this behavior, omit the `src` attribute. +//! If you'd rather use a typical proc-macro which generates hidden code, just +//! omit the src attribute. //! //! xflags correctly handles non-utf8 arguments. //! //! ## Syntax Reference //! -//! The **cmd** keyword introduces a command that accepts positional arguments -//! and switches. +//! The `xflags!` macro uses **cmd** keyword to introduce a command or +//! subcommand that accepts positional arguments and switches. //! //! ``` //! xflags::xflags! { @@ -75,9 +126,9 @@ //! ``` //! xflags::xflags! { //! cmd switches { -//! optional -h, --help -//! repeated --verbose +//! optional -q,--quiet //! required --pass-me +//! repeated --verbose //! } //! } //! ``` @@ -98,20 +149,21 @@ //! } //! ``` //! -//! Positional arguments are specified before the opening curly brace: +//! Arguments without `--` in then are are positional. //! //! ``` //! use std::{path::PathBuf, ffi::OsString}; //! //! xflags::xflags! { -//! cmd positional-arguments +//! cmd positional-arguments { //! required program: PathBuf //! repeated args: OsString -//! { } +//! } //! } //! ``` //! -//! Nesting **cmd** is allowed: +//! Nesting **cmd** is allowed. `xflag` automatically generates boilerplate +//! enums for subcommands: //! //! ```ignore //! xflags::xflags! { @@ -148,12 +200,12 @@ //! } //! //! impl App { -//! pub const HELP: &'static str = Self::HELP_; -//! +//! pub fn from_env_or_exit() -> Self { +//! Self::from_env_or_exit_() +//! } //! pub fn from_env() -> xflags::Result<Self> { //! Self::from_env_() //! } -//! //! pub fn from_vec(args: Vec<std::ffi::OsString>) -> xflags::Result<Self> { //! Self::from_vec_(args) //! } @@ -161,6 +213,9 @@ //! // generated end //! ``` //! +//! Switches are always "inherited". Both `app -v foo` and `app foo -v` produce +//! the same result. +//! //! To make subcommand name optional use the **default** keyword to mark a //! subcommand to select if no subcommand name is passed. The name of the //! default subcommand affects only the name of the generated Rust struct, it @@ -176,8 +231,8 @@ //! } //! ``` //! -//! Commands, arguments, and switches can documented. Doc comments become a part -//! of generated help: +//! Commands, arguments, and switches can be documented. Doc comments become a +//! part of generated help: //! //! ``` //! mod flags { @@ -185,14 +240,11 @@ //! //! xflags::xflags! { //! /// Run basic system diagnostics. -//! cmd healthck +//! cmd healthck { //! /// Optional configuration file. //! optional config: PathBuf -//! { //! /// Verbosity level, can be repeated multiple times. //! repeated -v, --verbose -//! /// Print the help message. -//! optional -h, --help //! } //! } //! } @@ -200,24 +252,18 @@ //! fn main() { //! match flags::Healthck::from_env() { //! Ok(flags) => { -//! if flags.help { -//! println!("{}", flags::Healthck::HELP); -//! return; -//! } //! run_checks(flags.config, flags.verbose); //! } -//! Err(err) => { -//! eprintln!("{}", err); -//! } +//! Err(err) => err.exit() //! } //! } //! //! # fn run_checks(_config: Option<std::path::PathBuf>, _verbosity: u32) {} //! ``` //! -//! The **src** keyword controlls how the code generation works. If it is -//! absent, `xflags` acts as a typical procedure macro, which generates a bunch -//! of structs and impls. +//! The **src** keyword controls how the code generation works. If it is absent, +//! `xflags` acts as a typical procedure macro, which generates a bunch of +//! structs and impls. //! //! If the **src** keyword is present, it should specify the path to the file //! with `xflags!` invocation. The path should be relative to the directory with @@ -226,7 +272,7 @@ //! directly to the specified file. //! //! By convention, `xflag!` macro should be invoked from the `flags` submodule. -//! The `flags::` preffix should be used to refer to command names. Additional +//! The `flags::` prefix should be used to refer to command names. Additional //! validation logic can go to the `flags` module: //! //! ``` @@ -250,21 +296,43 @@ //! } //! } //! ``` +//! +//! The `parse_or_exit!` macro is a syntactic sure for `xflags!`, which +//! immediately parses the argument, exiting the process if needed. +//! `parse_or_exit` only supports single top-level command and doesn't need the +//! `cmd` keyword. +//! +//! ## Limitations +//! +//! `xflags` follows +//! [Fuchsia](https://fuchsia.dev/fuchsia-src/development/api/cli#command_line_arguments) +//! conventions for command line arguments. GNU conventions such as grouping +//! short-flags (`-xyz`) or gluing short flag and a value `(-fVAL)` are not +//! supported. +//! +//! `xflags` requires the command line interface to be fully static. It's +//! impossible to include additional flags at runtime. +//! +//! Implementation is not fully robust, there might be some residual bugs in +//! edge cases. use std::fmt; /// Generates a parser for command line arguments from a DSL. /// /// See the module-level for detailed syntax specification. -pub use xflags_macros::xflags; +pub use xflags_macros::{parse_or_exit, xflags}; pub type Result<T, E = Error> = std::result::Result<T, E>; -/// This type represents an error that can occur during command line argument -/// parsing. +/// An error occurred when parssing command line arguments. +/// +/// Either the command line was syntactically invalid, or `--help` was +/// explicitly requested. #[derive(Debug)] pub struct Error { msg: String, + help: bool, } impl fmt::Display for Error { @@ -280,7 +348,23 @@ impl Error { /// /// Use this to report custom validation errors. pub fn new(message: impl Into<String>) -> Error { - Error { msg: message.into() } + Error { msg: message.into(), help: false } + } + + /// Error that carries `--help` message. + pub fn is_help(&self) -> bool { + self.help + } + + /// Prints the error and exists the process. + pub fn exit(self) -> ! { + if self.is_help() { + println!("{self}"); + std::process::exit(0) + } else { + eprintln!("{self}"); + std::process::exit(2) + } } } diff --git a/vendor/xflags/src/rt.rs b/vendor/xflags/src/rt.rs index 3c33196af..988e6cc23 100644 --- a/vendor/xflags/src/rt.rs +++ b/vendor/xflags/src/rt.rs @@ -4,7 +4,7 @@ use crate::{Error, Result}; macro_rules! format_err { ($($tt:tt)*) => { - Error { msg: format!($($tt)*) } + Error { msg: format!($($tt)*), help: false } }; } @@ -94,6 +94,14 @@ impl Parser { format_err!("unexpected argument: {:?}", arg) } + pub fn subcommand_required(&self) -> Error { + format_err!("subcommand is required") + } + + pub fn help(&self, help: &'static str) -> Error { + Error { msg: help.to_string(), help: true } + } + pub fn optional<T>(&self, flag: &str, mut vals: Vec<T>) -> Result<Option<T>> { if vals.len() > 1 { bail!("flag specified more than once: `{}`", flag) @@ -107,8 +115,4 @@ impl Parser { } vals.pop().ok_or_else(|| format_err!("flag is required: `{}`", flag)) } - - pub fn subcommand<T>(&self, cmd: Option<T>) -> Result<T> { - cmd.ok_or_else(|| format_err!("subcommand is required")) - } } |