Merge pull request #1731 from epage/clap3

Port mdBook to clap3

Author: ehuss

.github/workflows/main.yml

@@ -31,7 +31,8 @@ jobs:
             rust: stable
           - build: msrv
             os: ubuntu-latest
-            rust: 1.46.0
+            # sync MSRV with docs: guide/src/guide/installation.md
+            rust: 1.54.0
     steps:
     - uses: actions/checkout@master
     - name: Install Rust

Cargo.lock

@@ -18,7 +18,8 @@ description = "Creates a book from markdown files"
 [dependencies]
 anyhow = "1.0.28"
 chrono = "0.4"
-clap = "2.24"
+clap = { version = "3.0", features = ["cargo"] }
+clap_complete = "3.0"
 env_logger = "0.7.1"
 handlebars = "4.0"
 lazy_static = "1.0"

Cargo.toml

@@ -1,18 +1,18 @@
 use crate::nop_lib::Nop;
-use clap::{App, Arg, ArgMatches, SubCommand};
+use clap::{App, Arg, ArgMatches};
 use mdbook::book::Book;
 use mdbook::errors::Error;
 use mdbook::preprocess::{CmdPreprocessor, Preprocessor, PreprocessorContext};
 use semver::{Version, VersionReq};
 use std::io;
 use std::process;
 
-pub fn make_app() -> App<'static, 'static> {
+pub fn make_app() -> App<'static> {
     App::new("nop-preprocessor")
         .about("A mdbook preprocessor which does precisely nothing")
         .subcommand(
-            SubCommand::with_name("supports")
-                .arg(Arg::with_name("renderer").required(true))
+            App::new("supports")
+                .arg(Arg::new("renderer").required(true))
                 .about("Check whether a renderer is supported by this preprocessor"),
         )
 }

examples/nop-preprocessor.rs

@@ -20,7 +20,7 @@ To make it easier to run, put the path to the binary into your `PATH`.
 
 To build the `mdbook` executable from source, you will first need to install Rust and Cargo.
 Follow the instructions on the [Rust installation page].
-mdBook currently requires at least Rust version 1.46.
+mdBook currently requires at least Rust version 1.54.
 
 Once you have installed Rust, the following command can be used to build and install mdBook:
 

guide/src/guide/installation.md

@@ -1,22 +1,28 @@
 use crate::{get_book_dir, open};
-use clap::{App, ArgMatches, SubCommand};
+use clap::{arg, App, Arg, ArgMatches};
 use mdbook::errors::Result;
 use mdbook::MDBook;
 
 // Create clap subcommand arguments
