Skip to content

doc: "if and only if" should be "if" in util.parseArgs default value #58958

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

Merged
aduh95 merged 3 commits into from
Jul 15, 2025
Merged

doc: "if and only if" should be "if" in util.parseArgs default value #58958

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fa18174
doc: "if and only if" should be "if" in util.parseArgs default value
Slayer95 Jul 4, 2025
00e31c5
doc: extend explanation of `default` in util.parseArgs
Slayer95 Jul 14, 2025
087f8c0
Prefer "falsy" over "falsey"
Slayer95 Jul 14, 2025
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
2 changes: 1 addition & 1 deletion doc/api/util.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1956,7 +1956,7 @@ changes:
`false`, values for the option are last-wins. **Default:** `false`.
* `short` {string} A single character alias for the option.
* `default` {string | boolean | string\[] | boolean\[]} The default value to
be used if (and only if) the option does not appear in the arguments to be
be used if the option does not appear in the arguments to be
Copy link
Member

@himself65 himself65 Jul 5, 2025

Choose a reason for hiding this comment

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

upstream comment:

#54431 (comment)

Copy link
Contributor Author

@Slayer95 Slayer95 Jul 5, 2025

Choose a reason for hiding this comment

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

Re: #54431, the critical part is "the option does not appear in the arguments to be parsed".

However, the way it's currently worded "if and only if", it literally means that the value passed as default behaves as a sentinel value: when it matches, the option was missing; otherwise, the option was in the arguments provided.

But that's not how it works. It's a one-side implication.

Copy link
Contributor

@aduh95 aduh95 Jul 5, 2025

Choose a reason for hiding this comment

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

Well it says "to be used", so I don't think it says the value could not be the default value if the option appears in the arguments.
Maybe we can try to rephrase it further to remove the ambiguity:

    * `default` {string | boolean | string\[] | boolean\[]} It must be of the
      same type as the `type` property. When `multiple` is `true`, it must be an
      array. It is ignored when when the option appears in the arguments to be
      parsed.

Copy link
Member

@shadowspawn shadowspawn Jul 10, 2025

Choose a reason for hiding this comment

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

@aduh95 That leaves out what default is actually used for. Adding your suggestion to the previous text:

`default` {string | boolean | string\[] | boolean\[]} The default value to
      be used if the option does not appear in the arguments to be parsed,
      and ignored if the option does appear. It must be of the same type as the
     `type` property. When `multiple` is `true`, it must be an array.

Copy link
Contributor Author

@Slayer95 Slayer95 Jul 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

`default` {string | boolean | string\[] | boolean\[]} The default value to
      be used if the option does not appear in the arguments to be parsed,
      and ignored if the option does appear. It must be of the same type as the
     `type` property. When `multiple` is `true`, it must be an array.

This wording is also an "if and only if", just more verbose. This wording implies that if string option --foo has a default value of "bar", then --foo=bar is ignored.

I'd go with this:

* `default` {string | boolean | string\[] | boolean\[]} The value to be used if the
      option does not appear in the arguments to be parsed. It must be of the
      same type as the `type` property. When `multiple` is `true`, it must be an
      array. It is ignored when the option appears in the arguments to be
      parsed.

Copy link
Contributor Author

@Slayer95 Slayer95 Jul 14, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I added a new commit, with an expanded text that is hopefully clearer in the context of #54396 and #54431. Does this work for you, @shadowspawn ?

Copy link
Member

@shadowspawn shadowspawn Jul 15, 2025

Choose a reason for hiding this comment

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

What is this new text about: even if the provided value is falsy? I don't understand why this has been added.

Otherwise, I agree hopefully clearer, spelling out the (if and only if). :-)

Copy link
Contributor Author

@Slayer95 Slayer95 Jul 15, 2025

Choose a reason for hiding this comment

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

What is this new text about: even if the provided value is falsy? I don't understand why this has been added.

This is my takeaway from #54396. "falsy" meaning x == false, but actually left open to interpretation, so that whatever false/empty/zero/value someone may think will lead to the parser entering defaulting mechanics, it will not be taken.

Otherwise, I agree hopefully clearer, spelling out the (if and only if). :-)

Well, this was an if (and only if) -note the distinct position of the parens. Whenever such half-parenthesized construct is used, it means that if some convenient assumptions are made, a backwards implication holds, but there are readings where the implication is only forwards. i.e. Considering those additional assumptions, the text turns out to mean not p <=> q, but p => q ∧ r <= s, where either p is equivalent to r, or q is equivalent to s.

Sorry for beating the dead horse, but I think I didn't manage to properly justify how the previous text was problematic, and I just took the chance.

Copy link
Member

@shadowspawn shadowspawn Jul 15, 2025

Choose a reason for hiding this comment

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

This is my takeaway from #54396. "falsy" meaning x == false, but actually left open to interpretation, so that whatever false/empty/zero/value someone may think will lead to the parser entering defaulting mechanics, it will not be taken.

That wasn't the issue, and thanks for asking me to take a look. The previous wording change was a bit difficult (like this one!) and clearly hasn't worked for everyone.

The original cause for a wording change was that someone came in hoping to allow:

util
util --foo
util --foo FOO

The previous wording did not make it clear enough to them that they couldn't use a default value to cover that middle case.

Copy link
Contributor Author

@Slayer95 Slayer95 Jul 15, 2025

Choose a reason for hiding this comment

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

I wanted to liberally fit util --foo in the "foo is falsey" when parsed as a string; but I forgot it would actually be true if parsed as a boolean. I also wanted to make the "it is ignored..." sentence explicitly non-normative. But there's no such concept in Node.js docs. Documentation is hard. 😄

parsed. It must be of the same type as the `type` property. When `multiple`
is `true`, it must be an array.
* `strict` {boolean} Should an error be thrown when unknown arguments
Expand Down