At attempt to clarify option parsing for my own understanding.
- argument -- a sequence of characters or bytes
- option -- an argument that selects behavior of the program
- option-argument -- an argument expected after and providing a value for an option
- operand -- an argument that specifies input for the program; aka "non-option argument" or sometimes just "argument"
- exactly "-" is a non-option argument
- short options prefixed with "-"
- short options may have a value specified in the same argument after the option character
- long options prefixed with "--"
- long options may have a value specified in the same argument separated by "="
- generally rare
- prefixes may be "@", "+", or others
- options may take one value in the immediately following argument
- options may explicitly not take a value
- short options are often allowed to be combined; eg. "-a -b" to "-ab"
- impossible to parse without a spec
- first non-option argument ends option processing
- "--" is discarded and ends option processing
- whenever the first non-option argument does not end option processing
- however, "--" is discarded and still ends option processing
- options which select entirely separate behavior
- common examples: help and version
- catch-all for everything not otherwise defined
- could be broken down into more categories
- notable examples: find, ps, dd
Above all else, programs should have fewer options.
Consider evolution. In general, short options are the most convenient given sufficient familiarity, but are very limited and can be the least readable. Default to long options and assign short options with some thought.
Avoid non-hyphen options if at all possible. Avoid interspersed options for consistency with the (common) case of a program which has program-plus-arguments as arguments (eg. watch, daemontools). Avoid option-arguments as inflexible -- though POSIX prefers them.
Unsupplied values ("-a", "--b") should select the default for that option. Use a different option or a long option starting with "no-" to select non-defaults; eg. "--no-backup", or "--quiet" vs "--verbose". If no default is available (the value is required), then indicate that error. If the option is boolean (the value is prohibited), use a "no-" prefix rather than a value (eg. "--no-feat" rather than "--feat=no").
Reserve long options starting with "X-" (eg. "--X-abc") for options without a stable interface; ie. in testing or dev.
Avoid alternate mode options whenever an acceptable alternative exists. Single-file scripts benefit from --help, though perhaps a single comment block in the source would work just as well.
Unsorted:
- option names start with an ASCII letter or number and contain only ASCII characters
- short options have equivalent and indistinguishable long options; eg. "-a" / "--a", "-bv" / "--b=v"
- never alias "--help" to "-h" -- short options are too handy for a rarely used option, no matter how useful
- What is today "-v" might tomorrow become "-vvvv" because "v" was required to not take an option and it was combined with other options ("-avbc"). Backup options ("-b") might learn how to name files ("-bEXT"). Or "--verbose" might learn to filter categories ("--verbose=info,debug", "-vinfo,debug") instead of merely toggling a bool.