Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation on tricks and traps of using optional options #1332

Merged
merged 12 commits into from
Sep 13, 2020
Merged

Add documentation on tricks and traps of using optional options #1332

Changes from 1 commit
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
94b7f1b
Add documentation on tricks and traps of using optional options
heyjiawei Aug 18, 2020
0588e30
Fix grammar and example. Add future works
heyjiawei Aug 19, 2020
3f8623e
Update variadic optional options
heyjiawei Aug 24, 2020
5746704
Add terminology section
heyjiawei Aug 24, 2020
9812ee7
Add that commander follows GNU utility convention
heyjiawei Aug 25, 2020
c686ee3
Update terminology; remove our terms from official terms
heyjiawei Aug 25, 2020
3e29566
Update example using option as boolean flag and also having it accept…
heyjiawei Aug 28, 2020
5a2b953
Refactor and expand intro and parse ambiguity
shadowspawn Aug 30, 2020
53cf35b
Expand fragments a little, reword GNU reference
shadowspawn Aug 30, 2020
8113f41
Some tweaks, and add GNU link
shadowspawn Aug 30, 2020
3434f4d
Rework, and move file
shadowspawn Sep 4, 2020
0b5f249
Merge pull request #1 from shadowspawn/feature/more-about-options-fork
heyjiawei Sep 13, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Update terminology; remove our terms from official terms
  • Loading branch information
@heyjiawei
heyjiawei committed Aug 25, 2020
commit c686ee325f3303ddfbd6590066e25329b76c8209
9 changes: 6 additions & 3 deletions optional-options-docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,12 @@ There are potential challenges using options with optional values. They seem qui
| Term(s) | Explanation | code example (if any) |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| option(s), flags, non-positional arguments | The term options consist of hyphen-minus characters <br />(that is ‘-’) followed by letters or digits. <br /> options can take an argument or choose not to. <br/>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. <br /> If they are enclosed with square brackets `[]`, these option arguments are optional. | `.option('-o, --option [optionalValue]')` |
| option argument(s) | options are followed by an option argument. <br /> 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]')` |
| optional options | flags that take in optional argument |

## Parsing ambiguity

There is parsing ambiguity when using option as boolean flag and also having it accept operands and subcommands.
There is parsing ambiguity when using option as boolean flag and also having it accept operands(sometimes called a positional argument or command argument, referring to `Command.arguments()`) and subcommands.

```
program.command('example')
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest change the example to taking an argument, and no subcommands. I think that will be the common problem case, whether it is a single level command, or down in a subcommand.

Also, I would like it to look like it does something. My boring description you worked from was `example -o optionalValue' but it is more fun when the program looks more interesting. I struggle to come up with nice examples!

For this section we just need one optional value and one optional argument, so the command should make sense with one, or the other, or both.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh what is the difference between optional value and optional argument? I though they are the same thing
.option("-o, --option [optionalValue]")

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops, that raises another thing I had been thinking about: terminology!

When I wrote "optional argument" I was intending to mean a non-option argument, sometimes called an "operand" or "positional argument". I am not very familiar with either term, and wonder whether "non-option argument" is simple and clear.

What I meant was a non-option argument, like:

program.arguments('[file]');

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll dump some research on terminology in here for reference. I haven't decided what terms to recommend yet!

A number of sources use "positional" as a qualifier, which I assume is meaning in particular that the order matters.

https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
The utility in the example is named utility_name. It is followed by options, option-arguments, and operands. The arguments that consist of characters and single letters or digits, such as 'a', are known as "options" (or, historically, "flags"). Certain options are followed by an "option-argument", as shown with [ -c option_argument]. The arguments following the last options and option-arguments are named "operands".

https://docs.python.org/3/library/argparse.html
The add_argument() method must know whether an optional argument, like -f or --foo, or a positional argument, like a list of filenames, is expected. The first arguments passed to add_argument() must therefore be either a series of flags, or a simple argument name. For example, an optional argument could be created like:

yargs
.options()
.command()
.positional()

https://oclif.io/docs
Arguments are positional arguments passed to the command.
Flag options are non-positional arguments passed to the command. Flags can either be option flags which take an argument, or boolean flags which do not. An option flag must have an argument.

https://github.com/spf13/cobra#concepts
Cobra is built on a structure of commands, arguments & flags.
Commands represent actions, Args are things and Flags are modifiers for those actions.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

okay, I understand the term you are referring to now. I added a terminology section explaining only the terms used in this document.

I usually clump the terms together if they mean about the same thing. This is good if we come from different backgrounds because we would have something easy to cross-reference to.

I also add a new terminology if I find myself giving it an alias; in this case the borrowed alias "optional options" though I'm not sure if the terminology is well explained

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we get the terms nice and clean, I'll be updating the README to be more consistent! I have been trying hard to be clear there, but I haven't got it consistent yet.

Mentioning terms used in other places is potentially useful, but I don't want "our" terms and "other" terms just listed mixed together. Perhaps, "sometimes called", like:

operand (sometimes called a positional argument)

I do not see "operand" used very much apart from the Open Group, and currently considering "command argument" to match up quite nicely with Command.arguments().

I had been trying to reduce use of "argument" because seemed different before and after parsing, but maybe qualifying could work. So there are CLI arguments before parsing (e.g. process.args), option arguments, and command arguments.

Expand Down Expand Up @@ -53,6 +52,10 @@ The POSIX convention is that options always come before operands. The GNU utilit

## Combining short flags with optional values

optional options are option(s) which functions as a flag but may also take a value (declared using square brackets).

optional values (sometimes called option arguments) are values of these optional flag.

```
program
.option("-o, --others [count]", "others servings")
Expand Down