Skip to content
Kevin K edited this page Sep 21, 2015 · 9 revisions

Usage

Why use clap instead of docopt or getopts?

Disclaimer: This question is not meant to criticize any other argument parsing library. We all have our strengths and weaknesses. When in doubt, try them all!

This question has a two part answer; one for when you should use clap and another for when either doctopt or getopts may be a better fit. This answer does not address personal preferences, because sometimes people just like the feel or ergonomics of one library over another.

Reasons to use clap

  • You want all the nice CLI features your users may expect, yet you don't want to implement them all yourself. You'd like to focus your application, not argument parsing.
  • In addition to the point above; you don't want to sacrifice performance to get all those nice features
  • You have complex requirements/conflicts between your various valid args.
  • You want to use subcommands (although other libraries also support subcommands, they are not nearly as feature rich as those provided by clap)
  • You want some sort of custom validation built into the argument parsing process, instead of as part of your application (which allows for earlier failures, better error messages, more cohesive experience, etc.)
  • You need more performance than docopt provides

Reasons to docopt

  • You want automatic serialization of your arguments into Rust types (Although clap can do this, docopt is better at it)
  • You are on nightly Rust and want the library to automatically generate an "arguments struct" from the matched args
  • You are porting an application which uses docopt and already have the usage string already defined

Reasons to use getopts

  • You need absolutely as few allocations as possible and don't mind implementing nearly everything yourself
  • You want a portion of the arg parsing process to be very custom (again, implementing the details yourself)

How many methods are there to create an App/Arg?

To build an App there are two:

  • Builder Pattern
  • Yaml

To build an Arg there are three:

  • Builder Pattern
  • Usage Strings
  • Yaml

There is another method in the works for both App and Arg using macros which is a combination of usage and builder patterns to achieve a very nice balance between performance (actually the fastest) and verbosity.

Why is there a default subcommand of help? Why not at least be opt-in via settings?

There is only a default subcommand of help when other subcommands have been defined manually. So it's opt-in(ish), being that you only get a help subcommand if you're actually using subcommands.

Also, if the user defined a help subcommand themselves, the auto-generated one wouldn't be added (meaning it's only generated if the user hasn't defined one themselves).

Implementation

Do App and Arg really need so many lifetimes? Can't they all just be bound to one? Why not just own Strings?

In the early days they were all bound to the 'static lifetime. But there are times when you want pull just a single a piece of information for an App or Arg at runtime or even dynamically, and therefore can't just use 'static.

The reason for not using owned Strings was to try and keep clap competitive in the performance department. In nearly all benchmarks we've run, clap keeps up with naked parsing while still providing all those features. 99% of the settings and args use a lot of 'static lifetimes and don't need to be re-allocated in order to be used.

Clone this wiki locally
You can’t perform that action at this time.