-pub fn make_subcommand<'a, 'b>() -> App<'a, 'b> {
-    SubCommand::with_name("build")
+pub fn make_subcommand<'help>() -> App<'help> {
+    App::new("build")
         .about("Builds a book from its markdown files")
-        .arg_from_usage(
-            "-d, --dest-dir=[dest-dir] 'Output directory for the book{n}\
-             Relative paths are interpreted relative to the book's root directory.{n}\
-             If omitted, mdBook uses build.build-dir from book.toml or defaults to `./book`.'",
+        .arg(
+            Arg::new("dest-dir")
+                .short('d')
+                .long("dest-dir")
+                .value_name("dest-dir")
+                .help(
+                    "Output directory for the book{n}\
+                    Relative paths are interpreted relative to the book's root directory.{n}\
+                    If omitted, mdBook uses build.build-dir from book.toml or defaults to `./book`.",
+                ),
         )
-        .arg_from_usage(
-            "[dir] 'Root directory for the book{n}\
-             (Defaults to the Current Directory when omitted)'",
-        )
-        .arg_from_usage("-o, --open 'Opens the compiled book in a web browser'")
+        .arg(arg!([dir]
+            "Root directory for the book{n}\
+            (Defaults to the Current Directory when omitted)"
+        ))
+        .arg(arg!(-o --open "Opens the compiled book in a web browser"))
 }
 
 // Build command implementation

src/cmd/build.rs

@@ -1,23 +1,28 @@
 use crate::get_book_dir;
 use anyhow::Context;
-use clap::{App, ArgMatches, SubCommand};
+use clap::{arg, App, Arg, ArgMatches};
 use mdbook::MDBook;
 use std::fs;
 
 // Create clap subcommand arguments
-pub fn make_subcommand<'a, 'b>() -> App<'a, 'b> {
-    SubCommand::with_name("clean")
+pub fn make_subcommand<'help>() -> App<'help> {
+    App::new("clean")
         .about("Deletes a built book")
-        .arg_from_usage(
-            "-d, --dest-dir=[dest-dir] 'Output directory for the book{n}\
-             Relative paths are interpreted relative to the book's root directory.{n}\
-             Running this command deletes this directory.{n}\
-             If omitted, mdBook uses build.build-dir from book.toml or defaults to `./book`.'",
-        )
-        .arg_from_usage(
-            "[dir] 'Root directory for the book{n}\
-             (Defaults to the Current Directory when omitted)'",
+        .arg(
+            Arg::new("dest-dir")
+                .short('d')
+                .long("dest-dir")
+                .value_name("dest-dir")
+                .help(
+                    "Output directory for the book{n}\
+                    Relative paths are interpreted relative to the book's root directory.{n}\
+                    If omitted, mdBook uses build.build-dir from book.toml or defaults to `./book`.",
+                ),
         )
+        .arg(arg!([dir]
+            "Root directory for the book{n}\
+            (Defaults to the Current Directory when omitted)"
+        ))
 }
 
 // Clean command implementation

src/cmd/clean.rs

@@ -1,5 +1,5 @@
 use crate::get_book_dir;
-use clap::{App, Arg, ArgMatches, SubCommand};
+use clap::{arg, App, Arg, ArgMatches};
 use mdbook::config;
 use mdbook::errors::Result;
 use mdbook::MDBook;
@@ -8,25 +8,25 @@ use std::io::Write;
 use std::process::Command;
 
 // Create clap subcommand arguments
-pub fn make_subcommand<'a, 'b>() -> App<'a, 'b> {
-    SubCommand::with_name("init")
+pub fn make_subcommand<'help>() -> App<'help> {
+    App::new("init")
         .about("Creates the boilerplate structure and files for a new book")
         // the {n} denotes a newline which will properly aligned in all help messages
-        .arg_from_usage(
-            "[dir] 'Directory to create the book in{n}\
-             (Defaults to the Current Directory when omitted)'",
-        )
-        .arg_from_usage("--theme 'Copies the default theme into your source folder'")
-        .arg_from_usage("--force 'Skips confirmation prompts'")
+        .arg(arg!([dir]
+            "Directory to create the book in{n}\
+            (Defaults to the Current Directory when omitted)"
+        ))
+        .arg(arg!(--theme "Copies the default theme into your source folder"))
+        .arg(arg!(--force "Skips confirmation prompts"))
         .arg(
-            Arg::with_name("title")
+            Arg::new("title")
                 .long("title")
                 .takes_value(true)
                 .help("Sets the book title")
                 .required(false),
         )
         .arg(
-            Arg::with_name("ignore")
+            Arg::new("ignore")
                 .long("ignore")
                 .takes_value(true)
                 .possible_values(&["none", "git"])

src/cmd/init.rs

@@ -1,7 +1,7 @@
 #[cfg(feature = "watch")]
 use super::watch;
 use crate::{get_book_dir, open};
-use clap::{App, Arg, ArgMatches, SubCommand};
+use clap::{arg, App, Arg, ArgMatches};
 use futures_util::sink::SinkExt;
 use futures_util::StreamExt;
 use mdbook::errors::*;
@@ -18,37 +18,43 @@ use warp::Filter;
 const LIVE_RELOAD_ENDPOINT: &str = "__livereload";
 
 // Create clap subcommand arguments
-pub fn make_subcommand<'a, 'b>() -> App<'a, 'b> {
-    SubCommand::with_name("serve")
+pub fn make_subcommand<'help>() -> App<'help> {
+    App::new("serve")
         .about("Serves a book at http://localhost:3000, and rebuilds it on changes")
-        .arg_from_usage(
-            "-d, --dest-dir=[dest-dir] 'Output directory for the book{n}\
-             Relative paths are interpreted relative to the book's root directory.{n}\
-             If omitted, mdBook uses build.build-dir from book.toml or defaults to `./book`.'",
-        )
-        .arg_from_usage(
-            "[dir] 'Root directory for the book{n}\
-             (Defaults to the Current Directory when omitted)'",
+        .arg(
+            Arg::new("dest-dir")
+                .short('d')
+                .long("dest-dir")
+                .value_name("dest-dir")
+                .help(
+                    "Output directory for the book{n}\
+                    Relative paths are interpreted relative to the book's root directory.{n}\
+                    If omitted, mdBook uses build.build-dir from book.toml or defaults to `./book`.",
+                ),
         )
+        .arg(arg!([dir]
+            "Root directory for the book{n}\
+            (Defaults to the Current Directory when omitted)"
+        ))
         .arg(
-            Arg::with_name("hostname")
-                .short("n")
+            Arg::new("hostname")
+                .short('n')
                 .long("hostname")
                 .takes_value(true)
                 .default_value("localhost")
-                .empty_values(false)
+                .forbid_empty_values(true)
                 .help("Hostname to listen on for HTTP connections"),
         )
         .arg(
-            Arg::with_name("port")
-                .short("p")
+            Arg::new("port")
+                .short('p')
                 .long("port")
                 .takes_value(true)
                 .default_value("3000")
-                .empty_values(false)
+                .forbid_empty_values(true)
                 .help("Port to use for HTTP connections"),
         )
-        .arg_from_usage("-o, --open 'Opens the book server in a web browser'")
+        .arg(arg!(-o --open "Opens the compiled book in a web browser"))
 }
 
 // Serve command implementation