From 88a335ff971ff0ca55e224e1599890c5691d8fb8 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 31 Dec 2021 11:59:15 -0600 Subject: [PATCH] fix(complete): Give crates more specific names `clap_generate` originally intended to be "generate anything". With `fig`, we already broke one part out. With #3174's man support, we are also looking at keeping it separate: - More freedom to iterate on the API - Uniqueness (and potential weight) of its dependencies - man generation is normally more for distribution while completions are a mix of being distributed with the app or the app generating the completions (which will be exacerbated if we move most completion parsing logic to be in Rust) So `clap_generate` is having a lot more limited of a role than the original name conveys. I worry the generic name will be a hindrance to people discovering and using it (yes, documentation can help but there are limits). I hesitated because we are on the verge of releasing 3.0. However, doing it even later will be even more disruptive because more people will be using it (crates.io lists ~70 people using `clap_generate`). To ease things, we are still releasing `clap_generate` as a wrapper around `clap_complete`. --- CHANGELOG.md | 2 +- Cargo.toml | 2 + README.md | 4 +- clap_complete/CONTRIBUTING.md | 11 + clap_complete/Cargo.toml | 44 +++ clap_complete/LICENSE-APACHE | 201 ++++++++++++++ clap_complete/LICENSE-MIT | 21 ++ clap_complete/README.md | 23 ++ .../examples/bash_completion.rs | 2 +- .../examples/value_hints.rs | 2 +- .../examples/value_hints_derive.rs | 2 +- .../src/generators/mod.rs | 4 +- .../src/generators/shells/bash.rs | 0 .../src/generators/shells/elvish.rs | 0 .../src/generators/shells/fish.rs | 0 .../src/generators/shells/mod.rs | 0 .../src/generators/shells/powershell.rs | 0 .../src/generators/shells/zsh.rs | 0 clap_complete/src/lib.rs | 255 ++++++++++++++++++ .../src/macros.rs | 0 {clap_generate => clap_complete}/src/shell.rs | 0 {clap_generate => clap_complete}/src/utils.rs | 0 .../tests/completions/bash.rs | 0 .../tests/completions/elvish.rs | 0 .../tests/completions/fish.rs | 0 .../tests/completions/mod.rs | 2 +- .../tests/completions/powershell.rs | 0 .../tests/completions/zsh.rs | 0 clap_complete/tests/generate_completions.rs | 21 ++ .../tests/value_hints.rs | 2 +- clap_complete_fig/Cargo.toml | 36 +++ clap_complete_fig/LICENSE-APACHE | 201 ++++++++++++++ clap_complete_fig/LICENSE-MIT | 21 ++ clap_complete_fig/README.md | 9 + .../examples/fig_completion.rs | 4 +- .../src/fig.rs | 2 +- clap_complete_fig/src/lib.rs | 14 + .../tests/completions/fig.rs | 0 .../tests/completions/mod.rs | 2 +- .../tests/generate_completions.rs | 4 +- .../tests/value_hints.rs | 2 +- clap_generate/Cargo.toml | 20 +- clap_generate/src/lib.rs | 248 ++--------------- .../{generate_completions.rs => warning.rs} | 2 + clap_generate_fig/Cargo.toml | 11 +- clap_generate_fig/src/lib.rs | 16 +- src/build/app/mod.rs | 6 +- src/build/arg/value_hint.rs | 2 +- 48 files changed, 907 insertions(+), 291 deletions(-) create mode 100644 clap_complete/CONTRIBUTING.md create mode 100644 clap_complete/Cargo.toml create mode 100644 clap_complete/LICENSE-APACHE create mode 100644 clap_complete/LICENSE-MIT create mode 100644 clap_complete/README.md rename {clap_generate => clap_complete}/examples/bash_completion.rs (83%) rename {clap_generate => clap_complete}/examples/value_hints.rs (98%) rename {clap_generate => clap_complete}/examples/value_hints_derive.rs (98%) rename {clap_generate => clap_complete}/src/generators/mod.rs (94%) rename {clap_generate => clap_complete}/src/generators/shells/bash.rs (100%) rename {clap_generate => clap_complete}/src/generators/shells/elvish.rs (100%) rename {clap_generate => clap_complete}/src/generators/shells/fish.rs (100%) rename {clap_generate => clap_complete}/src/generators/shells/mod.rs (100%) rename {clap_generate => clap_complete}/src/generators/shells/powershell.rs (100%) rename {clap_generate => clap_complete}/src/generators/shells/zsh.rs (100%) create mode 100644 clap_complete/src/lib.rs rename {clap_generate => clap_complete}/src/macros.rs (100%) rename {clap_generate => clap_complete}/src/shell.rs (100%) rename {clap_generate => clap_complete}/src/utils.rs (100%) rename {clap_generate => clap_complete}/tests/completions/bash.rs (100%) rename {clap_generate => clap_complete}/tests/completions/elvish.rs (100%) rename {clap_generate => clap_complete}/tests/completions/fish.rs (100%) rename {clap_generate => clap_complete}/tests/completions/mod.rs (93%) rename {clap_generate => clap_complete}/tests/completions/powershell.rs (100%) rename {clap_generate => clap_complete}/tests/completions/zsh.rs (100%) create mode 100644 clap_complete/tests/generate_completions.rs rename {clap_generate => clap_complete}/tests/value_hints.rs (99%) create mode 100644 clap_complete_fig/Cargo.toml create mode 100644 clap_complete_fig/LICENSE-APACHE create mode 100644 clap_complete_fig/LICENSE-MIT create mode 100644 clap_complete_fig/README.md rename {clap_generate_fig => clap_complete_fig}/examples/fig_completion.rs (81%) rename {clap_generate_fig => clap_complete_fig}/src/fig.rs (99%) create mode 100644 clap_complete_fig/src/lib.rs rename {clap_generate_fig => clap_complete_fig}/tests/completions/fig.rs (100%) rename {clap_generate_fig => clap_complete_fig}/tests/completions/mod.rs (93%) rename {clap_generate_fig => clap_complete_fig}/tests/generate_completions.rs (88%) rename {clap_generate_fig => clap_complete_fig}/tests/value_hints.rs (99%) rename clap_generate/tests/{generate_completions.rs => warning.rs} (96%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 00709c44..4f3cabf6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -153,7 +153,7 @@ Easier to catch changes: - `Arg::short` and `Arg::value_delimiter` now take a `char` instead of a `&str` - `ArgMatches` panics on unknown arguments - Removed `VersionlessSubcommands`, making it the default (see [clap-rs/clap#2812](https://github.com/clap-rs/clap/issues/2812)) -- Completion generation has been split out into [clap_generate](./clap_generate). +- Completion generation has been split out into [clap_complete](./clap_complete). - Removed `ArgSettings::EmptyValues` in favor of `ArgSettings::ForbidEmptyValues` - Validator signatures have been loosed: - `Arg::validator` now takes first argument as `Fn(&str) -> Result` instead of diff --git a/Cargo.toml b/Cargo.toml index dd4f3ba9..58dac60d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,8 @@ [workspace] members = [ "clap_derive", + "clap_complete", + "clap_complete_fig", "clap_generate", "clap_generate_fig", ] diff --git a/README.md b/README.md index e81a1391..2aa7e77b 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ OPTIONS: ### Aspirations - Out of the box, users get a polished CLI experience - - Including common argument behavior, help generation, suggested fixes for users, colored output, [shell completions](https://github.com/clap-rs/clap/tree/master/clap_generate), etc + - Including common argument behavior, help generation, suggested fixes for users, colored output, [shell completions](https://github.com/clap-rs/clap/tree/master/clap_complete), etc - Flexible enough to port your existing CLI interface - However, we won't necessarily streamline support for each use case - Reasonable parse performance @@ -102,7 +102,7 @@ CLI parsers optimized for other use cases. - [wild](https://crates.io/crates/wild) for supporting wildcards (`*`) on Windows like you do Linux - [argfile](https://crates.io/crates/argfile) for loading additional arguments from a file (aka response files) -- [clap_generate](https://crates.io/crates/clap_generate) for shell completion support +- [clap_complete](https://crates.io/crates/clap_complete) for shell completion support - [clap-verbosity-flag](https://crates.io/crates/clap-verbosity-flag) - [clap-cargo](https://crates.io/crates/clap-cargo) - [concolor-clap](https://crates.io/crates/concolor-clap) diff --git a/clap_complete/CONTRIBUTING.md b/clap_complete/CONTRIBUTING.md new file mode 100644 index 00000000..763adc69 --- /dev/null +++ b/clap_complete/CONTRIBUTING.md @@ -0,0 +1,11 @@ +# How to Contribute + +See the [clap-wide CONTRIBUTING.md](../CONTRIBUTING.md). This will contain `clap_complete` specific notes. + +### Scope + +`clap_complete` contains the core completion generators, meaning ones +maintained by the clap maintainers that get priority for features and fixes. +Additional, including contributor-maintained generators can also be contributed +to the clap repo and sit alongside `clap_complete` in a `clap_complete_` +crate. diff --git a/clap_complete/Cargo.toml b/clap_complete/Cargo.toml new file mode 100644 index 00000000..3fa80bcb --- /dev/null +++ b/clap_complete/Cargo.toml @@ -0,0 +1,44 @@ +[package] +name = "clap_complete" +version = "3.0.0-rc.11" +edition = "2018" +include = [ + "src/**/*", + "Cargo.toml", + "LICENSE-*", + "README.md" +] +description = "Generate shell completion scripts for your clap::App" +repository = "https://github.com/clap-rs/clap/tree/master/clap_complete" +documentation = "https://docs.rs/clap_complete" +keywords = [ + "clap", + "cli", + "completion", + "bash", +] +categories = ["command-line-interface"] +license = "MIT OR Apache-2.0" +readme = "README.md" + +[package.metadata.release] +pre-release-replacements = [ + {file="README.md", search="github.com/clap-rs/clap/blob/[^/]+/", replace="github.com/clap-rs/clap/blob/{{tag_name}}/", exactly=4, prerelease = true}, +] + +[lib] +bench = false + +[dependencies] +clap = { path = "../", version = "=3.0.0-rc.11", default-features = false, features = ["std"] } + +[dev-dependencies] +pretty_assertions = "1.0" +clap = { path = "../", version = "=3.0.0-rc.11", default-features = false, features = ["std", "derive"] } + +[features] +default = [] +debug = ["clap/debug"] + +[package.metadata.docs.rs] +targets = ["x86_64-unknown-linux-gnu"] diff --git a/clap_complete/LICENSE-APACHE b/clap_complete/LICENSE-APACHE new file mode 100644 index 00000000..261eeb9e --- /dev/null +++ b/clap_complete/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_complete/LICENSE-MIT b/clap_complete/LICENSE-MIT new file mode 100644 index 00000000..5acedf04 --- /dev/null +++ b/clap_complete/LICENSE-MIT @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2015-2016 Kevin B. Knapp + +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_complete/README.md b/clap_complete/README.md new file mode 100644 index 00000000..4879ce80 --- /dev/null +++ b/clap_complete/README.md @@ -0,0 +1,23 @@ + +# clap_complete + +> **Shell completion generation for `clap`** + +[![Crates.io](https://img.shields.io/crates/v/clap_complete?style=flat-square)](https://crates.io/crates/clap_complete) +[![Crates.io](https://img.shields.io/crates/d/clap_complete?style=flat-square)](https://crates.io/crates/clap_complete) +[![License](https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square)](https://github.com/clap-rs/clap/blob/clap_complete-v3.0.0-rc.11/LICENSE-APACHE) +[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/clap-rs/clap/blob/clap_complete-v3.0.0-rc.11/LICENSE-MIT) + +Dual-licensed under [Apache 2.0](LICENSE-APACHE) or [MIT](LICENSE-MIT). + +1. [About](#about) +2. [API Reference](https://docs.rs/clap_complete) +3. [Questions & Discussions](https://github.com/clap-rs/clap/discussions) +4. [CONTRIBUTING](https://github.com/clap-rs/clap/blob/clap_complete-v3.0.0-rc.11/clap_complete/CCONTRIBUTING.md) +5. [Sponsors](https://github.com/clap-rs/clap/blob/clap_complete-v3.0.0-rc.11/README.md#sponsors) + +## About + +### Related Projects + +- [clap_complete_fig](https://crates.io/crates/clap_complete_fig) for [fig](https://fig.io/) shell completion support diff --git a/clap_generate/examples/bash_completion.rs b/clap_complete/examples/bash_completion.rs similarity index 83% rename from clap_generate/examples/bash_completion.rs rename to clap_complete/examples/bash_completion.rs index b36bcbd0..8153fde6 100644 --- a/clap_generate/examples/bash_completion.rs +++ b/clap_complete/examples/bash_completion.rs @@ -1,5 +1,5 @@ use clap::App; -use clap_generate::{generate, generators::Bash}; +use clap_complete::{generate, generators::Bash}; use std::io; fn main() { diff --git a/clap_generate/examples/value_hints.rs b/clap_complete/examples/value_hints.rs similarity index 98% rename from clap_generate/examples/value_hints.rs rename to clap_complete/examples/value_hints.rs index 917a69d9..074f996f 100644 --- a/clap_generate/examples/value_hints.rs +++ b/clap_complete/examples/value_hints.rs @@ -13,7 +13,7 @@ //! ./target/debug/examples/value_hints -- //! ``` use clap::{App, AppSettings, Arg, ValueHint}; -use clap_generate::{generate, Generator, Shell}; +use clap_complete::{generate, Generator, Shell}; use std::io; fn build_cli() -> App<'static> { diff --git a/clap_generate/examples/value_hints_derive.rs b/clap_complete/examples/value_hints_derive.rs similarity index 98% rename from clap_generate/examples/value_hints_derive.rs rename to clap_complete/examples/value_hints_derive.rs index 8390cb28..7644bb48 100644 --- a/clap_generate/examples/value_hints_derive.rs +++ b/clap_complete/examples/value_hints_derive.rs @@ -13,7 +13,7 @@ //! ./target/debug/examples/value_hints_derive -- //! ``` use clap::{App, AppSettings, IntoApp, Parser, ValueHint}; -use clap_generate::{generate, Generator, Shell}; +use clap_complete::{generate, Generator, Shell}; use std::ffi::OsString; use std::io; use std::path::PathBuf; diff --git a/clap_generate/src/generators/mod.rs b/clap_complete/src/generators/mod.rs similarity index 94% rename from clap_generate/src/generators/mod.rs rename to clap_complete/src/generators/mod.rs index 73d58434..12359019 100644 --- a/clap_generate/src/generators/mod.rs +++ b/clap_complete/src/generators/mod.rs @@ -16,7 +16,7 @@ pub trait Generator { /// ``` /// # use std::io::Write; /// # use clap::App; - /// use clap_generate::Generator; + /// use clap_complete::Generator; /// /// pub struct Fish; /// @@ -39,7 +39,7 @@ pub trait Generator { /// ``` /// use std::{io::Write, fmt::write}; /// use clap::App; - /// use clap_generate::Generator; + /// use clap_complete::Generator; /// /// pub struct ClapDebug; /// diff --git a/clap_generate/src/generators/shells/bash.rs b/clap_complete/src/generators/shells/bash.rs similarity index 100% rename from clap_generate/src/generators/shells/bash.rs rename to clap_complete/src/generators/shells/bash.rs diff --git a/clap_generate/src/generators/shells/elvish.rs b/clap_complete/src/generators/shells/elvish.rs similarity index 100% rename from clap_generate/src/generators/shells/elvish.rs rename to clap_complete/src/generators/shells/elvish.rs diff --git a/clap_generate/src/generators/shells/fish.rs b/clap_complete/src/generators/shells/fish.rs similarity index 100% rename from clap_generate/src/generators/shells/fish.rs rename to clap_complete/src/generators/shells/fish.rs diff --git a/clap_generate/src/generators/shells/mod.rs b/clap_complete/src/generators/shells/mod.rs similarity index 100% rename from clap_generate/src/generators/shells/mod.rs rename to clap_complete/src/generators/shells/mod.rs diff --git a/clap_generate/src/generators/shells/powershell.rs b/clap_complete/src/generators/shells/powershell.rs similarity index 100% rename from clap_generate/src/generators/shells/powershell.rs rename to clap_complete/src/generators/shells/powershell.rs diff --git a/clap_generate/src/generators/shells/zsh.rs b/clap_complete/src/generators/shells/zsh.rs similarity index 100% rename from clap_generate/src/generators/shells/zsh.rs rename to clap_complete/src/generators/shells/zsh.rs diff --git a/clap_complete/src/lib.rs b/clap_complete/src/lib.rs new file mode 100644 index 00000000..c27ec31e --- /dev/null +++ b/clap_complete/src/lib.rs @@ -0,0 +1,255 @@ +// Copyright ⓒ 2015-2018 Kevin B. Knapp +// +// `clap_complete` is distributed under the terms of both the MIT license and the Apache License +// (Version 2.0). +// See the [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) files in this repository +// for more information. + +#![doc(html_logo_url = "https://raw.githubusercontent.com/clap-rs/clap/master/assets/clap.png")] +#![doc = include_str!("../README.md")] +#![warn(missing_docs, trivial_casts, unused_allocation, trivial_numeric_casts)] +#![forbid(unsafe_code)] +#![allow(clippy::needless_doctest_main)] + +//! ## Quick Start +//! +//! - For generating at compile-time, see [`generate_to`] +//! - For generating at runtime, see [`generate`] +//! +//! [`Shell`] is a convenience `enum` for an argument value type that implements `Generator` +//! for each natively-supported shell type. +//! +//! ## Example +//! +//! ```rust,no_run +//! use clap::{App, AppSettings, Arg, ValueHint}; +//! use clap_complete::{generate, Generator, Shell}; +//! use std::io; +//! +//! fn build_cli() -> App<'static> { +//! App::new("example") +//! .arg(Arg::new("file") +//! .help("some input file") +//! .value_hint(ValueHint::AnyPath), +//! ) +//! .arg( +//! Arg::new("generator") +//! .long("generate") +//! .possible_values(Shell::possible_values()), +//! ) +//! } +//! +//! fn print_completions(gen: G, app: &mut App) { +//! generate(gen, app, app.get_name().to_string(), &mut io::stdout()); +//! } +//! +//! fn main() { +//! let matches = build_cli().get_matches(); +//! +//! if let Ok(generator) = matches.value_of_t::("generator") { +//! let mut app = build_cli(); +//! eprintln!("Generating completion file for {}...", generator); +//! print_completions(generator, &mut app); +//! } +//! } +//! ``` + +const INTERNAL_ERROR_MSG: &str = "Fatal internal error. Please consider filing a bug \ + report at https://github.com/clap-rs/clap/issues"; + +#[macro_use] +#[allow(missing_docs)] +mod macros; + +/// Contains some popular generators +pub mod generators; +/// Contains supported shells for auto-completion scripts +mod shell; +/// Helpers for writing generators +pub mod utils; + +use std::ffi::OsString; +use std::fs::File; +use std::io::Error; +use std::io::Write; +use std::path::PathBuf; + +#[doc(inline)] +pub use generators::Generator; +#[doc(inline)] +pub use shell::Shell; + +/// Generate a completions file for a specified shell at compile-time. +/// +/// **NOTE:** to generate the file at compile time you must use a `build.rs` "Build Script" or a +/// [`cargo-xtask`](https://github.com/matklad/cargo-xtask) +/// +/// # Examples +/// +/// The following example generates a bash completion script via a `build.rs` script. In this +/// simple example, we'll demo a very small application with only a single subcommand and two +/// args. Real applications could be many multiple levels deep in subcommands, and have tens or +/// potentially hundreds of arguments. +/// +/// First, it helps if we separate out our `App` definition into a separate file. Whether you +/// do this as a function, or bare App definition is a matter of personal preference. +/// +/// ``` +/// // src/cli.rs +/// +/// use clap::{App, Arg}; +/// +/// pub fn build_cli() -> App<'static> { +/// App::new("compl") +/// .about("Tests completions") +/// .arg(Arg::new("file") +/// .help("some input file")) +/// .subcommand(App::new("test") +/// .about("tests things") +/// .arg(Arg::new("case") +/// .long("case") +/// .takes_value(true) +/// .help("the case to test"))) +/// } +/// ``` +/// +/// In our regular code, we can simply call this `build_cli()` function, then call +/// `get_matches()`, or any of the other normal methods directly after. For example: +/// +/// ```ignore +/// // src/main.rs +/// +/// mod cli; +/// +/// fn main() { +/// let _m = cli::build_cli().get_matches(); +/// +/// // normal logic continues... +/// } +/// ``` +/// +/// Next, we set up our `Cargo.toml` to use a `build.rs` build script. +/// +/// ```toml +/// # Cargo.toml +/// build = "build.rs" +/// +/// [dependencies] +/// clap = "*" +/// +/// [build-dependencies] +/// clap = "*" +/// clap_complete = "*" +/// ``` +/// +/// Next, we place a `build.rs` in our project root. +/// +/// ```ignore +/// use clap_complete::{generate_to, generators::Bash}; +/// use std::env; +/// use std::io::Error; +/// +/// include!("src/cli.rs"); +/// +/// fn main() -> Result<(), Error> { +/// let outdir = match env::var_os("OUT_DIR") { +/// None => return Ok(()), +/// Some(outdir) => outdir, +/// }; +/// +/// let mut app = build_cli(); +/// let path = generate_to( +/// Bash, +/// &mut app, // We need to specify what generator to use +/// "myapp", // We need to specify the bin name manually +/// outdir, // We need to specify where to write to +/// )?; +/// +/// println!("cargo:warning=completion file is generated: {:?}", path); +/// +/// Ok(()) +/// } +/// ``` +/// +/// Now, once we compile there will be a `{bin_name}.bash` file in the directory. +/// Assuming we compiled with debug mode, it would be somewhere similar to +/// `/target/debug/build/myapp-/out/myapp.bash`. +/// +/// **NOTE:** Please look at the individual [generators] +/// to see the name of the files generated. +pub fn generate_to( + gen: G, + app: &mut clap::App, + bin_name: S, + out_dir: T, +) -> Result +where + G: Generator, + S: Into, + T: Into, +{ + app.set_bin_name(bin_name); + + let out_dir = PathBuf::from(out_dir.into()); + let file_name = gen.file_name(app.get_bin_name().unwrap()); + + let path = out_dir.join(file_name); + let mut file = File::create(&path)?; + + _generate::(gen, app, &mut file); + Ok(path) +} + +/// Generate a completions file for a specified shell at runtime. +/// +/// Until `cargo install` can install extra files like a completion script, this may be +/// used e.g. in a command that outputs the contents of the completion script, to be +/// redirected into a file by the user. +/// +/// # Examples +/// +/// Assuming a separate `cli.rs` like the [example above](generate_to()), +/// we can let users generate a completion script using a command: +/// +/// ```ignore +/// // src/main.rs +/// +/// mod cli; +/// use std::io; +/// use clap_complete::{generate, generators::Bash}; +/// +/// fn main() { +/// let matches = cli::build_cli().get_matches(); +/// +/// if matches.is_present("generate-bash-completions") { +/// generate(Bash, &mut cli::build_cli(), "myapp", &mut io::stdout()); +/// } +/// +/// // normal logic continues... +/// } +/// +/// ``` +/// +/// Usage: +/// +/// ```shell +/// $ myapp generate-bash-completions > /usr/share/bash-completion/completions/myapp.bash +/// ``` +pub fn generate(gen: G, app: &mut clap::App, bin_name: S, buf: &mut dyn Write) +where + G: Generator, + S: Into, +{ + app.set_bin_name(bin_name); + _generate::(gen, app, buf) +} + +fn _generate(gen: G, app: &mut clap::App, buf: &mut dyn Write) +where + G: Generator, + S: Into, +{ + app._build_all(); + + gen.generate(app, buf) +} diff --git a/clap_generate/src/macros.rs b/clap_complete/src/macros.rs similarity index 100% rename from clap_generate/src/macros.rs rename to clap_complete/src/macros.rs diff --git a/clap_generate/src/shell.rs b/clap_complete/src/shell.rs similarity index 100% rename from clap_generate/src/shell.rs rename to clap_complete/src/shell.rs diff --git a/clap_generate/src/utils.rs b/clap_complete/src/utils.rs similarity index 100% rename from clap_generate/src/utils.rs rename to clap_complete/src/utils.rs diff --git a/clap_generate/tests/completions/bash.rs b/clap_complete/tests/completions/bash.rs similarity index 100% rename from clap_generate/tests/completions/bash.rs rename to clap_complete/tests/completions/bash.rs diff --git a/clap_generate/tests/completions/elvish.rs b/clap_complete/tests/completions/elvish.rs similarity index 100% rename from clap_generate/tests/completions/elvish.rs rename to clap_complete/tests/completions/elvish.rs diff --git a/clap_generate/tests/completions/fish.rs b/clap_complete/tests/completions/fish.rs similarity index 100% rename from clap_generate/tests/completions/fish.rs rename to clap_complete/tests/completions/fish.rs diff --git a/clap_generate/tests/completions/mod.rs b/clap_complete/tests/completions/mod.rs similarity index 93% rename from clap_generate/tests/completions/mod.rs rename to clap_complete/tests/completions/mod.rs index b0cf8e2a..5ec5c9f2 100644 --- a/clap_generate/tests/completions/mod.rs +++ b/clap_complete/tests/completions/mod.rs @@ -1,5 +1,5 @@ use clap::{App, AppSettings, Arg, ValueHint}; -use clap_generate::{generate, generators::*}; +use clap_complete::{generate, generators::*}; use std::fmt; mod bash; diff --git a/clap_generate/tests/completions/powershell.rs b/clap_complete/tests/completions/powershell.rs similarity index 100% rename from clap_generate/tests/completions/powershell.rs rename to clap_complete/tests/completions/powershell.rs diff --git a/clap_generate/tests/completions/zsh.rs b/clap_complete/tests/completions/zsh.rs similarity index 100% rename from clap_generate/tests/completions/zsh.rs rename to clap_complete/tests/completions/zsh.rs diff --git a/clap_complete/tests/generate_completions.rs b/clap_complete/tests/generate_completions.rs new file mode 100644 index 00000000..11b10be1 --- /dev/null +++ b/clap_complete/tests/generate_completions.rs @@ -0,0 +1,21 @@ +use clap::{App, Arg}; +use clap_complete::{generate, generators::*}; +use std::io; + +#[test] +fn generate_completions() { + let mut app = App::new("test_app") + .arg(Arg::new("config").short('c').global(true)) + .arg(Arg::new("v").short('v').conflicts_with("config")) + .subcommand( + App::new("test") + .about("Subcommand") + .arg(Arg::new("debug").short('d')), + ); + + generate(Bash, &mut app, "test_app", &mut io::sink()); + generate(Fish, &mut app, "test_app", &mut io::sink()); + generate(PowerShell, &mut app, "test_app", &mut io::sink()); + generate(Elvish, &mut app, "test_app", &mut io::sink()); + generate(Zsh, &mut app, "test_app", &mut io::sink()); +} diff --git a/clap_generate/tests/value_hints.rs b/clap_complete/tests/value_hints.rs similarity index 99% rename from clap_generate/tests/value_hints.rs rename to clap_complete/tests/value_hints.rs index 6748e2a9..19213f81 100644 --- a/clap_generate/tests/value_hints.rs +++ b/clap_complete/tests/value_hints.rs @@ -1,5 +1,5 @@ use clap::{App, AppSettings, Arg, ValueHint}; -use clap_generate::generators::*; +use clap_complete::generators::*; use completions::common; mod completions; diff --git a/clap_complete_fig/Cargo.toml b/clap_complete_fig/Cargo.toml new file mode 100644 index 00000000..a135ea43 --- /dev/null +++ b/clap_complete_fig/Cargo.toml @@ -0,0 +1,36 @@ +[package] +name = "clap_complete_fig" +version = "3.0.0-rc.11" +edition = "2018" +include = [ + "src/**/*", + "Cargo.toml", + "LICENSE-*", + "README.md" +] +description = "A generator library used with clap for Fig completion scripts" +repository = "https://github.com/clap-rs/clap/tree/master/clap_complete_fig" +documentation = "https://docs.rs/clap_complete_fig" +keywords = [ + "clap", + "cli", + "generate", + "completion", + "fig", +] +categories = ["command-line-interface"] +license = "MIT OR Apache-2.0" +readme = "README.md" + +[lib] +bench = false + +[dependencies] +clap = { path = "../", version = "=3.0.0-rc.11", default-features = false, features = ["std"] } +clap_complete = { path = "../clap_complete", version = "=3.0.0-rc.11"} + +[dev-dependencies] +pretty_assertions = "1.0" + +[package.metadata.docs.rs] +targets = ["x86_64-unknown-linux-gnu"] diff --git a/clap_complete_fig/LICENSE-APACHE b/clap_complete_fig/LICENSE-APACHE new file mode 100644 index 00000000..261eeb9e --- /dev/null +++ b/clap_complete_fig/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_complete_fig/LICENSE-MIT b/clap_complete_fig/LICENSE-MIT new file mode 100644 index 00000000..5acedf04 --- /dev/null +++ b/clap_complete_fig/LICENSE-MIT @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2015-2016 Kevin B. Knapp + +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_complete_fig/README.md b/clap_complete_fig/README.md new file mode 100644 index 00000000..3c8d1ca8 --- /dev/null +++ b/clap_complete_fig/README.md @@ -0,0 +1,9 @@ +# clap_complete_fig + +Generates [Fig](https://github.com/withfig/autocomplete) completions for [`clap`](https://github.com/clap-rs/clap) based CLIs + + +- [Questions & Discussions](https://github.com/clap-rs/clap/discussions) +- [CONTRIBUTING](../CONTRIBUTING.md) + + diff --git a/clap_generate_fig/examples/fig_completion.rs b/clap_complete_fig/examples/fig_completion.rs similarity index 81% rename from clap_generate_fig/examples/fig_completion.rs rename to clap_complete_fig/examples/fig_completion.rs index 7d3ad69c..d3907b74 100644 --- a/clap_generate_fig/examples/fig_completion.rs +++ b/clap_complete_fig/examples/fig_completion.rs @@ -1,6 +1,6 @@ use clap::App; -use clap_generate::generate; -use clap_generate_fig::Fig; +use clap_complete::generate; +use clap_complete_fig::Fig; use std::io; fn main() { diff --git a/clap_generate_fig/src/fig.rs b/clap_complete_fig/src/fig.rs similarity index 99% rename from clap_generate_fig/src/fig.rs rename to clap_complete_fig/src/fig.rs index 7a8892ea..9d345fc4 100644 --- a/clap_generate_fig/src/fig.rs +++ b/clap_complete_fig/src/fig.rs @@ -3,7 +3,7 @@ use std::io::Write; // Internal use clap::*; -use clap_generate::*; +use clap_complete::*; /// Generate fig completion file pub struct Fig; diff --git a/clap_complete_fig/src/lib.rs b/clap_complete_fig/src/lib.rs new file mode 100644 index 00000000..7eddf08f --- /dev/null +++ b/clap_complete_fig/src/lib.rs @@ -0,0 +1,14 @@ +// `clap_complete_fig` is distributed under the terms of both the MIT license and the Apache License +// (Version 2.0). +// See the [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) files in this repository +// for more information. + +//! Generates [Fig](https://github.com/withfig/autocomplete) completions for [`clap`](https://github.com/clap-rs/clap) based CLIs + +#![doc(html_logo_url = "https://raw.githubusercontent.com/clap-rs/clap/master/assets/clap.png")] +#![warn(missing_docs, trivial_casts, unused_allocation, trivial_numeric_casts)] +#![forbid(unsafe_code)] +#![allow(clippy::needless_doctest_main)] + +mod fig; +pub use fig::Fig; diff --git a/clap_generate_fig/tests/completions/fig.rs b/clap_complete_fig/tests/completions/fig.rs similarity index 100% rename from clap_generate_fig/tests/completions/fig.rs rename to clap_complete_fig/tests/completions/fig.rs diff --git a/clap_generate_fig/tests/completions/mod.rs b/clap_complete_fig/tests/completions/mod.rs similarity index 93% rename from clap_generate_fig/tests/completions/mod.rs rename to clap_complete_fig/tests/completions/mod.rs index 9e5c593f..885f281d 100644 --- a/clap_generate_fig/tests/completions/mod.rs +++ b/clap_complete_fig/tests/completions/mod.rs @@ -1,5 +1,5 @@ use clap::{App, AppSettings, Arg, ValueHint}; -use clap_generate::{generate, generators::*}; +use clap_complete::{generate, generators::*}; use std::fmt; mod fig; diff --git a/clap_generate_fig/tests/generate_completions.rs b/clap_complete_fig/tests/generate_completions.rs similarity index 88% rename from clap_generate_fig/tests/generate_completions.rs rename to clap_complete_fig/tests/generate_completions.rs index 276cc00c..3e6d9cc2 100644 --- a/clap_generate_fig/tests/generate_completions.rs +++ b/clap_complete_fig/tests/generate_completions.rs @@ -1,6 +1,6 @@ use clap::{App, Arg}; -use clap_generate::generate; -use clap_generate_fig::Fig; +use clap_complete::generate; +use clap_complete_fig::Fig; use std::io; #[test] diff --git a/clap_generate_fig/tests/value_hints.rs b/clap_complete_fig/tests/value_hints.rs similarity index 99% rename from clap_generate_fig/tests/value_hints.rs rename to clap_complete_fig/tests/value_hints.rs index 08946677..df3c6c57 100644 --- a/clap_generate_fig/tests/value_hints.rs +++ b/clap_complete_fig/tests/value_hints.rs @@ -1,5 +1,5 @@ use clap::{App, AppSettings, Arg, ValueHint}; -use clap_generate_fig::Fig; +use clap_complete_fig::Fig; use completions::common; mod completions; diff --git a/clap_generate/Cargo.toml b/clap_generate/Cargo.toml index 25e03f7c..2d080baf 100644 --- a/clap_generate/Cargo.toml +++ b/clap_generate/Cargo.toml @@ -8,7 +8,7 @@ include = [ "LICENSE-*", "README.md" ] -description = "A generator library used with clap for shell completion scripts, manpage, etc." +description = "Renamed to clap_complete" repository = "https://github.com/clap-rs/clap/tree/master/clap_generate" documentation = "https://docs.rs/clap_generate" keywords = [ @@ -22,24 +22,10 @@ categories = ["command-line-interface"] license = "MIT OR Apache-2.0" readme = "README.md" -[package.metadata.release] -pre-release-replacements = [ - {file="README.md", search="github.com/clap-rs/clap/blob/[^/]+/", replace="github.com/clap-rs/clap/blob/{{tag_name}}/", exactly=4, prerelease = true}, -] - -[lib] -bench = false - [dependencies] clap = { path = "../", version = "=3.0.0-rc.11", default-features = false, features = ["std"] } - -[dev-dependencies] -pretty_assertions = "1.0" -clap = { path = "../", version = "=3.0.0-rc.11", default-features = false, features = ["std", "derive"] } +clap_complete = { path = "../clap_complete", version = "=3.0.0-rc.11" } [features] default = [] -debug = ["clap/debug"] - -[package.metadata.docs.rs] -targets = ["x86_64-unknown-linux-gnu"] +debug = ["clap_complete/debug"] diff --git a/clap_generate/src/lib.rs b/clap_generate/src/lib.rs index 77cf64b3..5d13792b 100644 --- a/clap_generate/src/lib.rs +++ b/clap_generate/src/lib.rs @@ -1,182 +1,24 @@ -// Copyright ⓒ 2015-2018 Kevin B. Knapp -// -// `clap_generate` is distributed under the terms of both the MIT license and the Apache License -// (Version 2.0). -// See the [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) files in this repository -// for more information. - -#![doc(html_logo_url = "https://raw.githubusercontent.com/clap-rs/clap/master/assets/clap.png")] -#![doc = include_str!("../README.md")] -#![warn(missing_docs, trivial_casts, unused_allocation, trivial_numeric_casts)] -#![forbid(unsafe_code)] -#![allow(clippy::needless_doctest_main)] - -//! ## Quick Start -//! -//! - For generating at compile-time, see [`generate_to`] -//! - For generating at runtime, see [`generate`] -//! -//! [`Shell`] is a convenience `enum` for an argument value type that implements `Generator` -//! for each natively-supported shell type. -//! -//! ## Example -//! -//! ```rust,no_run -//! use clap::{App, AppSettings, Arg, ValueHint}; -//! use clap_generate::{generate, Generator, Shell}; -//! use std::io; -//! -//! fn build_cli() -> App<'static> { -//! App::new("example") -//! .arg(Arg::new("file") -//! .help("some input file") -//! .value_hint(ValueHint::AnyPath), -//! ) -//! .arg( -//! Arg::new("generator") -//! .long("generate") -//! .possible_values(Shell::possible_values()), -//! ) -//! } -//! -//! fn print_completions(gen: G, app: &mut App) { -//! generate(gen, app, app.get_name().to_string(), &mut io::stdout()); -//! } -//! -//! fn main() { -//! let matches = build_cli().get_matches(); -//! -//! if let Ok(generator) = matches.value_of_t::("generator") { -//! let mut app = build_cli(); -//! eprintln!("Generating completion file for {}...", generator); -//! print_completions(generator, &mut app); -//! } -//! } -//! ``` - -const INTERNAL_ERROR_MSG: &str = "Fatal internal error. Please consider filing a bug \ - report at https://github.com/clap-rs/clap/issues"; - -#[macro_use] -#[allow(missing_docs)] -mod macros; - -/// Contains some popular generators -pub mod generators; -/// Contains supported shells for auto-completion scripts -mod shell; -/// Helpers for writing generators -pub mod utils; - use std::ffi::OsString; -use std::fs::File; use std::io::Error; use std::io::Write; use std::path::PathBuf; -#[doc(inline)] -pub use generators::Generator; -#[doc(inline)] -pub use shell::Shell; +#[deprecated(since = "3.0.0", note = "Renamed to `clap_complete`")] +pub use clap_complete::Generator; +#[deprecated(since = "3.0.0", note = "Renamed to `clap_complete`")] +pub use clap_complete::Shell; -/// Generate a completions file for a specified shell at compile-time. -/// -/// **NOTE:** to generate the file at compile time you must use a `build.rs` "Build Script" or a -/// [`cargo-xtask`](https://github.com/matklad/cargo-xtask) -/// -/// # Examples -/// -/// The following example generates a bash completion script via a `build.rs` script. In this -/// simple example, we'll demo a very small application with only a single subcommand and two -/// args. Real applications could be many multiple levels deep in subcommands, and have tens or -/// potentially hundreds of arguments. -/// -/// First, it helps if we separate out our `App` definition into a separate file. Whether you -/// do this as a function, or bare App definition is a matter of personal preference. -/// -/// ``` -/// // src/cli.rs -/// -/// use clap::{App, Arg}; -/// -/// pub fn build_cli() -> App<'static> { -/// App::new("compl") -/// .about("Tests completions") -/// .arg(Arg::new("file") -/// .help("some input file")) -/// .subcommand(App::new("test") -/// .about("tests things") -/// .arg(Arg::new("case") -/// .long("case") -/// .takes_value(true) -/// .help("the case to test"))) -/// } -/// ``` -/// -/// In our regular code, we can simply call this `build_cli()` function, then call -/// `get_matches()`, or any of the other normal methods directly after. For example: -/// -/// ```ignore -/// // src/main.rs -/// -/// mod cli; -/// -/// fn main() { -/// let _m = cli::build_cli().get_matches(); -/// -/// // normal logic continues... -/// } -/// ``` -/// -/// Next, we set up our `Cargo.toml` to use a `build.rs` build script. -/// -/// ```toml -/// # Cargo.toml -/// build = "build.rs" -/// -/// [dependencies] -/// clap = "*" -/// -/// [build-dependencies] -/// clap = "*" -/// clap_generate = "*" -/// ``` -/// -/// Next, we place a `build.rs` in our project root. -/// -/// ```ignore -/// use clap_generate::{generate_to, generators::Bash}; -/// use std::env; -/// use std::io::Error; -/// -/// include!("src/cli.rs"); -/// -/// fn main() -> Result<(), Error> { -/// let outdir = match env::var_os("OUT_DIR") { -/// None => return Ok(()), -/// Some(outdir) => outdir, -/// }; -/// -/// let mut app = build_cli(); -/// let path = generate_to( -/// Bash, -/// &mut app, // We need to specify what generator to use -/// "myapp", // We need to specify the bin name manually -/// outdir, // We need to specify where to write to -/// )?; -/// -/// println!("cargo:warning=completion file is generated: {:?}", path); -/// -/// Ok(()) -/// } -/// ``` -/// -/// Now, once we compile there will be a `{bin_name}.bash` file in the directory. -/// Assuming we compiled with debug mode, it would be somewhere similar to -/// `/target/debug/build/myapp-/out/myapp.bash`. -/// -/// **NOTE:** Please look at the individual [generators] -/// to see the name of the files generated. +#[deprecated(since = "3.0.0", note = "Renamed to `clap_complete::generators`")] +pub mod generators { + pub use clap_complete::generators::*; +} + +#[deprecated(since = "3.0.0", note = "Renamed to `clap_complete::utils`")] +pub mod utils { + pub use clap_complete::utils::*; +} + +#[deprecated(since = "3.0.0", note = "Renamed to `clap_complete::generate_to`")] pub fn generate_to( gen: G, app: &mut clap::App, @@ -188,68 +30,14 @@ where S: Into, T: Into, { - app.set_bin_name(bin_name); - - let out_dir = PathBuf::from(out_dir.into()); - let file_name = gen.file_name(app.get_bin_name().unwrap()); - - let path = out_dir.join(file_name); - let mut file = File::create(&path)?; - - _generate::(gen, app, &mut file); - Ok(path) + clap_complete::generate_to(gen, app, bin_name, out_dir) } -/// Generate a completions file for a specified shell at runtime. -/// -/// Until `cargo install` can install extra files like a completion script, this may be -/// used e.g. in a command that outputs the contents of the completion script, to be -/// redirected into a file by the user. -/// -/// # Examples -/// -/// Assuming a separate `cli.rs` like the [example above](generate_to()), -/// we can let users generate a completion script using a command: -/// -/// ```ignore -/// // src/main.rs -/// -/// mod cli; -/// use std::io; -/// use clap_generate::{generate, generators::Bash}; -/// -/// fn main() { -/// let matches = cli::build_cli().get_matches(); -/// -/// if matches.is_present("generate-bash-completions") { -/// generate(Bash, &mut cli::build_cli(), "myapp", &mut io::stdout()); -/// } -/// -/// // normal logic continues... -/// } -/// -/// ``` -/// -/// Usage: -/// -/// ```shell -/// $ myapp generate-bash-completions > /usr/share/bash-completion/completions/myapp.bash -/// ``` +#[deprecated(since = "3.0.0", note = "Renamed to `clap_complete`")] pub fn generate(gen: G, app: &mut clap::App, bin_name: S, buf: &mut dyn Write) where G: Generator, S: Into, { - app.set_bin_name(bin_name); - _generate::(gen, app, buf) -} - -fn _generate(gen: G, app: &mut clap::App, buf: &mut dyn Write) -where - G: Generator, - S: Into, -{ - app._build_all(); - - gen.generate(app, buf) + clap_complete::generate(gen, app, bin_name, buf) } diff --git a/clap_generate/tests/generate_completions.rs b/clap_generate/tests/warning.rs similarity index 96% rename from clap_generate/tests/generate_completions.rs rename to clap_generate/tests/warning.rs index f9446cfe..293b2a34 100644 --- a/clap_generate/tests/generate_completions.rs +++ b/clap_generate/tests/warning.rs @@ -1,3 +1,5 @@ +#![allow(deprecated)] + use clap::{App, Arg}; use clap_generate::{generate, generators::*}; use std::io; diff --git a/clap_generate_fig/Cargo.toml b/clap_generate_fig/Cargo.toml index 45ad7376..4ee28a9f 100644 --- a/clap_generate_fig/Cargo.toml +++ b/clap_generate_fig/Cargo.toml @@ -8,7 +8,7 @@ include = [ "LICENSE-*", "README.md" ] -description = "A generator library used with clap for Fig completion scripts" +description = "Renamed to clap_complete_fig" repository = "https://github.com/clap-rs/clap/tree/master/clap_generate_fig" documentation = "https://docs.rs/clap_generate_fig" keywords = [ @@ -26,11 +26,4 @@ readme = "README.md" bench = false [dependencies] -clap = { path = "../", version = "=3.0.0-rc.11", default-features = false, features = ["std"] } -clap_generate = { path = "../clap_generate", version = "=3.0.0-rc.11"} - -[dev-dependencies] -pretty_assertions = "1.0" - -[package.metadata.docs.rs] -targets = ["x86_64-unknown-linux-gnu"] +clap_complete_fig = { path = "../clap_complete_fig", version = "=3.0.0-rc.11"} diff --git a/clap_generate_fig/src/lib.rs b/clap_generate_fig/src/lib.rs index 5e6b0167..78272081 100644 --- a/clap_generate_fig/src/lib.rs +++ b/clap_generate_fig/src/lib.rs @@ -1,14 +1,2 @@ -// `clap_generate_fig` is distributed under the terms of both the MIT license and the Apache License -// (Version 2.0). -// See the [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) files in this repository -// for more information. - -//! Generates [Fig](https://github.com/withfig/autocomplete) completions for [`clap`](https://github.com/clap-rs/clap) based CLIs - -#![doc(html_logo_url = "https://raw.githubusercontent.com/clap-rs/clap/master/assets/clap.png")] -#![warn(missing_docs, trivial_casts, unused_allocation, trivial_numeric_casts)] -#![forbid(unsafe_code)] -#![allow(clippy::needless_doctest_main)] - -mod fig; -pub use fig::Fig; +#[deprecated(since = "3.0.0", note = "Renamed to clap_complete_fig::Fig")] +pub use clap_complete_fig::Fig; diff --git a/src/build/app/mod.rs b/src/build/app/mod.rs index 8abb8e35..0e68f034 100644 --- a/src/build/app/mod.rs +++ b/src/build/app/mod.rs @@ -2577,7 +2577,7 @@ impl<'help> App<'help> { Ok(matcher.into_inner()) } - // used in clap_generate (https://github.com/clap-rs/clap_generate) + // used in clap_complete (https://github.com/clap-rs/clap_complete) #[doc(hidden)] pub fn _build_all(&mut self) { self._build(); @@ -2587,7 +2587,7 @@ impl<'help> App<'help> { self._build_bin_names(); } - // used in clap_generate (https://github.com/clap-rs/clap_generate) + // used in clap_complete (https://github.com/clap-rs/clap_complete) #[doc(hidden)] pub fn _build(&mut self) { debug!("App::_build"); @@ -2875,7 +2875,7 @@ impl<'help> App<'help> { } } - // used in clap_generate (https://github.com/clap-rs/clap_generate) + // used in clap_complete (https://github.com/clap-rs/clap_complete) #[doc(hidden)] pub fn _build_bin_names(&mut self) { debug!("App::_build_bin_names"); diff --git a/src/build/arg/value_hint.rs b/src/build/arg/value_hint.rs index 45109d2d..b61a3e77 100644 --- a/src/build/arg/value_hint.rs +++ b/src/build/arg/value_hint.rs @@ -4,7 +4,7 @@ use std::str::FromStr; /// /// See [Arg::value_hint][crate::Arg::value_hint] to set this on an argument. /// -/// See the `clap_generate` crate for completion script generation. +/// See the `clap_complete` crate for completion script generation. /// /// Overview of which hints are supported by which shell: ///