From 6dde6618d052fe0670744db73d8e4c0fcc4e4a9e Mon Sep 17 00:00:00 2001 From: heyjiawei Date: Mon, 24 Aug 2020 23:53:29 +0800 Subject: [PATCH] Add terminology section --- optional-options-docs.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/optional-options-docs.md b/optional-options-docs.md index 1e9e70083..5963208e1 100644 --- a/optional-options-docs.md +++ b/optional-options-docs.md @@ -2,6 +2,14 @@ There are potential challenges using options with optional values. They seem quite attractive and the README used to use them more than options with require values but in practice, they are a bit tricky and aren't a free choice. +## Terminology + +| Term(s) | Explanation | code example (if any) | +| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | +| option(s), flags, non-positional arguments | The term options consist of hyphen-minus characters
(that is ‘-’) followed by letters or digits.
options can take an argument or choose not to.
options that do not take an argument are term boolean flag(s) or boolean option(s) | `.option('-s, --small', 'small pizza size')` | +| optional value(s), option argument(s) | options are followed by an option argument.
If they are enclosed with square brackets `[]`, these option arguments are optional. | `.option('-o, --option [optionalValue]')` | +| operand(s), non-option argument(s) | arguments following the last options and option-arguments are named “operands” | `.arguments('[file]')` | + ## Parsing ambiguity There is parsing ambiguity when using option as boolean flag and also having it accept operands and subcommands. @@ -38,7 +46,7 @@ To reduce such ambiguity, you can do the following: 1. always use `--` before operands 2. add your options after operands -3. convert arguments into options! Options work pretty nicely together. +3. convert operands into options! Options work pretty nicely together. ## Combining short flags with optional values