Expand description
Documentation: Overview
A common requirement of a program is the need to process command line arguments supplied to it. This library was designed to assist Rust based programs in this area.
Motivation
While other solutions already existed for Rust programs, they arguably tried to do too much; their designs were geared towards completely taking over every aspect of argument handling. While removing as much of the burden from the application programmer as possible is a desirable goal, these existing solutions in attempting to do this imposed significant restrictions on compatible program designs. It appeared that the Rust crate ecosystem was missing a more fundamental and broadly applicable solution.
Some/all of these solutions also forced a “builder” type pattern of describing options through
successive method calls, lacking a more efficient option of directly defining the data
structure. This includes preventing efficient declaration of a static
/const
set.
Design
In C programming, the common getopt
and getopt_long
functions have, for a long time, served
to assist in this area. This library was inspired by them and designed as a similar fundamental
and broadly applicable assistant.
The basic premise of usage is simple:
- Provide the processing function with a description of available options along with the input arguments to be processed, and it returns the results of its analysis.
- You can then work through this analysis to respond as applicable: Output error information if the user made a mistake; output help/usage information if requested; store state information from recognised flag type options; and store data (converting values as necessary) from non-options and recognised “with data arg” options.
- Proceed on with whatever your program was designed to do.
Differences to the old getopt
/getopt_long
C solution include:
- All processing can be done in one go, rather than with recursive function calls.
- Use of static global variables for “position” tracking is avoided.
- Non-options are not shuffled to the end of the list, unlike the default behaviour of
getopt
. - The “convenience” functionality of
-W foo
being treated as--foo
is not supported (unnecessary complexity).
Mismatch suggestions
This library does not (currently) itself provide any suggestion mechanism for failed option matches - i.e. the ability to take an unmatched long option and pick the most likely of the available options that the user may have actually meant to use, to suggest to them when reporting the error. There is nothing however stopping users of this library from running unmatched options through a third-party library to obtain the suggestion to display.
Crate name origins
The gong
crate name was chosen in homage to the venerable C getopt
, and can be considered a
“next-gen” solution for people moving to the Rust programming language.
Get-Opt Next-Gen →
gong
Hopefully this crate will become as common and universally adopted as getopt
in C code.