Exploring Click

[epage]

TODO: Left off at options

This is a rough series of notes exploring whats interesting about Click, from a clap perspective so we can consider what we can learn or to keep more options in consideration when exploring solutions.

My hope is we can do the same with other respected non-Rust CLI arg parsers.

High Level

For goals, the ones that stand out for clap are

• Is lazily composable without restrictions.
• Is fully nestable and composable.
  • These two lead to interesting design decisions. For example, when they compare to argparse, they call out "argparse has built-in behavior to guess if something is an argument or an option. This becomes a problem when dealing with incomplete command lines; the behaviour becomes unpredictable without full knowledge of a command line. This goes against Click’s ambitions of dispatching to subparsers."
• Support for prompting of custom values.
• Comes with useful common helpers (getting terminal dimensions, ANSI colors, fetching direct keyboard input, screen clearing, finding config paths, launching apps and editors, etc.).

For non-goals

• Configurability: "The other question is why Click goes away from optparse and hardcodes certain behaviors instead of staying configurable. There are multiple reasons for this. The biggest one is that too much configurability makes it hard to achieve a consistent command line experience."
• Auto-correction: "The question came up why Click does not auto correct parameters given that even optparse and argparse support automatic expansion of long arguments. The reason for this
  is that it’s a liability for backwards compatibility. "

Terminology:

• arguments: Denoted by position. Limits on how optional they can be
  • can accept an arbitrary number of values
• options: Denoted by a named flag.
  • automatic prompting for missing input
  • act as flags (boolean or otherwise)
  • option values can be pulled from environment variables, arguments can not
  • options are fully documented in the help page, arguments are not (this is intentional as arguments might be too specific to be automatically documented)

API

The first thing of note is it uses function attributes for its API, rather than struct/class attributes. fncmd explores that direction for clap.

Integrated types

Those of note:

• bool: A parameter that accepts boolean values. This is automatically used for boolean flags. The string values “1”, “true”, “t”, “yes”, “y”, and “on” convert to True. “0”, “false”, “f”, “no”, “n”, and “off” convert to False.
• Files: attached to the lifetime of their container
  • Handles stdio automatically
  • Lazily opens files for write
  • Supports atomic file writes
• Path
  • Includes optional validation like "is present", "is dir", etc
  • Includes mutations like "resolve"
• Ranges
  • Includes clamping support
  • Considering people use integer sizes in the derive for a rough range, it seems there is a desire for this in clap
• DateTime
  • humantime seems a bit much to bake into clap but could be handy to have a helper for it
• Custom types

[ofek]

Great to see this! Whenever you do more with coloring please explore https://github.com/Textualize/rich