Refactor and port CLI from Docopt to Clap (#2066)

[axelchalon]

• Previously we had the flags, arguments and subcommands in a text file for the help message, and once more in mod.rs to parse the command line. Now, mod.rs is the single source of truth and it also contains the usage and help messages of the flags/arguments/subcommands included. We generate the help message automatically based on this, with the default value included like before.
• Subcommands and sub-subcommands now also have their own help messages : parity account --help, parity account list --help. Their help messages are very scanty for now, so some (more) help would be welcome. The help messages of the subcommands are generated by clap.
• As per Clap specs, global ("top-level") arguments (for example --chain) must now come before the subcommand, i.e. parity snapshot --chain=dev mysnapshot.dump won't work; it needs to be parity --chain=dev snapshot mysnapshot.dump. The --help message was modified to convey this: parity [options] snapshot <FILE> for example. This is a breaking change, I believe. Likewise, subcommand-specific arguments aren't allowed before the subcommand anymore.
• Because we want to still have the global arguments available when using subcommands, we cannot use the argument value syntax when value is the name of a subcommand; e.g. parity --ui-path signer won't work because signer is the name of a subcommand, and Clap parses this as running the signer subcommand with the global argument ui-path having an empty value. For those special cases we need to use the argument=value syntax: parity --ui-path=signer. I edited the corresponding test. (also filed an issue on clap, Argument value should take precedence over subcommand with the same name clap-rs/clap#1031) [EDIT: Clap fixed the issue]
• For the record, the macro allows only two levels of subcommands, for example parity account import.
• Made the naming more consistent: flag_s are CLI switches (boolean) such as (--no-config), arg_s take values (--chain dev, <FILE>). I renamed some arguments because of this.
• I had to discard the internal options --can-restart and --force-direct from the help message because these flags are not parsed by clap but parsed beforehand, and the help message is generated based on clap arguments. If it is preferable to leave their help messages in the --help output, let me know and we could add them to the clap flags (even though their values from the clap Args struct wouldn't be used anywhere).
• I split the --password argument depending on what command/subcommand it's for: arg_signer_sign_password, arg_wallet_import_password, arg_account_new_password, arg_password (the latter bing the only one of those arguments to be a vec), and removed the legacy option flag_warp, as its value was systematically the opposite of flag_no_warp (both values are fetched from the config file entry "warp"); I switched to using flag_no_warp instead of flag_warp on the one instance in the codebase where flag_warp as used. Also, the legacy flag flag_dapps_apis_all is now like all the other flags a bool, not an Option<bool>.
• It might not be clear for the users that the config.toml files in parity/cli are only used for test purposes, so I moved them to a test subfolder.
• The default values printed in the --help message for the options do not take into account the config file parameters; they are the built-in defaults. But I think it was also this way with docopt.
• The syntax for multiple arguments is --argument value1 value2, although it would be possible to use commas as delimiters with clap instead.

Here's the --help output: https://gist.github.com/axelchalon/71e1f34019771f444d8380b21a88e2c8

Subcommand and subsubcommand --help output: https://gist.github.com/axelchalon/7a6762be783094a455a0e1b4a5181e88

...and --version output: https://gist.github.com/axelchalon/2639d0a3b1628c57afd242ee3163c430

[parity-cla-bot]

It looks like @axelchalon signed our Contributor License Agreement. 👍

Many thanks,

Parity Technologies CLA Bot

[debris]

warning: unused import: dir
--> parity/cli/mod.rs:20:5
|
20 | use dir;
| ^^^
|
= note: #[warn(unused_imports)] on by default

[axelchalon]

fixed

[debris]

Here's the --help output: https://gist.github.com/axelchalon/71e1f34019771f444d8380b21a88e2c8

Can you wrap it to 100 or 120 characters per line? this function might be helpful

Subcommand and subsubcommand --help output: https://gist.github.com/axelchalon/7a6762be783094a455a0e1b4a5181e88

That's a huuuge improvement!

As per Clap specs, global ("top-level") arguments (for example --chain) must now come before the subcommand

I can't talk for others, but I'm totally fine with this change

I will review it further tomorrow

[keorn]

Cool.
--can-restart and --force-direct should remain in help (all options should be there).

[rphmeier]

Closes #2066

[rphmeier]

I would suggest that the help message for parity --help exclude all flags which exist only for subcommands if not already done.

[axelchalon]

Yes, the parity --help output only displays the help of "top-level" flags/arguments.

This being said, I just noticed that some of those top-level options are actually only used for subcommands (namely all the "Import/export" options except for, afaik, "flag_no_seal_check"), so I moved them to the subcommand's options. Let me know if there are other top-level options that are subcommand-specific!

I updated the gist of the parity --help output.

[tomusdrw]

lgtm

[tomusdrw]

Should those two be grouped together?

[axelchalon]

what do you mean?

[tomusdrw]

like:
parity snapshot take and parity snapshot restore

Right now while parity snapshot is self-describing, I had to check the docs what parity restore is supposed to do.

[axelchalon]

yeah, makes sense! I too think it'd be better this way, but then the usage would change from the current version (currently it's parity snapshot and parity restore; I didn't change the name of the subcommands or options, simply refactored). It wouldn't be hard to find the new subcommand, but it'd be a breaking change in case people have scripts running with the current syntax for example. maybe we can keep this PR a refactoring one?

[tomusdrw]

A separate PR is fine for me, although we already break backward compatibility by disallowing options after the command name.

[gavofyork]

@5chdn please work with @axelchalon for the 1.8.0 release's changelog - this will break quite a lot of installations.