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.

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

Finalize variable names for arguments returned by parse #12

Closed
shadowspawn opened this issue Nov 14, 2021 · 5 comments · Fixed by #22
Closed

Finalize variable names for arguments returned by parse #12

shadowspawn opened this issue Nov 14, 2021 · 5 comments · Fixed by #22

Comments

@shadowspawn
Copy link
Collaborator

shadowspawn commented Nov 14, 2021

I am unsure what semantic meaning to give args as a name in the returned object. To be fair, this is made worse by my experience with Commander, where program.args are the "positionals" left after parsing by removing the options and option-values.

I suspect it is short for "arguments" and skirting around what terminology to use. I think is reasonable to describe the input parameters to parseArgs as "arguments", but less clear when talking about the results of parsing.

The Initial Proposal returned options and positionals, and raised the question of terminology (and used "Flags", "Options", "Positionals"):

@shadowspawn shadowspawn changed the title Question args property name Question args property name in returned value Nov 14, 2021
@bcoe
Copy link
Collaborator

bcoe commented Nov 14, 2021

@shadowspawn I kind of like values and flags, thoughts?

@shadowspawn
Copy link
Collaborator Author

shadowspawn commented Nov 15, 2021

I did a bit of a survey. Terminology used in programmer guides to describe options/flags:

Programming object holding options/flags after parsing:

  • Commander: object of options (key:value)

  • Yargs: object of options (key:value, and positionals in _)

  • minimist: : object of options (key:value, and positionals in _)

  • argparse: object with combined option and arguments (key:value)

  • oclif: result object has flags property which is object of options (key:value)

@shadowspawn
Copy link
Collaborator Author

values and flags

Short version: better, yes.

@ljharb
Copy link
Member

ljharb commented Nov 15, 2021

To me, flags are only booleans; “option” seems like the most universal and intuitive term. An argument can be an option argument, or a positional argument, or an option value; an option can be a flag, or not.

@shadowspawn
Copy link
Collaborator Author

Long comment, not disagreeing.

I see the term "flag" get used three ways:

  • "flag" rather than "option" to describe the whole feature of non-positional (e.g. Cobra and Oclif)
  • "flag" to describe options which do not take a value (as ljharb describes)
  • "flag" to describe the argument with the hyphen or double hyphen in front of if, and hence short-flag and long-flag

Personally, I was using both the second and third forms in documentation. When I noticed my own inconsistency, I switched to saying "boolean option" for an option not taking an option-argument so using "flag" just one way.

I am still pretty comfortable with "flag" as term for not taking an option-argument. (And staying away from mentioning boolean might decrease assumptions leading to the --explode=false problem. 😄 )

bcoe added a commit that referenced this issue Dec 4, 2021
Based on #12, and sifting through online conversatino [like this](https://unix.stackexchange.com/questions/285575/whats-the-difference-between-a-flag-an-option-and-an-argument), this refactor
proposes using the terminology "args" for options that take arguments,
and "flags" for options that are boolean.

Fixes #12
@bcoe bcoe added this to the Merge into Node.js milestone Dec 4, 2021
@bcoe bcoe changed the title Question args property name in returned value Finalize variable names for arguments returned by parse Dec 4, 2021
@bcoe bcoe closed this as completed in #22 Dec 20, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants